Network Component  Version 7.11.0
MDK Middleware for IPv4 and IPv6 Networking
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
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. More...
 

Functions

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

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

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_EventSuccessRemote host responded to ping.
netPing_EventTimeoutPing session has timed out, remote host did not respond.

Parameter for:

Function Documentation

netStatus netPing_Echo ( const NET_ADDR addr,
netPing_cb_t  cb_func 
)

Start ICMP ping process. [thread-safe].

Parameters
[in]addrstructure containing IP address of remote host.
[in]cb_funccallback 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) {
printf ("Remote host responded to ping.\n");
break;
printf ("Ping timeout, no response.\n");
break;
}
}
netStatus netPing_EchoX ( const char *  target,
uint32_t  flags 
)

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

Parameters
[in]targetremote hostname or absolute IP address.
[in]flagsping 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_ONLYForce using IP version 4 only.
NET_PING_IP6_ONLYForce 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.
  • netBusy: Ping client is busy.
  • netTimeout: Target host not responding.

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");
}