hs.socket.udp

Работа с пользовательскими протоколами с помощью асинхронных сокетов UDP.

Для сокетов TCP см. hs.socket.

С помощью этих сокетов можно делать много полезных и нетривиальных вещей. Пример простого пинга-понга:

function ping(data, addr)
  print(data)
  addr = hs.socket.parseAddress(addr)
  hs.timer.doAfter(1, function()
    client:send("ping", addr.host, addr.port)
  end)
end

function pong(data, addr)
  print(data)
  addr = hs.socket.parseAddress(addr)
  hs.timer.doAfter(1, function()
    server:send("pong", addr.host, addr.port)
  end)
end

server = hs.socket.udp.server(9001, pong):receive()
client = hs.socket.udp.new(ping):send("ping", "localhost", 9001):receive()

Что приведет к следующему бесконечному обмену:

20:26:56    LuaSkin: (secondary thread): Data written to UDP socket
            LuaSkin: (secondary thread): Data read from UDP socket
ping
20:26:57    LuaSkin: (secondary thread): Data written to UDP socket
            LuaSkin: (secondary thread): Data read from UDP socket
pong
20:26:58    LuaSkin: (secondary thread): Data written to UDP socket
            LuaSkin: (secondary thread): Data read from UDP socket
ping
20:26:59    LuaSkin: (secondary thread): Data written to UDP socket
            LuaSkin: (secondary thread): Data read from UDP socket
pong
...

Можно делать какие-то глупые вещи с фабрикой обратных вызовов и включением широковещательной рассылки:

local function callbackMaker(name)
  local fun = function(data, addr)
    addr = hs.socket.parseAddress(addr)
    print(name.." received data:\n"..data.."\nfrom host: "..addr.host.." port: "..addr.port)
  end
  return fun
end

local listeners = {}
local port = 9001

for i=1,3 do
  table.insert(listeners, hs.socket.udp.new(callbackMaker("listener "..i)):reusePort():listen(port):receive())
end

broadcaster = hs.socket.udp.new():broadcast()
broadcaster:send("hello!", "255.255.255.255", port)

Поскольку ни IPv4, ни IPv6 не были отключены, широковещательная рассылка принимается по обоим протоколам (показаны адреса IPv6 «с двойной стековой» поддержкой):

listener 2 received data:
hello!
from host: ::ffff:192.168.0.3 port: 53057
listener 1 received data:
hello!
from host: ::ffff:192.168.0.3 port: 53057
listener 3 received data:
hello!
from host: ::ffff:192.168.0.3 port: 53057
listener 1 received data:
hello!
from host: 192.168.0.3 port: 53057
listener 3 received data:
hello!
from host: 192.168.0.3 port: 53057
listener 2 received data:
hello!
from host: 192.168.0.3 port: 53057

Обзор API

Переменные - Настраиваемые значения

timeout

Функции - API-вызовы, предоставляемые непосредственно расширением

parseAddress

Конструкторы - API-вызовы, возвращающие объект, обычно предоставляющий методы API

new
server

Методы - API-вызовы, которые можно выполнить только на объекте, возвращаемом конструктором

broadcast
close
closed
connect
connected
enableIPv
info
listen
pause
preferIPv
read
readOne
receive
receiveOne
reusePort
send
setBufferSize
setCallback
setTimeout
write

Документация API

Переменные

timeout

Подпись	`hs.socket.udp.timeout`
Тип	Переменная
Описание	Таймаут для операций с сокетом в секундах.
Примечания	Новые объекты `hs.socket.udp` будут созданы с этим значением таймаута, но могут индивидуально изменить его с помощью метода `hs.socket.udp:setTimeout`. Если значение таймаута отрицательно, операции не будут использовать таймаут. Значение по умолчанию равно `-1`.
Исходный код	extensions/socket/socket.lua строка 173

Функции

parseAddress

Подпись	`hs.socket.udp.parseAddress(sockaddr) -> table or nil`
Тип	Функция
Описание	Псевдоним для `hs.socket.parseAddress`
Параметры
Возвращаемое значение
Исходный код	extensions/socket/socket.lua строка 184

