pcap.h

winpcap

/* -*- Mode: c; tab-width: 8; indent-tabs-mode: 1; c-basic-offset: 8; -*- */
/*
 * Copyright (c) 1993, 1994, 1995, 1996, 1997
 *	The Regents of the University of California.  All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 * 3. All advertising materials mentioning features or use of this software
 *    must display the following acknowledgement:
 *	This product includes software developed by the Computer Systems
 *	Engineering Group at Lawrence Berkeley Laboratory.
 * 4. Neither the name of the University nor of the Laboratory may be used
 *    to endorse or promote products derived from this software without
 *    specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 *
 * @(#) $Header: /usr/cvsroot/winpcap/dox/libpcap/funcs/pcap.h,v 1.17 2003/07/08 11:45:27 fulvio Exp $ (LBL)
 */



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


/** \name Deprecated Functions

	These functions should be avoided because they have been replaced
	with something else.
 */
//\{ 


/*!	\brief It opens a live capture from the network.
\deprecated Use the pcap_open() instead.

  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.  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.   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(char *device, int snaplen, int promisc, int to_ms, char *ebuf);


/*!	\brief It creates a pcap_t structure without starting a capture.
\deprecated Use the pcap_open() instead.

  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 It opens a savefile in the tcpdump/libpcap format to read the packets.
\deprecated Use the pcap_open() instead.

  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.
  errbuf is used to return error text and is only  set  when
  pcap_open_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 <b>Deprecated</b>
\deprecated Use the pcap_findalldevs_ex() instead.

       It returns the list of the interfaces  available on the system.

       pcap_findalldevs() constructs 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 pcap_if_t.

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


/*! 	\brief It returns the first valid device in the system.
\deprecated Use the 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 It returns the subnet and netmask of an interface.
\deprecated Use the 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(char *device, bpf_u_int32 *netp, bpf_u_int32 *maskp, char *errbuf);


//\}
// End of deprecated functions








/** \name Discouraged Functions

	These functions are still valid, but we suggest to avoid their use and replace these calls 
	with something else.
 */
//\{ 

/*!	\brief It collects a group of packets.
\deprecated Use the pcap_next_ex() instead.

       It returns when \b cnt packets have been received 
       or when the timeout set with pcap_open_live() expires.

       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 pointer
       packet data.

       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.

       \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 It collects a group of packets.
\deprecated Use the pcap_next_ex() instead.

       Returns when \b cnt packets have been received, but doesn't respect 
       the timeout set with pcap_open_live(), therefore it can block forever.

       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
       occur s).

\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 It returns the next available packet.
\deprecated Use the pcap_next_ex() instead.

       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 supplied.)

\sa pcap_dispatch(), pcap_loop()
*/

u_char *pcap_next(pcap_t *p, struct pcap_pkthdr *h);


/*! \brief It returns statistics on current capture.
\deprecated Use the pcap_next_ex() instead.

 pcap_stats()  returns  0  and fills in a pcap_stat struct.
 The values represent packet statistics from the  start  of
 the  run  to the time of the call. If there is an error or
 the  underlying  packet  capture  doesn't  support  packet
 statistics,  -1  is  returned  and  the  error text can be
 obtained    with    pcap_perror()    or     pcap_geterr().
 pcap_stats()  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_ex(), pcap_open_live()
*/
int pcap_stats(pcap_t *p, struct pcap_stat *ps);


/*! \brief It returns the stdio stream of an offile capture.
\deprecated Use the pcap_dump() instead.

       pcap_file() returns the standard I/O stream of the "savefile",
	   if    a    "savefile"    was    opened   with
       pcap_open_offline(), or NULL,  if  a  network  device  was
       opened with pcap_open_live().

\sa pcap_open_offline(), pcap_open_live()
*/
FILE *pcap_file(pcap_t *p);


/*!	\brief It returns the file descriptor of a capture device.
\deprecated This function has different behaviours in Unix and Win32.

       pcap_fileno() returns  the  file  descriptor  number  from
       which  captured  packets are read, if a network device was
       opened with pcap_open_live(), or -1, if a "savefile" was
       opened with pcap_open_offline().


\sa pcap_open_offline(), pcap_open_live()
*/
int pcap_fileno(pcap_t *p);

//\}
// End of discouraged functions