Collects and processes packets.
pcap Library (libpcap.a)
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.
Item | Description |
---|---|
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.