|
6u3oH
|
Дата: Вторник, 16.06.2015, 19:54 | Сообщение # 1
|
Главный и единственный
Группа: Администратор
Сообщений: 36
Статус: Не в сети
|
Автор: Morning Rainbow
Версия: 0.2.1b (beta)
Описание:
Модуль является обёрткой над библиотекой libcurl, которая предназначена для того, чтобы взаимодействовать с различными серверами по множеству различных протоколов с синтаксисом URL.
Поддерживаемые протоколы: FTP, FTPS, HTTP, HTTPS, TFTP, SCP, SFTP, Telnet, DICT, LDAP, POP3, IMAP и SMTP.
Слинкованные библиотеки (win):
История изменений:
Функции:
curl_easy_escape(CURL:handle, url[], escapedUrl[], len)
Кодирует для URL выбранную строку.
Функция немного отличается от оригинальной. handle - curl дескриптор, url - строка для кодирования, escapedUrl - закодированная строка, len - размер escapedUrl. Возвращает реальный размер закодированной строки.
Примечание: Вам не нужно вызывать curl_free, как указано в документации. Это делает модуль.
curl_easy_init()
Начинает новую easy-сессию libcurl.
Возвращает дескриптор curl.
curl_easy_cleanup(CURL:handle)
Завершает libcurl easy сессию.
CURLcode:curl_easy_getinfo(CURL:handle, CURLINFO:info, ...)
Получает информацию для указанного curl дескриптора. Информация записывается в переменную указанную 3-им аргументом.
handle - curl дескриптор, info - значение определяет какую информацию нужно получить, 3 аргумент - массив-строка (в этом случае 4-ым аргументом указывается размер), либо числовая переменная, либо переменная типа Float, либо числовая переменная с тэгом curl_slist (ставить тэг не обязательно, но вам будет проще ориентироваться в коде, тэг curl_slist означает, что в переменной содержится указатель на структуру curl_slist)
CURLcode:curl_easy_pause(CURL:handle, bitmask)
Приостанавливает или возобновляет передачу данных.
handle - curl дескриптор, bitmask - указывает новое состояние соединения.
curl_easy_perform(CURL:handle, callbackComplite[], data[] = {}, data_len = 0)
Начинает передачу данных.
Имеет отличие от оригинальной функции. Так во 2-ом параметре нужно указать имя функции, которая вызовется по завершении передачи, в 3-ем параметре можно указать массив, который будет передан в функцию колбэк (в этом случае необходимо указать 4-ый параметр - размер массива).
Прототип функции колбэка: public CurlCallback(CURLcode:code, CURL:curl, data[], data_size)
Примечание: Вызов функции не блокирует сервер, выполнение передачи идёт в отдельном потоке.
CURLcode:curl_easy_recv(CURL:handle, buffer[], len, &n)
Получает "сырые" (raw) данные.
buffer[] - здесь будут содержаться принятые данные, len - размер буфера, n - здесь будет содержаться реальное количество принятых байт.
Примечание: Эта функция уже работает в блокирующем режиме.
curl_easy_reset(CURL:handle)
Сбрасывает все параметры сессии.
CURLcode:curl_easy_send(CURL:handle, buffer[], len, &n)
Передаёт "сырые" (raw) данные.
buffer[] - буфер с данными, которые необходимо отправить, len - размер буфера (укажите меньше, если требуется), n - будет содержать реальное количество отправленных байт.
Примечание: Функция работает в блокирующем режиме.
CURLcode:curl_easy_setopt(CURL:handle, CURLoption:option, ...)
Смотрите в описании на сайте. Примечания под спойлером.
curl_easy_strerror(CURLcode:code, errorBuf[], len)
Возвращает строку, которая описывает код ошибки.
Отличается от оригинальной функции, 2-ым параметром укажите буфер, куда будет записано описание ошибки, параметр len - размер буфера.
curl_easy_unescape(CURL:handle, url[], unescapedUrl[], len)
Возвращает декодированную строку URL-кодированной строки. :)
Немного отличается от оригинальной функции. url - строка для декодирования, unescapedUrl - здесь укажите буфер, куда будет записана декодированная строка, len - размер unescapedUrl.
Возвращает реальный размер декодированной строки.
Примечание: Вам не нужно вызывать curl_free, как указано в документации. Это делает модуль.
CURLFORMcode:curl_formadd(&curl_httppost:first, &curl_httppost:last, ...)
Добавляет раздел в multipart/formdata HTTP POST.
Подробное описание смотрите на сайте. Примечания под спойлером.
curl_formfree(&curl_httppost:first)
Освобождает память, выделенную под список multipart/formdata HTTP POST параметров.
curl_slist:curl_slist_append(curl_slist:list, buffer[])
Добавляет строку в конец связного списка curl_slist.
list - указатель на последний элемент списка, buffer - строка для добавления.
Возвращает указатель на новый последний элемент списка.
Вы должны обязательно вызвать curl_slist_free_all, после того как curl завершит работу со структурой.
curl_slist_free_all(curl_slist:list)
Освобождает весь список curl_slist.
curl_version(buf[], len)
Возвращает версию curl, включенные библиотеки и их версии.
buf - буфер, куда положить информацию о версиях, len - размер буфера.
Общие примечания:
0) Модуль сам НЕ очищает curl дескрипторы, вы должны сами контролировать очистку (вызов curl_easy_cleanup для каждого открытого дескриптора), все курлы должны быть очищены к моменту смены карты. Так же, если есть активные передачи к моменту смены карты, то модуль попытается сгенерировать ошибку передачи чтобы как можно скорее завершить поток в котором выполняется передача и вызвать колбэк curl_easy_perform (вызовется после plugin_end()).
Проще всего проводить очистку в колбэке curl_easy_perform.
1) Вы НЕ должны вызывать curl_easy_cleanup и другие функции очистки пока передача не завершилась!
2) Пока нет возможности реально установить/получить значение переменной типа curl_off_t, сейчас происходит преобразование типа к cell (обычная ячейка amxx), но это не очень правильно. Значения зачастую будут некорректными.
3) Всегда определяйте опцию CURLOPT_BUFFERSIZE, если используете колбэк WRITEFUNCTION укажите в качестве параметра размер буфера не более 1024, иначе рискуете получить ошибки stack error, возможно даже повесить сервер. Если вы получаете ошибки stack error при использовании других колбэков, то можно определить в плагине #pragma dynamic 30000.
4) Не забывайте, что вам необходимо очищать память по указателям для curl_slist и curl_httppost с помощью функций curl_slist_free_all и curl_formfree соответственно.
5) Если будет что-то не так с опциями CURLAUTH_*, то сообщайте :)
Рекомендации:
1) Если планируется "долгосрочная" передача, то можно временно убрать лимит игры на карте, когда передача завершится восстановить;
2) Вы можете использовать 1 дескриптор curl несколько раз для одного url, однако при текущей реализации логики модуля будет сложнее очистить дескриптор в месте отличном от колбэка curl_easy_perform;
3) Используйте curl_easy_setopt(curl, CURLOPT_VERBOSE, 1) для отладки плагина, если затрудняетесь определить причину неполадки в плагине. (По-умолчания вывод дебаг информации будет осуществляться в консоль сервера, вы можете определить колбэк CURLOPT_DEBUGFUNCTION для изменения вывода)
Примеры кода:
1) Отправка email через SMTP-сервер;
2) Простейший пример отправки GET запроса через HTTP;
3) Плагин для отправки сообщения Вконтакте.
Для компиляции под linux нужно написать Makefile, в архиве с исходным кодом уже есть статическая библиотека libcurl и по идее код должен компилироваться под linux без допилов.
Windows версия не будет работать на Windows Server 2003 и Windows XP.
Более подробную информацию, многие ссылки и сам модуль можете скачать в источнике.
|
|
|
|
|
