hs.socket

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

Для UDP-сокетов см. hs.socket.udp.

hs.socket реализован с помощью CocoaAsyncSocket. Функции метки CocoaAsyncSocket предоставляют удобный способ реализации пользовательских протоколов.

Например, вы можете легко реализовать базовый HTTP-клиент следующим образом (хотя для реального мира рекомендуется использовать hs.http):

local TAG_HTTP_HEADER, TAG_HTTP_CONTENT = 1, 2
local body = ""
local function httpCallback(data, tag)
  if tag == TAG_HTTP_HEADER then
    print(tag, "TAG_HTTP_HEADER"); print(data)
    local contentLength = data:match("\r\nContent%-Length: (%d+)\r\n")
    client:read(tonumber(contentLength), TAG_HTTP_CONTENT)
  elseif tag == TAG_HTTP_CONTENT then
    print(tag, "TAG_HTTP_CONTENT"); print(data)
    body = data
  end
end

client = hs.socket.new(httpCallback):connect("google.com", 80)
client:write("GET /index.html HTTP/1.0\r\nHost: google.com\r\n\r\n")
client:read("\r\n\r\n", TAG_HTTP_HEADER)

Что приведет к следующему выводу в консоль (настройте уровень детализации логов с помощью hs.socket.setLogLevel()) :

            LuaSkin: (secondary thread): TCP socket connected
            LuaSkin: (secondary thread): Data written to TCP socket
            LuaSkin: (secondary thread): Data read from TCP socket
1 TAG_HTTP_HEADER
HTTP/1.0 301 Moved Permanently
Location: http://www.google.com/index.html
Content-Type: text/html; charset=UTF-8
Date: Thu, 03 Mar 2016 08:38:02 GMT
Expires: Sat, 02 Apr 2016 08:38:02 GMT
Cache-Control: public, max-age=2592000
Server: gws
Content-Length: 229
X-XSS-Protection: 1; mode=block
X-Frame-Options: SAMEORIGIN

            LuaSkin: (secondary thread): Data read from TCP socket
2 TAG_HTTP_CONTENT
&lt;HTML&gt;&lt;HEAD&gt;&lt;meta http-equiv=&quot;content-type&quot; content=&quot;text/html;charset=utf-8&quot;&gt;
&lt;TITLE&gt;301 Moved&lt;/TITLE&gt;&lt;/HEAD&gt;&lt;BODY&gt;
&lt;H1&gt;301 Moved&lt;/H1&gt;
The document has moved
&lt;A HREF=&quot;http://www.google.com/index.html&quot;&gt;here&lt;/A&gt;.
&lt;/BODY&gt;&lt;/HTML&gt;
            LuaSkin: (secondary thread): TCP socket disconnected Socket closed by remote peer

Подмодули

hs.socket.udp

Обзор API

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

timeout

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

parseAddress

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

new
server

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

connect
connected
connections
disconnect
info
listen
read
receive
send
setCallback
setTimeout
startTLS
write

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

Переменные

timeout

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

Функции

parseAddress

Подпись	`hs.socket.parseAddress(sockaddr) -> table or nil`
Тип	Функция
Описание	Парсит двоичную структуру адреса сокета в читаемый столбец.
Параметры	`sockaddr` - Двоичная структура адреса сокета, обычно получаемая из метода `info` или в `hs.socket.udp`’s обработчик чтения.
Возвращаемое значение	Столбец, описывающий адрес с ключами или `nil`: host - Строка, содержащая IP-адрес хоста. port - Число, содержащее порт. addressFamily - Число, содержащее семейство адресов.
Примечания	Некоторые определения семейства адресов из `<sys/socket.h>`: Семейство адресов \| Число \| Описание :--- \| :--- \| : AF_UNSPEC \| 0 \| неопределенное AF_UNIX \| 1 \| локальный для хоста (каналы) AF_LOCAL \| AF_UNIX \| обратная совместимость AF_INET \| 2 \| интернет: UDP, TCP и т. д. AF_NS \| 6 \| протоколы XEROX NS AF_CCITT \| 10 \| протоколы CCITT, X.25 и т. д. AF_APPLETALK \| 16 \| Apple Talk AF_ROUTE \| 17 \| Внутренний протокол маршрутизации AF_LINK \| 18 \| интерфейс уровня связи AF_INET6 \| 30 \| IPv6
Исходный код	extensions/socket/libsocket.m строка 187

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

new

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

server

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

Методы

connect

Подпись	`hs.socket:connect(host, port \| path [, fn]) -> self or nil`
Тип	Метод
Описание	Подключает неподключенный сокет.
Параметры	`host` - Строка, содержащая имя хоста или IP-адрес. `port` - Номер порта [1-65535]. `path` - Строка, содержащая путь к сокету Unix-домена. `fn` - Необязательная одноразовая функция обратного вызова, которая выполняется после установления подключения. Обратный вызов не получает параметров.
Возвращаемое значение	Объект `hs.socket`, или `nil` в случае возникновения ошибки.
Примечания	Должен быть предоставлен либо хост/порт, либо путь к сокету Unix-домена. Если порт не передан, первый параметр предполагается как путь к файлу сокета.
Исходный код	extensions/socket/libsocket.m строка 234

connected

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

connections

Подпись	`hs.socket:connections() -> number`
Тип	Метод
Описание	Возвращает количество подключений к сокету.
Параметры	Нет
Возвращаемое значение	Количество подключений к сокету.
Примечания	Этот метод возвращает не более 1 для сокетов по умолчанию (не для прослушивания).
Исходный код	extensions/socket/libsocket.m строка 593

