Jump to: navigation, search

Table of Contents >> IPv6 Programmer's Reference

#include <trsocket.h>

int tfNgPingOpenStart (
const struct sockaddr_storage * remoteAddrPtr,
ttUser32Bit 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 remoteAddrPtr parameter. PING echo requests are sent every pingInterval milliseconds. 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 re-quests and to close the ICMP socket, the user must call tfPingClose().


  • remoteAddrPtr
    Remote IPv4 or IPv6 address to gather ICMP statistics from.
  • pingInterval
    Interval in milliseconds at which to retry sending a Ping packet (if 0, use default of 1 second).
  • pingDataLength
    User Data length of the PING echo request. If set to zero, defaults to 56bytes. If set to a value between 1, and 3, defaults to 4 bytes.
  • pingUserCBFuncPtr
    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. Can be set to null function pointer if the user does not wish to be notified of incoming network traffic.


  • other
    New ICMP socket descriptor

Note 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

    remoteHostNamePtr was a null pointer
    pingInterval was negative
    pingDataLength was negative of bigger than 65595, maximum value allowed by the IP protocol.
    There was insufficient user memory available to complete the operation.
    pingDataLength exceeds socket send queue limit, orpingDataLength exceeds the IPMTU, and fragmentation is not allowed.
    No route to remote host

Table of Contents >> IPv6 Programmer's Reference