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

# Internal Functions
[Remote Capture]

## Functions
void | sock_geterror (const char *caller, char *string, int size)
| It retrieves the error message after an error occurred in the socket interface.
int | sock_init (char *errbuf)
| It initializes sockets.
void | sock_cleanup ()
| It deallocates sockets.
int | sock_ismcastaddr (const struct sockaddr *saddr)
| It checks if the sockaddr variable contains a multicast address.
int | sock_open (struct addrinfo *addrinfo, int server, int nconn, char *errbuf)
| It initializes a network connection both from the client and the server side.
int | sock_close (SOCKET sock, char *errbuf)
| Closes the present (TCP and UDP) socket connection.
int | sock_validaddr (const char *address, const char *port, struct addrinfo *hints, struct addrinfo **addrinfo, char *errbuf)
| Checks that the address, port and flags given are valids and it returns an 'addrinfo' stucture.
int | sock_send (SOCKET socket, const char *buffer, int size, char *errbuf)
| It sends the amount of data contained into 'buffer' on the given socket.
int | sock_bufferize (const char *buffer, int size, char *tempbuf, int *offset, int totsize, int checkonly, char *errbuf)
| It copies the amount of data contained into 'buffer' into 'tempbuf'. and it checks for buffer overflows.
int | sock_recv (SOCKET socket, char *buffer, int size, char *errbuf)
| It waits on a connected socket and it manages to receive exactly 'size' bytes.
int | sock_recv_dgram (SOCKET sock, char *buffer, int size, char *errbuf)
| It waits on a connected socket and it manages to receive one message.
int | sock_discard (SOCKET socket, int size, char *errbuf)
| It discards N bytes that are currently waiting to be read on the current socket.
int | sock_check_hostlist (char *hostlist, const char *sep, struct sockaddr_storage *from, char *errbuf)
| Checks that one host (identified by the sockaddr_storage structure) belongs to an 'allowed list'.
int | sock_cmpaddr (struct sockaddr_storage *first, struct sockaddr_storage *second)
| Compares two addresses contained into two sockaddr_storage structures.
int | rpcap_deseraddr (struct sockaddr_storage *sockaddrin, struct sockaddr_storage **sockaddrout, char *errbuf)
| It traslates (i.e. de-serializes) a 'sockaddr_storage' structure from the network byte order to the host byte order.
int | pcap_read_nocb_remote (pcap_t *p, struct pcap_pkthdr **pkt_header, u_char **pkt_data)
| It reads a packet from the network socket. This does not make used of callback (hence the "nocb" string into its name).
int | pcap_read_remote (pcap_t *p, int cnt, pcap_handler callback, u_char *user)
| It reads a packet from the network socket.
void | pcap_close_remote (pcap_t *p)
| It sends a CLOSE command to the capture server.
int | pcap_stats_remote (pcap_t *p, struct pcap_stat *ps)
| It retrieves network statistics from the other peer.
pcap_stat * | pcap_stats_ex_remote (pcap_t *p)
| It retrieves network statistics from the other peer.
pcap_stat * | rpcap_stats_remote (pcap_t *p, struct pcap_stat *ps, int mode)
| It retrieves network statistics from the other peer.
pcap_t * | pcap_opensource_remote (const char *source, struct pcap_rmtauth *auth, char *errbuf)
| It opens a remote adapter by opening an RPCAP connection and so on.
int | pcap_startcapture_remote (pcap_t *fp)
| It starts a remote capture.
int | pcap_updatefilter_remote (pcap_t *fp, struct bpf_program *prog)
| Update a filter on a remote host.
int | pcap_setfilter_remote (pcap_t *fp, struct bpf_program *prog)
| Send a filter to a remote host.
void | pthread_suspend (int msec)
| Suspends a pthread for msec milliseconds.
void | rpcap_thrdatamain_stream (void *ptr)
| Main function of the thread which waits for data packets (i.e. packets which carry a captured packet) in case of a TCP data connection.
void | rpcap_thrdatamain_dgram (void *ptr)
| Main function of the thread which waits for data packets (i.e. packets which carry a captured packet) in case of a UDP data connection.
int | rpcap_senderror (SOCKET sock, char *error, unsigned short errcode, char *errbuf)
| It sends a RPCAP error to the other peer.
int | rpcap_sendauth (SOCKET sock, struct pcap_rmtauth *auth, char *errbuf)
| Sends the authentication message.
void | rpcap_createhdr (struct rpcap_header *header, uint8 type, uint16 value, uint32 length)
| Creates a structure of type rpcap_header.
int | rpcap_checkmsg (char *errbuf, SOCKET sock, struct rpcap_header *header, uint8 first,...)
| Checks if the header of the received message is correct.
int | rpcap_checkver (SOCKET sock, struct rpcap_header *header, char *errbuf)
| Checks if the version contained into the message is compatible with the one handled by this implementation.
int | rpcap_remoteact_getsock (const char *host, char *errbuf)
| It returns the socket currently used for this active connection (active mode only).

## Function Documentation

void pcap_close_remote | ( | pcap_t * | fp | ) |

| It sends a CLOSE command to the capture server. This function is called when the user wants to close a pcap_t adapter. In case we're capturing from the network, it sends a command to the other peer that says 'ok, let's stop capturing'. This function is called automatically when the user calls the pcap_close(). Parameters and return values are exactly the same of the pcap_close(). Warning: Since we're closing the connection, we do not check for errors. Definition at line 300 of file pcap-remote.c. References activeHosts, activehosts::next, rpcap_createhdr(), sock_cleanup(), sock_close(), sock_discard(), sock_recv(), sock_send(), and activehosts::sockctrl. Referenced by pcap_close().

