From: Jonathan Rose <jrose@digium.com>
Date: Thu, 2 Feb 2012 18:31:37 +0000 (+0000)
Subject: Backports some documentation for func_curl from 10 to 1.8
X-Git-Tag: 1.8.11.0-rc1~66
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=749b33018eb369e465c1c572e431a68dbabee7f4;p=thirdparty%2Fasterisk.git

Backports some documentation for func_curl from 10 to 1.8

For some reason this function was completely undocumented in 1.8. I copied the
10 docs over to 1.8 and removed references to an enumerator that was added in
the Asterisk 10 version of func_curl.  That was the only change I noted.

(closes issue ASTERISK-19186)
Reported by: Olivier Krief


git-svn-id: https://origsvn.digium.com/svn/asterisk/branches/1.8@353818 65c4cc65-6c06-0410-ace0-fbb531ad65f3
---

diff --git a/funcs/func_curl.c b/funcs/func_curl.c
index 1a14ddca49..130d5a6240 100644
--- a/funcs/func_curl.c
+++ b/funcs/func_curl.c
@@ -51,6 +51,113 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 #include "asterisk/utils.h"
 #include "asterisk/threadstorage.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" />
+			<parameter name="post-data">
+				<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 />
+		<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="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="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</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>
+					</enum>
+				</enumlist>
+			</parameter>
+		</syntax>
+		<description>
+			<para>Options may be set globally or per channel.  Per-channel
+			settings will override global settings.</para>
+		</description>
+		<see-also>
+			<ref type="function">CURL</ref>
+			<ref type="function">HASH</ref>
+		</see-also>
+	</function>
+ ***/
+
 #define CURLVERSION_ATLEAST(a,b,c) \
 	((LIBCURL_VERSION_MAJOR > (a)) || ((LIBCURL_VERSION_MAJOR == (a)) && (LIBCURL_VERSION_MINOR > (b))) || ((LIBCURL_VERSION_MAJOR == (a)) && (LIBCURL_VERSION_MINOR == (b)) && (LIBCURL_VERSION_PATCH >= (c))))