Skip to content
This repository has been archived by the owner on Jun 9, 2023. It is now read-only.

Latest commit

 

History

History
74 lines (62 loc) · 10.3 KB

hs.network.host.md

File metadata and controls

74 lines (62 loc) · 10.3 KB
Raw

docs » hs.network.host

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

API Overview

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.
|

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.
|

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.
|

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.
|

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.

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.