pcap.h

Windows XP下的抓包程序实现

\warning pcap_stats_ex()  is  supported  only on live captures, not on  "savefiles"; no statistics are stored in
"savefiles", so no statistics are available when reading from a "savefile".

\sa pcap_stats()
*/
struct pcap_stat *pcap_stats_ex(pcap_t *p, int *pcap_stat_size);

/*! \brief Set the size of the kernel buffer associated with an adapter.

\e dim specifies the size of the buffer in bytes.
The return value is 0 when the call succeeds, -1 otherwise. If an old buffer was already created 
with a previous call to pcap_setbuff(), it is deleted and its content is discarded. 
pcap_open_live() creates a 1 MByte buffer by default.

\sa pcap_open_live(), pcap_loop(), pcap_dispatch()
*/
int pcap_setbuff(pcap_t *p, int dim);


/*! \brief Set the working mode of the interface p to mode. 

Valid values for mode are 
MODE_CAPT (default capture mode) and MODE_STAT (statistical mode). See the tutorial "\ref wpcap_tut9"
for details about statistical mode.
*/
int pcap_setmode(pcap_t *p, int mode);


/*! \brief Set the minumum amount of data received by the kernel in a single call.

pcap_setmintocopy() changes the minimum amount of data in the kernel buffer that causes a read from 
the application to return (unless the timeout expires). If the value of \e size is large, the kernel 
is forced to wait the arrival of several packets before copying the data to the user. This guarantees 
a low number of system calls, i.e. low processor usage, and is a good setting for applications like 
packet-sniffers and protocol analyzers. Vice versa, in presence of a small value for this variable, 
the kernel will copy the packets as soon as the application is ready to receive them. This is useful 
for real time applications that need the best responsiveness from the kernel.

\sa pcap_open_live(), pcap_loop(), pcap_dispatch()
*/
int pcap_setmintocopy(pcap_t *p, int size);



/*! \brief Return the handle of the event associated with the interface p. 

	This event can be passed to functions like WaitForSingleObject() or WaitForMultipleObjects() to wait 
	until the driver's buffer contains some data without performing a read.

	We disourage the use of this function because it is not portable.

\sa pcap_open_live()
*/
HANDLE pcap_getevent(pcap_t *p);

/*! \brief Allocate a send queue. 

This function allocates a send queue, i.e. a buffer containing a set of raw packets that will be transimtted
on the network with pcap_sendqueue_transmit().

memsize is the size, in bytes, of the queue, therefore it determines the maximum amount of data that the 
queue will contain.

Use pcap_sendqueue_queue() to insert packets in the queue.

\sa pcap_sendqueue_queue(), pcap_sendqueue_transmit(), pcap_sendqueue_destroy()
*/
pcap_send_queue* pcap_sendqueue_alloc(u_int memsize);

/*! \brief Destroy a send queue. 

Deletes a send queue and frees all the memory associated with it.

\sa pcap_sendqueue_alloc(), pcap_sendqueue_queue(), pcap_sendqueue_transmit()
*/
void pcap_sendqueue_destroy(pcap_send_queue* queue);

/*! \brief Add a packet to a send queue. 

pcap_sendqueue_queue() adds a packet at the end of the send queue pointed by the queue parameter. 
pkt_header points to a pcap_pkthdr structure with the timestamp and the length of the packet, pkt_data
points to a buffer with the data of the packet.

The pcap_pkthdr structure is the same used by WinPcap and libpcap to store the packets in a file, 
therefore sending a capture file is straightforward.
'Raw packet' means that the sending application will have to include the protocol headers, since every packet 
is sent to the network 'as is'. The CRC of the packets needs not to be calculated, because it will be 
transparently added by the network interface.

\sa pcap_sendqueue_alloc(), pcap_sendqueue_transmit(), pcap_sendqueue_destroy()
*/
int pcap_sendqueue_queue(pcap_send_queue* queue, const struct pcap_pkthdr *pkt_header, const u_char *pkt_data);


/*! \brief Send a queue of raw packets to the network.

This function transmits the content of a queue to the wire. p is a 
pointer to the adapter on which the packets will be sent, queue points to a pcap_send_queue structure 
containing the packets to send (see pcap_sendqueue_alloc() and pcap_sendqueue_queue()), sync determines if the 
send operation must be synchronized: if it is non-zero, the packets are sent respecting the timestamps,
otherwise they are sent as fast as possible.

The return value is the amount of bytes actually sent. If it is smaller than the size parameter, an
error occurred during the send. The error can be caused by a driver/adapter problem or by an inconsistent/bogus 
send queue.

\note Using this function is more efficient than issuing a series of pcap_sendpacket(), because the packets are
buffered in the kernel driver, so the number of context switches is reduced. Therefore, expect a better 
throughput when using pcap_sendqueue_transmit.

\note When Sync is set to TRUE, the packets are synchronized in the kernel with a high precision timestamp.
This requires a non-negligible amount of CPU, but allows normally to send the packets with a precision of some 
microseconds (depending on the accuracy of the performance counter of the machine). Such a precision cannot 
be reached sending the packets with pcap_sendpacket().

\sa pcap_sendqueue_alloc(), pcap_sendqueue_queue(), pcap_sendqueue_destroy()
*/
u_int pcap_sendqueue_transmit(pcap_t *p, pcap_send_queue* queue, int sync);


