hs.network.ping

Проверка доступности сервера путем отправки запросов ICMP Echo Requests.

• server — строка, содержащая имя хоста или IP-адрес сервера для проверки. Поддерживаются как IPv4, так и IPv6 адреса.
• count — необязательное целое число, по умолчанию 5, определяющее количество запросов ICMP Echo Requests, отправляемых серверу.
• interval — необязательное число, по умолчанию 1.0, в секундах, определяющее задержку между отправкой каждого запроса echo. Для установки этого параметра необходимо также указать count.
• timeout — необязательное число, по умолчанию 2.0, в секундах, определяющее время ожидания ответа echo перед тем как считать его истекшим. Для установки этого параметра необходимо также указать count и interval.
• class — необязательная строка, по умолчанию "any", определяющая, какой IP-версии (IPv4 или IPv6) следует использовать для отправки пакетов ICMP. Строка должна быть одной из следующих:
  • any — использует версию IP, которая соответствует первому адресу, к которому server разрешает имя
  • IPv4 — использовать IPv4; если server не может разрешить имя до IPv4 адреса, или если IPv4 трафик не поддерживается в сети, пинг завершится с ошибкой.
  • IPv6 — использовать IPv6; если server не может разрешить имя до IPv6 адреса, или если IPv6 трафик не поддерживается в сети, пинг завершится с ошибкой.
• fn — функция обратного вызова, которая получает сообщения об обновлениях для процесса пинга. Подробности относительно функции обратного вызова см. в примечаниях.

• объект ping

• Для удобства вы можете вызвать этот конструктор как hs.network.ping(server, ...).

• Весь процесс пинга займет максимум count * interval + timeout секунд от didStart до didFinish.

• По умолчанию функция обратного вызова, если fn не указана, выводит результаты каждого ответа echo при получении в консоль Hammerspoon и сводку по завершении. Вывод должен быть знаком всем, кто использовал ping из командной строки.

• Если вы предоставляете собственную функцию обратного вызова, она должна принимать от 2 до 4 аргументов и не возвращать значения. Возможные аргументы, которые будут отправлены, будут следующими:

  • "didStart" — указывает, что разрешение адреса завершено и пинг начнет отправлять ICMP запросы echo.

    • object — объект ping, для которого предназначен обратный вызов
    • message — сообщение для обратного вызова, в данном случае "didStart"

  • "didFail" — указывает, что процесс пинга завершился ошибкой, скорее всего из-за ошибки разрешения адреса или из-за разрыва сетевого подключения.

    • object — объект ping, для которого предназначен обратный вызов
    • message — сообщение для обратного вызова, в данном случае "didFail"
    • error — строка, содержащая сообщение об ошибке

  • "sendPacketFailed" — указывает, что определенный запрос ICMP Echo Request завершился неудачно по какой-либо причине.

    • object — объект ping, для которого предназначен обратный вызов
    • message — сообщение для обратного вызова, в данном случае "sendPacketFailed"
    • sequenceNumber — порядковый номер пакета ICMP, который не удалось отправить
    • error — строка, содержащая сообщение об ошибке

  • "receivedPacket" — указывает, что запрос ICMP Echo Request получил ожидаемый ответ ICMP Echo Reply.

    • object — объект ping, для которого предназначен обратный вызов
    • message — сообщение для обратного вызова, в данном случае "receivedPacket"
    • sequenceNumber — порядковый номер принятого пакета ICMP

  • "didFinish" — указывает, что пинг завершил отправку всех запросов ICMP Echo Request или был отменен.

    • object — объект ping, для которого предназначен обратный вызов
    • message — сообщение для обратного вызова, в данном случае "didFinish"

Возвращает строку, содержащую разрешенный IPv4 или IPv6 адрес, к которому этот объект ping отправляет запросы echo.

• Ничего

• Строка, содержащая IPv4 или IPv6 адрес, к которому этот объект ping отправляет запросы echo, или "<адрес не разрешен>", если адрес не может быть разрешен.

Отменяет текущий процесс пинга, немедленно завершая его.

• Ничего

• Ничего

• сообщение didFinish будет отправлено в функцию обратного вызова в качестве последнего сообщения.

Получение или установка количества запросов ICMP Echo Request, которые будут отправлены процессом пинга.

• count — необязательное целое число, определяющее общее количество запросов echo, которое должен отправить процесс пинга. Если указано, это число должно быть больше числа уже отправленных запросов.

• если аргумент не указан, возвращает текущее количество запросов echo, которые отправит процесс пинга; если аргумент указан и процесс пинга не завершен, возвращает объект ping; если процесс пинга уже завершен, то этот метод возвращает nil.

Возвращает, приостановлен ли процесс пинга в данный момент.

• Ничего

• Булево значение, указывающее, приостановлен ли процесс пинга (true) или нет (false)

Возвращает, активен ли процесс пинга в данный момент.

• Ничего

