Icmp.h File Reference

ICMP API: basic types and functions. More...

#include <windows.h>

Go to the source code of this file.

Classes
struct	IpHeader
	IP Header as defined in RFC 791. More...
struct	IcmpRedirectQuench
	ICMP Redirect quench as defined in RFC 792. More...
struct	IcmpEchoQuench
	ICMP Echo Request or Echo Response quench as defined in RFC 792. More...
union	IcmpQuench
struct	IcmpHeader
	ICMP Message common header content as defined in RFC 792. More...
struct	IcmpRawMessage
	ICMP response data. Referring to ICMP specification, the ICMP response message contains additional data. This data includes IP message header and 16 bytes of IP message data. In this library, response always contains 16 bytes of ICMP message that is IcmpHeader structure. More...
union	IcmpData
	ICMP response data. The data may be at most ICMP_ECHO_MAX_DATA_LEN long. In this library the data content of ICMP message contains either raw data (this may be fetched from buffet field) or structured ICMP raw message (this includes IP message header). More...
struct	IcmpMessage
	ICMP Message as defined in RFC 792. The message contains ICMP header where type of request and request specific attributes (quench) are set and optional message data. More...
struct	IcmpResponseMessage
	ICMP response message. It contains IP header and ICMP message as defined in RFC 792. Such structure is defined because this is the content of ICMP response received from WIN32 raw socket. More...
Defines
#define	IP_PROTOCOL_ICMP   1
#define	ICMP_ECHOREPLY   0
#define	ICMP_DESTINATIONUNREACHABLE   3
#define	ICMP_SOURCEQUENCH   4
#define	ICMP_REDIRECT   5
#define	ICMP_ECHOREQEST   8
#define	ICMP_TIMEEXCEEDED   11
#define	ICMP_PARAMETERPROBLEM   12
#define	IP_HEADER_LEN   20
	The length of IP header expressed in bytes.
#define	ICMP_PAYLOAD_MIN_LEN   8
	The minimum length of ICMP payload message - such message may be followed by additional data.
#define	ICMP_ERROR_MESSAGE_LEN   (IP_HEADER_LEN + ICMP_PAYLOAD_MIN_LEN)
	The length of data attached to ICMP messages in case the ICMP message reports error condition.
#define	IP_MESSAGE_MAX_LEN   0xFFFF
	The maximum size of IP packet.
#define	ICMP_ECHO_MAX_DATA_LEN   (IP_MESSAGE_MAX_LEN - ICMP_PAYLOAD_MIN_LEN - IP_HEADER_LEN)
	The maximum size of ICMP echo data content.
Functions
int	IcmpInitialize (void)
	Initialize ICMP library.
void	IcmpRelease (void)
	Release resources allocated by IcmpInitialize() function.
SOCKET	IcmpCreateSocket (void)
	Create socket for ICMP communictario.
int	IcmpCloseSocket (SOCKET socket)
	Close socket opened by IcmpCreateSocket()
int	IcmpWait (SOCKET socket, long timeout)
	Wait until socket has data to read.
int	IcmpSendEcho (SOCKET socket, const INT8 *destAddress, UINT16 identifier, UINT16 sequenceNumber, void *dataBuffer, size_t dataLength)
	Send ICMP EchoRequest.
int	IcmpReadMessage (SOCKET socket, IcmpResponseMessage *response)
	Read message from socket assuming received message has ICMP structure.
BOOL	IcmpDecodeResponseMessage (const IcmpResponseMessage *message, UINT8 *srcAddress, UINT8 *dstAddress, UINT8 *type, UINT8 *code, UINT16 *identifier, UINT16 *sequenceNumber, void *dataBuffer, size_t dataBuffferLength, size_t *dataLength)
	Decode ICMP response message.
int	IcmpGetSocketError (SOCKET socket)
	Get code of error reported by socket.
int	IcmpGetLastError (void)
	Get WIN32 API error code.
LPTSTR	IcmpGetErrorString (int errorCode)
	Get error string.
void	IcmpReleaseErrorString (LPTSTR errorStr)
	Release string allocated by IcmpGetErrorString function.

---

Detailed Description

ICMP API: basic types and functions.

File contains definitions of data structures and functions sufficient to send ICMP packet, receive response and proper error handling.

---

Function Documentation

int IcmpCloseSocket

(

SOCKET

socket

)

Close socket opened by IcmpCreateSocket()

In order to release system resources this function must be executed for each socket created by IcmpCreateSocket function. It is thread safe an may be run from different thread than socket was created.