Конструкторы

new

Подпись	`hs.socket.udp.new([fn]) -> hs.socket.udp object`
Тип	Конструктор
Описание	Создает объект асинхронного сокета UDP без соединения.
Параметры	`fn` - необязательная функция обратного вызова для чтения данных из сокета, для удобства задаваемая здесь.
Возвращаемое значение	Объект `hs.socket.udp`.
Исходный код	extensions/socket/libsocket_udp.m строка 111

server

Подпись	`hs.socket.udp.server(port[, fn]) -> hs.socket.udp object`
Тип	Конструктор
Описание	Создает сокет UDP и привязывает его к порту для прослушивания.
Параметры	`port` - номер порта [0-65535]. Порты [1-1023] являются привилегированными. Порт 0 позволяет ОС выбрать любой доступный порт. `fn` - необязательная функция обратного вызова для чтения данных из сокета, для удобства задаваемая здесь.
Возвращаемое значение	Объект `hs.socket.udp`.
Исходный код	extensions/socket/socket.lua строка 208

Методы

broadcast

Подпись	`hs.socket.udp:broadcast([flag]) -> self or nil`
Тип	Метод
Описание	Включает широковещательную рассылку в базовом сокете.
Параметры	`flag` - необязательный булевый параметр: `true` для включения широковещательной рассылки, `false` для её отключения. По умолчанию `true`.
Возвращаемое значение	Объект `hs.socket.udp` или `nil` в случае ошибки.
Примечания	По умолчанию базовый сокет в ОС не позволит отправлять широковещательные сообщения. Для отправки широковещательных сообщений необходимо включить эту функцию в сокете. Широковещательное сообщение — это сообщение UDP по адресам вроде "192.168.255.255" или "255.255.255.255", которое доставляется каждому хосту в сети. По умолчанию эта функция отключена (ОС) для предотвращения случайных широковещательных сообщений, перегружающих сеть.
Исходный код	extensions/socket/libsocket_udp.m строка 418

close

Подпись	`hs.socket.udp:close() -> self`
Тип	Метод
Описание	Немедленно закрывает сокет, освобождая его для повторного использования. Любые ожидающие операции отправки отбрасываются.
Параметры	Нет
Возвращаемое значение	Объект `hs.socket.udp`.
Исходный код	extensions/socket/libsocket_udp.m строка 222

closed

Подпись	`hs.socket.udp:closed() -> bool`
Тип	Метод
Описание	Возвращает статус закрытия сокета.
Параметры	Нет
Возвращаемое значение	`true` если сокет закрыт, иначе `false`.
Примечания	Сокеты UDP обычно предназначены для работы без соединения. Отправка пакета в любое место, независимо от того, получит ли её получатель, открывает сокет до его явного закрытия. Активный прослушивающий сокет не будет закрыт, но не будет «подключенным», если не был вызван метод `hs.socket.udp:connect`.
Исходный код	extensions/socket/libsocket_udp.m строка 675

connect

Подпись	`hs.socket.udp:connect(host, port[, fn]) -> self or nil`
Тип	Метод
Описание	Подключает сокет, если он не подключен.
Параметры	`host` - строка, содержащая имя хоста или IP-адрес. `port` - номер порта [1-65535]. `fn` - необязательная функция обратного вызова, выполняемая после установления соединения. Функция обратного вызова не принимает параметров.
Возвращаемое значение	Объект `hs.socket.udp` или `nil` в случае ошибки.
Примечания	По дизайну UDP — протокол без соединения, и подключение не требуется. Выбор подключения к определенному хосту/порту имеет следующий эффект: Вы сможете отправлять данные только подключенному хосту/порту; Вы сможете получать данные только от подключенного хоста/порта; Вы получите сообщения ICMP, которые поступают от подключенного хоста/порта, такие как «отказ в подключении». Фактический процесс подключения сокета UDP не приводит к обмену данными по сокету, он просто изменяет внутреннее состояние сокета. Вы не можете привязать сокет для прослушивания после того, как он был подключен. Вы можете подключить сокет только один раз.
Исходный код	extensions/socket/libsocket_udp.m строка 145