• Булево значение, указывающее, активен ли процесс пинга (true) или нет (false)

• Этот метод вернет false только если процесс пинга завершил отправку всех запросов echo или был отменён с помощью hs.network.ping:cancel. Чтобы определить, отправляет ли процесс в данный момент запросы echo, см. hs.network.ping:isPaused.

Возвращает таблицу, содержащую информацию об ICMP-эхо-пакетах, отправленных этим объектом pingObject.

• sequenceNumber - необязательное целое число, указывающее порядковый номер ICMP-эхо-пакета, о котором требуется получить информацию.

• Если sequenceNumber указан, возвращает таблицу с парами «ключ-значение», содержащую информацию о конкретном ICMP-эхо-пакете с этим порядковым номером, или пустую таблицу, если такой пакет ещё не был отправлен. Если порядковый номер не указан, возвращает таблицу массивов со всеми ICMP-эхо-пакетами, отправленными этим объектом.

• Порядковые номера начинаются с 0, в то время как индексы таблиц Lua-массивов начинаются с 1. Если вы не указываете sequenceNumber для этого метода, элемент с индексом 1 возвращаемой таблицы массивов будет содержать таблицу, описывающую ICMP-эхо-пакет с порядковым номером 0, элемент с индексом 2 будет описывать ICMP-эхо-пакет с порядковым номером 1 и т. д.

• Таблица ICMP-эхо-пакета будет содержать следующие пары «ключ-значение»:

  • sent - число, указывающее время отправки запроса эха для этого пакета. Это число представляет количество секунд, прошедших с полуночи 1 января 1970 года по Гринвичу, и является числом с плавающей точкой, поэтому перед использованием его в качестве аргумента для функции Lua os.date необходимо применить функцию math.floor.
  • recv - число, указывающее время получения ответа эха для этого пакета. Это число представляет количество секунд, прошедших с полуночи 1 января 1970 года по Гринвичу, и является числом с плавающей точкой, поэтому перед использованием его в качестве аргумента для функции Lua os.date необходимо применить функцию math.floor.
  • icmp - таблица, предоставленная объектом hs.network.ping.echoRequest, содержащая подробности о конкретном ICMP-пакете, которому соответствует эта запись. Она будет содержать следующие ключи:
    • checksum - контрольная сумма ICMP-пакета, используемая для обеспечения целостности данных.
    • code - код управления ICMP-сообщением. Должен всегда быть 0.
    • identifier - идентификатор ICMP, сгенерированный внутри для сопоставления запросов и ответов пакетов.
    • payload - строка, содержащая полезную нагрузку ICMP для этого пакета. Она была составлена для того, чтобы ICMP-пакет был ровно 64 байта, чтобы соответствовать соглашению для запросов эха ICMP.
    • sequenceNumber - порядковый номер ICMP для этого пакета.
    • type - тип управления ICMP-сообщением. Для ICMPv4 это будет 0, если ответ получен, или 8, если ответ ещё не получен. Для ICMPv6 это будет 129, если ответ получен, или 128, если ответ ещё не получен.
    • _raw - строка, содержащая ICMP-пакет в виде сырых данных.

Приостановить процесс пинга.

• Нет

• Если процесс пинга активен, возвращает pingObject; если процесс завершён, возвращает nil.

Возобновить процесс пинга, если он был приостановлен.

• Нет

• Если процесс пинга активен, возвращает pingObject; если процесс завершён, возвращает nil.

Возвращает количество отправленных ICMP-запросов эха.

• Нет

• Количество отправленных запросов эха.

Возвращает имя хоста или строку IP-адреса, переданную конструктору hs.network.ping.ping.

• Нет

• Строка, соответствующая имени хоста или IP-адресу, переданному конструктору hs.network.ping.ping для этого объекта.

Установить или удалить функцию обратного вызова для pingObject.

• fn - функция, которая должна быть установлена в качестве обратного вызова, или nil, если вы хотите использовать функцию по умолчанию.

• объект pingObject

• Поскольку процесс пинга начинается сразу же после создания с помощью конструктора hs.network.ping.ping, предпочтительно назначить обратный вызов в самом конструкторе.
• Этот метод предоставляется как способ изменения обратного вызова на основе других событий (например, изменения текущей сети или местоположения).
• Если вы действительно хотите создать pingObject без обратного вызова, вам нужно сделать что-то вроде hs.network.ping.ping(...):setCallback(function() end).

Возвращает строку, содержащую сводную информацию о процессе пинга.

• Нет

• строка с кратким описанием текущего состояния процесса пинга

• Строка с кратким описанием будет похожа на следующую:

--- hostname ping statistics 
5 packets transmitted, 5 packets received, 0.0 packet loss
round-trip min/avg/max = 2.282/4.133/4.926 ms

• Количество полученных пакетов будет соответствовать количеству отправленных пакетов, а не значению, возвращаемому hs.network.ping:count.