http_client Expand API with the "old" http_query function
[sip-router] / modules / http_client / doc / http_client_devel.xml
1 <?xml version="1.0" encoding='ISO-8859-1'?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
4
5 <!-- Include general documentation entities -->
6 <!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
7 %docentities;
8
9 ]>
10 <!-- Module Developer's Guide -->
11
12 <chapter>
13         
14         <title>&develguide;</title>
15         <section>
16         <title>Available Functions</title>
17                 <section>
18                         <title>
19                         <function moreinfo="none">http_connect(msg, connection, url, result, content_type, post)</function>
20                         </title>
21                         <para>
22                         Sends HTTP GET or POST request to a given connection. If content_type and post
23                         are NULL GET will be used. If post is not null the data will be POSTed using
24                         the specified content_type.
25                         </para>
26                         <para>
27                         Returns the status code of the HTTP response (if &gt;= 100), or a curl error code (if &lt; 100)
28                         </para>
29                         <para>Meaning of the parameters is as follows:</para>
30                         <itemizedlist>
31                         <listitem>
32                                 <para><emphasis>struct sip_msg *msg</emphasis></para>
33                                 <para>
34                                 The current sip message structure.
35                                 </para>
36                         </listitem>
37                         <listitem>
38                                 <para><emphasis>const str *connection</emphasis></para>
39                                 <para>
40                                 The name of a preset http_con connection to use for this query.
41                                 </para>
42                         </listitem>
43                         <listitem>
44                                 <para><emphasis>const str *url</emphasis></para>
45                                 <para>
46                                 A string that will be appended to the base URL specified in the connection.
47                                 This parameter can be NULL, which means nothing will be appended to the base URL.
48                                 </para>
49                         </listitem>
50                         <listitem>
51                                 <para><emphasis>str *result</emphasis></para>
52                                 <para>
53                                 A pointer to a string that will contain the response body.
54                                 On success, the data is allocated in pkg memory by the http_client module
55                                 and must be freed by the caller.
56                                 </para>
57                         </listitem>
58                         <listitem>
59                                 <para><emphasis>const char *content_type</emphasis></para>
60                                 <para>
61                                 A null-terminated string specifying the content type to place in a Content-Type header.
62                                 Use NULL when a message body is not required.
63                                 </para>
64                         </listitem>
65                         <listitem>
66                                 <para><emphasis>const str *post</emphasis></para>
67                                 <para>
68                                 A string containing the message body to send.
69                                 Use NULL when a message body is not required.
70                                 </para>
71                         </listitem>
72                         </itemizedlist>
73                 </section>
74                 <section>
75                         <title>
76                         <function moreinfo="none">http_query(msg, url, dest, post)</function>
77                         </title>
78                         <para>
79                         Sends HTTP GET or POST request to a given connection. If post data 
80                         is defined, POST will be used, otherwise GET. The default settings
81                         defined as module params of the http_client module will be used for
82                         the connection.
83                         </para>
84                         <para>Meaning of the parameters is as follows:</para>
85                         <itemizedlist>
86                         <listitem>
87                                 <para><emphasis>struct sip_msg *msg</emphasis></para>
88                                 <para>
89                                 The current sip message structure.
90                                 </para>
91                         </listitem>
92                         <listitem>
93                                 <para><emphasis>const char *url</emphasis></para>
94                                 <para>
95                                 A string that will be used as the URL specified in the connection.
96                                 </para>
97                         </listitem>
98                         <listitem>
99                                 <para><emphasis>str *dest</emphasis></para>
100                                 <para>
101                                 A pointer to a string that will contain the first line of the response body.
102                                 On success, the data is allocated in pkg memory by the http_client module
103                                 and must be freed by the caller.
104                                 </para>
105                         </listitem>
106                         <listitem>
107                                 <para><emphasis>const char *post</emphasis></para>
108                                 <para>
109                                 If not null, the data will be posted to the URL.
110                                 </para>
111                         </listitem>
112                         </itemizedlist>
113                 </section>
114
115
116         </section>
117
118 </chapter>
119