pcap.h

Windows XP下的抓包程序实现

/** @defgroup wpcapfunc Exported functions
 *  @ingroup wpcap
 *  Functions exported by wpcap.dll
 *  @{
 */


/** \name Unix-compatible Functions

	These functions are part of the libpcap library, and therefore work
	both on Windows and on Linux.
	\note errbuf in pcap_open_live(), pcap_open_dead(), pcap_open_offline(), 
	pcap_setnonblock(), pcap_getnonblock(), pcap_findalldevs(), 
	pcap_lookupdev(), and pcap_lookupnet() is assumed to be able to hold at 
	least PCAP_ERRBUF_SIZE chars.
 */
//\{ 

/*! \brief Prototype of the callback function that receives the packets. 

When pcap_dispatch() or pcap_loop() are called by the user, the packets are passed to the application
by means of this callback. user is a user-defined parameter that contains the state of the
capture session, it corresponds to the \e user parameter of pcap_dispatch() and pcap_loop(). pkt_header is
the header associated by the capture driver to the packet. It is NOT a protocol header. pkt_data
points to the data of the packet, including the protocol headers.
*/
typedef void (*pcap_handler)(u_char *user, const struct pcap_pkthdr *pkt_header,
			     const u_char *pkt_data);

/*!	\brief Open a live capture from the network.

	pcap_open_live()  is  used  to  obtain a packet capture descriptor to
	look at packets on the network.  device is a  string  that  specifies
	the  network  device to open; on Linux systems with 2.2 or later kernels, 
	a device argument of "any" or NULL can be used to capture packets  
	from  all  interfaces.   snaplen specifies the maximum number of
	bytes to capture.  If this value is less than the size  of  a  packet
	that is captured, only the first snaplen bytes of that packet will be
	captured and provided as packet data.  A value  of  65535  should  be
	sufficient,  on  most  if  not  all networks, to capture all the data
	available from the packet.  promisc specifies if the interface is  to
	be  put  into promiscuous mode.  (Note that even if this parameter is
	false, the interface could well be in promiscuous mode for some other
	reason.)  For now, this doesn't work on the "any" device; if an argument 
	of "any" or NULL is  supplied,  the  promisc  flag  is  ignored.
	to_ms  specifies  the read timeout in milliseconds.  The read timeout
	is used to arrange that the read not necessarily  return  immediately
	when  a  packet  is seen, but that it wait for some amount of time to
	allow more packets to arrive and to read multiple packets from the OS
	kernel  in  one operation.  Not all platforms support a read timeout;
	on platforms that don't, the read timeout is ignored.  A  zero  value
	for  to_ms,  on  platforms  that support a read timeout, will cause a
	read to wait forever to allow enough packets to arrive, with no timeout.  
	errbuf is used to return error or warning text.  It will be set
	to error text when pcap_open_live() fails and returns  NULL.   errbuf
	may  also  be  set  to warning text when pcap_open_live() succeds; to
	detect this case the caller should  store  a  zero-length  string  in
	errbuf before calling pcap_open_live() and display the warning to the
	user if errbuf is no longer a zero-length string.

\sa pcap_open_offline(), pcap_open_dead(), pcap_findalldevs(), pcap_close()
*/
pcap_t *pcap_open_live(const char *device, int snaplen, int promisc, int to_ms, char *ebuf);


/*!	\brief Create a pcap_t structure without starting a capture.

  pcap_open_dead()  is  used for creating a pcap_t structure
  to use when calling the other functions in libpcap.  It is
  typically  used  when just using libpcap for compiling BPF
  code.

\sa pcap_open_offline(), pcap_open_live(), pcap_findalldevs(), pcap_compile(), pcap_setfilter(), pcap_close()
*/
pcap_t *pcap_open_dead(int linktype, int snaplen);


