ICMP
Classes | Defines | Functions
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:
socketsocket 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:
messagemessage to be decoded
srcAddressmessage sender address
dstAddressICMP EchoRequest destination address
typetype of ISMP message
codethe code related to message type (see RFC 791)
identifiermessage ID
sequenceNumbermessage sequence number
dataBufferdata buffer to store decoded ICMP EchoResponse data
dataBuffferLengthmaximum length of data buffer
dataLengththe 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:
errorCodecode 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:
socketsocket 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:
socketsocket to read message from
responsethe 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:
errorStrstring 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:
socketraw socket the message will be sent through
destAddressaddress to send message to
identifieridentifier of ICMP message
sequenceNumbersequence number of ICMP message
dataBufferdata to be send in ICMP message
dataLengthlength 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:
socketsocket to wait for data
timeoutmaximum 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)
 All Classes Files Functions Variables Defines