/*!	\brief Create a list of network devices that can be opened with pcap_open().
	
	This function is a superset of the old 'pcap_findalldevs()', which is obsolete, and which
	allows listing only the devices present on the local machine.
	Vice versa, pcap_findalldevs_ex() allows listing the devices present on a remote 
	machine as well. Additionally, it can list all the pcap files available into a given folder.
	Moreover, pcap_findalldevs_ex() is platform independent, since it
	relies on the standard pcap_findalldevs() to get addresses on the local machine.

	In case the function has to list the interfaces on a remote machine, it opens a new control
	connection toward that machine, it retrieves the interfaces, and it drops the connection.
	However, if this function detects that the remote machine is in 'active' mode,
	the connection is not dropped and the existing socket is used.

	The 'source' is a parameter that tells the function where the lookup has to be done and
	it uses the same syntax of the pcap_open().

	Differently from the pcap_findalldevs(), the interface names (pointed by the alldevs->name
	and the other ones in the linked list) are already ready to be used in the pcap_open() call.
	Vice versa, the output that comes from pcap_findalldevs() must be formatted with the new
	pcap_createsrcstr() before passing the source identifier to the pcap_open().

	\param source: a char* buffer that keeps the 'source localtion', according to the new WinPcap
	syntax. This source will be examined looking for adapters (local or remote) (e.g. source
	can be 'rpcap://' for local adapters or 'rpcap://host:port' for adapters on a remote host)
	or pcap files (e.g. source can be 'file://c:/myfolder/').<br>
	The strings that must be prepended to the 'source' in order to define if we want
	local/remote adapters or files is defined in the new \link remote_source_string Source 
	Specification Syntax \endlink.

	\param auth: a pointer to a pcap_rmtauth structure. This pointer keeps the information
	required to authenticate the RPCAP connection to the remote host.
	This parameter is not meaningful in case of a query to the local host: in that case
	it can be NULL.

	\param alldevs: a 'struct pcap_if_t' pointer, which will be properly allocated inside
	this function. When the function returns, it is set to point to the first element 
	of the interface list; each element of the list is of type 'struct pcap_if_t'.

	\param errbuf: a pointer to a user-allocated buffer (of size PCAP_ERRBUF_SIZE)
	that will contain the error message (in case there is one).

	\return '0' if everything is fine, '-1' if some errors occurred. The list of the devices 
	is returned in the 'alldevs' variable.
	When the function returns correctly, 'alldevs' cannot be NULL. In other words, this 
	function returns '-1' also in case the system does not have any interface to list.

	The error message is returned in the 'errbuf' variable. An error could be due to 
	several reasons:
	- libpcap/WinPcap was not installed on the local/remote host
	- the user does not have enough privileges to list the devices / files
	- a network problem
	- the RPCAP version negotiation failed
	- other errors (not enough memory and others).
	
	\warning There may be network devices that cannot be opened with pcap_open() by the process
	calling pcap_findalldevs(), because, for example, that process might not have
	sufficient privileges to open them for capturing; if so, those devices will not 
	appear on the list.

	\warning The interface list must be deallocated manually by using the pcap_freealldevs().
*/
int pcap_findalldevs_ex(char *source, struct pcap_rmtauth *auth, pcap_if_t **alldevs, char *errbuf);


/*!	\brief Accept a set of strings (host name, port, ...), and it returns the complete 
	source string according to the new format (e.g. 'rpcap://1.2.3.4/eth0').

	This function is provided in order to help the user creating the source string
	according to the new format.
	An unique source string is used in order to make easy for old applications to use the
	remote facilities. Think about tcpdump, for example, which has only one way to specify
	the interface on which the capture has to be started.
	However, GUI-based programs can find more useful to specify hostname, port and
	interface name separately. In that case, they can use this function to create the 
	source string before passing it to the pcap_open() function.

	\param source: a user-allocated buffer that will contain the complete source string
	wen the function returns.<br>
	The source will start with an identifier according to the new \link remote_source_string 
	Source Specification Syntax	\endlink.<br>
	This function assumes that the allocated buffer is at least PCAP_BUF_SIZE bytes.

	\param type: its value tells the type of the source we want to create. It can assume 
	the values defined in the \link remote_source_ID Source identification
	Codes \endlink.<br>

	\param host: an user-allocated buffer that keeps the host (e.g. "foo.bar.com") we 
	want to connect to.
	It can be NULL in case we want to open an interface on a local host.

	\param port: an user-allocated buffer that keeps the network port (e.g. "2002") we 
	want to use for the RPCAP protocol.
	It can be NULL in case we want to open an interface on a local host.

	\param name: an user-allocated buffer that keeps the interface name we want to use
	(e.g. "eth0").
	It can be NULL in case the return string (i.e. 'source') has to be used with the
	pcap_findalldevs_ex(), which does not require the interface name.

	\param errbuf: a pointer to a user-allocated buffer (of size PCAP_ERRBUF_SIZE)
	that will contain the error message (in case there is one).

	\return '0' if everything is fine, '-1' if some errors occurred. The string containing
	the complete source is returned in the 'source' variable.

	\warning If the source is longer than PCAP_BUF_SIZE, the excess characters are truncated.
*/
int pcap_createsrcstr(char *source, int type, const char *host, const char *port, const char *name, char *errbuf);


/*!	\brief Parse the source string and returns the pieces in which the source can be split.

	This call is the other way round of pcap_createsrcstr().
	It accepts a null-terminated string and it returns the parameters related 
	to the source. This includes:
	- the type of the source (file, winpcap on a remote adapter, winpcap on local adapter),
	which is determined by the source prefix (PCAP_SRC_IF_STRING and so on)
	- the host on which the capture has to be started (only for remote captures)
	- the 'raw' name of the source (file name, name of the remote adapter, name 
	of the local adapter), without the source prefix. The string returned does not 
	include the type of the source itself (i.e. the string returned does not include "file://" 
	or rpcap:// or such).

	The user can omit some parameters in case it is not interested in them.

	\param source: a null-terminated string containing the WinPcap source. This source starts
	with an identifier according to the new \link remote_source_string Source Specification Syntax
	\endlink.