Three calls are provided in the PING Application Program Interface. First, the user calls tfPingOpenStart(). This opens an ICMP socket and sends periodic PING echo request packets. tfPingOpenStart() is passed a pointer to a character array containing a dotted decimal IP address representation of the remote host, the interval in seconds between PING echo requests, the user data length of the PING echo requests, and a pointer to a call back function to be called upon reception of a PING echo reply, or a network ICMP error message. If successful, tfPingOpenStart() returns a socket descriptor.
The system will keep sending PING echo requests from the timer until the user calls tfPingClose(), passing the socket descriptor as returned by tfPingOpenStart() as the parameter. Prior to calling tfPingClose(), the user can call tfPingGetStatistics() to retrieve results and statistics of the PING connection such as number of packets transmitted, number of packets received, round trip time of the last PING echo request, error code as given by a received network ICMP error message, etc.. The user passes the socket descriptor returned by tfPingOpenStart() as the first parameter to tfPingGetStatistics(), and a pointer to a ttPingInfo structure as the second parameter, where the system will copy the results and statistics of the PING connection if the tfPingGetStatistics() returns with no error. The user can be notified of incoming PING echo replies or incoming ICMP error messages if he specifies a non-null call back function pointer as the last parameter to tfPingOpenStart(). In that case, the call back function is called every time a PING echo reply or an ICMP error message is received. The call back function takes one parameter: the socket descriptor as returned by the tfPingOpenStart(). The user can then retrieve the PING connection information by calling tfPingGetStatistics().