Collects and processes packets.
pcap Library (libpcap.a)
int pcap_dispatch(pcap_t * p, int cnt, pcap_handler callback,
u_char * user);
The pcap_dispatch subroutine reads and processes packets. This subroutine can be called to read and process packets that are stored in a previously saved packet capture data file, known as the savefile. The subroutine can also read and process packets that are being captured live.
Notice that the third parameter, callback, is of the type pcap_handler. This is a pointer to a user-provided subroutine with three parameters. Define this user-provided subroutine as follows:
void user_routine(u_char *user, struct pcap_pkthdr *phdr, u_char *pdata)
The parameter, user, is the user parameter that is passed into the pcap_dispatch subroutine. The parameter, phdr, is a pointer to the pcap_pkthdr structure which precedes each packet in the savefile. The parameter, pdata, points to the packet data. This allows users to define their own handling of packet capture data.
|callback||Points to a user-provided routine that will be called for each packet
read. The user is responsible for providing a valid pointer, and that
unpredictable results can occur if an invalid pointer is supplied.
Note: The pcap_dump subroutine can also be specified as the callback parameter. If this is done, the pcap_dump_open subroutine should be called first. The pointer to the pcap_dumper_t struct returned from the pcap_dump_open subroutine should be used as the user parameter to the pcap_dispatch subroutine. The following program fragment illustrates this use:
|cnt||Specifies the maximum number of packets to process before returning. A cnt of -1 processes all the packets received in one buffer. A cnt of 0 processes all packets until an error occurs, EOF is reached, or the read times out (when doing live reads and a non-zero read timeout is specified).|
|p||Points to a packet capture descriptor returned from the pcap_open_offline or the pcap_open_live subroutine. This will be used to store packet data that is read in.|
|user||Specifies the first argument to pass into the callback routine.|
Upon successful completion, the pcap_dispatch subroutine returns the number of packets read. If EOF is reached in a savefile, zero is returned. If the pcap_dispatch subroutine is unsuccessful, -1 is returned. In this case, the pcap_geterr or pcap_perror subroutine can be used to get the error text.
The pcap_dump (pcap_dump Subroutine) subroutine, pcap_dump_close (pcap_dump_close Subroutine) subroutine, pcap_dump_open (pcap_dump_open Subroutine) subroutine, pcap_geterr (pcap_geterr Subroutine) subroutine, pcap_open_live (pcap_open_live Subroutine) subroutine, pcap_open_offline (pcap_open_offline Subroutine) subroutine, pcap_perror (pcap_perror Subroutine) subroutine.