func_curl.c

/*
 * Asterisk -- An open source telephony toolkit.
 *
 * Copyright (C)  2004 - 2006, Tilghman Lesher
 *
 * Tilghman Lesher <curl-20050919@the-tilghman.com>
 * and Brian Wilkins <bwilkins@cfl.rr.com> (Added POST option)
 *
 * app_curl.c is distributed with no restrictions on usage or
 * redistribution.
 *
 * See http://www.asterisk.org for more information about
 * the Asterisk project. Please do not directly contact
 * any of the maintainers of this project for assistance;
 * the project provides a web site, mailing lists and IRC
 * channels for your use.
 *
 */

/*! \file
 *
 * \brief Curl - Load a URL
 *
 * \author Tilghman Lesher <curl-20050919@the-tilghman.com>
 *
 * \note Brian Wilkins <bwilkins@cfl.rr.com> (Added POST option)
 *
 * \extref Depends on the CURL library  - http://curl.haxx.se/
 *
 * \ingroup functions
 */

/*** MODULEINFO
	<depend>res_curl</depend>
	<depend>curl</depend>
	<support_level>core</support_level>
 ***/

#include "asterisk.h"

#include <curl/curl.h>

#include "asterisk/lock.h"
#include "asterisk/file.h"
#include "asterisk/channel.h"
#include "asterisk/pbx.h"
#include "asterisk/cli.h"
#include "asterisk/module.h"
#include "asterisk/app.h"
#include "asterisk/utils.h"
#include "asterisk/threadstorage.h"
#include "asterisk/test.h"

/*** DOCUMENTATION
	<function name="CURL" language="en_US">
		<synopsis>
			Retrieve content from a remote web or ftp server
		</synopsis>
		<syntax>
			<parameter name="url" required="true">
				<para>The full URL for the resource to retrieve.</para>
			</parameter>
			<parameter name="post-data">
				<para><emphasis>Read Only</emphasis></para>
				<para>If specified, an <literal>HTTP POST</literal> will be
				performed with the content of
				<replaceable>post-data</replaceable>, instead of an
				<literal>HTTP GET</literal> (default).</para>
			</parameter>
		</syntax>
		<description>
			<para>When this function is read, a <literal>HTTP GET</literal>
			(by default) will be used to retrieve the contents of the provided
			<replaceable>url</replaceable>. The contents are returned as the
			result of the function.</para>
			<example title="Displaying contents of a page" language="text">
			exten => s,1,Verbose(0, ${CURL(http://localhost:8088/static/astman.css)})
			</example>
			<para>When this function is written to, a <literal>HTTP GET</literal>
			will be used to retrieve the contents of the provided
			<replaceable>url</replaceable>. The value written to the function
			specifies the destination file of the cURL'd resource.</para>
			<example title="Retrieving a file" language="text">
			exten => s,1,Set(CURL(http://localhost:8088/static/astman.css)=/var/spool/asterisk/tmp/astman.css))
			</example>
			<note>
				<para>If <literal>live_dangerously</literal> in <literal>asterisk.conf</literal>
				is set to <literal>no</literal>, this function can only be written to from the
				dialplan, and not directly from external protocols. Read operations are
				unaffected.</para>
			</note>
		</description>
		<see-also>
			<ref type="function">CURLOPT</ref>
		</see-also>
	</function>
	<function name="CURLOPT" language="en_US">
		<synopsis>
			Sets various options for future invocations of CURL.
		</synopsis>
		<syntax>
			<parameter name="key" required="yes">
				<enumlist>
					<enum name="cookie">
						<para>A cookie to send with the request.  Multiple
						cookies are supported.</para>
					</enum>
					<enum name="conntimeout">
						<para>Number of seconds to wait for a connection to succeed</para>
					</enum>
					<enum name="dnstimeout">
						<para>Number of seconds to wait for DNS to be resolved</para>
					</enum>
					<enum name="followlocation">
						<para>Whether or not to follow HTTP 3xx redirects (boolean)</para>
					</enum>
					<enum name="ftptext">
						<para>For FTP URIs, force a text transfer (boolean)</para>
					</enum>
					<enum name="ftptimeout">
						<para>For FTP URIs, number of seconds to wait for a
						server response</para>
					</enum>
					<enum name="header">
						<para>Include header information in the result
						(boolean)</para>
					</enum>
					<enum name="httpheader">
						<para>Add HTTP header. Multiple calls add multiple headers.
						Setting of any header will remove the default
						"Content-Type application/x-www-form-urlencoded"</para>
					</enum>
					<enum name="httptimeout">
						<para>For HTTP(S) URIs, number of seconds to wait for a
						server response</para>
					</enum>
					<enum name="maxredirs">
						<para>Maximum number of redirects to follow. The default is -1,
						which allows for unlimited redirects. This only makes sense when
						followlocation is also set.</para>
					</enum>
					<enum name="proxy">
						<para>Hostname or IP address to use as a proxy server</para>
					</enum>
					<enum name="proxytype">
						<para>Type of <literal>proxy</literal></para>
						<enumlist>
							<enum name="http" />
							<enum name="socks4" />
							<enum name="socks5" />
						</enumlist>
					</enum>
					<enum name="proxyport">
						<para>Port number of the <literal>proxy</literal></para>
					</enum>
					<enum name="proxyuserpwd">
						<para>A <replaceable>username</replaceable><literal>:</literal><replaceable>password</replaceable>
						combination to use for authenticating requests through a
						<literal>proxy</literal></para>
					</enum>
					<enum name="referer">
						<para>Referer URL to use for the request</para>
					</enum>
					<enum name="useragent">
						<para>UserAgent string to use for the request</para>
					</enum>
					<enum name="userpwd">
						<para>A <replaceable>username</replaceable><literal>:</literal><replaceable>password</replaceable>
						to use for authentication when the server response to
						an initial request indicates a 401 status code.</para>
					</enum>
					<enum name="ssl_verifypeer">
						<para>Whether to verify the server certificate against
						a list of known root certificate authorities (boolean).</para>
					</enum>
					<enum name="hashcompat">
						<para>Assuming the responses will be in <literal>key1=value1&amp;key2=value2</literal>
						format, reformat the response such that it can be used
						by the <literal>HASH</literal> function.</para>
						<enumlist>
							<enum name="yes" />
							<enum name="no" />
							<enum name="legacy">
								<para>Also translate <literal>+</literal> to the
								space character, in violation of current RFC
								standards.</para>
							</enum>
						</enumlist>
					</enum>
					<enum name="failurecodes">
						<para>A comma separated list of HTTP response codes to be treated as errors</para>
					</enum>
				</enumlist>
			</parameter>
		</syntax>
		<description>
			<para>Options may be set globally or per channel.  Per-channel
			settings will override global settings. Only HTTP headers are added instead of overriding</para>
		</description>
		<see-also>