#hs.network.host

This sub-module provides functions for acquiring host information, such as hostnames, addresses, and reachability.

#API Overview

Functions - API calls offered directly by the extension

addressesForHostname
hostnamesForAddress
reachabilityForAddress
reachabilityForHostname

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

cancel
isRunning

#API Documentation

#Functions

#addressesForHostname


Signature	`hs.network.host.addressesForHostname(name[, fn]) -> table \| hostObject`
Type	Function
Description	Get IP addresses for the hostname specified.
Parameters	name - the hostname to lookup IP addresses for fn - an optional callback function which, when provided, will perform the address resolution in an asynchronous, non-blocking manner.
Returns	If this function is called without a callback function, returns a table containing the IP addresses for the specified name. If a callback function is specified, then a host object is returned.
Notes	If no callback function is provided, the resolution occurs in a blocking manner which may be noticeable when network access is slow or erratic. If a callback function is provided, this function acts as a constructor, returning a host object and the callback function will be invoked when resolution is complete. The callback function should take two parameters: the string "addresses", indicating that an address resolution occurred, and a table containing the IP addresses identified. Generates an error if network access is currently disabled or the hostname is invalid.
Examples	None
Source	extensions/network/libnetwork_host.m line 268

#hostnamesForAddress


Signature	`hs.network.host.hostnamesForAddress(address[, fn]) -> table \| hostObject`
Type	Function
Description	Get hostnames for the IP address specified.
Parameters	address - a string or number representing an IPv4 or IPv6 network address to lookup hostnames for. If the argument is a number, it is treated as the 32 bit numerical representation of an IPv4 address. fn - an optional callback function which, when provided, will perform the hostname resolution in an asynchronous, non-blocking manner.
Returns	If this function is called without a callback function, returns a table containing the hostnames for the specified address. If a callback function is specified, then a host object is returned.
Notes	If no callback function is provided, the resolution occurs in a blocking manner which may be noticeable when network access is slow or erratic. If a callback function is provided, this function acts as a constructor, returning a host object and the callback function will be invoked when resolution is complete. The callback function should take two parameters: the string "names", indicating that hostname resolution occurred, and a table containing the hostnames identified. Generates an error if network access is currently disabled or the IP address is invalid.
Examples	None
Source	extensions/network/libnetwork_host.m line 287

#reachabilityForAddress


Signature	`hs.network.host.reachabilityForAddress(address[, fn]) -> integer \| hostObject`
Type	Function
Description	Get the reachability status for the IP address specified.
Parameters	address - a string or number representing an IPv4 or IPv6 network address to check the reachability for. If the argument is a number, it is treated as the 32 bit numerical representation of an IPv4 address. fn - an optional callback function which, when provided, will determine the address reachability in an asynchronous, non-blocking manner.
Returns	If this function is called without a callback function, returns the numeric representation of the address reachability status. If a callback function is specified, then a host object is returned.
Notes	If no callback function is provided, the resolution occurs in a blocking manner which may be noticeable when network access is slow or erratic. If a callback function is provided, this function acts as a constructor, returning a host object and the callback function will be invoked when resolution is complete. The callback function should take two parameters: the string "reachability", indicating that reachability was determined, and the numeric representation of the address reachability status. Generates an error if network access is currently disabled or the IP address is invalid. The numeric representation is made up from a combination of the flags defined in `hs.network.reachability.flags`. Performs the same reachability test as `hs.network.reachability.forAddress`.
Examples	None
Source	extensions/network/libnetwork_host.m line 306

#reachabilityForHostname


Signature	`hs.network.host.reachabilityForHostname(name[, fn]) -> integer \| hostObject`
Type	Function
Description	Get the reachability status for the IP address specified.
Parameters	name - the hostname to check the reachability for. If the argument is a number, it is treated as the 32 bit numerical representation of an IPv4 address. fn - an optional callback function which, when provided, will determine the address reachability in an asynchronous, non-blocking manner.
Returns	If this function is called without a callback function, returns the numeric representation of the hostname reachability status. If a callback function is specified, then a host object is returned.
Notes	If no callback function is provided, the resolution occurs in a blocking manner which may be noticeable when network access is slow or erratic. If a callback function is provided, this function acts as a constructor, returning a host object and the callback function will be invoked when resolution is complete. The callback function should take two parameters: the string "reachability", indicating that reachability was determined, and the numeric representation of the hostname reachability status. Generates an error if network access is currently disabled or the IP address is invalid. The numeric representation is made up from a combination of the flags defined in `hs.network.reachability.flags`. Performs the same reachability test as `hs.network.reachability.forHostName`.
Examples	None
Source	extensions/network/libnetwork_host.m line 327

#Methods

#cancel


Signature	`hs.network.host:cancel() -> hostObject`
Type	Method
Description	Cancels an in-progress asynchronous host resolution.
Parameters	None
Returns	the hostObject
Notes	This method has no effect if the resolution has already completed.
Examples	None
Source	extensions/network/libnetwork_host.m line 367

#isRunning


Signature	`hs.network.host:isRunning() -> boolean`
Type	Method
Description	Returns whether or not resolution is still in progress for an asynchronous query.
Parameters	None
Returns	true, if resolution is still in progress, or false if resolution has already completed.
Notes	None
Examples	None
Source	extensions/network/libnetwork_host.m line 350