Ping Client

A Ping Client checks the reachability of a host on IP network. More...

Content
	Enumerations
	Ping Callback Events.

Typedefs
typedef void(*	netPing_cb_t) (netPing_Event event)
	Ping Event callback function.

Functions
netStatus	netPing_Echo (const NET_ADDR *addr, netPing_cb_t cb_func)
	Start ICMP ping process. [thread-safe].
netStatus	netPing_EchoX (const char *target, uint32_t flags)
	Start ICMP ping process in blocking mode. [thread-safe].

Description

A Ping Client checks the reachability of a host on IP network.

The Ping Client is used to test the reachability of a network device on an IP network and to measure the round-trip time for messages sent from the host to a destination node. It operates by sending Internet Control Message Protocol (ICMP) Echo request packets to the target and waiting for an ICMP Echo reply.

Typedef Documentation

netPing_cb_t

void(* netPing_cb_t)(netPing_Event event)

Ping Event callback function.

Parameters

[in]

event

- Ping event as defined in netPing_Event.

Returns

none.

Is the type definition for the Ping callback function. Users must provide the function. The callback function uses the event argument to signal one of the following Ping events:

Event	Description
netPing_EventSuccess	Remote host responded to ping.
netPing_EventTimeout	Ping session has timed out, remote host did not respond.

Parameter for:

• netPing_Echo

Function Documentation

netPing_Echo()

netStatus netPing_Echo	(	const NET_ADDR *	addr,
		netPing_cb_t	cb_func
	)

Start ICMP ping process. [thread-safe].

Parameters

[in]	addr	structure containing IP address of remote host.
[in]	cb_func	callback function to call, when ping session ends.

Returns

status code that indicates the execution status of the function.

The non-blocking function netPing_Echo starts the ping process on the Network Core. This causes the Ping client to send an echo request to the remote IP address. The result of the operation is provided with the callback function.

The argument addr is a pointer to the buffer containing the IP address of the remote host to be pinged.

The argument cb_func points to an event callback function called by the Ping client (running on Network Core) when the ping session ends. Refer to netPing_cb_t.

Possible netStatus return values:

• netOK: Ping client started successfully.
• netInvalidParameter: Invalid parameter provided.
• netBusy: Ping client is busy.

Code Example

static void ping_callback (netPing_Event event);
 
void ping_host (void) {
  const NET_ADDR addr = { NET_ADDR_IP4, 0, 192, 168, 0, 100 };
 
  if (netPing_Echo (&addr, ping_callback) == netOK) {
    printf("Ping started.\n");
  }
  else {
    printf("Ping not ready or bad parameters.\n");
  }
}
 
static void ping_callback (netPing_Event event) {
  switch (event) {
    case netPing_EventSuccess:
      printf ("Remote host responded to ping.\n");
      break;
    case netPing_EventTimeout:
      printf ("Ping timeout, no response.\n");
      break;
  }
}

netPing_EchoX()

netStatus netPing_EchoX	(	const char *	target,
		uint32_t	flags
	)

Start ICMP ping process in blocking mode. [thread-safe].

Parameters

[in]	target	remote hostname or absolute IP address.
[in]	flags	ping process control flags.

Returns

status code that indicates the execution status of the function.

The blocking function netPing_EchoX starts the ping process on the Network Core and returns the result of the operation. This causes the Ping client to send an echo request to the remote IP address and wait for an echo response.

The argument target is a fully qualified domain name or an absolute IP address of the remote host that needs to be pinged. If target is a hostname, the ping client uses the DNS resolver to resolve the destination IP address.

The argument flags specify the IP version to be used for ping. The value of 0 for flags is the use default ping settings.

Flags	Description
NET_PING_IP4_ONLY	Force using IP version 4 only.
NET_PING_IP6_ONLY	Force using IP version 6 only.

Possible netStatus return values:

• netOK: Target host responded ok.
• netInvalidParameter: Invalid or not supported parameter.
• netDnsResolverError: Target name not existing.
• netTimeout: Target host not responding.

Note

To use this function, you must enable the DNS client in the selection of RTE Components.

Code Example (absolute IP address)

if (netPing_EchoX ("192.168.0.100", 0) == netOK) {
  printf ("Target host responded to ping.\n");
}
else {
  printf ("Ping timeout, no response.\n");
}

Code Example (fully qualified domain name)

if (netPing_EchoX ("www.arm.com", 0) == netOK) {
  printf ("Target host responded to ping.\n");
}
else {
  printf ("Ping timeout, no response.\n");
}