# hs.network.ping

This module provides a basic ping function which can test host availability. Ping is a network diagnostic tool commonly found in most operating systems which can be used to test if a route to a specified host exists and if that host is responding to network traffic.

---

# Submodules

• hs.network.ping.echoRequest

---

# API Overview

Constructors - API calls which return an object, typically one that offers API methods

• ping

Methods - API calls which can only be made on an object returned by a constructor

• address
• cancel
• count
• isPaused
• isRunning
• packets
• pause
• resume
• sent
• server
• setCallback
• summary

---

# API Documentation

# Constructors

# ping

| | | | --------------------------------------------|-------------------------------------------------------------------------------------| | Signature | hs.network.ping.ping(server, [count], [interval], [timeout], [class], [fn]) -> pingObject | | Type | Constructor | | Description | Test server availability by pinging it with ICMP Echo Requests. | | Parameters |

• server - a string containing the hostname or ip address of the server to test. Both IPv4 and IPv6 addresses are supported.
• count - an optional integer, default 5, specifying the number of ICMP Echo Requests to send to the server.
• interval - an optional number, default 1.0, in seconds specifying the delay between the sending of each echo request. To set this parameter, you must supply count as well.
• timeout - an optional number, default 2.0, in seconds specifying how long before an echo reply is considered to have timed-out. To set this parameter, you must supply count and interval as well.
• class - an optional string, default "any", specifying whether IPv4 or IPv6 should be used to send the ICMP packets. The string must be one of the following: any - uses the IP version which corresponds to the first address the server resolves to IPv4 - use IPv4; if server cannot resolve to an IPv4 address, or if IPv4 traffic is not supported on the network, the ping will fail with an error. IPv6 - use IPv6; if server cannot resolve to an IPv6 address, or if IPv6 traffic is not supported on the network, the ping will fail with an error.
• fn - the callback function which receives update messages for the ping process. See the Notes for details regarding the callback function.

| | Returns |

• a pingObject

| | Notes |

• For convenience, you can call this constructor as hs.network.ping(server, ...)
• the full ping process will take at most count``interval + timeout seconds from didStart to didFinish.
• the default callback function, if fn is not specified, prints the results of each echo reply as they are received to the Hammerspoon console and a summary once completed. The output should be familiar to anyone who has used ping from the command line.
• If you provide your own callback function, it should expect between 2 and 4 arguments and return none. The possible arguments which are sent will be one of the following:
• "didStart" - indicates that address resolution has completed and the ping will begin sending ICMP Echo Requests.
• object - the ping object the callback is for
• message - the message to the callback, in this case "didStart"
• "didFail" - indicates that the ping process has failed, most likely due to a failure in address resolution or because the network connection has dropped.
• object - the ping object the callback is for
• message - the message to the callback, in this case "didFail"
• error - a string containing the error message that has occurred
• "sendPacketFailed" - indicates that a specific ICMP Echo Request has failed for some reason.
• object - the ping object the callback is for
• message - the message to the callback, in this case "sendPacketFailed"
• sequenceNumber - the sequence number of the ICMP packet which has failed to send
• error - a string containing the error message that has occurred
• "receivedPacket" - indicates that an ICMP Echo Request has received the expected ICMP Echo Reply
• object - the ping object the callback is for
• message - the message to the callback, in this case "receivedPacket"
• sequenceNumber - the sequence number of the ICMP packet received
• "didFinish" - indicates that the ping has finished sending all ICMP Echo Requests or has been cancelled
• object - the ping object the callback is for
• message - the message to the callback, in this case "didFinish"

| | Examples | None | | Source | extensions/network/ping/network_ping.lua line 340 |

---

# Methods

# address

---

# cancel

---

# count

---

# isPaused

---

# isRunning

---

# packets

---

# pause

---

# resume

---

# sent

---

# server

---

# setCallback

---

# summary

---

---