16.02.2006 Джеф Феллинг
Curl поможет управлять данными, размещенными в Web В данной статье рассматривается бесплатный инструмент Curl, с помощью которого можно передавать и принимать Web-страницы из командной строки. Благодаря Curl легко автоматизировать многие
Curl поможет управлять данными, размещенными в Web
В данной статье рассматривается бесплатный инструмент Curl, с помощью которого можно передавать и принимать Web-страницы из командной строки. Благодаря Curl легко автоматизировать многие операции информационной защиты и администрирования, например извлечь Web-страницу для анализа или загрузить исправление для системы безопасности из Web.
Установка Curl
Curl входит в состав многих дистрибутивов Unix. Имеются двоичные файлы и исходные тексты для большинства других операционных систем. Даже программисты, работающие с открытым PHP, могут использовать Curl для безопасного доступа к Web-контенту непосредственно из PHP-сценариев.
Для работы Curl с Web-узлами Secure Sockets Layer (SSL) необходим пакет OpenSSL. Существуют две версии Curl: одна с SSL, другая без SSL. Рекомендую первую, поскольку SSL надежно защищает данные.
Прежде чем использовать Curl с функциями SSL, необходимо загрузить из сети и отдельно установить пакет OpenSSL. Двоичные файлы OpenSSL for Windows можно загрузить с сайта проекта GnuWin32 SourceForge по адресу . На этом сайте имеется и много других полезных инструментов, портированных в Windows.
Следует загрузить и установить пакет OpenSSL, затем скопировать два DLL-файла в каталог system32:
Copy "C:Program FilesGnuWin32 binlibeay32.dll" %windir%system32 copy "C:Program FilesGnuWin32 binlibssl32.dll" %windir%system32
После этого можно установить Curl. SSL-совместимые двоичные файлы Curl для Windows можно найти по адресу http://curl.haxx.se/latest.cgi?curl=win32-ssl-sspi . Новейшая версия, curl 7.15.0, находится в win32-ssl-sspi.zip, который содержит файл curl.exe и документацию.
После установки Curl следует убедиться в его работоспособности, введя команду
Curl http://isc.sans.org/ infocon.txt
Если на экране появится слово, обозначающее цвет (например, green), значит, Curl работает. В этом простом примере Curl извлекает содержание Infocon из Web-узла Internet Storm Center института SANS. Green означает, что Internet функционирует нормально и серьезных угроз не обнаружено. Если же вместо green на экране появляются слова yellow, orange или red, то отложите эту статью и посетите сайт http://isc.sans.org , чтобы узнать о состояниях повышенной опасности в Internet. В случае ошибки необходимо проверить правильность установки Curl.
В сущности, Curl извлекает Web-страницу, а затем выдает исходный текст HTML страницы на консоль. Однако возможности утилиты шире. Curl располагает встроенной функцией проверки ошибок. Например, команда
Curl http://noserverhere
выдает ошибку Curl: (6) Could not resolve host: noserverhere; Host not found. Коды ошибок можно использовать в сценариях, чтобы проверить доступность Web-страницы или реакцию Web-сервера. Например, если использовать Curl для ежедневного извлечения Web-страницы, в частности суточной статистики Web-узла, можно дополнить сценарий исходным текстом, отыскивающим коды ошибок. Если Curl выдает код ошибки Curl: (7) couldn?t connect to host, то можно немедленно передать предупреждение или отправить сообщение по электронной почте.
Извлечение шифрованных данных
Одно из важнейших достоинств Curl - совместимость с SSL. Запрошенные страницы HTTPS передаются через сеть в зашифрованном виде, а затем Curl выводит на экран восстановленный текст. Кроме того, Curl проверяет сертификаты - дату завершения действия сертификата, соответствие имени хост-компьютера хост-имени в сертификате и уровень доверия к корневому сертификату - и предупреждает, если сертификат некорректен. Параметр -cacert позволяет указать определенный файл сертификата. Проверка сертификатов отменяется с помощью параметра -k. Альтернативный подход - использовать параметр -insecure.
Не только для WWW
Возможности Curl шире простой пересылки файлов через Internet. С помощью Curl можно быстро получить список каталогов FTP-сайта:
Curl ftp://myftpsite
Чтобы увидеть подкаталоги сайта, следует ввести команду
Curl ftp://myftpsite/subdir/
Для загрузки файла из сети достаточно указать в URL имя файла. В следующем примере файл с именем readme.txt загружается прямо из командной строки и отображается на экране:
Curl ftp://ftp.microsoft.com/ deskapps/games/readme.txt
Нередко проще подготовить сценарий с Curl для ввода FTP-файлов, чем использовать команду FTP интерактивно.
По умолчанию данные выводятся непосредственно на консоль, но их можно перенаправить в файл с помощью параметров -o и -O. Чтобы получить страницу и сохранить ее на диске, следует указать параметр -o. Параметр -O сохраняет полученную страницу в локальном файле, и Curl извлекает имя удаленного документа. Если в URL имя файла не указано, то эта операция закончится неудачей. Если использовать Curl для передачи на Web-узел запроса без имени файла, но нужно сохранить результат в файле, можно указать имя файла в командной строке, например:
Аутентификация
Curl обеспечивает методы аутентификации Basic, Digest и интегрированный. На большинстве сайтов доступ к страницам с аутентификацией на базе форм можно получить с использованием функций отправки Curl, что будет продемонстрировано чуть ниже. Это значит, что можно передать данные формы, в частности имя пользователя и пароль, на удаленный Web-узел, на Web-странице которого выводится запрос на ввод информации. Для пересылки учетных данных можно использовать параметр -u или вставить их в URL, что традиционно делается в FTP, например:
Curl ftp://username: password@myhtmlsite
С помощью Curl приемы, заимствованные из FTP, можно перенести в HTTP, как в следующем примере:
Curl http://username:password @myhtmlsite/default.htm
Curl также обеспечивает доступ к Web-страницам через proxy-сервер. Поэтому Curl можно настроить на использование proxy-сервера для аутентификации в режимах Basic, Digest и NTLM.
Читайте документацию
В одной статье трудно охватить все многочисленные функции Curl, среди которых и загрузка файлов на сервер (-T), и просмотр только информации в заголовке HTTP (-I), и просмотр всех данных в детальном режиме (-V), и скрытый вывод (-s). Я рекомендую более подробно ознакомиться с функциями Curl в руководстве, опубликованном по адресу http://curl.haxx.se/docs .
Пример использования Curl
Ознакомившись с основами Curl, рассмотрим простой пример извлечения данных из Web-узла при заданных входных данных. Построим простой инструмент Whois, который демонстрирует простоту и удобство применения Curl и процедуру отправки данных на Web-узел с использованием параметра -d. В данном примере Curl посылает IP-адрес на Web-узел Arin Whois, а затем извлекает результаты из этого сайта. Whois отыскивает информацию о владельце IP-адреса.
Перед началом работы важно исследовать Web-узел, так как в исходном тексте каждого сайта есть свои особенности, и Curl не всегда одинаково работает с любыми сайтами. Предварительное посещение сайта позволяет собрать необходимую информацию для работы Curl. В данном примере я воспользовался браузером, чтобы посетить Web-узел http://www.arin.net/whois/ , и обратил внимание, что на сайте имеется единственное поле ввода данных, в котором посетители указывают интересующий их IP-адрес. Необходимо получить детали этого поля, которое представляет собой часть Web-формы. В данном примере используется Perl-сценарий formfind.pl (http://cool.haxx.se/cvs.cgi/curl/perl/contrib/ formfind?rev=HEAD&content-type=text/vnd.viewcvs-markup ). Сценарий Formfind.pl преобразует данные формы в удобные выходные результаты и упрощает ручной поиск данных в HTML. Конечно, для запуска Formfind на компьютере должен быть развернут Perl. Хороший пакет Win32 Perl можно заказать на сайте ActiveState ActivePerl по адресу http://www.activestate.com .
Рассмотрим пример более подробно. Во-первых, обратимся к Web-узлу, содержащему форму, которая запрашивает информацию:
Curl -o whoisOutputFile http://www.arin.net/whois/
Эта команда извлекает страницу Whois из http://www.arin.net и сохраняет ее в текстовом файле whoisOutputFile, который содержит исходный текст HTML, воспроизводимый браузером при посещении сайта.
Затем необходимо найти и выделить данные формы:
./formfind.pl
Formfind выдает переменные формы и их возможные величины. В данном примере выходные результаты имеют довольно простой вид (см. экран 1 ).
Следует обратить внимание на данные формы Input с именем queryinput. Это текстовое поле, в которое Curl должен послать искомый IP-адрес. Конкретный IP-адрес не имеет значения - в данном примере использовался адрес Microsoft. С помощью параметра -d искомый IP-адрес пересылается в поле queryinput:
Curl -d "queryinput= 207.46.133.140" http://ws.arin.net/cgibin/ whois.pl
Команда Curl с параметром -d отыскивает данные в форме, в данном случае queryinput, которые представляют собой искомый IP-адрес. При этом меняется целевой адрес; форма должна передавать данные на новый URL, который представляет сценарий whois.pl. Новый целевой адрес можно увидеть на выходе formfind на экране 1.
В данном примере также получен исходный текст HTML ответа Whois, но он скрыт группой тэгов HTML. По умолчанию сообщение о статусе Curl показывает размер документа, процент выполнения и скорость пересылки. Выходные данные можно немного расчистить и отфильтровать имя организации, которой принадлежит IP-адрес. Статус Curl можно блокировать с помощью параметра -s. Команду следует выполнять через grep, чтобы получить только OrgName:
Curl -s -d "queryinput= 207.46.133.140" http://ws.arin.net/cgibin/ whois.pl | grep OrgName
В данном примере выходные результаты показывают, что OrgName - Microsoft Corp.
@echo off curl -k -s -d "queryinput= %1" http://ws.arin.net/cgibin/ whois.pl | grep OrgName
В этой статье речь пойдет о таком мощном инструменте как cURL, а также о библиотеке для php, которая предоставляет доступ к этому инструменту — libcurl. Для чего все это нужно? Для связи с сервером по протоколам передачи данных, например, http или ftp. Остальные протоколы нам не особо интересны, если кто-то хочет углубляться в эту тему, то придется уже копать англоязычные ресурсы, а в этой статье будут основы и примеры использования.
Что вообще такое cURL и libcurl? Общие моменты
Итак, библиотека libcurl предоставляет нам возможность передачи данных на сервер, и получения ответов от него. Что нам это дает? Возможность эмуляции поведения пользователя или ! Вы можете получать содержимое страниц для последующего парсинга, можете получать заголовки ответов сервиса и программно авторизироваться на сайтах, делать скрипты постинга сообщений (например, в твиттер или на форумах) или информации. Все ограничивается лишь вашей фантазией!
Установка cURL на Denwer (Денвер). Как начать пользоваться libcurl?
Первое, что мы должны сделать, это установить библиотеку. На локальном компьютере я пользуюсь сборкой Denwer, как и подавляющее большинство начинающих вебмастеров, на которых и рассчитана статья. Опытные пользователи, которые самостоятельно устанавливают связку php+apache+mysql смогут установить и cURL, не мне объяснять им как это делается;) А мы, новички, пользуемся готовыми решениями, чтобы было проще. Поэтому, устанавливаем libcurl следующим образом:
- Скачиваем готовый пакет расширений «PHP5: дополнительные модули ».
- Соответственно, устанавливаем его. Ничего сложного, согласитесь:)
- Открываем в блокноте (я всегда рекомендую Notepad++) файл:
X:/webservers/usr/local/php5/php.ini //где X - ваш диск, куда установлен вебсервер
и убираем точку с запятой в начале сроки:
;extension=php_curl.dll
- Делаем рестарт сервера Денвер.
Готово. Чтобы проверить работоспособность библиотеки можете вызвать функцию phpinfo() и найти там строчку: cURL support enabled. Поздравляю с первой победой.
Описание cURL и первые шаги
Для началом работы с инструментом, его нужно инициализировать. Делается это следующим образом:
$ch = curl_init();
Мы использовали функцию инициализации сессии cURL. При этом, можно задать URL сразу, вот так:
$ch = curl_init("https://сайт");
А можно сделать это потом, в опциях. Порядок установки опций не имеет значения. Делается это другой функцией:
Curl_setopt (resource ch, string option, mixed value)
Первый параметр этой функции, то есть resource ch мы уже создали чуть выше, а вот параметров option и value очень много. Я думаю, что не стоит копипастить сюда их все, а достаточно лишь дать ссылку на подробное описание функции, надеюсь никто не обидится: curl_setopt .
Приведу пример установки опций как раз на примере URL:
$url = "https://сайт"; curl_setopt($ch, CURLOPT_URL,$url);
Еще парочка примеров задания опций: давайте получим заголовок ответа сервера, при этом не будем получать саму страницу:
Curl_setopt($ch, CURLOPT_HEADER, 1); // читать заголовок curl_setopt($ch, CURLOPT_NOBODY, 1); // читать ТОЛЬКО заголовок без тела
Итак, мы инициализировали сессию, задали нужные нам параметры, теперь выполняем получившийся запрос, закрываем сессию и выводим результат:
$result = curl_exec($ch); curl_close($ch); echo $result;
В итоге получаем наш первый полностью рабочий пример использования библиотеки libcurl:
$ch = curl_init(); $url = "https://сайт"; curl_setopt($ch, CURLOPT_URL,$url); curl_setopt($ch, CURLOPT_HEADER, 1); // читать заголовок curl_setopt($ch, CURLOPT_NOBODY, 1); // читать ТОЛЬКО заголовок без тела $result = curl_exec($ch); curl_close($ch); echo $result;
Как оно работает, надеюсь, понятно, ведь мы рассмотрели каждый шаг по отдельности:) В результате мы получаем заголовок HTTP ответа от сервера, который чуть ниже обязательно разберем, чтобы лучше понимать все этапы взаимодействия браузера и сервера:
HTTP/1.1 200 OK Server: nginx/1.2..php 1
Великолепно! Мы получили заголовок ответа от сервера и опробовали библиотеку в действии. Чем это нам полезно? Тем, что теперь вы примерно представляете себе последовательность действий при работе с cURL:
- Инициализировать сессию (curl_init)
- Задать нужные нам опции (curl_setopt)
- Выполнить полученный запрос (curl_exec)
- Завершить сессию (curl_close)
Структура заголовка HTTP запроса
Для примера я обратился к странице ya.ru и в просмотрел сформированный запрос браузера и полученный от сервера ответ. Вот и они:
Запрос
GET / HTTP/1.1
— Пытаемся получить страницу по адресу /, то есть главную, находящуюся в корне папки. Используем протокол версии 1.1.
User-Agent: Opera/9.80 (Windows NT 6.1; WOW64) Presto/2.12.388 Version/12.14
— Представляемся серверу, мы — браузер Опера.
Host: ya.ru
— Доменное имя запрашиваемого ресурса.
Accept: text/html, application/xml;q=0.9, application/xhtml+xml, image/png, image/webp, image/jpeg, image/gif, image/x-xbitmap, */*;q=0.1
— Список допустимых форматов ресурса.
Accept-Language: ru-RU,ru;q=0.9,en;q=0.8
— Список поддерживаемых языков.
Accept-Encoding: gzip, deflate
— Поддерживаемые способы кодирования.
Cookie: yandexuid=ХХХХХ
— Куки, при необходимости.
Connection: Keep-Alive
— Просим не разрывать соединение и оставаться на связи.
Ответ
HTTP/1.1 200 Ok
— Получаем ответ с кодом 200, значит все ОК.
Server: nginx
— Сервер представился — это nginx.
Date: Sun, 10 Mar 2013 14:10:50 GMT
— Текущие дата и время на сервере.
Content-Type: text/html; charset=UTF-8
— Тип контента и кодировка.
Connection: close
— Сервер не хочет поддерживать с нами постоянного соединения, поэтому сразу же его закрывает. Для следующего запроса будет установлено новое соединение.
Cache-Control: no-cache,no-store,max-age=0,must-revalidate
— Управление кэшированием. В данном случае оно отключено.
Expires: Sun, 10 Mar 2013 14:10:50 GMT
— Дата предполагаемого истечения срока действия сессии. В нашем случае оно совпадает с временем открытия, так как сервер тут же его закрыл, сразу после обработки.
Last-Modified: Sun, 10 Mar 2013 14:10:50 GMT
— Время последней модификации.
Content-Encoding: gzip
— Способ кодирования информации.
Полный список всех параметров, которые можно встретить в заголовке HTTP запроса можно посмотреть на википедии .
Теперь вы примерно представляете как общаются между собой ваш браузер и web-сервер. Это очень полезно знать и понимать, ведь мы будем пытаться эмулировать действия браузера с помощью библиотеки libcurl. Идем дальше.
Пример работы с библиотекой
Я считаю, что после того, как некоторые общие моменты уже ясны и вроде бы все понятно, то самое время переходить к практике и на примере уже оттачивать свое мастерство. Лично у меня всегда сразу руки чешутся все попробовать на практике:)
Раз уж cURL так хорош для парсеров, то рассмотрим функцию получения кода страницы по ее адресу. При этом на выходе получим массив с заголовком, содержимым страницы и даже коды ошибок, если что-то пойдет не так.
Function get_web_page($url) { $uagent = "Opera/9.80 (Windows NT 6.1; WOW64) Presto/2.12.388 Version/12.14"; $ch = curl_init($url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); // возвращает веб-страницу curl_setopt($ch, CURLOPT_HEADER, 0); // не возвращает заголовки curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1); // переходит по редиректам curl_setopt($ch, CURLOPT_ENCODING, ""); // обрабатывает все кодировки curl_setopt($ch, CURLOPT_USERAGENT, $uagent); // useragent curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 120); // таймаут соединения curl_setopt($ch, CURLOPT_TIMEOUT, 120); // таймаут ответа curl_setopt($ch, CURLOPT_MAXREDIRS, 10); // останавливаться после 10-ого редиректа $content = curl_exec($ch); $err = curl_errno($ch); $errmsg = curl_error($ch); $header = curl_getinfo($ch); curl_close($ch); $header["errno"] = $err; $header["errmsg"] = $errmsg; $header["content"] = $content; return $header; }
Входные параметры:
url
— адрес страницы или сайта.
Значения выходных параметров (массив с тремя элементами):
header[‘errno’]
— если что-то пошло не так, то тут будет код ошибки.
header[‘errmsg’]
— здесь при этом будет текст ошибки.
header[‘content’]
— собственно сама страница\файл\картинка и т.д.
Используем функцию, например, так:
$result = get_web_page("https://ya.ru"); if (($result["errno"] != 0)||($result["http_code"] != 200)) { echo $result["errmsg"]; } else { $page = $result["content"]; echo $page; }
Все должно пройти без ошибок и вы получите код страницы в переменной $page . Если же попробовать получить несуществующую страницу yaaaaaaaaaaaa.ru, то получим ошибку:
Could not resolve host: yaaaaaaaaaaaa.ru; Host not found
Все обрабатывается корректно и красиво:)
Дальше с кодом страницы можно делать все что угодно, например, парсить регулярками. Но это все в следующих уроках, а пока что остановимся на этом.
Применение libcurl с языками C и Python
Разрабатывать приложения, опирающиеся на протоколы уровня приложений, такие как HTTP и FTP, не очень трудно, но и не тривиально. К тому же такая разработка не находится в центре внимания, поскольку в большинстве случаев гораздо важнее то, что лежит выше этих протоколов. Libcurl как раз и интересен тем, что делает акцент на приложение, а не на преходящий аспект разработки. Отметим, что не многие приложения имеют свой собственный стек TCP/IP – ведь повторное использование всего, что только можно, минимизирует нагрузку на программиста и повышает надежность приложения.
Эта статья начинается с краткого введения в протоколы прикладного уровня, а затем переходит к изучению cURL, libcurl и их применению.
Web-протоколы
Разработка современных приложений существенно отличается от того, что было в недавнем прошлом. Сегодня приложения должны поддерживать связь через сеть или Интернет, предоставляя в распоряжение пользователей сетевой API или интерфейс, а также обеспечивать гибкость посредством пользовательских сценариев. Как правило, современные приложения экспортируют Web-интерфейс с помощью HTTP и передают уведомления о нештатных ситуациях посредством Simple Mail Transport Protocol (SMTP). Эти протоколы позволяют передавать Web-браузеру, работающему в устройстве, конфигурацию или статус и принимать от устройств стандартные сообщения на стандартный клиент электронной почты (соответственно через HTTP и SMTP).
Эти Web-сервисы, как правило, построены поверх уровня сокетов стека сетевых протоколов (рисунок 1). Уровень сокетов реализует API, который восходит к операционной системе Berkeley Software Distribution (BSD) и изолирует детали нижележащих протоколов транспортного и сетевого уровней.
Рисунок 1. Стек сетевых протоколов и libcurl
Web-сервисы обеспечивают взаимодействие между протоколами клиента и сервера. В контексте HTTP сервер – это оконечное устройство, а клиент – браузер в удаленной точке. Для SMTP сервер – это почтовый шлюз или удаленный пользователь, а клиент – оконечное устройство. В некоторых случаях взаимодействие протоколов происходит в два этапа (запрос и ответ), а в других для поддержания связи требуется гораздо больше трафика. Такое взаимодействие может создать значительные трудности, которые преодолеваются с помощью API, таких как libcurl.
Введение в cURL
Происхождение и содержание cURL
cURL предложил Даниель Штенберг, но вклад в разработку внесли свыше 600 программистов. Бесспорно, это полезная технология с широкой областью применения.
Первоначально cURL разработан как средство перемещения файлов между конечными точками с использованием различных протоколов, таких как FTP, HTTP, SCP и другие. Сначала это была утилита командной строки, но теперь это также библиотека с привязками более чем к 30 языкам. Так что теперь, вместо того чтобы использовать cURL из командной строки, можно создавать приложения, которые включают в себя эти важные функции. Библиотека libcurl также переносима и поддерживает Linux®, IBM® AIX®, BSD, Solaris и многие другие варианты UNIX®.
Получение и установка cURL/libcurl
Получить и установить libcurl легко, но процесс зависит от дистрибутива Linux. На Ubuntu эти пакеты можно установить с помощью утилиты apt-get . Две следующие строки показывают, как установить libcurl и Python-привязки для libcurl:
$ sudo apt-get install libcurl3 $ sudo apt-get install python-pycurlУтилита apt-get гарантирует соблюдение всех зависимостей в процессе установки.
cURL в командной строке
cURL начинался как инструмент командной строки для передачи данных с использованием синтаксиса Uniform Resource Locator (URL). Ввиду популярности этой функции в форме командной строки была создана библиотека для ее интеграции в приложения. Сегодня cURL для командной строки служит оболочкой библиотеки cURL. Эта статья начинается с изучения cURL в командной строке, а затем углубляется в использование этой утилиты в качестве библиотеки.
Две типичных области применения cURL – это передача файлов с использованием протоколов HTTP и FTP. cURL предоставляет простой интерфейс к этим и другим протоколам. Чтобы извлечь файл из Web-сайта с помощью HTTP, достаточно указать cURL имя локального файла, в который нужно записать Web-страницу, а также URL Web-сайта и файл для передачи. Слишком много слов для той простой командной строки, которая приведена в листинге 1.
Листинг 1. Пример использования cURL для извлечения файла с Web-сайта
$ curl -o test html www.exampledomain.com % Total % Received % Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed 100 43320 100 43320 0 0 55831 0 --:--:-- --:--:-- --:--:-- 89299 $Обратите внимание: я указал домен, а не файл, так что получу корневой файл (index.html). Чтобы передать этот файл на сайт FTP с использованием cURL, нужно указать файл для загрузки с опцией -T , а затем ввести URL FTP-сайта и путь к файлу (листинг 2).
Листинг 2. Пример использования cURL для загрузки файла на FTP-сайт
$ curl -T test.html ftp://user:[email protected]/ftpdir/ % Total % Received % Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed 100 43320 0 0 100 43320 0 38946 0:00:01 0:00:01 --:--:-- 124k $Бывает ли проще? Достаточно освоить несколько простых моделей, и cURL окажется предельно простым в применении. Но многообразие имеющихся опций очень велико – запрос помощи из командной строки cURL (--help) выводит 129 строк. Большое число опций позволяет управлять всем – от многословия до безопасности и различных зависящих от протокола настраиваемых элементов.
С точки зрения разработчика, это не самый приятный аспект cURL. Углубимся в библиотеку cURL и посмотрим, как добавить эти протоколы передачи файлов в свое приложение.
cURL как библиотека
Если вы наблюдали за языками сценариев на протяжении последних 10 лет, то заметили явные изменения в их составе. Такие языки сценариев, как Python, Ruby, Perl и многие другие включают не только уровень сокетов, как C или C++, но и интерфейсы протокола прикладного уровня. Эти языки сценариев содержат высокоуровневые функции, которые делают тривиальным, например, создание сервера или клиента HTTP. Библиотека libcurl добавляет функциональность, схожую с такими языками, как C и C++, но таким образом, что можно работать с множеством языков. Libcurl примерно одинаково ведет себя во всех языках, которые поддерживает, хотя, так как эти языки могут значительно различаться (C и Scheme), могут различаться и способы обеспечения этого поведения.
Библиотека libcurl включает в себя функции, которые иллюстрируются в листингах и , в форме API, поэтому ее можно использовать в высокоуровневых языках (на сегодняшний день более 30). В этой статье представлены два примера применения libcurl. Первый исследует простой клиент HTTP на языке C (подходит для создания Web-пауков), а второй представляет собой простой клиент HTTP на Python.
HTTP-клиент на языке С
API для C обеспечивает два API поверх функциональности libcurl. Простой интерфейс – это простой синхронный API (т. е. при обращении к libcurl с запросом она выполняет его до конца или до сообщения об ошибке). Мультиинтерфейс обеспечивает контроль над libcurl, позволяя приложению выполнять несколько одновременных передач и управлять тем, куда и когда libcurl переносит данные.
В этом примере используется простой интерфейс. Этот API все же предоставляет некоторый контроль над процессом перемещения данных (с использованием функций обратного вызова), но при этом соответствует своему названию. В листинге 3 приводится пример на языке С для HTTP.
Листинг 3. Клиент HTTP на языке С с использованием простого интерфейса libcurl
#includeВ верхней части расположены необходимые файлы include , в том числе корневой файл cURL. Далее я определил пару переменных для передачи. Первая, wr_buf , представляет собой буфер, в который будут записываться входные данные. wr_index отражает индекс текущей записи буфера.
Опустимся к функции main , которая выполняет установку с помощью простого API. Все вызовы cURL проходят через указатель, который хранит состояние конкретного запроса. Он определен как CURL pointer reference. Этот пример создает также специальный возвратный код, называемый CURLcode . Перед использованием любых функций libcurl нужно вызывать curl_easy_init , чтобы получить указатель CURL . Далее обратите внимание на несколько вызовов функции curl_easy_setopt . Это настройки указателей для конкретной операции. Для этих вызовов вводится указатель, команда и опция. Сначала в этом примере применяется оператор CURLOPT_URL для задания URL извлекаемых данных. Затем следует CURL_WRITEDATA для создания контекстной переменной (в нашем случае это внутренняя переменная записи ошибок). Наконец, CURLOPT_WRITEFUNCTION определяет функцию, которую нужно вызвать при наличии данных. API вызовет эту функцию один или несколько раз с данными, считанными им после сигнала запуска.
Чтобы начать передачу, вызовите функцию curl_easy_perform . Ее задача заключается в выполнении передачи с учетом предварительно заданной конфигурации. При вызове этой функции она возвращает результат только после успешной передачи или ошибки. Последние элементы main предназначены для передачи возвращаемых статусов, запуска чтения страницы и, наконец, для очистки с помощью функции curl_easy_cleanup (по завершении операции).
Теперь рассмотрим функцию write_data . Эта функция обратного вызова, которая вызывается, когда данные по конкретной операции получены. Обратите внимание, что когда данные считываются с Web-сайта, они записываются к вам (write_data). Обратный вызов содержит буфер (с готовыми данными), число элементов и их размер (их произведение дает общий объем данных в буфере), а также указатель контекста. Первая задача заключается в том, чтобы обеспечить достаточную емкость буфера (wr_buf) для записи данных. В противном случае он устанавливает указатель контекста и возвращает ноль, что указывает на наличие проблемы. Иначе, он копирует данные из буфера cURL в ваш буфер и наращивает индекс, указывая на следующее место для записи. В этом примере строка завершается, так что впоследствии к нему можно применить printf . Наконец, он возвращает в libcurl количество обработанных байтов. Это говорит libcurl о том, что данные приняты, и их можно удалить. Вот и все – не правда ли, простой способ считать файл с Web-сайта в память?
HTTP-клиент на Python
В этом разделе приводится пример, подобный HTTP-клиенту на языке С, но на этот раз написанный на Python. Python – это полезный объектно-ориентированный язык сценариев, который отлично подходит для создания прототипов и коммерческого программного обеспечения. В примере предполагается, что вы немного знакомы с Python, но он используется очень мало, так что глубокие знания не потребуются.
Код простого HTTP-клиента, написанный на языке Python с использованием pycurl , приведен в листинге 4.
Листинг 4. HTTP-клиент на Python с использованием интерфейса pycurl из libcurl
import sys import pycurl wr_buf = "" def write_data(buf): global wr_buf wr_buf += buf def main(): c = pycurl.Curl() c.setopt(pycurl.URL, "http://www.exampledomain.com") c.setopt(pycurl.WRITEFUNCTION, write_data) c.perform() c.close() main() sys.stdout.write(wr_buf)Создание прототипа на Python
Здесь иллюстрируется одно из преимуществ языка Python при создании прототипов. Довольно широкая функциональность достигается при небольшом количестве кода. На С можно получить более высокую производительность, но если вашей целью является быстрое создание кода для проверки идеи, лучше воспользоваться высокоуровневыми языками сценариев, такими как Python.
Этот код значительно проще, чем версия на C. Он начинается с импортирования необходимых модулей (стандартного системного модуля sys и модуля pycurl). Далее определяется буфер записи (wr_buf). Как и в программе на C, я декларирую функцию write_data . Обратите внимание, что эта функция принимает один аргумент: буфер данных, считанных с сервера HTTP. Я просто взял этот буфер и добавил его к глобальному буферу записи. Функция main начинает с создания указателя Curl , затем использует для записи методы setopt для определения URL и WRITEFUNCTION . Она вызывает метод perform для запуска передачи и закрывает указатель. Наконец, она вызывает функцию main и передает буфер записи в stdout . Обратите внимание, что в данном случае указатель ошибки контекста не нужен, поскольку используется конкатенация строк Python, а значит, не нужно использовать строку со статически заданным размером.
Что дальше
Эта статья лишь "скребет по поверхности" libcurl, учитывая огромное количество протоколов и языков, поддерживаемых библиотекой. Но, надеюсь, она демонстрирует, как легко создавать приложения, использующие протоколы уровня приложений, такие как HTTP. Web-сайт libcurl (см. раздел ) содержит большое количество примеров и значительный объем полезной документации. Поэтому в следующий раз при разработке Web-браузера, спайдера или другого приложения, которому требуется протокол уровня приложения, попробуйте libcurl. Это наверняка ускорит процесс разработки, и вы получите от него удовольствие.
CURL - это пакет программного обеспечения, состоящий из утилиты командной строки и библиотеки для передачи данных с использованием синтаксиса URL.
CURL поддерижвает множество протоколов, среди них DICT, FILE, FTP, FTPS, Gopher, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, POP3, POP3S, RTMP, RTSP, SCP, SFTP, SMTP, SMTPS, Telnet и TFTP.
Загрузить отдельный файл
Следующая команда получит содержимое URL и отобразит его в стандартном выводе (т. е. в вашем терминале).
Curl https://mi-al.ru/ > mi-al.htm % Total % Received % Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed 100 14378 0 14378 0 0 5387 0 --:--:-- 0:00:02 --:--:-- 5387
Сохранение вывода cURL в файлМы можем сохранить результат команды curl в файл, используя опции -o/-O.
- -o (o нижнего регистра) результат будет сохранён в файле, заданном в командной строке
- -O (O верхнего регистра) имя файла будет взято из URL и будет использовано для сохранения полученных данных.
$ curl -o mygettext.html http://www.gnu.org/software/gettext/manual/gettext.html
Теперь будет сохранена страница gettext.html в файле с названием ‘mygettext.html’. Когда curl запущена с опцией -o, она отображает шкалу прогресса загрузки следующим образом.
% Total % Received % Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed 66 1215k 66 805k 0 0 33060 0 0:00:37 0:00:24 0:00:13 45900 100 1215k 100 1215k 0 0 39474 0 0:00:31 0:00:31 --:--:-- 68987
Когда вы используете curl -O (O верхнего регистра), она сама по себе сохранит содержимое в файл под названием ‘gettext.html’ на локальной машине.
$ curl -O http://www.gnu.org/software/gettext/manual/gettext.html
Примечание: Когда curl должна писать данные в терминал, она отключает шкалу прогресса, чтобы не было путаницы в напечатанных данных. Мы можем исользовать ‘>’|’-o’|’-O’ опции для передачи результатов в файл.
Выборка нескольких файлов одновременно
Мы можем загрузить несколько файлов за один раз, задав все URL в командной строке.
Curl -O URL1 -O URL2
Команда ниже загрузит оба index.html и gettext.html и сохранит их с теми же именами в текущей директории.
Curl -O http://www.gnu.org/software/gettext/manual/html_node/index.html -O http://www.gnu.org/software/gettext/manual/gettext.html
Пожалуйста, обратите внимание, когда мы загружаем несколько файлов с одного сервера как показано выше, curl попытается повторно использовать соединение.
Следуем за HTTP Location в заголовках с опцией -L
По умолчанию, CURL не следует за HTTP Location в заголовках (редиректы). Когда запрошенная веб-страница перемещена в другое место, то соответствующий ответ будет передан в заголовках HTTP Location.
Например, когда кто-то печатает google.com в строке браузера из своей страны, они автоматически будут перенаправлены на ‘google.co.xx’. Это делается на основе заголовка HTTP Location как показано ниже.
Curl https://www.google.com/?gws_rd=ssl
302 Moved
The document has moved here.Приведённый выше вывод говорит, что запрашиваемый документ был перемещён в ‘
Скрыто от гостей
.Вы можете указать curl следовать редиректам, это делается с использованием опции -L как показано ниже. Теперь будет загружен исходный код html с
Скрыто от гостей
.Curl -L https://www.google.com/?gws_rd=ssl
Вообновление предыдущей закачкиИспользуя опцию -C вы можете продолжить закачку, которая была остановлена по каким-либо причинам. Это будет полезным при обрыве загрузки больших файлов.
Если мы говорим ‘-C -’, то curl будет искать, с какого места возобновить загрузку. Мы также можем задать ‘-C <смещение>’. Заданное смещение байт будет пропущено от начала исходного файла.
Начните большую загрузку с curl и нажмите Ctrl-C для остановки посреди закачки.
$ curl -O http://www.gnu.org/software/gettext/manual/gettext.html ############## 20.1%
Закачка была остановлена на 20.1%. Используя “curl -C -” мы можем продолжить загрузку с того места, где мы остановились. Теперь загрузка продолжиться с 20.1%.
Curl -C - -O http://www.gnu.org/software/gettext/manual/gettext.html ############### 21.1%
Ограничение скорости передачи данныхВы можете ограничить величину скорости передачи данных опцией –limit-rate. Вы можете передать максимальную скорость в качестве аргумента.
$ curl --limit-rate 1000B -O http://www.gnu.org/software/gettext/manual/gettext.html
Команда выше ограничит скорость передачи на 1000 байт/секунду. curl может использовать скорость выше на пиках. Но средняя скорость будет примерно 1000 байт/секунду.
Ниже показан индикатор прогресса для представленной выше команды. Вы можете видеть, что текущая скорость в районе 1000 байт.
% Total % Received % Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed 1 1215k 1 13601 0 0 957 0 0:21:40 0:00:14 0:21:26 999 1 1215k 1 14601 0 0 960 0 0:21:36 0:00:15 0:21:21 999 1 1215k 1 15601 0 0 962 0 0:21:34 0:00:16 0:21:18 999
Загрузить файл только если он изменён до/после заданного времениВы можете получить файлы, которые были изменены после определённого времени, используя опцию -z в curl. Это будет работать и для FTP и для HTTP.
Команда выше загрузит yy.html только если он изменялся позднее чем заданная дата и время.
Команда выше загрузит файл file.html, если он изменялся до заданной даты и времени. Наберите ‘man curl_getdate’ чтобы узнать больше о различных поддерживаемых синтаксисах для выражений даты.
Прохождение аутентификации HTTP в cURL
Иногда веб-сайты требуют имя пользователя и пароль для просмотра их содержимого. С помощью опции -u вы можете передать эти учётные данные из cURL на веб-сервер как показано ниже.
$ curl -u username:password URL
Примечание: По умолчанию curl использует базовую HTTP аутентификацию. Мы можем задать иные методы аутентификации используя –ntlm | –digest.
cURL может также использоваться для загрузки файлов с FTP серверов. Если заданный FTP путь является директорией, то по умолчанию будет выведен список файлов в ней.
$ curl -u ftpuser:ftppass -O ftp://ftp_server/public_html/xss.php
Команда выше загрузит файл xss.php с ftp-сервера и сохранит его в локальной директории.
$ curl -u ftpuser:ftppass -O ftp://ftp_server/public_html/
Здесь URL отсылает к директории. Следовательно, cURL сделает список файлов и директорий по заданному URL адресу.
CURL поддерживает диапазоны заданные в URL. Когда дан диапазон, будут загружены соответствующие файлы внутри этого диапазона. Это будет полезным при загрузке пакетов с сайтов FTP зеркал.
$ curl ftp://ftp.uk.debian.org/debian/pool/main//
Команда выше сделает список всех пакетов в диапазоне a-z в терминале.
Выгрузка файлов на FTP-сервер
Curl также может использоваться для выгрузки на FTP-сервер с опцией -T.
$ curl -u ftpuser:ftppass -T myfile.txt ftp://ftp.testserver.com
Команда выше выгрузит файл с именем myfile.txt на FTP-сервер. Вы можете также выгрузить несколько файлов за один раз используя диапазоны.
$ curl -u ftpuser:ftppass -T "{file1,file2}" ftp://ftp.testserver.com
Опционально мы можем использовать “.” для получения из стандартного ввода и передачи его на удалённую машину.
$ curl -u ftpuser:ftppass -T - ftp://ftp.testserver.com/myfile_1.txt
Команда выше получит вывод от пользователя из стандартного ввода и сохранит содержимое на ftp-сервере под именем ‘myfile_1.txt’.
Вы можете задать ‘-T’ для каждого URL, и каждая пара адрес-файл будут определять что куда выгружать
Больше информации с увеличением вербальности и опцией трассировки
Вы можете узнать что происходит, используя опцию -v. Опция -v включает вербальный режим и будет печатать подробности.
Curl -v https://www.google.co.th/?gws_rd=ssl
Команда выше выведет следующее
* Rebuilt URL to: https://www.google.co.th/?gws_rd=ssl * Hostname was NOT found in DNS cache * Trying 27.123.17.49... * Connected to www.google.co.th (27.123.17.49) port 80 (#0) > GET / HTTP/1.1 > User-Agent: curl/7.38.0 > Host: www.google.co.th > Accept: */* > < HTTP/1.1 200 OK < Date: Fri, 14 Aug 2015 23:07:20 GMT < Expires: -1 < Cache-Control: private, max-age=0 < Content-Type: text/html; charset=windows-874 < P3P: CP="This is not a P3P policy! See https://support.google.com/accounts/answer/151657?hl=en for more info." * Server gws is not blacklisted < Server: gws < X-XSS-Protection: 1; mode=block < X-Frame-Options: SAMEORIGIN < Set-Cookie: PREF=ID=1111111111111111:FF=0:TM=1439593640:LM=1439593640:V=1:S=FfuoPPpKbyzTdJ6T; expires=Sun, 13-Aug-2017 23:07:20 GMT; path=/; domain=.google.co.th ... ... ...
Если вам нужно больше детальной информации, тогда вы можете использовать опцию –trace. Опция –trace включит полный дамп трассировки всех входящих/исходящих данных для заданного файла
curl dict://dict.org/d:girl:fd-eng-rus
220 pan.alephnull.com dictd 1.12.1/rf on Linux 3.14-1-amd64
Больше информации по DICT можно найти прочитав
Скрыто от гостей
.Использование прокси для загрузки файла
Мы можем указать cURL использовать прокси для определённых операций, это делается опцией -x. Нам нужно задать хост и порт прокси.
$ curl -x proxysever.test.com:3128 https://www.google.co.in/?gws_rd=ssl
Отправка электронной почты с использованием протокола SMTP в curlcURL также может быть использована для отправки электронной почты по протоколу SMTP. Вам нужно указать адрес от кого, адрес кому и IP адрес почтового сервера как показано ниже.
$ curl --mail-from [email protected] --mail-rcpt [email protected] smtp://mailserver.com
Когда команда будет введена, начнётся ожидание введения пользователем данных для письма. Когда вы закончите набирать сообщение, напечатайте. (точку) в качестве последней строки, и письмо будет немедленно отправлено.
Subject: Testing This is a test mail .
(PHP 4 >= 4.0.2, PHP 5, PHP 7)
curl_setopt — Устанавливает параметр для сеанса CURL
Список параметров
Дескриптор cURL, полученный из curl_init() .
Устанавливаемый параметр CURLOPT_XXX .
Значение параметра option .
bool :
| Параметр | Замечания | |
|---|---|---|
| CURLOPT_AUTOREFERER | TRUE для автоматической установки поля Referer: в запросах, перенаправленных заголовком Location: . | |
| CURLOPT_BINARYTRANSFER | TRUE для возврата необработанного ответа при использовании константы CURLOPT_RETURNTRANSFER . | С PHP 5.1.3 эта опция больше не требуется: необработанный вывод всегда возвращается при использовании опции CURLOPT_RETURNTRANSFER . |
| CURLOPT_COOKIESESSION | TRUE для указания текущему сеансу начать новую "сессию" cookies. Это заставит libcurl проигнорировать все "сессионные" cookies, которые она должна была бы загрузить, полученные из предыдущей сессии. По умолчанию, libcurl всегда сохраняет и загружает все cookies, вне зависимости от того, являются ли они "сессионными" или нет. "Сессионные" cookies - это cookies без срока истечения, которые должны существовать только для текущей "сессии". | |
| CURLOPT_CERTINFO | TRUE для вывода информации о сертификате SSL в поток STDERR при безопасных соединениях. | Добавлена в cURL 7.19.1. Доступна, начиная с версии PHP 5.3.2. Для корректной работы требует включенной опции CURLOPT_VERBOSE . |
| CURLOPT_CONNECT_ONLY | TRUE сообщает библиотеке, чтобы она провела необходимые аутентификацию прокси и настройку соединения, но не передавала данные. Эта опция реализована для HTTP, SMTP и POP3. | Добавлена в 7.15.2. Доступна с версии PHP 5.5.0. |
| CURLOPT_CRLF | TRUE для преобразования концов строк Unix в CRLF. | |
| CURLOPT_DNS_USE_GLOBAL_CACHE | TRUE для использования глобального кэша DNS. Этот параметр не является потокобезопасным и по умолчанию включен. | |
| CURLOPT_FAILONERROR | TRUE для подробного отчета при неудаче, если полученный HTTP-код больше или равен 400. Поведение по умолчанию возвращает страницу как обычно, игнорируя код. | |
| CURLOPT_FILETIME | TRUE для попытки получения даты модификации удаленного документа. Это значение может быть получено с помощью параметра CURLINFO_FILETIME из функции curl_getinfo() . | |
| CURLOPT_FOLLOWLOCATION | TRUE для следования любому заголовку "Location: " , отправленному сервером в своем ответе (учтите, что это происходит рекурсивно, PHP будет следовать за всеми посылаемыми заголовками "Location: " , за исключением случая, когда установлена константа CURLOPT_MAXREDIRS ). | |
| CURLOPT_FORBID_REUSE | TRUE для принудительного закрытия соединения после завершения его обработки так, чтобы его нельзя было использовать повторно. | |
| CURLOPT_FRESH_CONNECT | TRUE для принудительного использования нового соединения вместо закэшированного. | |
| CURLOPT_FTP_USE_EPRT | TRUE для использования EPRT (и LPRT) при активных FTP загрузках. Используйте FALSE для того, чтобы отключить EPRT и LPRT и использовать только PORT. | |
| CURLOPT_FTP_USE_EPSV | TRUE для первоначальной пробы команды EPSV при FTP передачах. Если команда не удалась, будет произведен обратный откат к PASV. Установите в FALSE для отключения EPSV. | |
| CURLOPT_FTP_CREATE_MISSING_DIRS | TRUE для создания отсутствующих директорий, если FTP-операция обнаруживает несуществующий путь. | |
| CURLOPT_FTPAPPEND | TRUE для записи удаленного файла в конец, вместо перезаписывания его поверх существующего файла. | |
| CURLOPT_TCP_NODELAY | Задает на постоянной основе должна ли опция TCP_NODELAY установлена или очищена (1 = установлена, 0 = очищена). По умолчанию опция очищается. | Доступна с версии PHP 5.2.1 для версий собранных с libcurl 7.11.2 или новее. |
| CURLOPT_FTPASCII | Псевдоним CURLOPT_TRANSFERTEXT . Используйте его вместо этого. | |
| CURLOPT_FTPLISTONLY | TRUE для возврата только списка имен из FTP директории. | |
| CURLOPT_HEADER | TRUE для включения заголовков в вывод. | |
| CURLINFO_HEADER_OUT | TRUE для отслеживания строки запроса дескриптора. | Доступен, начиная с версии PHP 5.1.3. Префикс CURLINFO_ употреблен специально. |
| CURLOPT_HTTPGET | TRUE для сброса метода HTTP-запроса в метод GET. Так как GET используется по умолчанию, этот параметр необходим только в случае, если метод запроса был ранее изменен. | |
| CURLOPT_HTTPPROXYTUNNEL | TRUE для туннелирования через указанный HTTP-прокси. | |
| CURLOPT_MUTE | TRUE для полного отключения сообщений функций cURL. | Удалена в cURL 7.15.5 (Можно использовать опцию CURLOPT_RETURNTRANSFER) |
| CURLOPT_NETRC | TRUE для считывания файла ~/.netrc на предмет логина и пароля для удаленного сайта, с которым устанавливается соединение. | |
| CURLOPT_NOBODY | TRUE для исключения тела ответа из вывода. Метод запроса устанавливается в HEAD. Смена этого параметра в FALSE не меняет его обратно в GET. | |
| CURLOPT_NOPROGRESS | TRUE для отмены индикатора прогресса при передачах cURL.
|
|
| CURLOPT_NOSIGNAL | TRUE для игнорирования любой функции cURL, посылающей сигналы PHP процессу. Этот параметр включен по умолчанию в многопоточных SAPIs для корректной работы таймаут параметров. | |
| CURLOPT_POST | TRUE для использования обычного HTTP POST. Данный метод POST использует обычный , обычно используемый в HTML-формах. | |
| CURLOPT_PUT | TRUE для загрузки файла методом HTTP PUT. Используемый файл должен быть установлен с помощью параметров CURLOPT_INFILE и CURLOPT_INFILESIZE . | |
| CURLOPT_RETURNTRANSFER | TRUE для возврата результата передачи в качестве строки из curl_exec() вместо прямого вывода в браузер. | |
| CURLOPT_SAFE_UPLOAD | TRUE для отключения поддержки префикса @ для загружаемых файлов в CURLOPT_POSTFIELDS , который означает, что значения, переданные с @ могут безопасно передаваться в виде полей. Вместо префикса можно использовать опцию CURLFile d. | Добавлена в PHP 5.5.0 со значением по умолчанию FALSE . В PHP 5.6.0 стала по умолчанию равна TRUE . |
| CURLOPT_SSL_VERIFYPEER | FALSE для остановки cURL от проверки сертификата узла сети. Альтернативные сверяемые сертификаты могут быть указаны с помощью параметра CURLOPT_CAINFO или директории с сертификатами, указываемой параметром CURLOPT_CAPATH . | По умолчанию равно TRUE начиная с версии cURL 7.10. Дистрибутив по умолчанию устанавливается начиная с версии cURL 7.10. |
| CURLOPT_TRANSFERTEXT | TRUE для использования ASCII режима при FTP передачах. При использовании LDAP данные возвращаются простым текстом вместо HTML. В Windows системах поток STDOUT не устанавливается в бинарный режим. | |
| CURLOPT_UNRESTRICTED_AUTH | TRUE для продолжения посылки логина и пароля при редиректах (при использовании CURLOPT_FOLLOWLOCATION ), даже при изменении имени хоста. | |
| CURLOPT_UPLOAD | TRUE для подготовки к загрузке файла на сервер. | |
| CURLOPT_VERBOSE | TRUE для вывода дополнительной информации. Записывает вывод в поток STDERR , или файл, указанный параметром CURLOPT_STDERR . |
Для следующих значений параметра option , параметр value должен быть типа integer :
| Параметр | Устанавливаемое значение value | Замечания |
|---|---|---|
| CURLOPT_BUFFERSIZE | Размер буфера, используемого при каждом чтении. Однако, нет никакой гарантии что данный запрос будет завершен. | Добавлен в версии cURL 7.10. |
| CURLOPT_CLOSEPOLICY |
Одна из констант CURLCLOSEPOLICY_*
.
|
Удалена в PHP 5.6.0. |
| CURLOPT_CONNECTTIMEOUT | Количество секунд ожидания при попытке соединения. Используйте 0 для бесконечного ожидания. | |
| CURLOPT_CONNECTTIMEOUT_MS | Количество миллисекунд ожидания при попытке соединения. Используйте 0 для бесконечного ожидания. Если библиотека libcurl скомпилирована с использованием стандартного системного преобразователя имен, то соединение будет по-прежнему использовать полносекундное ожидание в качестве тайм-аута с минимально допустимым тайм-аутом в 1 секунду. | Добавлен в версии cURL 7.16.2. Доступно, начиная с версии PHP 5.2.3. |
| CURLOPT_DNS_CACHE_TIMEOUT | Количество секунд, в течение которых в памяти хранятся DNS-записи. По умолчанию этот параметр равен 120 (2 минуты). | |
| CURLOPT_FTPSSLAUTH | Метод FTP аутентификации (в активном режиме): CURLFTPAUTH_SSL (сначала проверяется SSL), CURLFTPAUTH_TLS (сначала проверяется TLS) или CURLFTPAUTH_DEFAULT (cURL решает сама). | Добавлен в версии cURL 7.12.2. |
| CURLOPT_HTTP_VERSION | CURL_HTTP_VERSION_NONE (по умолчанию, CURL сама выбирает используемую версию), CURL_HTTP_VERSION_1_0 (принудительное использование HTTP/1.0), or CURL_HTTP_VERSION_1_1 (принудительное использование HTTP/1.1). | |
| CURLOPT_HTTPAUTH |
Можно использовать побитовый оператор | (или) для комбинации нескольких методов вместе. В этом случае cURL опросит сервер на предмет поддерживаемых методов авторизации и выберет лучший из них. CURLAUTH_ANY - это псевдоним CURLAUTH_BASIC | CURLAUTH_DIGEST | CURLAUTH_GSSNEGOTIATE | CURLAUTH_NTLM . CURLAUTH_ANYSAFE - это псевдоним CURLAUTH_DIGEST | CURLAUTH_GSSNEGOTIATE | CURLAUTH_NTLM . |
|
| CURLOPT_INFILESIZE | Ожидаемый размер файла, в байтах, при загрузке файла на удаленный сервер. Учтите, что использование этой опции не остановит дальнейшую посылку данных, превышающих это значение, так как посылаемые данные зависят от результата CURLOPT_READFUNCTION . | |
| CURLOPT_LOW_SPEED_LIMIT | Верхний порог скорости передачи данных, в байтах в секунду. Проверка происходит в течение CURLOPT_LOW_SPEED_TIME секунд, после чего PHP считает передачу слишком медленной и прерывает ее. | |
| CURLOPT_LOW_SPEED_TIME | Максимальное количество секунд, в течение которых скорость передачи не должна превышать CURLOPT_LOW_SPEED_LIMIT , иначе PHP пометит передачу как слишком медленную и прекратит ее. | |
| CURLOPT_MAXCONNECTS | Максимальное количество постоянных соединений. При достижении лимита для определения закрываемого соединения используется параметр CURLOPT_CLOSEPOLICY . | |
| CURLOPT_MAXREDIRS | Максимальное количество принимаемых редиректов. Используйте этот параметр вместе с параметром CURLOPT_FOLLOWLOCATION . | |
| CURLOPT_PORT | Альтернативный порт соединения. | |
| CURLOPT_POSTREDIR | Битовая маска, содержащая 1 (301 Moved Permanently), 2 (302 Found) и 4 (303 See Other), чтобы задавать должен ли метод HTTP POST обрабатываться при включенной опции CURLOPT_FOLLOWLOCATION , если произошел указанный тип перенаправления. | Добавлено в cURL 7.19.1. Доступно с PHP 5.3.2. |
| CURLOPT_PROTOCOLS |
Битовая маска из значений CURLPROTO_* . Данная маска ограничивает используемые libcurl протоколы. Это позволяет иметь libcurl, работающую с большим количеством протоколов, и ограничивать работу определенных передач только для некоторого их набора. По умолчанию, libcurl использует все поддерживаемые протоколы. Смотрите также параметр CURLOPT_REDIR_PROTOCOLS . Корректные значения протоколов: CURLPROTO_HTTP , CURLPROTO_HTTPS , CURLPROTO_FTP , CURLPROTO_FTPS , CURLPROTO_SCP , CURLPROTO_SFTP , CURLPROTO_TELNET , CURLPROTO_LDAP , CURLPROTO_LDAPS , CURLPROTO_DICT , CURLPROTO_FILE , CURLPROTO_TFTP , CURLPROTO_ALL |
|
| CURLOPT_PROXYAUTH | Методы авторизации HTTP, используемые при соединении с прокси-сервером. Используйте те же самые битовые маски, которые были описаны у параметра CURLOPT_HTTPAUTH . В данный момент для авторизации прокси поддерживаются только CURLAUTH_BASIC и CURLAUTH_NTLM . | Добавлен в версии cURL 7.10.7. |
| CURLOPT_PROXYPORT | Номер порта прокси-сервера, к которому осуществляется соединение. Этот номер также может быть установлен с помощью параметра CURLOPT_PROXY . | |
| CURLOPT_PROXYTYPE | Либо CURLPROXY_HTTP (по умолчанию), либо CURLPROXY_SOCKS5 . | Добавлен в версии cURL 7.10. |
| CURLOPT_REDIR_PROTOCOLS | Битовая маска из значений CURLPROTO_* . Данная битовая масска ограничивает протоколы используемые libcurl при редиректе (при включенном параметре CURLOPT_FOLLOWLOCATION ). Это позволяет ограничить набор используемых протоколов при редиректах для некоторых передач. По умолчанию, libcurl поддерживает все протоколы, кроме FILE и SCP. В версиях, предшествовавших 7.19.4, перенаправление использовалось для всех протоколов без исключения. Смотрите также описание параметра CURLOPT_PROTOCOLS для списка констант со значениями протоколов. | Добавлен в версии cURL 7.19.4. |
| CURLOPT_RESUME_FROM | Смещение начала передачи, в байтах. | |
| CURLOPT_SSL_VERIFYHOST | Используйте 1 для проверки существования общего имени в сертификате SSL. Используйте 2 для проверки существования общего имени и также его совпадения с указанным хостом. В боевом окружении значение этого параметра должно быть 2 (установлено по умолчанию). | Поддержка значения 1 убрана в cURL 7.28.1 |
| CURLOPT_SSLVERSION | Одна из констант CURL_SSLVERSION_DEFAULT (0), CURL_SSLVERSION_TLSv1 (1), CURL_SSLVERSION_SSLv2 (2), CURL_SSLVERSION_SSLv3 (3), CURL_SSLVERSION_TLSv1_0 (4), CURL_SSLVERSION_TLSv1_1 (5) или CURL_SSLVERSION_TLSv1_2 (6). | |
| CURLOPT_TIMECONDITION | Способ трактовки параметра CURLOPT_TIMEVALUE . Используйте CURL_TIMECOND_IFMODSINCE для возвращения страницы, только если она была изменена со времени, указанного в параметре CURLOPT_TIMEVALUE . Если страница не была изменена, вернется заголовок "304 Not Modified" , подразумевая, что параметр CURLOPT_HEADER установлен в TRUE . Используйте CURL_TIMECOND_IFUNMODSINCE для обратного эффекта. По умолчанию используется CURL_TIMECOND_IFMODSINCE . | |
| CURLOPT_TIMEOUT | Максимально позволенное количество секунд для выполнения cURL-функций. | |
| CURLOPT_TIMEOUT_MS | Максимально позволенное количество миллисекунд для выполнения cURL-функций. Если libcurl собрана с использованием обычного системного распознавателя имен, то этот промежуток соединения все еще будет использовать секундное округление таймаутов, с минимально разрешенным таймаутом в одну секунду. | Добавлен в версии cURL 7.16.2. Доступен, начиная с версии PHP 5.2.3. |
| CURLOPT_TIMEVALUE | Количество секунд, начиная с 1 января 1970 года. Это время будет использовано параметром CURLOPT_TIMECONDITION . По умолчанию, используется параметр CURL_TIMECOND_IFMODSINCE . | |
| CURLOPT_MAX_RECV_SPEED_LARGE | Если скорость скачки превысит это значение (указанное в байтах в секунду) в среднем в течение всей передачи, то скачка будет приостановлена для поддержания средней скорости меньше либо равной данному параметру. По умолчанию скорость не ограничивается. | |
| CURLOPT_MAX_SEND_SPEED_LARGE | Если загрузка на сервер превысит это значение (указанное в байтах в секунду) в среднем в течение всей передачи, то загрузка будет приостановлена для поддержания средней скорости меньше либо равной данному параметру. По умолчанию скорость не ограничивается. | Добавлен в версии cURL 7.15.5. Доступен, начиная с версии PHP 5.4.0. |
| CURLOPT_SSH_AUTH_TYPES | Битовая маска, состоящая из одной или более констант: CURLSSH_AUTH_PUBLICKEY , CURLSSH_AUTH_PASSWORD , CURLSSH_AUTH_HOST , CURLSSH_AUTH_KEYBOARD . Установите CURLSSH_AUTH_ANY для того, чтобы libcurl выбрал одну из них самостоятельно. | Добавлено в cURL 7.16.1. |
| CURLOPT_IPRESOLVE | Позволяет приложению выбрать вид IP адреса, с которым определяется имя хоста. Это необходимо, если используется имя хоста, которое получается с использованием более одной версии IP адреса. Возможными значениями могут быть CURL_IPRESOLVE_WHATEVER , CURL_IPRESOLVE_V4 , CURL_IPRESOLVE_V6 , и по умолчанию CURL_IPRESOLVE_WHATEVER . | Добавлено в cURL 7.10.8. |
Для следующих значений параметра option , параметр value должен быть типа string :
| Параметр | Устанавливаемое значение value | Замечания |
|---|---|---|
| CURLOPT_CAINFO | Имя файла, содержащего один или более сертификатов, с которыми будут сверяться узлы. Этот параметр имеет смысл только при использовании совместно с CURLOPT_SSL_VERIFYPEER . | Требует абсолютный путь. |
| CURLOPT_CAPATH | Директория, содержащая несколько CA сертификатов. Используйте этот параметр совместно с CURLOPT_SSL_VERIFYPEER . | |
| CURLOPT_COOKIE | Содержимое заголовка "Cookie: " , используемого в HTTP-запросе. Обратите внимание, что несколько cookies разделяются точкой с запятой с последующим пробелом (например, "fruit=apple; colour=red ") | |
| CURLOPT_COOKIEFILE | Имя файла, содержащего cookies. Данный файл должен быть в формате Netscape или просто заголовками HTTP, записанными в файл. Если в качестве имени файла передана пустая строка, то cookies сохраняться не будут, но их обработка все еще будет включена. | |
| CURLOPT_COOKIEJAR | Имя файла, в котором будут сохранены все внутренние cookies текущей передачи после закрытия дескриптора, например, после вызова curl_close. | |
| CURLOPT_CUSTOMREQUEST | Собственный метод запроса, используемый вместо "GET" или "HEAD" при выполнении HTTP-запроса. Это полезно при запросах "DELETE" или других, более редких HTTP-запросах. Корректными значениями будут слова наподобие "GET" , "POST" , "CONNECT" и так далее; т.е. не вводите здесь всю строку с HTTP-запросом. Например, указание "GET /index.html HTTP/1.0\r\n\r\n" будет неправильным.
|
|
| CURLOPT_EGDSOCKET | Наподобие CURLOPT_RANDOM_FILE , за исключением того, что имя файла устанавливается в сокет Entropy Gathering Daemon. | |
| CURLOPT_ENCODING | Содержимое заголовка "Accept-Encoding: " . Это позволяет декодировать запрос. Поддерживаемыми кодировками являются "identity" , "deflate" и "gzip" . Если передана пустая строка, "" , посылается заголовок, содержащий все поддерживаемые типы кодировок. | Добавлен в версии cURL 7.10. |
| CURLOPT_FTPPORT | Значение, которое будет использоваться для определения IP-адреса для команды "PORT" FTP-протокола. Команда "PORT" сообщает серверу, с каким IP-адресом он должен устанавливать соединение. Это может быть IP-адрес, имя хоста, имя сетевого интерфейса (под Unix), или просто "-" для использования системного IP-адреса по умолчанию. | |
| CURLOPT_INTERFACE | Имя используемого сетевого интерфейса. Может быть именем интерфейса, IP адресом или именем хоста. | |
| CURLOPT_KEYPASSWD | Пароль, который требуется для использования приватного ключа CURLOPT_SSLKEY или CURLOPT_SSH_PRIVATE_KEYFILE . | Добавлено в cURL 7.16.1. |
| CURLOPT_KRB4LEVEL | Уровень безопасности KRB4 (Kerberos 4). Любое из следующих значений (в порядке от слабого к самому сильному) корректно: "clear" , "safe" , "confidential" , "private". . Если указанная строка отличается от данных значений, будет использовано значение "private" . Установка этого параметра в NULL полностью отключит безопасность KRB4. На данный момент безопасность KRB4 работает только с FTP транзакциями. | |
| CURLOPT_POSTFIELDS | Все данные, передаваемые в HTTP POST-запросе. Для передачи файла, укажите перед именем файла @ , а также используйте полный путь к файлу. Тип файла также может быть указан с помощью формата ";type=mimetype ", следующим за именем файла. Этот параметр может быть передан как в качестве url-закодированной строки, наподобие "para1=val1¶2=val2&... ", так и в виде массива, ключами которого будут имена полей, а значениями - их содержимое. Если value является массивом, заголовок Content-Type будет установлен в значение multipart/form-data . Начиная с версии PHP 5.2.0, при передаче файлов с префиксом @ , value должен быть массивом. С версии PHP 5.5.0, префикс @ устарел и файлы можно отправлять с помощью CURLFile . Префикс @ можно отключить, чтобы можно было передавать значения, начинающиеся с @ , задав опцию CURLOPT_SAFE_UPLOAD в значение TRUE . | |
| CURLOPT_PROXY | HTTP-прокси, через который будут направляться запросы. | |
| CURLOPT_PROXYUSERPWD | Логин и пароль, записанные в виде ":" , используемые при соединении через прокси. | |
| CURLOPT_RANDOM_FILE | Имя файла, используемого для инициализации генератора случайных чисел для SSL. | |
| CURLOPT_RANGE | Диапазон данных, которые нужно загрузить, в формате "X-Y" , причем либо X, либо Y могут быть опущены. Протокол HTTP также поддерживает передачу нескольких диапазонов, разделенных запятыми, они задаются в формате "X-Y,N-M" . | |
| CURLOPT_REFERER | Содержимое заголовка "Referer: " , который будет использован в HTTP-запросе. | |
| CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 | Строка, содержащая 32 шестнадцатеричных цифры. Строка должна являться контрольной суммой по алгоритму MD5 публичного ключа удаленного компьютера и libcurl будет сбрасывать соединение к удаленному хосту до тех пор, пока контрольная сумма не будет соответствовать публичному ключу. Эта опция предназначена только для передачи данных с помощью SCP и SFTP. | Добавлено в cURL 7.17.1. |
| CURLOPT_SSH_PUBLIC_KEYFILE | Имя файла для вашего публичного ключа. Если не задано, то libcurl использует по умолчанию файл $HOME/.ssh/id_dsa.pub, если переменная окружения HOME установлена и файл "id_dsa.pub" в текущей директории, если переменная HOME не установлена. | Добавлено в cURL 7.16.1. |
| CURLOPT_SSH_PRIVATE_KEYFILE | Имя файла для вашего приватного ключа. Если не задано, то libcurl использует по умолчанию файл $HOME/.ssh/id_dsa, если переменная окружения HOME установлена и файл "id_dsa" в текущей директории, если переменная HOME не установлена. Если файл защищен паролем, установите пароль с помощью CURLOPT_KEYPASSWD . | Добавлено в cURL 7.16.1. |
| CURLOPT_SSL_CIPHER_LIST | Список шифров, используемый в SSL-передачах. Например, RC4-SHA и TLSv1 являются корректными списками шифров. | |
| CURLOPT_SSLCERT | Имя файла с корректно отформатированным PEM-сертификатом. | |
| CURLOPT_SSLCERTPASSWD | Пароль, необходимый для использования сертификата CURLOPT_SSLCERT . | |
| CURLOPT_SSLCERTTYPE | Формат сертификата. Поддерживаются форматы "PEM" (по умолчанию), "DER" и "ENG" . | Добавлен в версии cURL 7.9.3. |
| CURLOPT_SSLENGINE | Идентификатор механизма шифрования для закрытого ключа SSL, указанного в параметре CURLOPT_SSLKEY . | |
| CURLOPT_SSLENGINE_DEFAULT | Идентификатор механизма шифрования, используемого для ассиметричных операций шифрования. | |
| CURLOPT_SSLKEY | Имя файла с закрытым ключом SSL. | |
| CURLOPT_SSLKEYPASSWD | Тайный пароль, необходимый для использования закрытого ключа SSL, указанного параметром CURLOPT_SSLKEY .
|
|
| CURLOPT_SSLKEYTYPE | Тип закрытого ключа SSL, указанного в параметре CURLOPT_SSLKEY . Поддерживаются следующие типы ключей: "PEM" (по умолчанию), "DER" и "ENG" . | |
| CURLOPT_URL | Загружаемый URL. Данный параметр может быть также установлен при инициализации сеанса с помощью curl_init() . | |
| CURLOPT_USERAGENT | Содержимое заголовка "User-Agent: " , посылаемого в HTTP-запросе. | |
| CURLOPT_USERPWD | Логин и пароль, используемые при соединении, указанные в формате ":" . |
Для следующих значений параметра option , параметр value должен быть массивом:
| Параметр | Устанавливаемое значение value | Замечания |
|---|---|---|
| CURLOPT_HTTP200ALIASES | Массив HTTP 200 ответов, которые будут трактоваться корректными ответами, а не ошибочными. | Добавлен в версии cURL 7.10.3. |
| CURLOPT_HTTPHEADER | Массив устанавливаемых HTTP-заголовков, в формате array("Content-type: text/plain", "Content-length: 100") | |
| CURLOPT_POSTQUOTE | Массив FTP-команд, выполняемых на сервере, после выполнения FTP-запроса. | |
| CURLOPT_QUOTE | Массив FTP-команд, выполняемых на сервере, перед выполнением FTP-запроса. |
Для следующих значений параметра option , параметр value должен быть потоковым дескриптором (возвращаемым, например, функцией fopen() ):
| Параметр | Устанавливаемое значение value |
|---|---|
| CURLOPT_FILE | Файл, в который будет записан результат передачи. По умолчанию используется поток вывода STDOUT (окно браузера). |
| CURLOPT_INFILE | Файл, из которого должно идти чтение данных, при загрузке на сервер. |
| CURLOPT_STDERR | Альтернативное файл для вывода ошибок, используемый вместо потока ошибок STDERR . |
| CURLOPT_WRITEHEADER | Файл, в который будут записаны заголовки текущей операции. |
Для следующих значений параметра option , параметр value должен быть правильным именем функции или замыканием:
| Параметр | Устанавливаемое значение value |
|---|---|
| CURLOPT_HEADERFUNCTION | Callback-функция принимает два параметра. Первым параметром является дескриптор cURL, вторым параметром является строка с записываемыми заголовками. Заголовки должны быть записаны с помощью данной callback-функции. Должна возвратить количество записанных байт. |
| CURLOPT_PASSWDFUNCTION | Callback-функция принимает три параметра. Первым параметром является дескриптор cURL, вторым параметром является строка с запросом пароля, третьим параметром является максимальная длина пароля. Должна возвратить строку, содержащую пароль. |
| CURLOPT_PROGRESSFUNCTION |
Callback-функция принимает пять параметров. Первый является декскриптором cURL, второй - общим количеством байт, которое ожидается загрузить с сервера, третий - количество уже загруженных байт, четвертый - общее количество байт, которое ожидается отправить на сервер, и пятый - количество уже отправленных байт.
Можно вернуть ненулевое значение, чтобы отменить передачу. В этом случае будет выставлена ошибка CURLE_ABORTED_BY_CALLBACK . |
| CURLOPT_READFUNCTION | Callback-функция принимает три параметра. Первым параметром является дескриптор cURL, вторым параметром является ресурс потока, переданный cURL через опцию CURLOPT_INFILE , а третьим параметром является максимально разрешенное количество данных для чтения. Callback-функция должна возвратить строку, с длиной не превышающей запрошенного количества данных, обычно с помощью чтения из переданного потокового ресурса. Должна возвратить пустую строку для сигнала о конце файла EOF . |
| CURLOPT_WRITEFUNCTION | Callback-функция принимает два параметра. Первым параметром является дескриптор cURL, а вторым параметром является строка с записываемыми данными. Данные должны быть сохранены с помощью данной функции. Она должна возвратить точное количество записанных байт, иначе закачка будет прервана с ошибкой. |
Другие значения:
Возвращаемые значения
Возвращает TRUE в случае успешного завершения или FALSE в случае возникновения ошибки.
Список изменений
| Версия | Описание |
|---|---|
| 5.6.0 | Опция CURL_SAFE_UPLOAD теперь имеет значение по умолчанию равное TRUE . |
| 5.6.0 | Удалена опция CURLOPT_CLOSEPOLICY и связанные с ней значения. |
| 5.5.0 | Ресурс cURL добавлен первым аргументом в callback-функцию CURLOPT_PROGRESSFUNCTION . |
| 5.5.0 | Добавлена опция CURLOPT_SHARE . |
| 5.3.0 | Добавлена опция CURLOPT_PROGRESSFUNCTION . |
| 5.2.10 | Добавлены параметры CURLOPT_PROTOCOLS и CURLOPT_REDIR_PROTOCOLS . |
| 5.1.0 | Добавлены параметры CURLOPT_AUTOREFERER , CURLOPT_BINARYTRANSFER , CURLOPT_FTPSSLAUTH , CURLOPT_PROXYAUTH и CURLOPT_TIMECONDITION . |
| 5.0.0 | Добавлены параметры CURLOPT_FTP_USE_EPRT , CURLOPT_NOSIGNAL , CURLOPT_UNRESTRICTED_AUTH , CURLOPT_BUFFERSIZE , CURLOPT_HTTPAUTH , CURLOPT_PROXYPORT , CURLOPT_PROXYTYPE , CURLOPT_SSLCERTTYPE и CURLOPT_HTTP200ALIASES . |
Примеры
Пример #1 Инициализация сеанса CURL и загрузка web-страницы
// создание нового ресурса cURL /* http://localhost/upload.php:
$ch
=
curl_init
();
$data
= array("name"
=>
"Foo"
,
"file"
=>
"@/home/user/test.png"
); Curl_setopt
($ch
,
CURLOPT_URL
,
"http://localhost/upload.php"
); Curl_exec
($ch
); Результат выполнения данного примера: Array
( => Foo)
Array
( => Array
( => test.png
=> image/png
=> /tmp/phpcpjNeQ
=> 0
=> 279)) Замечание
: Передача массива в CURLOPT_POSTFIELDS
закодирует данные в виде multipart/form-data
,
тогда как передача URL-кодированной строки закодирует данные в виде
application/x-www-form-urlencoded
.
$ch
=
curl_init
();
print_r($_POST);
print_r($_FILES);
*/
curl_setopt
($ch
,
CURLOPT_POST
,
1
);
curl_setopt
($ch
,
CURLOPT_POSTFIELDS
,
$data
);
?>
Примечания