disconnect

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

информация

Подпись	`hs.socket:info() -> table`
Тип	Метод
Описание	Возвращает информацию о сокете.
Параметры	Нет
Возвращаемое значение	Таблица, содержащая следующие ключи: connectedAddress - `string` (`sockaddr` структура) connectedHost - `string` connectedPort - `number` connectedURL - `string` connections - `number` isConnected - `boolean` isDisconnected - `boolean` isIPv4 - `boolean` isIPv4Enabled - `boolean` isIPv4PreferredOverIPv6 - `boolean` isIPv6 - `boolean` isIPv6Enabled - `boolean` isSecure - `boolean` localAddress - `string` (`sockaddr` структура) localHost - `string` localPort - `number` timeout - `number` unixSocketPath - `string` userData - `string`
Источник	extensions/socket/libsocket.m строка 614

прослушивание

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

чтение

Подпись	`hs.socket:read(delimiter[, tag]) -> self or nil`
Тип	Метод
Описание	Чтение данных из сокета.
Параметры	`delimiter` - Количество байтов для чтения или разделитель строки, например, "\n" или "\r\n". Данные читаются до и включая разделитель. `tag` - Необязательное целое число для маркировки операций чтения. Оно передаётся в обратный вызов для реализации конечных автоматов для обработки сложных протоколов.
Возвращаемое значение	Объект `hs.socket`, или `nil` в случае ошибки.
Примечания	Результаты передаются в функцию обратного вызова сокета setCallback, которую необходимо установить. Если вызов осуществляется для сокета прослушивания с несколькими соединениями, данные читаются из каждого из них.
Источник	extensions/socket/libsocket.m строка 369

получение

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

отправка

Подпись	`hs.socket:send(message[, tag]) -> self`
Тип	Метод
Описание	Псевдоним для `hs.socket:write`
Параметры
Возвращаемое значение
Источник	extensions/socket/socket.lua строка 231

установитьОбратныйВызов

Подпись	`hs.socket:setCallback([fn]) -> self`
Тип	Метод
Описание	Устанавливает обратный вызов для чтения из сокета.
Параметры	`fn` - Необязательная функция обратного вызова для обработки данных, прочитанных из сокета. `nil` или отсутствие аргумента удаляет обратный вызов. Обратный вызов получает 2 параметра: `data` - Прочитанные данные из сокета в виде строки. `tag` - Целое число, связанное с вызовом чтения, по умолчанию `-1`.
Возвращаемое значение	Объект `hs.socket`.
Примечания	Обратный вызов должен быть установлен для чтения данных из сокета.
Источник	extensions/socket/libsocket.m строка 473

установитьТаймаут

Подпись	`hs.socket:setTimeout(timeout) -> self`
Тип	Метод
Описание	Устанавливает таймаут для операций с сокетом.
Параметры	`timeout` - Число, содержащее длительность таймаута в секундах.
Возвращаемое значение	Объект `hs.socket`.
Примечания	Если значение таймаута отрицательно, операции не будут использовать таймаут, что является значением по умолчанию.
Источник	extensions/socket/libsocket.m строка 503

начатьTLS

Подпись	`hs.socket:startTLS([verify][, peerName]) -> self`
Тип	Метод
Описание	Обеспечивает безопасность сокета с помощью TLS.
Параметры	`verify` - Необязательный булевый параметр, который, если `false`, позволяет TLS-рукопожатие с серверами с самоподписанными сертификатами и не оценивает цепочку доверия. По умолчанию `true`, и опушен, если `peerName` указан. `peerName` - Необязательная строка, содержащая полное доменное имя узла для проверки, например, `store.apple.com`. Она должна соответствовать имени в сертификате X.509, предоставленном удаленной стороной. См. важное примечание по безопасности ниже.
Возвращаемое значение	Объект `hs.socket`.
Примечания	Соединение будет немедленно прервано, если TLS-переговоры завершатся неудачно. ВАЖНОЕ ПРИМЕЧАНИЕ ПО БЕЗОПАСНОСТИ: Параметры по умолчанию проверяют, подписан ли сертификат удаленной стороны доверенным агентством сертификации третьей стороны (например, verisign) и не истек ли он. Однако имя в сертификате не будет проверяться, если не будет задано значение для проверки посредством `peerName`. Важно понимать последствия этого для безопасности. Представьте, что вы пытаетесь создать защищенное соединение с MySecureServer.com, но ваш сокет перенаправлен на MaliciousServer.com из-за взломанного DNS-сервера. Если вы просто используете параметры по умолчанию, и MaliciousServer.com имеет действительный сертификат, параметры по умолчанию не обнаружат никаких проблем, так как сертификат действителен. Чтобы правильно защитить соединение в этом конкретном случае, вы должны установить `peerName` на "MySecureServer.com".
Источник	extensions/socket/libsocket.m строка 527

запись

Подпись	`hs.socket:write(message[, tag, fn]) -> self`
Тип	Метод
Описание	Запись данных в сокет.
Параметры	`message` - Строка, содержащая данные, которые нужно отправить по сокету. `tag` - Необязательное целое число для маркировки операций записи. `fn` - Необязательная одноразовая функция обратного вызова для выполнения после записи данных в сокет. Обратный вызов получает параметр тега, предоставленный здесь.
Возвращаемое значение	Объект `hs.socket`.
Примечания	Если вызов осуществляется для сокета прослушивания с несколькими соединениями, данные транслируются всем подключённым сокетам.
Источник	extensions/socket/libsocket.m строка 429