Main Page Modules Data Structures File List Data Fields Globals Related Pages

# Exported Functions
[Remote Capture]

## Functions
int | pcap_findalldevs_ex (char *host, char *port, SOCKET sockctrl, struct pcap_rmtauth *auth, pcap_if_t **alldevs, char *errbuf)
| It creates a list of network devices that can be opened with pcap_open().
int | pcap_createsrcstr (char *source, int type, const char *host, const char *port, const char *name, char *errbuf)
| Accepts 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').
int | pcap_parsesrcstr (const char *source, int *type, char *host, char *port, char *name, char *errbuf)
| Parses the source string and returns the pieces in which the source can be split.
pcap_t * | pcap_open (const char *source, int snaplen, int flags, int read_timeout, struct pcap_rmtauth *auth, char *errbuf)
| It opens a generic source in order to capture / send (WinPcap only) traffic.
int | pcap_remoteact_accept (const char *address, const char *port, const char *hostlist, char *connectinghost, struct pcap_rmtauth *auth, char *errbuf)
| It blocks until a network connection is accepted (active mode only).
int | pcap_remoteact_close (const char *host, char *errbuf)
| It drops an active connection (active mode only).
void | pcap_remoteact_cleanup ()
| Cleans the socket that is currently used in waiting active connections.
int | pcap_remoteact_list (char *hostlist, char sep, int size, char *errbuf)
| Returns the hostname of the host that have an active connection with us (active mode only).

## Function Documentation

int pcap_createsrcstr | ( | char * | source,
|  | int | type,
|  | const char * | host,
|  | const char * | port,
|  | const char * | name,
|  | char * | errbuf
| ) |

  | Accepts 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 to create 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. Parameters:
  source: | a user-allocated buffer that will contain the complete source string wen the function returns. This function assumes that the allocated buffer is at least PCAP_BUF_SIZE bytes.
  type: | its value tells the type of the source we want to create. It can assume the following values: PCAP_SRC_FILE: if we want a local file PCAP_SRC_IFLOCAL: if we want a local interface PCAP_SRC_IFREMOTE: if we want a remote interface
  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.
  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.
  name: | an user-allocated buffer that keeps the interface name we want to use (e.g. "eth0").
  errbuf: | a pointer to a user-allocated buffer (of size PCAP_ERRBUF_SIZE) that will contain the error message (in case there is one).
Returns: '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. Definition at line 495 of file pcap-new.c. References PCAP_SRC_FILE, PCAP_SRC_IFLOCAL, PCAP_SRC_IFREMOTE, and snprintf.

int pcap_findalldevs_ex | ( | char * | host,
|  | char * | port,
|  | SOCKET | sockctrl,
|  | struct pcap_rmtauth * | auth,
|  | pcap_if_t ** | alldevs,
|  | char * | errbuf
| ) |

  | It creates 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. 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 (see the 'sockctrl' parameters for more details). In the same way, if we're in active mode and the connection is already opened, it uses the existing socket. This function can rely on the pcap_createsrcstr() to create the string that keeps the capture device according to the new syntax, and the pcap_parsesrcstr() for the other way round. Parameters:
  host: | a char* buffer that keeps the address of the remote host on which we want to see the interface list. It can be NULL: in this case the function queries the local host for the locally installed interfaces. The address can be both numeric (e.g. '10.11.12.13', '1:2:3::4') and literal (e.g. 'foo.bar.com').
  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.
  sockctrl: | Socket to be used for the control connection. This parameter is meaningful only if the control connection is already open when the pcap_findalldevs() is called. This can be the case in which the 'ative' mode is used, in which the capturing machine opens a control connection toward the client in order to bypass in-middle firewalls. In that case, the control connection is already open, and we have to use this one instead of opening a new one.
  In case this parameter is non-zero, the 'host' and 'port' parameters are meaningless: the software will always try to retrieve the network adapters using this control connection, despite the value assumed by 'host' and 'port'. In case this parameter is non-zero, the socket is not closed at the end of the function and it remains open for future use. Parameters:
  port: | a char* buffer (e.g. "2003") that keeps the network port on which we want to connect to. It can be NULL: in this case the function uses the standard port, defined in RPCAP_DEFAULT_NETPORT.
  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'.
  errbuf: | a pointer to a user-allocated buffer (of size PCAP_ERRBUF_SIZE) that will contain the error message (in case there is one).
Returns: '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 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. The interface list must be deallocated manually by using the pcap_freealldevs(). Definition at line 150 of file pcap-new.c. References pcap_addr::addr, pcap_addr::broadaddr, pcap_addr::dstaddr, host, rpcap_findalldevs_if::namelen, pcap_addr::netmask, pcap_addr::next, pcap_findalldevs(), pcap_strerror(), port, rpcap_checkmsg(), rpcap_createhdr(), rpcap_deseraddr(), RPCAP_MSG_ERROR, RPCAP_MSG_FINDALLIF_REPLY, rpcap_remoteact_getsock(), rpcap_sendauth(), snprintf, sock_cleanup(), sock_close(), sock_discard(), sock_init(), sock_open(), sock_recv(), sock_send(), and sock_validaddr().