/*!	\brief Open a savefile in the tcpdump/libpcap format to read packets.

	pcap_open_offline() is called to open  a  "savefile"  for  reading.
	fname  specifies  the name of the file to open. The file has the same
	format as those used by tcpdump(1) and tcpslice(1).  The name "-"  in
	a    synonym    for    stdin.     Alternatively,    you    may   call
	pcap_fopen_offline() to read dumped data from an existing open stream
	fp.   Note  that  on  Windows, that stream should be opened in binary
	mode.  errbuf is used to return error  text  and  is  only  set  when
	pcap_open_offline() or pcap_fopen_offline() fails and returns NULL.

\sa pcap_open_live(), pcap_dump_open(), pcap_findalldevs(), pcap_close()
*/
pcap_t *pcap_open_offline(const char *fname, char *errbuf);

/*! \brief Open a file to write packets.

	pcap_dump_open()  is  called  to open a "savefile" for writing. The
	name "-" in a synonym for stdout.  NULL is returned on failure.  p is
	a pcap struct as returned by pcap_open_offline() or pcap_open_live().
	fname specifies the name of the file to open. Alternatively, you  may
	call  pcap_dump_fopen()  to write data to an existing open stream fp.
	Note that on Windows, that stream should be opened  in  binary  mode.
	If NULL is returned, pcap_geterr() can be used to get the error text.

\sa pcap_dump_close(), pcap_dump()
*/
pcap_dumper_t *pcap_dump_open(pcap_t *p, const char *fname);

/*! \brief Switch between blocking and nonblocking mode.

       pcap_setnonblock() puts a capture descriptor, opened  with
       pcap_open_live(),  into "non-blocking" mode, or takes it
       out of "non-blocking" mode,  depending  on  whether  the
       nonblock  argument  is non-zero or zero.  It has no effect
       on "savefiles".  If there is an error,  -1  is  returned
       and errbuf is filled in with an appropriate error message;
       otherwise, 0 is returned.  In  "non-blocking"  mode,  an
       attempt to read from the capture descriptor with pcap_dispatch() 
	   will, if no packets are currently available to  be
       read,  return  0  immediately rather than blocking waiting
       for packets to arrive.  pcap_loop() and  pcap_next()  will
       not work in "non-blocking" mode.

\sa pcap_getnonblock(), pcap_dispatch()
*/
int pcap_setnonblock(pcap_t *p, int nonblock, char *errbuf);


/*! \brief Get the "non-blocking" state of an interface.

       pcap_getnonblock()  returns  the  current "non-blocking"
       state of the capture descriptor; it always  returns  0  on
       "savefiles".   If  there is an error, -1 is returned and
       errbuf is filled in with an appropriate error message.

\sa pcap_setnonblock()
*/
int pcap_getnonblock(pcap_t *p, char *errbuf);

/*!	\brief Construct a list of network devices that can be 
  opened with pcap_open_live(). 
  
  \note that there may be network devices that cannot be opened with 
  pcap_open_live() 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.) 
  alldevsp is set to point to the first element of the list; each element 
  of the list is of type \ref pcap_if_t, 

  -1 is returned on failure, in which case errbuf is filled in with an 
  appropriate error message; 0 is returned on success.

\sa struct pcap_if, pcap_freealldevs(), pcap_open_live(), pcap_lookupdev(), pcap_lookupnet()
*/
int pcap_findalldevs(pcap_if_t **alldevsp, char *errbuf);

/*! \brief Free an interface list returned by pcap_findalldevs().

       pcap_freealldevs()  is  used  to  free a list allocated by pcap_findalldevs().

\sa pcap_findalldevs()
*/
void pcap_freealldevs(pcap_if_t *alldevsp);

/*! 	\brief Return the first valid device in the system.
\deprecated Use \ref pcap_findalldevs() or \ref pcap_findalldevs_ex() instead.

       pcap_lookupdev() returns a pointer  to  a  network  device
       suitable  for  use  with pcap_open_live() and pcap_lookupnet().
	   If there is an error, NULL is returned and  errbuf
       is filled in with an appropriate error message.

\sa pcap_findalldevs(), pcap_open_live()
*/
char *pcap_lookupdev(char *errbuf);


