tfPingOpenStart

Table of Contents >> Application Reference >> PING API

Note:	The content on this page has been deprecated.
	For the new content, please see tfNgPingOpenStart().

#include <trsocket.h>

int tfPingOpenStart	(
	char * remoteHostNamePtr,
	int pingInterval,
	int pingDataLength,
	ttPingCBFuncPtr pingUserCBFuncPtr
	);

Function Description

This function opens an ICMP socket and starts sending PING echo requests to a remote host as specified by the remoteHostName parameter. PING echo requests are sent every pingInterval seconds. The PING length (not including IP and ICMP headers) is given by the pingDataLength parameter. If the pingUserCBFuncPtr parameter is non-null, the function it points to is called for each received PING echo reply or ICMP error message, with the socket descriptor returned by tfPingOpenStart() passed as a parameter. To get the PING connection results and statistics, the user must call tfPingGetStatistics(). To stop the system from sending PING echo requests and to close the ICMP socket the user must call tfPingClose().

Parameters

• remoteHostNamePtr

  A pointer to a character array containing a dotted decimal IP address.

• pingInterval

  The interval in seconds between PING echo requests. If set to zero, Treck will use the default of 1,000 milliseconds.

• pingDataLength

  User data length of the PING echo request. If set to zero, Treck will use the default of 56 bytes. If set to a value between 1 and 3 Treck will use 4 bytes.

• pingUserCBFuncPtr

  A pointer to a user function to be called upon receiving a network PING echo reply or an ICMP error message with the socket descriptor as returned by tfPingOpenStart() passed as a parameter. This can be set to null if the user does not wish to be notified of incoming PING replies or ICMP error messages associated with this socket.

Example with a non-null function pointer

 
#include <trsocket.h>
 
void tfPingUserCB (int socketDescriptor);
 
...
socketDescriptor =  tfPingOpenStart ("192.168.0.2", 0, 0, tfPingUserCB);
 

Example with a null function pointer

 
#include <trsocket.h>
 
...
socketDescriptor = tfPingOpenStart("127.0.0.1",
                                   0,
                                   0,
                                   (ttPingCBFuncPtr)0);
 

Returns

• > 0

  New socket descriptor.

• TM_SOCKET_ERROR

  Failure

Note:

TM_SOCKET_ERROR means that this socket call has failed and the errorCode has been set on the socket itself. To retrieve the socket error the user must call tfGetSocketError(socketDescriptor).

Possible socket errors

• TM_EINVAL

  One of the following:

• remoteHostNamePtr is 0.
• pingInterval is negative.
• pingDataLength is negative or larger than 65,695 (the maximum value allowed by the IP protocol).

• TM_ENOBUFS

  Insufficient memory to complete the operation.

• TM_EMSGSIZE

  pingDataLength exceeds the socket send queue limit or it exceeds the IP MTU and fragmentation is not allowed.

• TM_EHOSTUNREACH

  No route to destination.

Table of Contents >> Application Reference >> PING API