pcap_t* pcap_open | ( | const char * | source,
|  | int | snaplen,
|  | int | flags,
|  | int | read_timeout,
|  | struct pcap_rmtauth * | auth,
|  | char * | errbuf
| ) |

  | It opens a generic source in order to capture / send (WinPcap only) traffic. The pcap_open() replaces all the pcap_open_xxx() functions with a single call. This function hides the differences between the different pcap_open_xxx() functions so that the programmer does not have to manage different opening function. In this way, the 'true' open function is decided according to the source type, which is included into the source string (in the form of source prefix). This function can rely on the pcap_createsrcstr() to create the string that keeps the capture device according to the new syntax, and the pcap_parsesrcstr() for the other way round. Parameters:
  source: | zero-terminated string containing the source name to open. The source name has to include the format prefix according to the syntax proposed by WinPcap. It cannot be NULL. On on Linux systems with 2.2 or later kernels, a device argument of "any" (i.e. rpcap://any) can be used to capture packets from all interfaces. In case the pcap_createsrcstr() is not used, remember that the new source syntax allows for these formats to be used in the pcap_open(): file://filename [we want to open a local file] rpcap://host.foo.bar/adaptername [everything literal, no port number] rpcap://host.foo.bar:1234/adaptername [everything literal, with port number] rpcap://10.11.12.13/adaptername [IPv4 numeric, no port number] rpcap://10.11.12.13:1234/adaptername [IPv4 numeric, with port number] rpcap://[10.11.12.13]:1234/adaptername [IPv4 numeric with IPv6 format, with port number] rpcap://[1:2:3::4]/adaptername [IPv6 numeric, no port number] rpcap://[1:2:3::4]:1234/adaptername [IPv6 numeric, with port number] rpcap://adaptername [local adapter, opened without using the RPCAP protocol] adaptername [to open a local adapter; kept for compability, but it is strongly discouraged] (NULL) [to open the first local adapter; kept for compability, but it is strongly discouraged]
  The following formats are not allowed: rpcap:// [to open the first local adapter] rpcap://hostname/ [to open the first remote adapter] Parameters:
  snaplen: | length of the packet that has to be retained. For each packet received by the filter, only the first 'snaplen' bytes are stored in the buffer and passed to the user application. For instance, snaplen equal to 100 means that only the first 100 bytes of each packet are stored.
  flags: | keeps several flags that can be needed for capturing packets. The allowed flags are the following: PCAP_OPENFLAG_PROMISCUOUS: if the adapter has to go in promiscuous mode. It is '1' if you have to open the adapter in promiscuous mode, '0' otherwise. Note that even if this parameter is false, the interface could well be in promiscuous mode for some other reason (for example because another capture process with promiscuous mode enabled is currently using that interface). On on Linux systems with 2.2 or later kernels (that have the "any" device), this flag does not work on the "any" device; if an argument of "any" is supplied, the 'promisc' flag is ignored. PCAP_OPENFLAG_SERVEROPEN_DP: it specifies who is responsible for opening the data connection in case of a remote capture (it means 'server open data path'). If it is '1', it specifies if the data connection has to be intitiated by the capturing device (which becomes like 'active'). If '0', the connection will be initiated by the client workstation. This flag is used to overcome the problem of firewalls, which allow only outgoing connections. In that case, the capturing device can open a connection toward the client workstation in order to allow the data trasfer. In fact, the data connection is opened using a random port (while the control connection uses a standard port), so it is hard to configure a firewall to permit traffic on the data path. This flag is meaningless if the source is not a remote interface. Addictionally, it is meaningless if the data connection is done using the UDP protocol, since in this case the connection wil always be opened by the server. In these cases, it is simply ignored. PCAP_OPENFLAG_UDP_DP: it specifies if the data trasfer (in case of a remote capture) has to be done with UDP protocol. If it is '1' if you want a UDP data connection, '0' if you want a TCP data connection; control connection is always TCP-based. A UDP connection is much lighter, but it does not guarantee that all the captured packets arrive to the client workstation. Moreover, it could be harmful in case of network congestion. This flag is meaningless if the source is not a remote interface. In that case, it is simply ignored.
  read_timeout: | 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 waits 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.
  auth: | a pointer to a 'struct pcap_rmtauth' that keeps the information required to authenticate the user on a remote machine. In case this is not a remote capture, this pointer can be set to NULL.
  errbuf: | a pointer to a user-allocated buffer which will contain the error in case this function fails. The pcap_open() and findalldevs() are the only two functions which have this parameter, since they do not have (yet) a pointer to a pcap_t structure, which reserves space for the error string. Since these functions do not have (yet) a pcap_t pointer (the pcap_t pointer is NULL in case of errors), they need an explicit 'errbuf' variable. '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.
Returns: A pointer to a 'pcap_t' which can be used as a parameter to the following calls (pcap_compile() and so on) and that specifies an opened WinPcap session. In case of problems, it returns NULL and the 'errbuf' variable keeps the error message. Warning: The source cannot be larger than PCAP_BUF_SIZE. Definition at line 881 of file pcap-new.c. References host, PCAP_BUF_SIZE, pcap_open_live(), pcap_open_offline(), pcap_opensource_remote(), pcap_parsesrcstr(), PCAP_SRC_FILE, PCAP_SRC_IFLOCAL, PCAP_SRC_IFREMOTE, pcap_t, port, and snprintf. Referenced by daemon_opensource(), and daemon_startcapture().

int pcap_parsesrcstr | ( | const char * | source,
|  | int * | type,
|  | char * | host,
|  | char * | port,
|  | char * | name,
|  | char * | errbuf
| ) |

  | Parses 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_KEY 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. Parameters:
  source: | a null-terminated string containing the WinPcap source
  type: | pointer to an integer, which is used to return the code corrisponding to the selected source. The code will be one of the following: PCAP_SRC_FILE PCAP_SRC_IFLOCAL PCAP_SRC_IFREMOTE In case the source string does not exists (i.e. 'source == NULL') or it is empty ('*source == NULL'), it returns PCAP_SRC_IF_LOCAL (i.e. you are ready to call pcap_open_live() ). This behavior is kept only for compatibility with older applications (e.g. tcpdump); therefore we suggest to move to the new syntax for sources.
  This parameter can be NULL in case the user is not interested in that. Parameters:
  host: | user-allocated buffer (of size PCAP_BUF_SIZE) that is used to return the host name on which the capture has to be started. This value is meaningful only in case of remote capture; otherwise, the returned string will be empty (""). This parameter can be NULL in case the user is not interested in that.
  port: | user-allocated buffer (of size PCAP_BUF_SIZE) that is used to return the port that has to be used by the RPCAP protocol to contact the other host. This value is meaningful only in case of remote capture and if the user wants to use a non-standard port; otherwise, the returned string will be empty (""). In case of remote capture, an emply string means "use the standard RPCAP port". This parameter can be NULL in case the user is not interested in that.
  name: | user-allocated buffer (of size PCAP_BUF_SIZE) that is used to return the source name, without the source prefix. If the name does not exist (for example because source contains 'rpcap://' that means 'default local adapter'), it returns NULL. This parameter can be NULL in case the user is not interested in that.
  errbuf: | pointer to a user-allocated buffer (of size PCAP_ERRBUF_SIZE) that will contain the error message (in case there is one). This parameter can be NULL in case the user is not interested in that.
Returns: '0' if everything is fine, '-1' if some errors occurred. The requested values (host name, network port, type of the source) are returned into the proper variables passed by reference. Definition at line 636 of file pcap-new.c. References host, PCAP_BUF_SIZE, PCAP_SRC_FILE, PCAP_SRC_IFLOCAL, PCAP_SRC_IFREMOTE, port, and snprintf. Referenced by pcap_open(), pcap_open_live(), and pcap_opensource_remote().

int pcap_remoteact_accept | ( | const char * | address,
|  | const char * | port,
|  | const char * | hostlist,
|  | char * | connectinghost,
|  | struct pcap_rmtauth * | auth,
|  | char * | errbuf
| ) |

  | It blocks until a network connection is accepted (active mode only). This function has been defined to allow the client dealing with the 'active mode'. In other words, in the 'active mode' the server opens the connection toward the client, so that the client has to open a socket in order to wait for connections. When a new connection is accepted, the RPCAP protocol starts as usual; the only difference is that the connection is initiated by the server. This function accepts only ONE connection, then it closes the waiting socket. This means that if some error occurs, the application has to call it again in order to accept another connection. This function returns when a new connection (coming from a valid host 'connectinghost') is accepted; it returns error otherwise. Parameters:
  address: | a string that keeps the network address we have to bind to; usually it is NULL (it means 'bind on all local addresses').
  port: | a string that keeps the network port on which we have to bind to; usually it is NULL (it means 'bind on the predefined port', i.e. RPCAP_DEFAULT_NETPORT_ACTIVE).
  hostlist: | a string that keeps the host name of the host from whom we are expecting a connection; it can be NULL (it means 'accept connection from everyone'). Host names are separated by a whatever character in the RPCAP_HOSTLIST_SEP list.
  connectinghost: | a user-allocated buffer that will contain the name of the host is trying to connect to us. This variable must be at least RPCAP_HOSTLIST_SIZE bytes..
  auth: | a pointer to a pcap_rmtauth structure. This pointer keeps the information required to authenticate the RPCAP connection to the remote host.
  errbuf: | a pointer to a user-allocated buffer (of size PCAP_ERRBUF_SIZE) that will contain the error message (in case there is one).
Returns: The SOCKET identifier of the new control connection if everything is fine, a negative number if some errors occurred. The error message is returned into the errbuf variable. In case it returns '-1', this means 'everything is fine', but the host cannot be admitted. In case it returns '-2', in means 'unrecoverable error' (for example it is not able to bind the socket, or something like that). In case it returns '-3', it means 'authentication failed'. The authentication check is performed only if the connecting host is among the ones that are allowed to connect to this host. The host that is connecting to us is returned into the hostlist variable, which ust be allocated by the user. This variable contains the host name both in case the host is allowed, and in case the connection is refused. Warning: Although this function returns the socket established by the new control connection, this value should not be used. This value will be stored into some libpcap internal variables and it will be managed automatically by the library. In other words, all the following calls to findalldevs() and pcap_open() will check if the host is among one that already has a control connection in place; if so, that one will be used. This function has several problems if used inside a thread, which is stopped when this call is blocked into the accept(). In this case, the socket on which we accept connections is not freed (thread termination is a very dirty job), so that we are no longer able to accept other connections until the program (i.e. the process) stops. In order to solve the problem, call the pcap_remoteact_cleanup(). Definition at line 996 of file pcap-new.c. References activeHosts, activehosts::host, hostlist, activehosts::next, pcap_strerror(), port, rpcap_sendauth(), rpcap_senderror(), snprintf, SOCK_ASSERT, sock_check_hostlist(), sock_close(), sock_cmpaddr(), sock_geterror(), sock_init(), sock_open(), sock_validaddr(), activehosts::sockctrl, SOCKET, and sockmain.

void pcap_remoteact_cleanup | ( |  | ) |

| Cleans the socket that is currently used in waiting active connections. This function does a very dirty job. The fact is that is the waiting socket is not freed if the pcap_remoteaccept() is killed inside a new thread. This function is able to clean the socket in order to allow the next calls to pcap_remoteact_accept() to work. This function is useful *only* if you launch pcap_remoteact_accept() inside a new thread, and you stops (not very gracefully) the thread (for example because the user changed idea, and it does no longer want to wait for an active connection). So, basically, the flow should be the following: launch a new thread call the pcap_remoteact_accept if this new thread is killed, call pcap_remoteact_cleanup(). This function has no effects in other cases. Returns: None. Definition at line 1249 of file pcap-new.c. References sock_cleanup().

int pcap_remoteact_close | ( | const char * | host,
|  | char * | errbuf
| ) |

  | It drops an active connection (active mode only). This function has been defined to allow the client dealing with the 'active mode'. This function closes an active connection that is still in place and it purges the host name from the 'activeHost' list. From this point on, the client will not have any connection with that host in place. Parameters:
  host: | a string that keeps the host name of the host for which we want to close the active connection.
  errbuf: | a pointer to a user-allocated buffer (of size PCAP_ERRBUF_SIZE) that will contain the error message (in case there is one).
Returns: '0' if everything is fine, '-1' if some errors occurred. The error message is returned into the errbuf variable. Definition at line 1153 of file pcap-new.c. References activeHosts, activehosts::host, activehosts::next, rpcap_createhdr(), snprintf, sock_cleanup(), sock_close(), sock_cmpaddr(), sock_send(), and activehosts::sockctrl.

int pcap_remoteact_list | ( | char * | hostlist,
|  | char | sep,
|  | int | size,
|  | char * | errbuf
| ) |

  | Returns the hostname of the host that have an active connection with us (active mode only). This function has been defined to allow the client dealing with the 'active mode'. This function returns the list of hosts that are currently having an active connection with us. This function is useful in order to delete an active connection that is still in place. Parameters:
  hostlist: | a user-allocated string that will keep the list of host that are currently connected with us.
  sep: | the character that has to be sued as a separator between the hosts (',' for example).
  size: | size of the hostlist buffer.
  errbuf: | a pointer to a user-allocated buffer (of size PCAP_ERRBUF_SIZE) that will contain the error message (in case there is one).
Returns: '0' if everything is fine, '-1' if some errors occurred. The error message is returned into the errbuf variable. Definition at line 1285 of file pcap-new.c. References activeHosts, activehosts::host, hostlist, activehosts::next, RPCAP_HOSTLIST_SIZE, size, snprintf, and sock_geterror().

documentation. Copyright (c) 2002-2003 Politecnico di Torino. All rights reserved.