pcap_t* pcap_opensource_remote | ( | const char * | source,
|  | struct pcap_rmtauth * | auth,
|  | char * | errbuf
| ) |

  | It opens a remote adapter by opening an RPCAP connection and so on. This function does basically the job of pcap_open_live() for a remote interface. In other words, we have a pcap_read for win32, which reads packets from NPF, another for LINUX, and so on. Now, we have a pcap_opensource_remote() as well. The difference, here, is the capture thread does not start until the pcap_startcapture_remote() is called. This is because, in remote capture, we cannot start capturing data as soon ad the 'open adapter' command is sent. Suppose the remote adapter is already overloaded; if we start a capture (which, by default, has a NULL filter) the new traffic can saturate the network. Instead, we want to "open" the adapter, then send a "start capture" command only when we're ready to start the capture. This funtion does this job: it sends a "open adapter" command (according to the RPCAP protocol), but it does not start the capture. Since the other libpcap functions do not share this way of life, we have to make some dirty things in order to make everyting working. Parameters:
  source: | see pcap_open().
  auth: | see pcap_open().
  errbuf: | a pointer to a user-allocated buffer (of size PCAP_ERRBUF_SIZE) that will contain the error message (in case there is one). It could be either a network problem, an RPCAP problem (e.g. authentication failed), and more.
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: In case we call the pcap_compile() and the capture is not started, the filter will be saved into the pcap_t structure, and it will be sent to the other host later (when the pcap_startcapture_remote() is called). Definition at line 554 of file pcap-remote.c. References host, PCAP_BUF_SIZE, pcap_close(), pcap_parsesrcstr(), PCAP_SRC_IFREMOTE, pcap_strerror(), pcap_t, rpcap_checkmsg(), rpcap_createhdr(), RPCAP_MSG_ERROR, RPCAP_MSG_OPEN_REPLY, RPCAP_NETBUF_SIZE, rpcap_remoteact_getsock(), rpcap_sendauth(), snprintf, sock_bufferize(), sock_close(), sock_discard(), sock_init(), sock_open(), sock_recv(), sock_send(), sock_validaddr(), and SOCKET. Referenced by pcap_open(), and pcap_open_live().

int pcap_read_nocb_remote | ( | pcap_t * | p,
|  | struct pcap_pkthdr ** | pkt_header,
|  | u_char ** | pkt_data
| ) |

| It reads a packet from the network socket. This does not make used of callback (hence the "nocb" string into its name). This function is called by the several pcap_next_ex() when they detect that we have a remote capture and they are the client side. In that case, they need to read packets from the socket. Parameters and return values are exactly the same of the pcap_next_ex(). Warning: By choice, this function does not make use of semaphores. A smarter implementation should put a semaphore into the data thread, and a signal will be raised as soon as there is data into the socket buffer. However this is complicated and it does not bring any advantages when reading from the network, in which network delays can be much more important than these optimizations. Therefore, we chose the following approach: the 'timeout' chosen by the user is split in two (half on the server side, with the usual meaning, and half on the client side) this function checks for packets; if there are no packets, it waits for timeout/2 and then it checks again. If packets are still missing, it returns, otherwise it reads packets. Definition at line 203 of file pcap-remote.c. References pthread_suspend(). Referenced by pcap_next_ex(), and pcap_read_remote().

int pcap_read_remote | ( | pcap_t * | p,
|  | int | cnt,
|  | pcap_handler | callback,
|  | u_char * | user
| ) |

| It reads a packet from the network socket. This function is called by the several pcap_read() when they detect that we have a remote capture and they are the client side. In that case, they need to read packets from the socket. This function relies on the pcap_read_nocb_remote to deliver packets. The difference, here, is that as soon as a packet is read, it is delivered to the application by means of a callback function. Parameters and return values are exactly the same of the pcap_read(). Definition at line 270 of file pcap-remote.c. References n, and pcap_read_nocb_remote(). Referenced by pcap_read().

int pcap_setfilter_remote | ( | pcap_t * | fp,
|  | struct bpf_program * | prog
| ) |

| Send a filter to a remote host. This function is called when the user wants to set a filter. In case we're capturing from the network, it sends the filter to the other peer. This function is called automatically when the user calls the pcap_setfilter(). Parameters and return values are exactly the same of the pcap_setfilter(). Definition at line 1228 of file pcap-remote.c. References pcap_updatefilter_remote(). Referenced by pcap_setfilter().

int pcap_startcapture_remote | ( | pcap_t * | fp | ) |

  | It starts a remote capture. This function is requires since the RPCAP protocol decouples the 'open' from the 'start capture' functions. This function takes all the parameters needed (which have been stored into the pcap_t structure) and sends them to the server. If everything is fine, it creates a new child thread that reads data from the network and puts data it into the user buffer. The pcap_read() will read data from the user buffer, as usual. The remote capture acts like a new "kernel", which puts packets directly into the buffer pointed by pcap_t. In fact, this function does not rely on a kernel that reads packets and put them into the user buffer; it has to do that on its own. Parameters:
  fp: | the pcap_t descriptor of the device currently open.
Returns: '0' if everything is fine, '-1' otherwise. The error message (if one) is returned into the 'errbuf' field of the pcap_t structure. Definition at line 761 of file pcap-remote.c. References activeHosts, rpcap_startcapreq::flags, host, activehosts::next, PCAP_BUF_SIZE, pcap_close(), PCAP_OPENFLAG_PROMISCUOUS, PCAP_OPENFLAG_UDP_DP, pcap_pack_bpffilter(), pcap_strerror(), rpcap_startcapreq::portdata, rpcap_startcapreq::read_timeout, rpcap_checkmsg(), rpcap_createhdr(), RPCAP_MSG_ERROR, RPCAP_MSG_STARTCAP_REPLY, RPCAP_NETBUF_SIZE, RPCAP_STARTCAPREQ_FLAG_DGRAM, RPCAP_STARTCAPREQ_FLAG_PROMISC, RPCAP_STARTCAPREQ_FLAG_SERVEROPEN, rpcap_startcapreq::snaplen, snprintf, sock_bufferize(), sock_close(), sock_discard(), sock_geterror(), sock_open(), sock_recv(), sock_send(), sock_validaddr(), and SOCKET. Referenced by pcap_next_ex(), and pcap_read().

