Сетевые запросы

Сетевой модуль stappler_network предоставляет упрощённый интерфейс для выполнения сетевых запросов поверх libcurl, выполняет инициализацию, реинициализацию и обеспечивает повторное использование существующих соединений.

Публичный интерфейс модуля неинформативен сам по себе и основан на функциях, определённых в SPNetworkData.h. Такое решение является компромиссом в попытке закрыть пользователю SDK возможность неверно использовать детали реализации.

Основные функции интерфейса:

• init — инициализирует интерфейс с используемым методом запроса и URL
• addHeader — добавляет заголовок к запросу
• setMailFrom — добавляет информацию об отправителе постового сообщения (для SMTP)
• addMailTo — добавляет получателя почтового сообщения (для SMTP)
• setAuthority — устанавливает данные для авторизации на сервере
• setProxy — устанавливает данные прокси-сервера
• setReceiveFile — устанавливает файл для записи результата запроса
• setReceiveCallback — устанавливает функцию для записи результата запроса
• setSendFile — устанавливает файл для отправки
• setSendCallback — устанавливает функцию для получения отправляемых данных
• setSendData — устанавливает объект данных (типа Value) для отправки
• setDownloadProgress — устанавливает функцию индикации прогресса загрузки ответа
• setUploadProgress — устанавливает функцию индикации прогресса отправки запроса
• setVerifyTls — устанавливает флаг необходимой верификации tls
• perform — выполняет запрос
• getResponseCode — получает код ответа
• getErrorCode — получает код ошибки при выполнении запроса
• getError — получает текст ошибки при выполнении запроса
• getReceivedHeaderString — получает строковое значение заголовка ответа
• getReceivedHeaderInt — получает целочисленное значение заголовка ответа
• getRecievedHeaders — получает заголовки ответа
• getResponseContentType — получает тип контента ответа

Запрос проходит следующие стадии выполнения:

• Пользовательская подготовка: заполняются необходимые структуры данных
• Вызов perform
• Системная подготовка, интерпретация пользовательских значений в значения CURL
• Выполнение запроса
• Системная финализация
• Возврат из perform
• Пользовательская финализация — чтение результата

MultiHandle позволяет обрабатывать несколько сетевых запросов в одном потоке. Его функции:

• addHandle: добавляет подготовленный запрос к списку исполняемых
• perform: продолжить выполнение запросов до исчерпания списка. Выполнение может быть остановлено из передаваемой функции возвратом false.

Context — внутренняя структура, хранящая данные запроса, уже находящегося на исполнении. Доступ к ней может быть необходим в случае собственной реализации мультиплексирования запросов без использования MultiHandle.

SDK предоставляет интерфейсу встроенный набор корневых сертификатов TLS на случай, если curl не может обнаружить их в системе. Такая возможность предоставляет лучший контроль над сертификатами на случай, если российские корневые сертификаты не будут входить в стандартный набор.