connected

Подпись	`hs.socket.udp:connected() -> bool`
Тип	Метод
Описание	Возвращает статус подключения сокета.
Параметры	Нет
Возвращаемое значение	`true` если подключен, иначе `false`.
Примечания	Сокеты UDP обычно предназначены для работы без соединения. Этот метод вернет `true` только если явно был вызван метод `hs.socket.udp:connect`.
Исходный код	extensions/socket/libsocket_udp.m строка 652

enableIPv

Подпись	`hs.socket.udp:enableIPv(version[, flag]) -> self or nil`
Тип	Метод
Описание	Включает или отключает IPv4 или IPv6 на базовом сокете. По умолчанию оба включены.
Параметры	`version` — число, содержащее версию IP (4 или 6) для включения или отключения. `flag` — булево значение: `true` для включения выбранной версии IP, `false` для отключения. По умолчанию `true`.
Возвращаемое значение	Объект `hs.socket.udp`, или `nil` в случае ошибки.
Примечания	Должен вызываться перед привязкой сокета. Если вы хотите создать сервер только для IPv6, сделайте следующее: `hs.socket.udp.new(callback):enableIPv(4, false):listen(port):receive()` Удобный конструктор `hs.socket.server` автоматически привяжет сокет и требует закрытия и повторного прослушивания для использования этого метода.
Исходный код	extensions/socket/libsocket_udp.m строка 486

info

Подпись	`hs.socket.udp:info() -> table`
Тип	Метод
Описание	Возвращает информацию о сокете.
Параметры	Нет
Возвращаемое значение	Таблица, содержащая следующие ключи: connectedAddress - `string` (структура `sockaddr`) connectedHost - `string` connectedPort - `number` isClosed - `boolean` isConnected - `boolean` isIPv4 - `boolean` isIPv4Enabled - `boolean` isIPv4Preferred - `boolean` isIPv6 - `boolean` isIPv6Enabled - `boolean` isIPv6Preferred - `boolean` isIPVersionNeutral - `boolean` localAddress - `string` (структура `sockaddr`) localAddress_IPv4 - `string` (структура `sockaddr`) localAddress_IPv6 - `string` (структура `sockaddr`) localHost - `string` localHost_IPv4 - `string` localHost_IPv6 - `string` localPort - `number` localPort_IPv4 - `number` localPort_IPv6 - `number` maxReceiveIPv4BufferSize - `number` maxReceiveIPv6BufferSize - `number` timeout - `number` userData - `string`
Исходный код	extensions/socket/libsocket_udp.m строка 699

listen

Подпись	`hs.socket.udp:listen(port) -> self or nil`
Тип	Метод
Описание	Привязывает неподключенный сокет к порту для прослушивания.
Параметры	`port` — номер порта [0-65535]. Порты [1-1023] являются привилегированными. Порт 0 позволяет ОС выбрать любой доступный порт.
Возвращаемое значение	Объект `hs.socket.udp`, или `nil` в случае ошибки.
Исходный код	extensions/socket/libsocket_udp.m строка 192

pause

Подпись	`hs.socket.udp:pause() -> self`
Тип	Метод
Описание	Приостанавливает чтение пакетов из сокета.
Параметры	Нет
Возвращаемое значение	Объект `hs.socket.udp`
Примечания	Для возобновления вызовите один из методов приема.
Исходный код	extensions/socket/libsocket_udp.m строка 243

preferIPv

Подпись	`hs.socket.udp:preferIPv([version]) -> self`
Тип	Метод
Описание	Устанавливает предпочтительную версию IP: IPv4, IPv6 или нейтральную (первая для разрешения).
Параметры	`version` — необязательное число, содержащее предпочтительную версию IP. Любое значение, отличное от 4 или 6, устанавливает поведение по умолчанию — нейтральное.
Возвращаемое значение	Объект `hs.socket.udp`.
Примечания	Если поиск DNS возвращает только результаты IPv4, сокет автоматически будет использовать IPv4. Если поиск DNS возвращает только результаты IPv6, сокет автоматически будет использовать IPv6. Если поиск DNS возвращает результаты как IPv4, так и IPv6, то используемый протокол зависит от настроенных предпочтений.
Исходный код	extensions/socket/libsocket_udp.m строка 523