struct pcap_stat* pcap_stats_ex_remote | ( | pcap_t * | p | ) |

| It retrieves network statistics from the other peer. This function is just a void cointainer, since the work is done by the rpcap_stats_remote(). See that funcion for more details. Parameters and return values are exactly the same of the pcap_stats_ex(). Definition at line 396 of file pcap-remote.c. References pcap_stats_ex_remote(), pcap_t, and rpcap_stats_remote(). Referenced by pcap_stats_ex(), and pcap_stats_ex_remote().

int pcap_stats_remote | ( | pcap_t * | p,
|  | struct pcap_stat * | ps
| ) |

| It retrieves network statistics from the other peer. This function is just a void cointainer, since the work is done by the rpcap_stats_remote(). See that funcion for more details. Parameters and return values are exactly the same of the pcap_stats(). Definition at line 373 of file pcap-remote.c. References rpcap_stats_remote(). Referenced by pcap_stats().

int pcap_updatefilter_remote | ( | pcap_t * | fp,
|  | struct bpf_program * | prog
| ) |

| Update a filter on a remote host. This function is called when the user wants to update a filter. In case we're capturing from the network, it sends the filter to the other peer. This function is *not* called automatically when the user calls the pcap_setfilter(). There will be two cases: the capture is already on: in this case, pcap_setfilter() calls pcap_updatefilter_remote() the capture has not started yet: in this case, pcap_setfilter() stores the filter into the pcap_t structure, and then the filter is sent with the pcap_startcap(). Parameters and return values are exactly the same of the pcap_setfilter(). Warning: This function *does not* clear the packet currently into the buffers. Therefore, the user has to expect to receive some packets that are related to the previous filter. If you want to discard all the packets before applying a new filter, you have to close the current capture session and start a new one. Definition at line 1161 of file pcap-remote.c. References bpf_program::bf_len, pcap_pack_bpffilter(), rpcap_checkmsg(), rpcap_createhdr(), RPCAP_MSG_UPDATEFILTER_REPLY, RPCAP_NETBUF_SIZE, SOCK_ASSERT, sock_bufferize(), sock_discard(), sock_recv(), and sock_send(). Referenced by pcap_setfilter_remote().

void pthread_suspend | ( | int | msec | ) |

| Suspends a pthread for msec milliseconds. This fucntion is provided since pthreads do not have a suspend() call. Definition at line 1252 of file pcap-remote.c. Referenced by daemon_serviceloop(), main_active(), main_startup(), pcap_read_nocb_remote(), rpcap_thrdatamain_dgram(), and rpcap_thrdatamain_stream().

int rpcap_checkmsg | ( | char * | errbuf,
|  | SOCKET | sock,
|  | struct rpcap_header * | header,
|  | uint8 | first,
|  | ... |
| ) |

  | Checks if the header of the received message is correct. This function is a way to easily check if the message received, in a certain state of the RPCAP protocol Finite State Machine, is valid. This function accepts, as a parameter, the list of message types that are allowed in a certain situation, and it returns the one which occurs. Parameters:
  errbuf: | a pointer to a user-allocated buffer (of size PCAP_ERRBUF_SIZE) that will contain the error message (in case there is one). It could be either problem occurred inside this function (e.g. a network problem in case it tries to send an error on the other peer and the send() call fails), an error message which has been sent to us from the other party, or a version error (the message receive has a version number that is incompabile with our).
  sock: | the socket that has to be used to receive data. This function can read data from socket in case the version contained into the message is not compatible with our. In that case, all the message is purged from the socket, so that the following recv() calls will return a new message.
  header: | a pointer to and 'rpcap_header' structure that keeps the data received from the network (still in network byte order) and that has to be checked.
  first: | this function has a variable number of parameters. From this point on, all the messages that are valid in this context must be passed as parameters. The message type list must be terminated with a '0' value, the null message type, which means 'no more types to check'. The RPCAP protocol does not define anything with message type equal to zero, so there is no ambiguity in using this value as a list terminator.
Returns: The message type of the message that has been detected. In case of errors (e.g. the header contains a type that is not listed among the allowed types), this function will return the following codes: (-1) if the version is incompatible. (-2) if the code is not among the one listed into the parameters list (-3) if a network error (connection reset, ...) RPCAP_MSG_ERROR if the message is an error message (it follow that the RPCAP_MSG_ERROR could not be present in the allowed message-types list, beucase this function checks for errors anyway) In case either the version is incompatible or nothing matches (i.e. it returns '-1' or '-2'), it discards the message body (i.e. it reads the remaining part of the message from the network and it discards it) so that the application is ready to receive a new message. Definition at line 1945 of file pcap-remote.c. References errbuf, int32, PCAP_ERRBUF_SIZE, rpcap_header::plen, rpcap_checkver(), RPCAP_MSG_ERROR, snprintf, SOCK_ASSERT, sock_discard(), sock_recv(), rpcap_header::type, and uint8. Referenced by daemon_checkauth(), daemon_serviceloop(), pcap_findalldevs_ex(), pcap_opensource_remote(), pcap_startcapture_remote(), pcap_updatefilter_remote(), rpcap_sendauth(), rpcap_stats_remote(), rpcap_thrdatamain_dgram(), and rpcap_thrdatamain_stream().

