tfNgPingOpenStart

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().


Parameters

  • 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.


Returns

  • TM_SOCKET_ERROR
    Error
  • 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

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


Table of Contents >> IPv6 Programmer's Reference