read

Подпись	`hs.socket.udp:read(delimiter[, tag]) -> self`
Тип	Метод
Описание	Псевдоним для `hs.socket.udp:receive`
Параметры
Возвращаемое значение
Исходный код	extensions/socket/socket.lua строка 237

readOne

Подпись	`hs.socket.udp:readOne(delimiter[, tag]) -> self`
Тип	Метод
Описание	Псевдоним для `hs.socket.udp:receiveOne`
Параметры
Возвращаемое значение
Исходный код	extensions/socket/socket.lua строка 243

receive

Подпись	`hs.socket.udp:receive([fn]) -> self or nil`
Тип	Метод
Описание	Читает пакеты из сокета по мере их поступления.
Параметры	`fn` — необязательно, передайте здесь обратный вызов для чтения.
Возвращаемое значение	Объект `hs.socket.udp`, или `nil` в случае ошибки.
Примечания	Результаты передаются в функцию обратного вызова обратный вызов, которую необходимо установить для использования этого метода. Существуют два режима работы для приема пакетов: по одному и непрерывно. В режиме по одному вызывайте receiveOne каждый раз, когда вы готовы обработать входящий UDP-пакет. Прием пакетов по одному может быть предпочтительнее для реализации определенного кода состояния машины, где ваша машина состояний может не всегда быть готова обработать входящие пакеты. В непрерывном режиме обратный вызов вызывается немедленно каждый раз при получении входящих UDP-пакетов. Прием пакетов непрерывно лучше подходит для приложений потоковой передачи в реальном времени. Вы можете переключаться между режимами по одному и непрерывно. Если сокет в настоящее время работает в режиме по одному, вызов этого метода переключит его в непрерывный режим.
Исходный код	extensions/socket/libsocket_udp.m строка 295

receiveOne

Подпись	`hs.socket.udp:receiveOne([fn]) -> self or nil`
Тип	Метод
Описание	Считывает один пакет из сокета.
Параметры	`fn` — необязательно, передайте здесь обратный вызов для чтения.
Возвращаемое значение	Объект `hs.socket.udp`, или `nil` в случае ошибки.
Примечания	Результаты передаются в функцию обратного вызова обратный вызов, которую необходимо установить для использования этого метода. Существуют два режима работы для приема пакетов: по одному и непрерывно. В режиме по одному вызывайте receiveOne каждый раз, когда вы готовы обработать входящий UDP-пакет. Прием пакетов по одному может быть предпочтительнее для реализации определенного кода состояния машины, где ваша машина состояний может не всегда быть готова обработать входящие пакеты. В непрерывном режиме обратный вызов вызывается немедленно каждый раз при получении входящих UDP-пакетов. Прием пакетов непрерывно лучше подходит для приложений потоковой передачи в реальном времени. Вы можете переключаться между режимами по одному и непрерывно. Если сокет в настоящее время работает в непрерывном режиме, вызов этого метода переключит его в режим по одному.
Исходный код	extensions/socket/libsocket_udp.m строка 321

END_OF_DOCUMENT_MARKER

reusePort

Signature	`hs.socket.udp:reusePort([flag]) -> self or nil`
Type	Method
Description	Включает повторное использование порта на сокете.
Parameters	`flag` - необязательный булевый параметр: `true` для включения повторного использования порта, `false` для отключения. По умолчанию `true`.
Returns	Объект `hs.socket.udp`, или `nil` в случае ошибки.
Notes	По умолчанию только один сокет может быть привязан к заданному IP-адресу и порту одновременно. Для того, чтобы несколько процессов могли одновременно привязаться к одному и тому же адресу и порту, необходимо включить эту функцию в сокете. Все процессы, которые хотят одновременно использовать адрес и порт, должны включить повторное использование порта на сокете, привязанном к этому порту. Метод должен быть вызван до привязки сокета.
Source	extensions/socket/libsocket_udp.m строка 452