int rpcap_checkver | ( | SOCKET | sock,
|  | struct rpcap_header * | header,
|  | char * | errbuf
| ) |

  | Checks if the version contained into the message is compatible with the one handled by this implementation. Right now, this function does not have any sophisticated task: if the versions are different, it returns -1 and it discards the message. It is expected that in the future this message will become more complex. Parameters:
  sock: | the socket that has to be used to receive data. This function can read data from socket in case the version contained into the message is not compatible with our. In that case, all the message is purged from the socket, so that the following recv() calls will return a new (clean) message.
  header: | a pointer to and 'rpcap_header' structure that keeps the data received from the network (still in network byte order) and that has to be checked.
  errbuf: | a pointer to a user-allocated buffer (of size PCAP_ERRBUF_SIZE) that will contain the error message (in case there is one). The error message is "incompatible version".
Returns: '0' if everything is fine, '-1' if some errors occurred. The error message is returned in the 'errbuf' variable. Definition at line 2043 of file pcap-remote.c. References rpcap_header::plen, RPCAP_VERSION, snprintf, sock_discard(), and rpcap_header::ver. Referenced by rpcap_checkmsg().

void rpcap_createhdr | ( | struct rpcap_header * | header,
|  | uint8 | type,
|  | uint16 | value,
|  | uint32 | length
| ) |

  | Creates a structure of type rpcap_header. This function is provided just because the creation of an rpcap header is quite a common task. It accepts all the values that appears into an rpcap_header, and it puts them in place using the proper hton() calls. Parameters:
  header: | a pointer to a user-allocated buffer which will contain the serialized header, ready to be sent on the network.
  type: | a value (in the host by order) which will be placed into the header.type field and that represents the type of the current message.
  value: | a value (in the host by order) which will be placed into the header.value field and that has a message-dependent meaning.
  length: | a value (in the host by order) which will be placed into the header.length field and that represents the payload length of the message.
Returns: Nothing. The serialized header is returned into the 'header' variable. Definition at line 1890 of file pcap-remote.c. References rpcap_header::plen, RPCAP_VERSION, rpcap_header::type, rpcap_header::value, and rpcap_header::ver. Referenced by daemon_checkauth(), daemon_endcapture(), daemon_findalldevs(), daemon_getstats(), daemon_getstatsnopcap(), daemon_opensource(), daemon_startcapture(), daemon_thrdatamain(), daemon_updatefilter(), pcap_close_remote(), pcap_findalldevs_ex(), pcap_opensource_remote(), pcap_remoteact_close(), pcap_startcapture_remote(), pcap_updatefilter_remote(), rpcap_sendauth(), rpcap_senderror(), and rpcap_stats_remote().

int rpcap_deseraddr | ( | struct sockaddr_storage * | sockaddrin,
|  | struct sockaddr_storage ** | sockaddrout,
|  | char * | errbuf
| ) |

  | It traslates (i.e. de-serializes) a 'sockaddr_storage' structure from the network byte order to the host byte order. It accepts a 'sockaddr_storage' structure as it is received from the network and it converts it into the host byte order (by means of a set of ntoh() ). The function will allocate the 'sockaddrout' variable according to the address family in use. In case the address does not belong to the AF_INET nor AF_INET6 families, 'sockaddrout' is not allocated and a NULL pointer is returned. This usually happens because that address does not exist on the other host, so the RPCAP daemon sent a 'sockaddr_storage' structure containing all 'zero' values. Parameters:
  sockaddrin: | a 'sockaddr_storage' pointer to the variable that has to be de-serialized.
  sockaddrout: | a 'sockaddr_storage' pointer to the variable that will contain the de-serialized data. The structure returned can be either a 'sockaddr_in' or 'sockaddr_in6'. This variable will be allocated automatically inside this function.
  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. Basically, the error can be only the fact that the malloc() failed to allocate memory. The error message is returned in the 'errbuf' variable, while the deserialized address is returned into the 'sockaddrout' variable. Warning: This function supports only AF_INET and AF_INET6 address families. The sockaddrout (if not NULL) must be deallocated by the user. Definition at line 133 of file pcap-remote.c. References pcap_strerror(), and snprintf. Referenced by pcap_findalldevs_ex().

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

  | It returns the socket currently used for this active connection (active mode only). This function is just for internal use; it returns the socket ID of the active connection currently opened. Parameters:
  host: | a string that keeps the host name of the host for which we want to get the socket ID for that 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: the socket identifier if everything is fine, '0' if this host is not in the active host list. It returns '-1' in case of error. The error message is returned into the errbuf variable. Warning: Win32: be carefully not to assign the returning value of this call to a SOCKET directly. It should lead to wrong results, since Win32 sockets are unsigned int; therefore a negative value could not be handled correctly. Definition at line 2086 of file pcap-remote.c. References activeHosts, activehosts::host, activehosts::next, snprintf, sock_cmpaddr(), and activehosts::sockctrl. Referenced by pcap_findalldevs_ex(), and pcap_opensource_remote().

int rpcap_sendauth | ( | SOCKET | sock,
|  | struct pcap_rmtauth * | auth,
|  | char * | errbuf
| ) |

  | Sends the authentication message. It sends the authentication parameters on the control socket. Ths function is required in order to open the connection with the other end party. Parameters:
  sock: | the socket we are currently using.
  auth: | authentication parameters that have to be sent.
  errbuf: | a pointer to a user-allocated buffer (of size PCAP_ERRBUF_SIZE) that will contain the error message (in case there is one). It could be network problem ot the fact that the authorization failed.