Parameters:

socket

socket to be closed

Returns:

SOCKET_ERROR in case of error, other value in success

SOCKET IcmpCreateSocket

(

void

)

Create socket for ICMP communictario.

Create socket in raw mode so it may be used for ICMP communication. Remember to close socket using IcmpCreateSocket() function in order to release system resources.

Returns:

handle to socket od SOCKET_ERROR in case of error

BOOL IcmpDecodeResponseMessage	(	const IcmpResponseMessage *	message,
		UINT8 *	srcAddress,
		UINT8 *	dstAddress,
		UINT8 *	type,
		UINT8 *	code,
		UINT16 *	identifier,
		UINT16 *	sequenceNumber,
		void *	dataBuffer,
		size_t	dataBuffferLength,
		size_t *	dataLength
	)

Decode ICMP response message.

Function takes IcmpResponseMessage and fetches its ICMP attributes. In case message cannot be recognized, the FALSE value is returned.

Parameters:

message	message to be decoded
srcAddress	message sender address
dstAddress	ICMP EchoRequest destination address
type	type of ISMP message
code	the code related to message type (see RFC 791)
identifier	message ID
sequenceNumber	message sequence number
dataBuffer	data buffer to store decoded ICMP EchoResponse data
dataBuffferLength	maximum length of data buffer
dataLength	the real length of received data

Returns:

The return value indicates status of operation. It is TRUE on success or FALSE in case of failure. More detailed operation status may be obtained

LPTSTR IcmpGetErrorString

(

int

errorCode

)

Get error string.

Function returns string describing given error code. String content is handled by Windows Operation System Function allocates resources for returned string so it must be released by IcmpReleaseErrorString function.

Parameters:

errorCode

code of error to be described

Returns:

string describing error code

int IcmpGetLastError

(

void

)

Get WIN32 API error code.

Function returns WIN32 API error code that was set by WIN32 API function.

Returns:

Code of error

int IcmpGetSocketError

(

SOCKET

socket

)

Get code of error reported by socket.

The error code is retrieved from socket using getsockopt function

Parameters:

socket

socket to read error from

Returns:

error code

int IcmpInitialize

(

void

)

Initialize ICMP library.

IcmpSocket Function initializes ICMP library, especially sockets by loading ws2.dll. It returns code of operation that can be found in documentation of Win32 WSAStartup function. In order to release resources allocated by this function, the IcmpRelease() must be executed.

Returns:

code of operation, 0 means success

int IcmpReadMessage	(	SOCKET	socket,
		IcmpResponseMessage *	response
	)

Read message from socket assuming received message has ICMP structure.

Function reads data from raw socket. It is assumed that it is ICMP message, but function does not verify this. Function does not change socket mode (blocking/not blocking) so application must properly handle socket behavior. When function file detailed error code may be obtained by IcmpGetLastError() function.

Parameters:

socket	socket to read message from
response	the message received

Returns:

size of received message or SOCKET_ERROR in case of error

void IcmpReleaseErrorString

(

LPTSTR

errorStr

)

Release string allocated by IcmpGetErrorString function.

Parameters:

errorStr

string allocated by IcmpGetErrorString function

int IcmpSendEcho	(	SOCKET	socket,
		const INT8 *	destAddress,
		UINT16	identifier,
		UINT16	sequenceNumber,
		void *	dataBuffer,
		size_t	dataLength
	)

Send ICMP EchoRequest.

Function sends ICMP echo message to given destination host. The ICMP message is constructed internally and is filled by given identifier, sequenceNumber and data (see IcmpMessage structure) Request is sent asynchronously and function returns code of operation according to WIN32 sendto implementation.

Parameters:

socket	raw socket the message will be sent through
destAddress	address to send message to
identifier	identifier of ICMP message
sequenceNumber	sequence number of ICMP message
dataBuffer	data to be send in ICMP message
dataLength	length of data

Returns:

size of sent message of SOCKET_ERROR in case of error

int IcmpWait	(	SOCKET	socket,
		long	timeout
	)

Wait until socket has data to read.

Function implements behavior of select functionality for receiving data from socket. It waits until some data is ready to read from socket or given timeout occurs.

Parameters:

socket	socket to wait for data
timeout	maximum time (in milliseconds) to wait for data

Returns:

0 on timeout, 1 when data is ready or SOCKET_ERROR in case of error

Remarks:

Function terminates if socket is closed (this may be don in other thread)