SOIcmpPing

Syntax

#include <cafe.h>
#include <cafe/network.h>

int SOIcmpPing(int handle, const void* data,
               int len, const struct sockaddr *dest_addr,
               int dest_len, unsigned timeout, int flag);

Parameters

handle Handle to ping from.
data Payload data to send with echo request. If NULL, a default payload will be sent with a size of 58 but the len must be specified as zero.
len Payload data size. Max is ICMP_MAX_PAYLOAD. When payload is NULL, zero must be specified for the len.
dest_addr Destination address. Multicast and broadcast addresses are NOT supported.
dest_len Destination address size. Only sizeof(struct sockaddr_in) is supported.
timeout Time out in milliseconds of how long to wait for ping reply.
flag Unused.

Return Values

Upon success, returns the round-trip time in milliseconds. Upon failure, -1 is returned and errno is set appropriately.

Errors

SO_ELIBNOTREADY Socket library is not initialized.
SO_ENOMEM Insufficient memory in the stack.
SO_EINVAL Invalid parameter passed.
SO_EMSGSIZE Invalid payload size. Max is ICMP_MAX_PAYLOAD
SO_EABORTED Ping was aborted.
SO_EINPROGRESS Ping already in progress. Only one ping per ICMP handle may be pending.
SO_ETIMEDOUT Ping timed out. Did not receive a response within timeout.
SO_ELOWER A lower IP error has occurred.
SO_ENOBUFS Indicates insufficient packet buffers in the network stack. Usually a transient condition and the operation can be retried after a few seconds. If it occurs repeatedly should be treated as a serious error and the corresponding handle should be closed.
SO_EFAULT An abnormal operation occurred in the stack. The corresponding handle should be closed for this type of serious error.
SO_ICMP_EDESTIN Destination unreachable. Either an ICMP destination unreachable packet was received, or the arp entry timed out. Call SOIcmpLastCodeType for details.
SO_ICMP_ESOURCEQ Received an ICMP source quench packet. Call SOIcmpLastCodeType for details.
SO_ICMP_ETIMEX Received an ICMP time exceeded packet. Call SOIcmpLastCodeType for details.
SO_ICMP_ETIMEX Received an ICMP IP header parameter problem packet. Call SOIcmpLastCodeType for details.

Description

Sends an echo request to a destination address and returns the round-trip time if successful.
SOIcmpPing is a blocking call and only one ping may be pending per ICMP handle. You may have more pending pings by creating more ICMP handles and using them on different threads. Only one echo request is sent per call.

For more information, see the ICMP API overview in SOIcmpCreateHandle.

Do Not Call From

Callbacks Do not call this function from any callback function.
Interrupt handler Do not call this function from any interrupt handler.
Exception handler Do not call this function from any exception handler.

See Also

SOIcmpCreateHandle
SOIcmpCloseHandle
SOIcmpCancel
SOIcmpLastCodeType

Revision History

2014/01/24 Initial version.


CONFIDENTIAL