Returns: '0' if everything is fine, '-1' if some errors occurred. The error message is returned in the 'errbuf' variable. The error message could be also 'the authentication failed'. Definition at line 1752 of file pcap-remote.c. References pcap_rmtauth::password, rpcap_checkmsg(), rpcap_createhdr(), RPCAP_MSG_AUTH_REPLY, RPCAP_MSG_ERROR, RPCAP_NETBUF_SIZE, RPCAP_RMTAUTH_NULL, RPCAP_RMTAUTH_PWD, rpcap_auth::slen1, rpcap_auth::slen2, snprintf, SOCK_ASSERT, sock_bufferize(), sock_discard(), sock_recv(), sock_send(), pcap_rmtauth::type, rpcap_auth::type, uint16, and pcap_rmtauth::username. Referenced by pcap_findalldevs_ex(), pcap_opensource_remote(), and pcap_remoteact_accept().

int rpcap_senderror | ( | SOCKET | sock,
|  | char * | error,
|  | unsigned short | errcode,
|  | char * | errbuf
| ) |

  | It sends a RPCAP error to the other peer. This function has to be called when the main program detects an error. This funcion will send on the other peer the 'buffer' specified by the user. This function *does not* request a RPCAP CLOSE connection. A CLOSE command must be sent explicitely by the program, since we do not know it the error can be recovered in some way or it is a non-recoverable one. Parameters:
  sock: | the socket we are currently using.
  error: | an user-allocated (and '0' termined) buffer that contains the error description thas has to be transmitted on the other peer. The error message cannot be longer than PCAP_ERRBUF_SIZE.
  errcode: | a integer which tells the other party the type of error we had; currently is is not too much used.
  errbuf: | a pointer to a user-allocated buffer (of size PCAP_ERRBUF_SIZE) that will contain the error message (in case there is one). It could be network problem.
Returns: '0' if everything is fine, '-1' if some errors occurred. The error message is returned in the 'errbuf' variable. Definition at line 1707 of file pcap-remote.c. References PCAP_ERRBUF_SIZE, rpcap_createhdr(), RPCAP_NETBUF_SIZE, sock_bufferize(), sock_send(), and uint16. Referenced by daemon_findalldevs(), daemon_getstats(), daemon_getstatsnopcap(), daemon_opensource(), daemon_serviceloop(), daemon_startcapture(), daemon_thrdatamain(), daemon_updatefilter(), main_passive(), and pcap_remoteact_accept().

struct pcap_stat * rpcap_stats_remote | ( | pcap_t * | p,
|  | struct pcap_stat * | ps,
|  | int | mode
| ) |

  | It retrieves network statistics from the other peer. This function can be called in two modes: PCAP_STATS_STANDARD: if we want just standard statistics (i.e. the pcap_stats() ) PCAP_STATS_EX: if we want extended statistics (i.e. the pcap_stats_ex() ) This 'mode' parameter is needed because in the standard pcap_stats() the variable that keeps the statistics is allocated by the user. Unfortunately, this structure has been extended in order to keep new stats. However, if the user has a smaller structure and it passes it to the pcap_stats, thid function will try to fill in more data than the size of the structure, so that the application goes in memory overflow. So, we need to know it we have to copy just the standard fields, or the extended fields as well. In case we want to copy the extended fields as well, the problem of memory overflow does no longer exist because the structure pcap_stat is no longer allocated by the program; it is allocated by the library instead. Parameters:
  p: | the pcap_t structure related to the current instance.
  ps: | a 'pcap_stat' structure, needed for compatibility with pcap_stat(), in which the structure is allocated by the user. In case of pcap_stats_ex, this structure and the function return value point to the same variable.
  mode: | one of PCAP_STATS_STANDARD or PCAP_STATS_EX.
Returns: The structure that keeps the statistics, or NULL in case of error. The error string is placed in the pcap_t structure. Definition at line 434 of file pcap-remote.c. References PCAP_STATS_STANDARD, pcap_t, pcap_stat::ps_drop, pcap_stat::ps_ifdrop, pcap_stat::ps_recv, rpcap_checkmsg(), rpcap_createhdr(), RPCAP_MSG_ERROR, RPCAP_MSG_STATS_REPLY, rpcap_stats_remote(), snprintf, sock_discard(), sock_recv(), and sock_send(). Referenced by pcap_stats_ex_remote(), pcap_stats_remote(), and rpcap_stats_remote().

void rpcap_thrdatamain_dgram | ( | void * | ptr | ) |

  | Main function of the thread which waits for data packets (i.e. packets which carry a captured packet) in case of a UDP data connection. This function does basically the job of the Operating System kernel in the local capture: it takes packet and it puts them into the user buffer. This function is different from the rpcap_thrdatamain_stream(), because UDP requires that a message coming from the network is received using a single recv() call. Vice versa, TCP sockets allows you reading only a few bytes each time, and the remaining part of the message is retained. From this point of view, UDP sockets makes this thread more epensive, because the message is first copied into a temporary buffer (allocated by the thread itself), then, if the WinPcap/libpcap user buffer has enough space, the data is copied into that buffer. Parameters:
  ptr: | it is a void pointer that will be casted into a pcap_t structure. This parameter is needed to retrieve the the socket (i.e. sockdata) we are currently using for the data connection, the control socket (in case we want to send error messages), and so on.
Returns: Nothing. Definition at line 1514 of file pcap-remote.c. References pcap_pkthdr::caplen, rpcap_pkthdr::caplen, errbuf, rpcap_pkthdr::len, pcap_pkthdr::len, rpcap_pkthdr::npkt, PCAP_ERRBUF_SIZE, pcap_t, pthread_suspend(), rpcap_checkmsg(), RPCAP_MSG_PACKET, RPCAP_NETBUF_SIZE, SOCK_ASSERT, sock_geterror(), sock_recv_dgram(), rpcap_pkthdr::timestamp_sec, rpcap_pkthdr::timestamp_usec, and pcap_pkthdr::ts.

