- * This function checks whether the header of the received message is correct.
- *
- * It 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 that occurs.
- *
- * \param errbuf: a pointer to a user-allocated buffer (of size
- * PCAP_ERRBUF_SIZE) that will contain the error message (in case there
- * is one). It could either be a problem that occurred inside this function
- * (e.g. a network problem in case it tries to send an error to our peer
- * and the send() call fails), an error message thathas been sent to us
- * from the other party, or a version error (the message received has a
- * version number that is incompatible with ours).
- *
- * \param 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 ours. In that case, all the message
- * is purged from the socket, so that the following recv() calls will
- * return a new message.
- *
- * \param 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.
- *
- * \param 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.
- *
- * \return 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 follows that
- * the RPCAP_MSG_ERROR could not be present in the allowed message-types
- * list, because 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.