/*!	\brief Return the subnet and netmask of an interface.
\deprecated Use \ref pcap_findalldevs() or \ref pcap_findalldevs_ex() instead.

       pcap_lookupnet()  is  used to determine the network number
       and mask associated with the network device device.   Both
       netp  and  maskp are bpf_u_int32 pointers.  A return of -1
       indicates an error in which case errbuf is filled in  with
       an appropriate error message.

\sa pcap_findalldevs()
*/
int pcap_lookupnet(const char *device, bpf_u_int32 *netp, bpf_u_int32 *maskp, char *errbuf);

/*!	\brief Collect a group of packets.

  pcap_dispatch() is used to collect and process packets. cnt specifies the maximum 
  number of packets to process before returning. This is not a minimum number; when 
  reading a live capture, only one bufferful of packets is read at a time, so fewer 
  than cnt packets may be processed. A cnt of -1 processes all the packets received 
  in one buffer when reading a live capture, or all the packets in the file when 
  reading a ``savefile''. callback specifies a routine to be called with three 
  arguments: a u_char pointer which is passed in from pcap_dispatch(), a const 
  struct \ref pcap_pkthdr pointer,
  and a const u_char pointer to the first caplen (as given in the struct pcap_pkthdr 
  a pointer to which is passed to the callback routine) bytes of data from the packet 
  (which won't necessarily be the entire packet; to capture the entire packet, you 
  will have to provide a value for snaplen in your call to pcap_open_live() that is 
  sufficiently large to get all of the packet's data - a value of 65535 should be 
  sufficient on most if not all networks).

  The number of packets read is returned. 0 is returned if no packets were read from 
  a live capture (if, for example, they were discarded because they didn't pass the 
  packet filter, or if, on platforms that support a read timeout that starts before 
  any packets arrive, the timeout expires before any packets arrive, or if the file 
  descriptor for the capture device is in non-blocking mode and no packets were 
  available to be read) or if no more packets are available in a ``savefile.'' A return 
  of -1 indicates an error in which case pcap_perror() or pcap_geterr() may be used 
  to display the error text. A return of -2 indicates that the loop terminated due to 
  a call to pcap_breakloop() before any packets were processed. If your application 
  uses pcap_breakloop(), make sure that you explicitly check for -1 and -2, rather 
  than just checking for a return value < 0.

  \note when reading a live capture, pcap_dispatch() will not necessarily return when 
  the read times out; on some platforms, the read timeout isn't supported, and, on 
  other platforms, the timer doesn't start until at least one packet arrives. This 
  means that the read timeout should NOT be used in, for example, an interactive 
  application, to allow the packet capture loop to ``poll'' for user input periodically, 
  as there's no guarantee that pcap_dispatch() will return after the timeout expires.

\sa pcap_loop(), pcap_next(), pcap_open_live(), pcap_open_offline(), pcap_handler
*/
int pcap_dispatch(pcap_t *p, int cnt, pcap_handler callback, u_char *user);


/*!	\brief Collect a group of packets.

  pcap_loop() is similar to pcap_dispatch() except it keeps reading packets until cnt 
  packets are processed or an error occurs. It does not return when live read timeouts 
  occur. Rather, specifying a non-zero read timeout to pcap_open_live() and then calling 
  pcap_dispatch() allows the reception and processing of any packets that arrive when 
  the timeout occurs. A negative cnt causes pcap_loop() to loop forever (or at least 
  until an error occurs). -1 is returned on an error; 0 is returned if cnt is exhausted; 
  -2 is returned if the loop terminated due to a call to pcap_breakloop() before any packets
  were processed. If your application uses pcap_breakloop(), make sure that you explicitly 
  check for -1 and -2, rather than just checking for a return value < 0.

\sa pcap_dispatch(), pcap_next(), pcap_open_live(), pcap_open_offline(), pcap_handler
*/
int pcap_loop(pcap_t *p, int cnt, pcap_handler callback, u_char *user);


/*! \brief Return the next available packet.

  pcap_next() reads the next packet (by calling pcap_dispatch() with a cnt of 1) and returns 
  a u_char pointer to the data in that packet. (The pcap_pkthdr struct for that packet is not