Объект IP
Объект IP (также часто "объект TCP") используется для работы с сокетами, TCP/IP и UDP соединениями, Http и пр. Объект поддерживает шифрование SSL/TLS, которое может быть использовано не только для получения информации по протоколу https, но и для целей обмена любой информацией по протоколу TCP/IP. Основными характеристиками объекта являются:
- Тип соединения (сокета). В большинстве случаев, обмен происходит с помощью протокола TCP/IP, однако, в редких случаях, требуется использование UDP (к примеру, DNS серверы работают с использованием данного протокола). В последнем случае, реальное соединение не устанавливается, а происходит обмен дейтаграммами, функции, работающие с обычными соединениями, типа ReceiveStr работать не будут, а используются специальные функции. Использование UDP пока не реализовано, но планируется к реализации.
- Серверное или клиентское соединение. Клиентское соединение позволяет осуществить связь с удаленной стороной по ее IP адресу, создавать код таких соединений достаточно просто, так как он линейный: подключение, обмен информацией, закрытие подключения. Серверное соединение создает слушающий сокет на локальном компьютере с определенным номером входящего порта, при этом задается имя функции, которая будет принимать новые соединения. После этого серверная сторона ждет соединений (к примеру, с помощью команды простоя Sleep). При установке соединения внешней стороной, система создает новый объект IP и вызывает указанную ранее функцию, в которой программа может либо осуществить обмен (при этом во время выполнения этого обмена новые входящие соединения будут ожидать своей очереди), либо запускает новый поток, который самостоятельно осуществляет обмен (в этом случае, сервер становится снова доступен для входящих соединений еще до завершения первого соединения). Как альтернатива такого подхода серверное соединение тоже можно выполнить, как линейный процесс без событий с помощью функций ListenEx и Accept. Выбор нужного подхода зависит от разработчика.
- Блокирующий сокет. Блокирующие сокеты отличаются тем, что при попытке считать информацию в определенном объеме, система ждет, пока информация полностью придет с удаленной стороны и отдает управление только когда информация полностью накоплена, либо произошел разрыв связи. Не блокирующие сокеты отличаются тем, что возвращают управление сразу, если новой информации на момент вызова не поступало. Это позволяет реализовать такие функции, как Receive или Peek, а также позволяет реализовать функцию ReceiveUntil с гораздо меньшими затратами ресурсов системы. В совокупности с этими функциями, обычно используется функция Wait. Для обычных (не шифрованных) соединений рекомендуется использовать не блокирующие сокеты, тогда как для шифрованных соединений обычно используются блокирующие. Даже если сокет не блокирующий, функции Receive или Peek не будут работать для шифрованных соединений.
- Шифрованные соединения. Шифрованные соединения обычно используются для получения страниц с https серверов или для создания таких серверов, однако, шифрование можно использовать и для внутренних нужд обмена с помощью TCP/IP. Включение шифрования производится после того, как соединение уже установлено для клиентов, либо после получения входящего соединения для серверов. Причем, включить шифрование можно даже после отправки или получения пакетов информации, однако, для получения страниц с https серверов, включение шифрования необходимо выполнить сразу после соединения с сервером. Система имеет ограниченный список поставщиков шифрования, этот список может быть расширен в будущем. Для включения шифрования для клиентов используется функция InitEncryption, для серверов, функция InitServerEncryption.
- Объект может представлять внутренний простой протокол USR1. Для обмена с использованием этого протокола, см. статью USR1 протокол.
Общие атрибуты и функции
| Идентификатор | Статус | Тип | Визуальная | Параметры | Описание |
|---|---|---|---|---|---|
| IsBlocking | Реализована | Атрибут | IPConnection.IsBlocking:<Блокирующий ли это сокет TCP (INT)> | Атрибут получает или изменяет свойство того, является ли данный сокет (соединение) блокирующим или нет. Операционная система не во всех случаях дает изменять такое свойство после начала обмена информацией, поэтому, рекомендуется изменять атрибут сразу же после установки соединения. Атрибут не будет работать, если соединение не установлено. | |
| IsServer, IsListening | Реализована | Атрибут | IPConnection.IsServer:<Является ли текущий объект серверным (INT)> | Атрибут получает свойство того, является ли текущий объект сервером (ожидает соединения), либо клиентом. | |
| IsIPv6 | Реализована | Атрибут | IPConnection.IsIPv6:<Настроен ли текущий сокет на протокол IPv6 (INT)> | Атрибут получает свойство того, настроен ли текущий сокет на протокол TCP/IPv6. Атрибут доступен для серверного сокета или клиентского сокета, после установки соединения. | |
| Socket | Реализована | Атрибут | IPConnection.Socket:<Системный сокет соединения (INT)> | Атрибут получает системный сокет соединения для объекта с установленным соединением. Такой сокет может быть использован, к примеру, во внешних вызовах DLL. | |
| Create | Реализована | Функция | IPConnection.Create():<Новое неактивное соединение (IPOBJECT)> | Функция создает неактивный объект соединения, который затем можно использовать, к примеру, для задания прокси сервера и дальнейшего соединения с удаленным сервером. | |
| Connect | Реализована | Функция | IPConnection.Connect(<Адрес соединения (STRING)>,<Блокирующий ли это сокет (INT)>=0,<Тип соединения (INT)>=0):<Новое соединение (IPOBJECT)> | Функция производит соединение TCP/IP с удаленным сервером, после установки соединения никакой дополнительной информации не отсылается. | |
| ConnectUSR1 | Реализована | Функция | IPConnection.ConnectUSR1(<Адрес соединения (STRING)>,<Пароль USR1 соединения (STRING)>,<Тип соединения (INT)>=0):<Новое соединение (IPOBJECT)> | Функция производит соединение TCP/IP с удаленным сервером по внутреннему протоколу системы. После соединения, обычно следующим шагом является объявление протокола USR1. | |
| Listen | Реализована | Функция | IPConnection.Listen(<Порт сокета (INT)>,<Функция глобального модуля, вызываемая при установке соединения (STRING)>,<Тип соединения (INT)>=0):<Объект сервера (IPOBJECT)> | Функция создает TCP/IP сервер на указанном порту. После установки внешнего соединения, система инициирует вызов указанной функции. Функция будет выполнена в корневом потоке. Если корневой поток в это время будет занят, система будет ожидать его освобождения, по время ожидания, принятие новых соединений будет приостановлено, соединения будут ждать в очереди операционной системы (размер очереди задан системой по умолчанию). Вызов Disconnect или удаление объекта из системы автоматически закрывает сервер и освобождает порт. | |
| ListenUSR1 | Реализована | Функция | IPConnection.ListenUSR1(<Порт сокета (INT)>,<Пароль USR1 соединения (STRING)>,<Функция глобального модуля, вызываемая при установке соединения (STRING)>,<Тип соединения (INT)>=0):<Объект сервера (IPOBJECT)> | Функция создает USR1 TCP/IP сервер на указанном порту. После установки внешнего соединения, система инициирует вызов указанной функции. Функция будет выполнена в корневом потоке. Если корневой поток в это время будет занят, система будет ожидать его освобождения, по время ожидания, принятие новых соединений будет приостановлено, соединения будут ждать в очереди операционной системы (размер очереди задан системой по умолчанию). Вызов Disconnect или удаление объекта из системы автоматически закрывает сервер и освобождает порт. | |
| ListenEx | Реализована | Функция | IPConnection.ListenEx(<Порт сокета (INT)>,<Тип соединения (INT)>=0):<Объект сервера (IPOBJECT)> | Функция создает TCP/IP сервер на указанном порту. Для получения новых соединений необходимо использовать функцию Accept в цикле ожидания, для которого удобно использовать особую функцию простоя Wait. Вызов Disconnect или удаление объекта из системы автоматически закрывает сервер и освобождает порт. | |
| Accept | Реализована | Функция | IPConnection.Accept():<Объект нового клиента или пустое значение (IPOBJECT)> | Функция используется для серверных объектов, созданных функцией ListenEx и позволяет получать новое клиентское подключение ожидающее в очереди подключений операционной системы. Если клиентские подключения в очереди отсутствуют, функция возвращает пустое значение. Обычно функция вызывается в цикле с ожиданием, создающимся функцией Wait. | |
| Disconnect | Реализована | Функция | IPConnection.Disconnect(<Быстрое закрытие соединения (INT)>=0) | Функция выполняет разрыв связи для TCP/IP соединения, также освобождает слушающий порт и удаляет сервер, если это соединение серверное. | |
| IsConnected | Реализована | Функция | IPConnection.IsConnected():<Установлена ли связь (INT)> | Функция возвращает единицу, если объект является TCP/IP сокетом и связь в данный момент установлена, иначе функция возвращает 0. | |
| UseProxy | Реализована | Функция | IPConnection.UseProxy(<Адрес и порт прокси сервера (STRING)>,<Тип прокси сервера (STRING)>,<Имя пользователя прокси (STRING)>,<Пароль пользователя прокси (STRING)>,<Дополнительные параметры прокси (STRING)>) | Функция настраивает прокси сервер для использования с данным соединением. Функция должна быть вызвана до фактического соединения с удаленной стороной на неактивном объекте, затем этот объект может использоваться совместно с функцией Connect. Для получения неактивного объекта соединения необходимо использовать функцию Create. | |
| InitEncryption | Реализована | Функция | IPConnection.InitEncryption(<Тип шифрования (STRING)>,<Путь и имя библиотеки шифрования (STRING)>,<Сертификаты и ключи (STRING)>,<Наименование метода клиента (STRING)>) | Функция инициализирует шифрование клиентской стороны на существующем IP соединении (чаще всего TCP/IP). См. описание для более полной информации. | |
| InitServerEncryption | Реализована | Функция | IPConnection.InitServerEncryption(<Тип шифрования (STRING)>,<Путь и имя библиотеки шифрования (STRING)>,<Сертификаты и ключи (STRING)>,<Наименование метода сервера (STRING)>) | Функция инициализирует шифрование серверной стороны на существующем IP соединении (чаще всего TCP/IP). См. описание для более полной информации. | |
| DeInitEncryption | Реализована | Функция | IPConnection.DeInitEncryption() | Функция отключает процедуру шифрования для существующего IP соединения (чаще всего TCP/IP). Разрыв связи при этом не производится. | |
| Timeout | Реализована | Функция | IPConnection.Timeout(<Новый тайм-аут в мс. (INT)>,<Тип тайм-аута (INT)>=0):<Текущий тайм-аут функций чтения или записи в мс. (INT)> | Функция получает или изменяет тайм-аут функций чтения, записи или соединения, заданный в миллисекундах. При чтении или записи, если за указанное время, не удается получить (отослать) какую-либо часть данных, соединение будет считаться разорванным. Правильно установленный тайм-аут позволяет вовремя освобождать ресурсы сервера и уменьшать последствия возможных атак DOS. | |
| SendCmd | Реализована | Функция | IPConnection.SendCmd(<4 буквенная команда (STRING)>) | TCP/IP функция отсылает 4 байта информации по установленному соединению. Информация задается в виде ANSI-строки. Функцию можно использовать как для блокирующих, так и для не блокирующих соединений. | |
| SendStr | Реализована | Функция | IPConnection.SendStr(<Строка для отправки (STRING)>,<Отослать строку в UTF-16 (INT)>=0) | TCP/IP функция отсылает строку по установленному соединению. Первыми отсылаются 4 байта -- размер строки в символах, затем само содержимое строки. Функцию можно использовать как для блокирующих, так и для не блокирующих соединений. | |
| SendStrRaw | Реализована | Функция | IPConnection.SendStrRaw(<Строка для отправки (STRING)>,<Отослать строку в UTF-16 (INT)>=0) | TCP/IP функция отсылает строку по установленному соединению. Длина строки не отсылается. Функцию можно использовать как для блокирующих, так и для не блокирующих соединений. | |
| SendBuffer | Реализована | Функция | IPConnection.SendBuffer(<Буфер для отправки информации (BUFFER)>,<Начальная позиция буфера (INT)>=0,<Размер отправляемых данных в байтах (INT)>) | TCP/IP функция отсылает данные из буфера по установленному соединению. Первыми отсылаются 4 байта -- размер данных в байтах, затем сами данные. Функцию можно использовать как для блокирующих, так и для не блокирующих соединений. | |
| SendBufferRaw | Реализована | Функция | IPConnection.SendBufferRaw(<Буфер для отправки информации (BUFFER)>,<Начальная позиция буфера (INT)>=0,<Размер отправляемых данных в байтах (INT)>) | TCP/IP функция отсылает данные из буфера по установленному соединению. Длина данных не отсылается. Функцию можно использовать как для блокирующих, так и для не блокирующих соединений. | |
| SendNumber | Реализована | Функция | IPConnection.SendNumber(<Число (NUMBER)>,<Тип числа (INT)>=0) | TCP/IP функция отсылает число указанного формата по установленному соединению. Функцию можно использовать как для блокирующих, так и для не блокирующих соединений. | |
| SendFile | Реализована | Функция | IPConnection.SendFile(<Путь и имя файла для отправки (STRING)>,<Упаковать файл перед отправкой (INT)>=0) | TCP/IP функция отсылает файл с помощью установленного соединения. Для приема файла на удаленной стороне необходимо использовать функцию ReceiveFile. Имя файла может иметь международные символы. Кроме содержимого файла на удаленную сторону отсылается также дата последней записи в файл (может использоваться для контроля необходимости обновления файла), и также само имя файла (удаленная сторона может принять файл по оригинальному имени). Файл может быть как локальным, так и находиться на сервере. Функцию можно использовать как для блокирующих, так и для не блокирующих соединений. | |
| Send | Реализована | Функция | IPConnection.Send(<Строка для отправки (STRING)>):<Количество байтов, которое было отправлено (INT)> | TCP/IP функция отсылает часть строки по установленному соединению. Длина строки не отсылается. Функцию можно использовать только для не блокирующих, не шифрованных соединений. Функция отсылает столько информации, сколько может принять буфер операционной системы, и, после этого сразу возвращает количество отосланных байт. Никакого внутреннего ожидания не выполняется. Функция работает быстрее других функций отправки, однако, требует создания дополнительного цикла ожидания готовности с помощью функции Wait. | |
| ReceiveOK | Реализована | Функция | IPConnection.ReceiveOK():<OK получено (INT)> | TCP/IP функция получает 4 байта информации по установленному соединению. Если 4 байта представляют собой слово "OK ", функция возвращает 1, иначе возвращается 0. Функцию можно использовать как для блокирующих, так и для не блокирующих соединений.
| |
| ReceiveCmd | Реализована | Функция | IPConnection.ReceiveCmd():<Полученная команда (STRING)> | TCP/IP функция получает 4 байта информации по установленному соединению, после чего возвращает эти байты в виде строки. Функцию можно использовать как для блокирующих, так и для не блокирующих соединений. | |
| ReceiveStr | Реализована | Функция | IPConnection.ReceiveStr(<Получаемая строка имеет формат UTF-16 (INT)>=0):<Полученная строка (STRING)> | TCP/IP функция получает строку по установленному соединению. Строка может быть как в ANSI-кодировке, так и в Unicode. Строка предваряется 4 байтами, задающими количество символов в ней. Строка может быть отослана с помощью функции SendStr. Функцию можно использовать как для блокирующих, так и для не блокирующих соединений. | |
| ReceiveStrRaw | Реализована | Функция | IPConnection.ReceiveStrRaw(<Длина получаемой строки (INT)>,<Получаемая строка имеет формат UTF-16 (INT)>=0):<Полученная строка (STRING)> | TCP/IP функция получает строку указанной длины по установленному соединению. Строка может быть как в ANSI-кодировке, так и в Unicode. Таким образом можно получать также бинарную информацию в виде ANSI-строки для дальнейшей ее обработки. Функцию можно использовать как для блокирующих, так и для не блокирующих соединений. | |
| ReceiveUntil | Реализована | Функция | IPConnection.ReceiveUntil(<Подстрока поиска (STRING)>):<Полученная строка (STRING)> | TCP/IP функция получает данные в ANSI-строку по установленному соединению до момента, когда встретится указанная подстрока поиска. Данные могут представлять собой бинарную информацию. Функцию можно использовать как для блокирующих, так и для не блокирующих соединений, однако для блокирующих или шифрованных соединений, функция может работать медленнее и использовать большее процессорное время. | |
| ReceiveInBuffer | Реализована | Функция | IPConnection.ReceiveInBuffer(<Буфер для получения информации (BUFFER)>,<Начальная позиция в буфере (INT)>=0) | TCP/IP функция получает информацию в буфер по установленному соединению. Информация предваряется 4 байтами, задающими ее размер в байтах. Информация может быть отослана с помощью функции SendBuffer либо функции SendStr. Функцию можно использовать как для блокирующих, так и для не блокирующих соединений. | |
| ReceiveInBufferRaw | Реализована | Функция | IPConnection.ReceiveInBufferRaw(<Буфер для получения информации (BUFFER)>,<Начальная позиция в буфере (INT)>=0,<Размер информации в байтах (INT)>) | TCP/IP функция получает информацию в буфер по установленному соединению. Функцию можно использовать как для блокирующих, так и для не блокирующих соединений. | |
| ReceiveNumber | Реализована | Функция | IPConnection.ReceiveNumber(<Тип числа (INT)>=0):<Полученное число (NUMBER)> | TCP/IP функция получает число указанного формата по установленному соединению. Функцию можно использовать как для блокирующих, так и для не блокирующих соединений. | |
| ReceiveFile | Реализована | Функция | IPConnection.ReceiveFile(<Имя файла для получения (STRING)>,<Путь по которому сохранить файл (STRING)>):<Путь и имя полученного файла (STRING)> | TCP/IP функция получает файл по установленному соединению. Для отсылки файла с удаленной стороны необходимо использовать функцию SendFile. Имя файла может иметь международные символы. Кроме содержимого файла принимается и устанавливается дата последней записи в файл (может использоваться для контроля необходимости обновления файла). Если имя файла не задано, будет использовано оригинальное имя файла, которое принимается с удаленной стороны. Если путь сохранения файла не задан, файл будет сохранен во временную папку текущего сеанса операционной системы. Файл может быть получен как локально, так в каталог сервера. Функцию можно использовать как для блокирующих, так и для не блокирующих соединений. | |
| Receive | Реализована | Функция | IPConnection.Receive(<Максимальный размер данных в байтах (INT)>):<Полученная строка (STRING)> | TCP/IP функция получает данные в ANSI-строку по установленному соединению. Данные могут представлять собой бинарную информацию. Функцию можно использовать только для не блокирующих, не шифрованных соединений. Функция получает столько информации, сколько в данный момент ожидает в буфере операционной системы, и, после этого сразу возвращает управление. Никакого внутреннего ожидания не выполняется. Функция работает быстрее других функций получения, однако, требует создания дополнительного цикла ожидания готовности данных с помощью функции Wait. | |
| Peek | Реализована | Функция | IPConnection.Peek():<Полученная строка (STRING)> | TCP/IP функция получает данные в ANSI-строку по установленному соединению, не удаляя их из буфера операционной системы. Данные могут представлять собой бинарную информацию. Функцию можно использовать только для не блокирующих, не шифрованных соединений. Функция получает столько информации, сколько в данный момент ожидает в буфере операционной системы, и, после этого сразу возвращает управление. Никакого внутреннего ожидания не выполняется. После выполнения Peek последующие функции группы Receive получат те же данные, что получила функция Peek. | |
| PeekSize | Реализована | Функция | IPConnection.PeekSize():<Размер данных в буфере операционной системы (INT)> | TCP/IP функция получает размер данных, ожидающих получения в буфере операционной системы, при этом данные из буфера не удаляются. Функцию можно использовать только для не блокирующих, не шифрованных соединений. | |
| Wait | Реализована | Функция | IPConnection.Wait(<Время ожидания готовности в мс. (INT)>,<Тип события для ожидания (INT)>=1) | TCP/IP функция работающая с установленным соединением, выполняет ожидание возникновения события в течение заданного времени, и возвращается в момент возникновения события, либо по истечении времени ожидания. Функция используется для исключения паузы между возникновением события и его обработкой, которая возникла бы при использовании функции Sleep. Доступны следующие события: событие, возникающее в момент поступления новых данных в буфер операционной системы (обычно совместно с функцией Receive), событие, возникающее после того, как были отправлены данные из буфера операционной системы и он готов принять новые данные (обычно совместно с функцией Send), событие, возникающее в момент, когда в очередь соединений поступило одно или более новое удаленное соединение (обычно совместно с функциями ListenEx и Accept). | |
| PeerAddress | Реализована | Функция | IPConnection.PeerAddress():<Удаленный адрес и порт текущего соединения (STRING)> | TCP/IP функция отдает удаленный адрес и порт текущего соединения в виде <Адрес>:<Порт> для IPv4 и [<Адрес>]:<Порт> для IPv6.
| |
| LocalAddress | Реализована | Функция | IPConnection.LocalAddress():<Локальный адрес и порт текущего соединения (STRING)> | TCP/IP функция отдает локальный адрес и порт текущего соединения в виде <Адрес>:<Порт> для IPv4 и [<Адрес>]:<Порт> для IPv6.
| |
| PerformHandshake | Планируется | Функция | IPConnection.PerformHandshake(<Серверная ли это сторона (INT)>,<Пароль или дополнительная информация (STRING)>,<Тип операции (INT)>=0):<Операция выполнена удачно (INT)> | Функция выполняет указанную проверку для удаленной стороны соединения. Обычно это проверка "рукопожатия" или корректности ввода противоположной стороной заданного пароля. |
Атрибуты и функции для работы с HTTP(S)
Любой объект IP имеет внутренние переменные для хранения http заголовка и http тела. Заголовок представляет собой обычный текст, строки которого разделены с помощью двух знаков переноса строки (с кодами 13 и 10, или _NEWLINE). Первой строкой всегда следует команда (если это запрос) или ответ (если это ответ на запрос), дальнейшие строки называются полями заголовка и заданы в следующем виде <Наименование поля>: <Значение поля> (к примеру, Content-Type: text/xml;charset=utf-8). И в запросе и в ответе на запрос заголовок отделяется от тела запроса (даже если оно отсутствует) с помощью двух знаков переноса строки. Заголовок должен содержать только ANSI-символы (международные символы обычно кодируются каким-либо методом, к примеру, URL кодируется с помощью HTTPURLEncode). Размер заголовка обычно не превышает 8Кб (но документального ограничения нет). Тело может содержать произвольную информацию (в случае страниц, это html, либо картинки и пр.) либо отсутствовать. При наличии тела, его длина обычно (но не всегда) задается в поле заголовка с наименованием Content-Length, и тип информации в поле заголовка Content-Type. Заголовок и тело можно заполнить непосредственно после создания объекта, затем их можно отослать по установленному соединению с помощью функций, типа HTTPSend. При загрузке запроса или ответа на запрос от удаленной стороны с помощью функций типа HTTPReceive переменные заголовка и тела заменяются на те, что были получены от удаленной стороны. Нужно также заметить, что функции получения тела запроса (HTTPReceive) отдают управление, когда тело будет полностью прочитано, для этого они находят его длину с помощью поля заголовка Content-Length. Если такое поле отсутствует, функции будут выполнять чтение до разрыва соединения удаленной стороной (так как неизвестен полный размер тела), если такое поведение не удовлетворят условиям задачи, необходимо выполнить чтение тела обычными TCP/IP функциями группы Receive.
| Идентификатор | Статус | Тип | Визуальная | Параметры | Описание |
|---|---|---|---|---|---|
| HTTPClear | Реализована | Функция | IPConnection.HTTPClear(<Режим операции (INT)>=3) | Функция очищает внутренние переменные объекта, в которых хранится заголовок и тело запроса HTTP. Обычно операция выполняется до начала заполнения нового запроса или ответа на запрос. | |
| HTTPSetOperation | Реализована | Функция | IPConnection.HTTPSetOperation(<Операция (STRING)>) | Функция устанавливает операцию в заголовке запроса или ответа на запрос. Примеры операций для запросов: GET /questions/2262/question HTTP/1.0, PUT /questions/2262/update HTTP/1.1. Пример операции ответа на запрос: HTTP/1.1 200 OK. Операция всегда следует первой строкой в заголовке http пакета.
| |
| HTTPGetOperation | Реализована | Функция | IPConnection.HTTPGetOperation():<Операция (STRING)> | Функция получает операцию из заголовка полученного запроса или ответа на запрос. Примеры возможных операций для запросов: GET /questions/2262/question HTTP/1.0, PUT /questions/2262/update HTTP/1.1. Пример возможной операции ответа на запрос: HTTP/1.1 200 OK. Операция всегда следует первой строкой в заголовке http пакета.
| |
| HTTPSetHeaderField | Реализована | Функция | IPConnection.HTTPSetHeaderField(<Имя поля (STRING)>,<Значение поля (STRING)>) | Функция устанавливает поле по его наименованию в заголовке запроса или ответа на запрос. Если поле уже существует, функция заменяется его значение, поэтому, она не годится для изменения полей "Set-Cookie", которых в заголовке ответа сервера может быть несколько. Для изменения полей cookie можно использовать объект Cookie, либо прочитать весь заголовок в виде строки, добавить строки с cookie и установить модифицированный заголовок в объект запроса. Для обычного http запроса рекомендуется наличие следующих полей: Host, User-Agent, Accept, Accept-Language, Connection, кроме того должны присутствовать поля Content-Type, Content-Length, если в запросе есть не пустое тело.
| |
| HTTPGetHeaderField | Реализована | Функция | IPConnection.HTTPGetHeaderField(<Имя поля (STRING)>):<Значение поля или пустое значение (STRING)> | Функция получает поле по его наименованию из заголовка полученного запроса или ответа на запрос. Если поле не существует, функция возвращает пустое значение. | |
| HTTPRemoveHeaderField | Реализована | Функция | IPConnection.HTTPRemoveHeaderField(<Имя поля (STRING)>) | Функция удаляет поле по его наименованию из заголовка полученного запроса или ответа на запрос. | |
| HTTPHeaderAsString | Реализована | Функция | IPConnection.HTTPHeaderAsString():<HTTP заголовок (STRING)> | Функция возвращает текущий HTTP заголовок в виде ANSI строки (без последнего дополнительного знака переноса строки). | |
| HTTPSetHeader | Реализована | Функция | IPConnection.HTTPSetHeader(<HTTP заголовок (STRING)>) | Функция обновляет текущий HTTP заголовок из аргумента в формате ANSI строки (наличие двух последних знаков переноса строки не обязательно). | |
| HTTPBodyAsString | Реализована | Функция | IPConnection.HTTPBodyAsString():<Тело HTTP запроса (STRING)> | Функция возвращает текущее тело HTTP запроса в виде ANSI строки (даже если тело представляет собой бинарную информацию). | |
| HTTPBodyAsBuffer | Реализована | Функция | IPConnection.HTTPBodyAsBuffer():<Тело HTTP запроса (BUFFER)> | Функция возвращает текущее тело HTTP запроса в виде объекта буфера (даже если тело является текстом). | |
| HTTPSetBody | Реализована | Функция | IPConnection.HTTPSetBody(<Тело HTTP запроса (STRING,BUFFER)>) | Функция обновляет текущее тело HTTP запроса из аргумента в формате ANSI строки или буфера. | |
| HTTPHeaderAndBodyAsString | Реализована | Функция | IPConnection.HTTPHeaderAndBodyAsString():<HTTP заголовок и тело запроса (STRING)> | Функция возвращает текущий HTTP заголовок и тело запроса (если оно присутствует) в виде ANSI строки (заголовок отделен от тела двумя знаками переноса строки). | |
| HTTPHeaderAndBodyAsBuffer | Реализована | Функция | IPConnection.HTTPHeaderAndBodyAsBuffer():<HTTP заголовок и тело запроса (BUFFER)> | Функция возвращает текущий HTTP заголовок и тело запроса (если оно присутствует) в виде объекта буфера (заголовок отделен от тела двумя знаками переноса строки). | |
| HTTPSetCookie | Реализована | Функция | IPConnection.HTTPSetCookie(<Наименование cookie (STRING)>,<Значение cookie (STRING)>) | Функция позволяет добавить информацию в поле заголовка Cookie. Функция обычно используется при формировании запроса на сервер для передачи сохраненных ранее переменных cookie. При использовании объекта cookie, нужный массив переменных можно загрузить в заголовок функцией CopyToHeader.
| |
| HTTPCookieRequestCount | Реализована | Функция | IPConnection.HTTPCookieRequestCount():<Количество полей Set-Cookie в ответе сервера (INT)> | Функция получает количество полей Set-Cookie, которые содержатся в данный момент в заголовке. Обычно функции, связанные с такими полями, применяются после получения ответа сервера, чтобы получить информацию о cookie, которые просит сохранить сервер. Вместо получения и обработки cookie с помощью функций HTTP, можно использовать объект cookie, информацию в который можно загрузить с помощью функции UpdateFromHeader.
| |
| HTTPGetCookieRequest | Реализована | Функция | IPConnection.HTTPGetCookieRequest(<Наименование или индекс cookie (STRING,INT)>):<Строка запроса cookie (STRING)> | Функция получает одно поле Set-Cookie из текущего заголовка по наименованию cookie или индексу поля. Полученная информация имеет формат <CookieName>=<value>[; <opt1>; <opt2>...] (к примеру, id=a3fWa; Expires=Wed, 21 Oct 2015 07:28:00 GMT; Secure; HttpOnly). В дальнейшем информацию можно разобрать в виде списка с помощью функции HTTPTranslateCookieRequest, если это необходимо. Обычно функции, связанные с такими полями, применяются после получения ответа сервера, чтобы получить информацию о cookie, которые просит сохранить сервер. Вместо получения и обработки cookie с помощью функций HTTP, можно использовать объект cookie, информацию в который можно загрузить с помощью функции UpdateFromHeader.
| |
| HTTPTranslateCookieRequest | Реализована | Функция | IPConnection.HTTPTranslateCookieRequest(<Строка запроса cookie (STRING)>):<Список директив запроса cookie (LIST)> | Функция превращает запрос из поля Set-Cookie (к примеру, полученный функцией HTTPGetCookieRequest) в список, разделяя его на директивы. Первым элементом списка всегда будет следовать значение cookie, наименования первого элемента будет совпадать с наименованием cookie. Последующие элементы будут содержать директивы запроса. Некоторые директивы могут не содержать текстового значения (к примеру, Secure, HttpOnly), для них значение элемента будет пустой строкой, для остальных значение будет заполнено значением директивы. Для директивы Expires значение будет автоматически переведено в тип данных дата и время, а для директивы Max-Age в число. Обычно функции, связанные с полями запроса cookie, применяются после получения ответа сервера, чтобы получить информацию о cookie, которые просит сохранить сервер. Вместо получения и обработки cookie с помощью функций HTTP, можно использовать объект cookie, информацию в который можно загрузить с помощью функции UpdateFromHeader. Важно: наименования cookie должны обрабатываться с учетом регистра.
| |
| HTTPDateToString | Реализована | Функция | IPConnection.HTTPDateToString(<Дата (DATE)>):<Дата в формате HTTP (STRING)> | Функция превращает значение в формате дата и время в строку с датой и временем в формате HTTP. Функция может быть вызвана непосредственно из интерфейса и создает строку в формате <day-name>, <day 2 digits>{ ,-}<month>{ ,-}<year 4 digits> <hour>:<minute>:<second> GMT. При этом, дата уже должна быть получена (к примеру, с помощью функции GMTDate) или переведена в часовой пояс GMT, функция не модифицирует дату. Для получения даты в формате HTTP также можно использовать функцию FormatDate, задав соответствующую маску.
| |
| HTTPSendAndReceive | Реализована | Функция | IPConnection.HTTPSendAndReceive(<После отправки запроса, ждать и получить ответ (INT)>=1):<Удачное выполнение (INT)> | Функция выполняет отправку подготовленного пакета (запроса или ответа на запрос), после чего при необходимости, может загрузить ответ удаленной стороны. Если ответ удаленной стороны не должен присутствовать (данный пакет был ответом), либо ответ не содержит поля Content-Length (к примеру, видео), необходимо вызвать функцию со значением аргумента, равным 0, либо использовать одну из функций HTTPReceive.
| |
| HTTPSend | Реализована | Функция | IPConnection.HTTPSend():<Удачное выполнение (INT)> | Функция выполняет отправку подготовленного пакета (запроса или ответа на запрос) для установленного TCP соединения. | |
| HTTPReceive | Реализована | Функция | IPConnection.HTTPReceive():<Удачное выполнение (INT)> | Функция выполняет загрузку HTTP пакета с удаленной стороны (загружаются заголовок и тело пакета). Если в заголовке пакета поле Content-Length отсутствует, тело будет загружаться до тех пор, пока не произойдет разрыв связи, если такое поведение нежелательно, можно загрузить заголовок с помощью функции HTTPReceiveHeader, а затем осуществить загрузку данных с помощью обычных функций TCP (к примеру, Receive).
| |
| HTTPReceiveHeader | Реализована | Функция | IPConnection.HTTPReceiveHeader():<Удачное выполнение (INT)> | Функция выполняет загрузку заголовка HTTP пакета с удаленной стороны. Тело пакета загружаться не будет. | |
| HTTPReceiveBody | Реализована | Функция | IPConnection.HTTPReceiveBody(<Размер тела пакета (INT)>):<Удачное выполнение (INT)> | Функция выполняет загрузку тела HTTP пакета с удаленной стороны. Если задан размер тела, функция осуществляет загрузку массива данных указанного размера, иначе будет выполняться загрузка до разрыва связи удаленной стороной. | |
| HTTPURLEncode | Реализована | Функция | IPConnection.HTTPURLEncode(<Строка для кодирования (STRING)>,<Режим кодирования (INT)>=0):<Результат кодирования (STRING)> | Функция выполняет кодирование произвольной строки в URL-формат, в строке-результате остаются только символы, которые можно использовать в URL. При кодировании международных символов, строка из формата UTF-16 обычно сначала переводится в формат UTF-8, однако, кодирование в UTF-16 разрешено. Функция может быть вызвана непосредственно из интерфейса. По своему действию функция совпадает с EncodeString с форматом кодирования Percent-encoding. | |
| HTTPURLDecode | Реализована | Функция | IPConnection.HTTPURLDecode(<Строка для декодирования (STRING)>):<Результат декодирования (STRING)> | Функция выполняет декодирование произвольной строки, закодированной в URL-формат, такие строки используются в URL или в полях заголовков HTTP пакетов. Строки с международными символами, обычно кодируются из формата UTF-8. Функция может быть вызвана непосредственно из интерфейса. По своему действию функция совпадает с DecodeString с форматом декодирования Percent-encoding. | |
| HTTPPunycodeEncode | Реализована | Функция | IPConnection.HTTPPunycodeEncode(<Строка для кодирования (STRING)>,<Режим кодирования (INT)>=1):<Результат кодирования (STRING)> | Функция выполняет кодирование произвольной строки в формат Punycode, используется для доменной части URL, если она содержит международные символы. Кодирование осуществляется в режиме URL или в режиме обычной строки. Допускается кодирование символов юникода с кодами >65535 (занимающих 4 байта). Функция может быть вызвана непосредственно из интерфейса. По своему действию функция совпадает с EncodeString с форматом кодирования Punycode (за исключением режима по умолчанию). | |
| HTTPPunycodeDecode | Реализована | Функция | IPConnection.HTTPPunycodeDecode(<Строка для декодирования (STRING)>,<Режим декодирования (INT)>=1):<Результат декодирования (STRING)> | Функция выполняет декодирование произвольной строки, закодированной в формат Punycode, используется для доменной части URL, если она содержит международные символы. Декодирование осуществляется в режиме URL или в режиме обычной строки. Корректно декодируются символы юникода с кодами >65535 (занимающие 4 байта). Функция может быть вызвана непосредственно из интерфейса. По своему действию функция совпадает с DecodeString с форматом декодирования Punycode (за исключением режима по умолчанию). | |
| HTTPDecodeChunked | Реализована | Функция | IPConnection.HTTPDecodeChunked() | Функция выполняет соединение тела полученного пакета, если он был фрагментирован при потоковой передаче (метод передачи chunked). Перед работой функция проверяет, имеется ли в заголовке поле Transfer-Encoding, и присутствует ли в нем значение chunked. Если оба условия выполняются, функция выполняет расшифровку (удаление служебной информации) тела запроса. Обновленное тело запроса записывается на место оригинального тела, если в служебной информации присутствовали дополнительные поля заголовка, они будут добавлены к заголовку, значение chunked будет удалено из поля Transfer-Encoding (само поле будет удалено из заголовка, если оно не содержало больше никаких значений).
| |
| HTTPCompress | Реализована | Функция | IPConnection.HTTPCompress(<Строка или буфер для компрессии (STRING,BUFFER)>,<Алгоритм компрессии (INT)>=0,<Уровень компрессии (INT)>=5):<Результат компрессии (STRING,BUFFER)> | Функция выполняет компрессию информации для отправки в теле HTTP-пакета. Обычно используется алгоритм gzip. При отправке сжатого пакета, в заголовке необходимо указать Content-Encoding: gzip (для алгоритма сжатия gzip).
| |
| HTTPDecompress | Реализована | Функция | IPConnection.HTTPDecompress(<Строка или буфер для декомпрессии (STRING,BUFFER)>,<Алгоритм компрессии (INT)>=0):<Результат декомпрессии (STRING,BUFFER)> | Функция выполняет декомпрессию информации, обычно полученной из тела HTTP-пакета. При обмене сжатыми пакетами, обычно используется алгоритм gzip. Для иницииации компрессии в заголовке исходящего пакета необходимо указать Accept-Encoding: gzip (для алгоритма сжатия gzip).
|
Атрибуты и функции для работы с объектом хранилища сookie
Объект является дочерним объектом объекта IP и позволяет работать с переменными запросов cookie, чтобы обеспечить эмуляцию поведения HTTP(S) сервера или браузера без необходимости написания дополнительных функций. При работе клиента, к примеру, обычной цепочкой вызова является после получения заголовка HTTP ответа сервера, вызвать UpdateFromHeader, чтобы скопировать новые cookie из заголовка, а перед новым запросом на сервер, вызвать CopyToHeader, чтобы вернуть нужные cookie в запрос.
| Идентификатор | Статус | Тип | Визуальная | Параметры | Описание |
|---|---|---|---|---|---|
| CreateCookieStorage | Планируется | Функция | IPConnection.Cookie.CreateCookieStorage():<Новый объект хранилище cookie (IPOBJECT)> | Функция создает новый объект хранилища сookie. Хранилище после создания будет пустым. | |
| UpdateFromHeader | Планируется | Функция | IPConnection.Cookie.UpdateFromHeader(<Строка или объект IP (STRING,IPOBJECT)>) | Функция обновляет или добавляет cookie из строки (которая должна являться заголовком пакета HTTP), либо из объекта IP, для которого установлено соединение и получен заголовок. | |
| CopyToHeader | Планируется | Функция | IPConnection.Cookie.CopyToHeader(<Строка или объект IP (STRING,IPOBJECT)>,<URL и путь запроса (STRING)>) | Функция добавляет нужные переменные cookie в текст заголовка пакета HTTP, который представлен либо строкой, либо объектом IP. | |
| RemoveExpired | Планируется | Функция | IPConnection.Cookie.RemoveExpired(<Дата и время для которых выполнить функцию (DATE)>=GMTDate) | Функция удаляет из хранилища переменные cookie, срок которых истек на указанные дату и время. По умолчанию используется текущая дата и время по Гринвичу. | |
| Clear | Планируется | Функция | IPConnection.Cookie.Clear(<URL и путь запроса (STRING)>) | Функция удаляет из хранилища переменные cookie, которые соответствуют указанную URL, либо все переменные cookie, если аргумент не задан. | |
| Count | Планируется | Функция | IPConnection.Cookie.Count():<Количество переменных cookie в хранилище (INT)> | Функция возвращает количество cookie в хранилище. | |
| GetName | Планируется | Функция | IPConnection.Cookie.GetName(<Индекс cookie (INT)>):<Наименование cookie (STRING)> | Функция получает наименование переменной cookie по ее индексу. | |
| Set | Планируется | Функция | IPConnection.Cookie.Set(<Индекс или наименование cookie (INT,STRING)>,<URL и путь запроса (STRING)>,<Значение cookie (STRING)>,<Директивы (STRING)>) | Функция обновляет значение указанной переменной cookie, также заменяет ее директивы. Если переменная cookie адресуется по наименованию, и она не существует в хранилище, она будет добавлена. Если для существующей переменной cookie директивы не указаны, они не будут изменены. | |
| Get | Планируется | Функция | IPConnection.Cookie.Get(<Индекс или наименование cookie (INT,STRING)>,<URL и путь запроса (STRING)>,<Директивы (STRING)>):<Значение cookie (STRING)> | Функция получает значение переменной cookie по ее наименованию или индексу, при этом можно задать URL при поиске по наименованию (так как одинаковые наименования могут быть сохранены с разных серверов). При необходимости функция также возвращает директивы переменной. При поиске по наименованию, если оно отсутвует, функция возвратит пустую строку для значения и директив cookie. | |
| AsTable | Планируется | Функция | IPConnection.Cookie.AsTable:<Таблица хранилища cookie (TAB)> | Функция представляет хранилище cookie в виде таблицы со столбцами Name, URL, Value, Options.
| |
| UpdateFromTable | Планируется | Функция | IPConnection.Cookie.UpdateFromTable(<Таблица хранилища cookie (TAB)>) | Функция обновляет переменные хранилища cookie из таблицы со столбцами Name, URL, Value, Options.
| |
| SaveToFile | Планируется | Функция | IPConnection.Cookie.SaveToFile(<Путь и имя файла (STRING)>,<URL и путь запроса (STRING)>) | Функция сохраняет переменные cookie хранилища со всеми их свойствами в текстовый файл. Возможно также сохранить только переменные, связанные с указанным URL. | |
| UpdateFromFile | Планируется | Функция | IPConnection.Cookie.UpdateFromFile(<Путь и имя файла (STRING)>) | Функция обновляет переменные cookie хранилища со всеми их свойствами из текстовый файл (ранее созданного функцией SaveToFile). |