send

Signature	`hs.socket.udp:send(message[, host, port][, tag, fn]) -> self`
Type	Method
Description	Отправляет пакет по указанному адресу назначения.
Parameters	`message` - строка, содержащая данные, которые будут отправлены по сокету. `host` - строка, содержащая имя хоста или IP-адрес. `port` - номер порта [1-65535]. `tag` - необязательное целое число для маркировки операций записи. `fn` - необязательная одноразовая функция обратного вызова, которая выполняется после отправки пакета. Функция обратного вызова получает параметр метки, предоставленный здесь.
Returns	Объект `hs.socket.udp`.
Notes	Для неподключённых сокетов удалённый пункт назначения указывается для каждого пакета. Если сокет был явно подключён с помощью `connect`, можно указать только параметр сообщения и необязательные параметры метки и/или обратного вызова записи. Обратите внимание, что подключение для UDP-сокета необязательно. Для подключённых сокетов данные могут быть отправлены только по подключённому адресу.
Source	extensions/socket/libsocket_udp.m строка 347

setBufferSize

Signature	`hs.socket.udp:setBufferSize(size[, version]) -> self`
Type	Method
Description	Устанавливает максимальный размер буфера, который будет выделен для операций приёма.
Parameters	`size` - число, содержащее размер буфера приёма в байтах. `version` - необязательное число, содержащее версию IP, для которой необходимо установить размер буфера. Любое значение, кроме 4 или 6, задаёт одинаковый размер для обеих версий.
Returns	Объект `hs.socket.udp`.
Notes	По умолчанию максимальный размер составляет 9216 байт. Теоретический максимальный размер любого пакета IPv4 UDP составляет `UINT16_MAX = 65535`. Теоретический максимальный размер любого пакета IPv6 UDP составляет `UINT32_MAX = 4294967295`. Поскольку ОС сообщает нам о размере каждого полученного UDP-пакета, фактический размер выделенного буфера для каждого пакета точный. На практике размер UDP-пакетов обычно значительно меньше максимального. Большинство протоколов будут отправлять и принимать пакеты только в несколько байт или установят ограничение на размер пакетов, чтобы предотвратить фрагментацию на уровне IP. Если вы установите слишком малый размер буфера, API сокетов в ОС будет безмолвно отбрасывать любые дополнительные данные.
Source	extensions/socket/libsocket_udp.m строка 555

setCallback

Signature	`hs.socket.udp:setCallback([fn]) -> self`
Type	Method
Description	Устанавливает функцию обратного вызова для чтения из сокета.
Parameters	`fn` - необязательная функция обратного вызова для обработки данных, считанных из сокета. `nil` или отсутствие аргументов удаляет функцию обратного вызова. Функция обратного вызова получает 2 параметра: `data` - данные, считанные из сокета, как строка. `sockaddr` - адрес отправителя в виде двоичной структуры адреса сокета. См. `parseAddress`.
Returns	Объект `hs.socket.udp`.
Notes	Функция обратного вызова должна быть установлена для чтения данных из сокета.
Source	extensions/socket/libsocket_udp.m строка 597

setTimeout

Signature	`hs.socket.udp:setTimeout(timeout) -> self`
Type	Method
Description	Устанавливает таймаут для операций с сокетом.
Parameters	`timeout` - число, содержащее время таймаута в секундах.
Returns	Объект `hs.socket.udp`.
Notes	Если значение таймаута отрицательно, операции не будут использовать таймаут, что является значением по умолчанию.
Source	extensions/socket/libsocket_udp.m строка 628

write

Signature	`hs.socket.udp:write(message[, tag]) -> self`
Type	Method
Description	Псевдоним для `hs.socket.udp:send`
Parameters
Returns
Source	extensions/socket/socket.lua строка 249