void rpcap_thrdatamain_stream | ( | void * | ptr | ) |

  | Main function of the thread which waits for data packets (i.e. packets which carry a captured packet) in case of a TCP data connection. This function does basically the job of the Operating System kernel in the local capture: it takes packets and it puts them into the user buffer. Parameters:
  ptr: | it is a void pointer that will be casted into a pcap_t structure. This parameter is needed to retrieve the the socket (i.e. sockdata) we are currently using for the data connection, the control socket (in case we want to send error messages), and so on.
Returns: Nothing. Definition at line 1298 of file pcap-remote.c. References pcap_pkthdr::caplen, rpcap_pkthdr::caplen, errbuf, rpcap_pkthdr::len, pcap_pkthdr::len, PCAP_ERRBUF_SIZE, pcap_t, rpcap_header::plen, pthread_suspend(), rpcap_checkmsg(), RPCAP_MSG_PACKET, SOCK_ASSERT, sock_discard(), sock_geterror(), sock_recv(), rpcap_pkthdr::timestamp_sec, rpcap_pkthdr::timestamp_usec, and pcap_pkthdr::ts.

int sock_bufferize | ( | const char * | buffer,
|  | int | size,
|  | char * | tempbuf,
|  | int * | offset,
|  | int | totsize,
|  | int | checkonly,
|  | char * | errbuf
| ) |

  | It copies the amount of data contained into 'buffer' into 'tempbuf'. and it checks for buffer overflows. This function basically copies 'size' bytes of data contained into 'buffer' into 'tempbuf', starting at offset 'offset'. Before that, it checks that the resulting buffer will not be larger than 'totsize'. Finally, it updates the 'offset' variable in order to point to the first empty location of the buffer. In case the function is called with 'checkonly' equal to 1, it does not copy the data into the buffer. It only checks for buffer overflows and it updates the 'offset' variable. This mode can be useful when the buffer already contains the data (maybe because the producer writes directly into the target buffer), so only the buffer overflow check has to be made. In this case, both 'buffer' and 'tempbuf' can be NULL values. Parameters:
  buffer: | a char pointer to a user-allocated buffer that keeps the data that has to be copied.
  size: | number of bytes that have to be copied.
  tempbuf: | user-allocated buffer (of size 'totsize') in which data has to be copied.
  offset: | an index into 'tempbuf' which keeps the location of its first empty location.
  totsize: | total size of the buffer in which data is being copied.
  checkonly: | '1' if we do not want to copy data into the buffer and we want just do a buffer ovreflow control, '0' if data has to be copied as well.
  errbuf: | a pointer to a user-allocated buffer (of size SOCK_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 in the 'errbuf' variable. When the function returns, 'tempbuf' will have the new string appended, and 'offset' will keep the length of that buffer. In case of 'checkonly == 1', data is not copied, but 'offset' is updated in any case. Warning: This function assumes that the buffer in which data has to be stored is large 'totbuf' bytes. In case of 'checkonly', be carefully to call this function *before* copying the data into the buffer. Otherwise, the control about the buffer overflow is useless. Definition at line 524 of file sockutils.c. References offset, size, and snprintf. Referenced by daemon_findalldevs(), daemon_getstats(), daemon_getstatsnopcap(), daemon_opensource(), daemon_startcapture(), daemon_thrdatamain(), pcap_opensource_remote(), pcap_pack_bpffilter(), pcap_startcapture_remote(), pcap_updatefilter_remote(), rpcap_sendauth(), and rpcap_senderror().

int sock_check_hostlist | ( | char * | hostlist,
|  | const char * | sep,
|  | struct sockaddr_storage * | from,
|  | char * | errbuf
| ) |

  | Checks that one host (identified by the sockaddr_storage structure) belongs to an 'allowed list'. This function is useful after an accept() call in order to check if the connecting host is allowed to connect to me. To do that, we have a buffer that keeps the list of the allowed host; this function checks the sockaddr_storage structure of the connecting host against this host list, and it returns '0' is the host is included in this list. Parameters:
  hostlist: | a string that contains the list of the allowed host.
  sep: | a string that keeps the separators used between the hosts (for example the space character) in the host list.
  from: | a sockaddr_storage structure, as it is returned by the accept() call.
  errbuf: | a pointer to a user-allocated buffer (of size SOCK_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 in the 'errbuf' variable. Definition at line 726 of file sockutils.c. References hostlist, snprintf, SOCK_ASSERT, sock_cmpaddr(), and sock_geterror(). Referenced by main_passive(), and pcap_remoteact_accept().

void sock_cleanup | ( |  | ) |

| It deallocates sockets. This function is pretty useless on UNIX, since socket deallocation is not required. However it is required on Win32. In UNIX, this function appears to be completely empty. Returns: No error values. Definition at line 192 of file sockutils.c. References sockcount. Referenced by main_cleanup(), pcap_close_remote(), pcap_findalldevs_ex(), pcap_remoteact_cleanup(), and pcap_remoteact_close().

int sock_close | ( | SOCKET | sock,
|  | char * | errbuf
| ) |

  | Closes the present (TCP and UDP) socket connection. This function sends a shutdown() on the socket in order to disable send() calls (while recv() ones are still allowed). Then, it closes the socket. Parameters:
  sock: | the socket identifier of the connection that has to be closed.
  errbuf: | a pointer to a user-allocated buffer (of size SOCK_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 in the 'errbuf' variable. Definition at line 334 of file sockutils.c. References sock_geterror(). Referenced by daemon_endcapture(), daemon_serviceloop(), daemon_startcapture(), main_passive(), pcap_close_remote(), pcap_findalldevs_ex(), pcap_opensource_remote(), pcap_remoteact_accept(), pcap_remoteact_close(), and pcap_startcapture_remote().

int sock_cmpaddr | ( | struct sockaddr_storage * | first,
|  | struct sockaddr_storage * | second
| ) |

  | Compares two addresses contained into two sockaddr_storage structures. This function is useful to compare two addresses, given their internal representation, i.e. an sockaddr_storage structure. The two structures do not need to be sockaddr_storage; you can have both 'sockaddr_in' and sockaddr_in6, properly acsted in order to be compliant to the function interface. This function will return '0' if the two addresses matches, '-1' if not. Parameters:
  first: | a sockaddr_storage structure, (for example the one that is returned by an accept() call), containing the first address to compare.
  second: | a sockaddr_storage structure containing the second address to compare.
Returns: '0' if the addresses are equal, '-1' if they are different. Definition at line 823 of file sockutils.c. Referenced by pcap_remoteact_accept(), pcap_remoteact_close(), rpcap_remoteact_getsock(), and sock_check_hostlist().

int sock_discard | ( | SOCKET | sock,
|  | int | size,
|  | char * | errbuf
| ) |

  | It discards N bytes that are currently waiting to be read on the current socket. This function is useful in case we receive a message we cannot undestand (e.g. wrong version number when receiving a network packet), so that we have to discard all data before reading a new message. This function will read 'size' bytes from the socket and discard them. It defines an internal buffer in which data will be copied; however, in case this buffer is not large enough, it will cycle in order to read everything as well. Parameters:
  sock: | the connected socket currently opened.
  size: | number of bytes that have to be discarded.
  errbuf: | a pointer to a user-allocated buffer (of size SOCK_ERRBUF_SIZE) that will contain the error message (in case there is one), due to a network problem.
Returns: '0' if everything is fine, '-1' if some errors occurred. The error message is returned in the 'errbuf' variable. Definition at line 672 of file sockutils.c. References size, SOCK_ASSERT, and sock_recv(). Referenced by daemon_checkauth(), daemon_opensource(), daemon_serviceloop(), daemon_startcapture(), daemon_updatefilter(), pcap_close_remote(), pcap_findalldevs_ex(), pcap_opensource_remote(), pcap_startcapture_remote(), pcap_updatefilter_remote(), rpcap_checkmsg(), rpcap_checkver(), rpcap_sendauth(), rpcap_stats_remote(), and rpcap_thrdatamain_stream().

void sock_geterror | ( | const char * | caller,
|  | char * | string,
|  | int | size
| ) |

  | It retrieves the error message after an error occurred in the socket interface. This function is defined because of the different way errors are returned in UNIX and Win32. This function provides a consistent way to retrieve the error message (after a socket error occurred) on all the platforms. Parameters:
  caller: | a pointer to a user-allocated string which contains a message that has to be printed *before* the true error message. It could be, for example, 'this error comes from the recv() call at line 31'.
  string: | a pointer to an user-allocated buffer that will contain the complete error message. This buffer has to be at least 'size' in length.
  size: | the size of the buffer in which the error message will be copied.
Returns: No return values. The error message is returned in the 'string' parameter. Definition at line 116 of file sockutils.c. References snprintf, and SOCK_ERRBUF_SIZE. Referenced by daemon_serviceloop(), daemon_startcapture(), main_passive(), pcap_remoteact_accept(), pcap_remoteact_list(), pcap_startcapture_remote(), rpcap_thrdatamain_dgram(), rpcap_thrdatamain_stream(), sock_check_hostlist(), sock_close(), sock_open(), sock_recv(), sock_recv_dgram(), and sock_send().

int sock_init | ( | char * | errbuf | ) |

  | It initializes sockets. This function is pretty useless on UNIX, since socket initialization is not required. However it is required on Win32. In UNIX, this function appears to be completely empty. Parameters:
  errbuf: | a pointer to a user-allocated buffer (of size SOCK_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 in the 'errbuf' variable. Definition at line 160 of file sockutils.c. References snprintf, and sockcount. Referenced by main(), pcap_findalldevs_ex(), pcap_opensource_remote(), and pcap_remoteact_accept().

int sock_ismcastaddr | ( | const struct sockaddr * | saddr | ) |

| It checks if the sockaddr variable contains a multicast address. Returns: '0' if the address is multicast, '-1' if it is not. Definition at line 208 of file sockutils.c. Referenced by sock_validaddr().

int sock_open | ( | struct addrinfo * | addrinfo,
|  | int | server,
|  | int | nconn,
|  | char * | errbuf
| ) |

  | It initializes a network connection both from the client and the server side. In case of a client socket, this function calls socket() and connect(). In the meanwhile, it checks for any socket error. If an error occurs, it writes the error message into 'errbuf'. In case of a server socket, the function calls socket(), bind() and listen(). In no cases this fucntion will authenticate the user on the remote host. This function has to be done in the rpcap_sendauth(). Parameters:
  addrinfo: | pointer to an addrinfo variable which will be used to open the socket and such. This variable is the one returned by the previous call to sockvalidateaddr().
  server: | '1' if this is a server socket, '0' otherwise.
  nconn: | number of the connections that are allowed to wait into the listen() call. This value has no meanings in case of a client socket.
  errbuf: | a pointer to a user-allocated buffer (of size SOCK_ERRBUF_SIZE) that will contain the error message (in case there is one).
Returns: the socket that has been opened (that has to be used in the following sockets calls) if everything is fine, '-1' if some errors occurred. The error message is returned in the 'errbuf' variable. Definition at line 254 of file sockutils.c. References snprintf, sock_geterror(), and SOCKET. Referenced by daemon_startcapture(), main_active(), main_startup(), pcap_findalldevs_ex(), pcap_opensource_remote(), pcap_remoteact_accept(), and pcap_startcapture_remote().

int sock_recv | ( | SOCKET | sock,
|  | char * | buffer,
|  | int | size,
|  | char * | errbuf
| ) |

  | It waits on a connected socket and it manages to receive exactly 'size' bytes. This function basically calls the recv() socket function and it checks that no error occurred. If that happens, it writes the error message into 'errbuf'. In case the socket does not have enough data available, it cycles on the recv() util the requested data (of size 'size') is arrived. Parameters:
  sock: | the connected socket currently opened.
  buffer: | a char pointer to a user-allocated buffer in which data has to be stored
  size: | size of the allocated buffer. WARNING: this indicates the number of bytes that we are expecting to be read. This function (differenctly from the rpcap_recv_dgram() ) block until the number of bytes read is equal to 'size'.
  errbuf: | a pointer to a user-allocated buffer (of size SOCK_ERRBUF_SIZE) that will contain the error message (in case there is one), due to a network problem.
Returns: the number of bytes read if everything is fine, '-1' if some errors occurred. The error message is returned in the 'errbuf' variable. Definition at line 566 of file sockutils.c. References size, snprintf, SOCK_ASSERT, and sock_geterror(). Referenced by daemon_checkauth(), daemon_opensource(), daemon_serviceloop(), daemon_startcapture(), daemon_unpackapplyfilter(), pcap_close_remote(), pcap_findalldevs_ex(), pcap_opensource_remote(), pcap_startcapture_remote(), pcap_updatefilter_remote(), rpcap_checkmsg(), rpcap_sendauth(), rpcap_stats_remote(), rpcap_thrdatamain_stream(), and sock_discard().

int sock_recv_dgram | ( | SOCKET | sock,
|  | char * | buffer,
|  | int | size,
|  | char * | errbuf
| ) |

  | It waits on a connected socket and it manages to receive one message. There is a difference here between this function and the sock_recv(): the previous one will loop until 'size' bytes are read (i.e. until a message with the expected size has arrived); here just one recv() is done, and all what is waiting in the socket bufer is read all at once. This function is required for UDP sockets, in which the message has to be read all at once, otherwise it is discarded. Therefore we have to call this function with a large buffer, in order to be sure no data is lost. It follow that the number of bytes received is usually less than the size buffer: therefore we must exit anyway, even if the number of bytes read is less than the size of the buffer. Parameters:
  sock: | the connected socket currently opened.
  buffer: | a char pointer to a user-allocated buffer in which data has to be stored.
  size: | size of the allocated buffer. WARNING: this indicates the maximum number of bytes that we can read. This function (differenctly from the rpcap_recv_dgram() ) does not block if the number of bytes read is equal to 'size'.
  errbuf: | a pointer to a user-allocated buffer (of size SOCK_ERRBUF_SIZE) that will contain the error message (in case there is one), due to a network problem.
Returns: the number of bytes read if everything is fine, '-1' if some errors occurred. The error message is returned in the 'errbuf' variable. Definition at line 635 of file sockutils.c. References sock_geterror(). Referenced by rpcap_thrdatamain_dgram().

int sock_send | ( | SOCKET | socket,
|  | const char * | buffer,
|  | int | size,
|  | char * | errbuf
| ) |

  | It sends the amount of data contained into 'buffer' on the given socket. This function basically calls the send() socket function and it checks that all the data specified in 'buffer' (of size 'size') will be sent. If an error occurs, it writes the error message into 'errbuf'. In case the socket buffer does not have enough space, it loops until all data has been sent. Parameters:
  socket: | the connected socket currently opened.
  buffer: | a char pointer to a user-allocated buffer in which data is contained.
  size: | number of bytes that have to be sent.
  errbuf: | a pointer to a user-allocated buffer (of size SOCK_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 in the 'errbuf' variable. Definition at line 443 of file sockutils.c. References size, and sock_geterror(). Referenced by daemon_checkauth(), daemon_endcapture(), daemon_findalldevs(), daemon_getstats(), daemon_getstatsnopcap(), daemon_opensource(), daemon_startcapture(), daemon_thrdatamain(), daemon_updatefilter(), pcap_close_remote(), pcap_findalldevs_ex(), pcap_opensource_remote(), pcap_remoteact_close(), pcap_startcapture_remote(), pcap_updatefilter_remote(), rpcap_sendauth(), rpcap_senderror(), and rpcap_stats_remote().

int sock_validaddr | ( | const char * | address,
|  | const char * | port,
|  | struct addrinfo * | hints,
|  | struct addrinfo ** | addrinfo,
|  | char * | errbuf
| ) |

  | Checks that the address, port and flags given are valids and it returns an 'addrinfo' stucture. This function basically calls the getaddrinfo() calls, and it performs a set of sanity checks to control that everything is fine (e.g. a TCP socket cannot have a mcast address, and such). If an error occurs, it writes the error message into 'errbuf'. Parameters:
  address: | a pointer to a user-allocated buffer containing the network address to check. It could be both a numeric - literal address, and it can be NULL or "" (useful in case of a server socket which has to bind to all addresses).
  port: | a pointer to a user-allocated buffer containing the network port to use.
  hints: | an addrinfo variable (passed by reference) containing the flags needed to create the addrinfo structure appropriately.
  addrinfo: | it represents the true returning value. This is a pointer to an addrinfo variable (passed by reference), which will be allocated by this function and returned back to the caller. This variable will be used in the next sockets calls.
  errbuf: | a pointer to a user-allocated buffer (of size SOCK_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 in the 'errbuf' variable. The addrinfo variable that has to be used in the following sockets calls is returned into the addrinfo parameter. Warning: The 'addrinfo' variable has to be deleted by the programmer by calling freeaddrinfo() when it is no longer needed. SOCKET: I should check all the accept() in order to bind to all addresses (in case addrinfo has more han one pointers, and all connect() to use all addresses (in the case the firs one fails) Definition at line 386 of file sockutils.c. References snprintf, and sock_ismcastaddr(). Referenced by daemon_startcapture(), main_active(), main_startup(), pcap_findalldevs_ex(), pcap_opensource_remote(), pcap_remoteact_accept(), and pcap_startcapture_remote().

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