modules: readme files regenerated - http_client ... [skip ci]
[sip-router] / src / modules / http_client / README
1 http_client
2
3 Olle E. Johansson
4
5    Edvina AB
6    <oej@edvina.net>
7
8 Juha Heinanen
9
10    TutPro Inc.
11    <jh@tutpro.com>
12
13 Carsten Bock
14
15    ng-voice GmbH
16    <carsten@ng-voice.com>
17
18 Hugh Waite
19
20    Xura Inc
21    <hugh.waite@xura.com>
22
23    Copyright © 2008-2009 Juha Heinanen
24
25    Copyright © 2013 Carsten Bock, ng-voice GmbH
26
27    Copyright © 2015 Olle E. Johansson, Edvina AB
28
29    Copyright © 2016 Hugh Waite, Xura Inc
30      __________________________________________________________________
31
32    Table of Contents
33
34    1. Admin Guide
35
36         1. Overview
37         2. Dependencies
38
39               2.1. Kamailio Modules
40               2.2. External Libraries or Applications
41
42         3. Parameters
43
44               3.1. httpredirect (int)
45               3.2. httpproxy (string)
46               3.3. httpproxyport (string)
47               3.4. useragent (string)
48               3.5. maxdatasize (int)
49               3.6. connection_timeout (int)
50               3.7. client_cert (string)
51               3.8. client_key (string)
52               3.9. cacert (string)
53               3.10. cipher_suites (string)
54               3.11. verify_peer (int)
55               3.12. verify_host (int)
56               3.13. tlsversion (int)
57               3.14. authmethod (int)
58               3.15. keep_connections (int)
59               3.16. httpcon (string)
60               3.17. config_file (string)
61
62         4. Functions
63
64               4.1. http_connect(connection, url, [content_type, data,]
65                       result)
66
67               4.2. http_connect_raw(connection, url, content_type, data,
68                       result)
69
70               4.3. http_get_redirect(connection, result)
71               4.4. http_client_query(url, [post-data], [hdrs], result)
72
73         5. Pseudovariables
74
75               5.1. $curlerror(error)
76
77         6. RPC Commands
78
79               6.1. httpclient.listcon
80
81         7. Counters
82
83               7.1. httpclient.connections
84               7.2. httpclient.connok
85               7.3. httpclient.connfail
86
87         8. Remarks
88
89    2. Developer Guide
90
91         1.
92         2. Available Functions
93
94               2.1. int http_connect(msg, connection, url, result,
95                       content_type, post)
96
97               2.2. int http_connection_exists(str *connection)
98               2.3. int http_query(msg, url, dest, post)
99               2.4. http_get_content_type(str connection)
100
101    List of Examples
102
103    1.1. Set httpredirect parameter
104    1.2. Set httpproxy parameter
105    1.3. Set httpproxyport parameter
106    1.4. Set useragent parameter
107    1.5. Set maxdatasize parameter
108    1.6. Set connection_timeout parameter
109    1.7. Set client_cert parameter
110    1.8. Set client_key parameter
111    1.9. Set cacert parameter
112    1.10. Set cipher_suites parameter
113    1.11. Set verify_peer parameter
114    1.12. Set verify_host parameter
115    1.13. Set tlsversion parameter
116    1.14. Set authmethod parameter
117    1.15. Set keep_connections parameter
118    1.16. Set httpcon parameter
119    1.17. Set config_file parameter
120    1.18. Short http_client config file
121    1.19. http_connect() usage
122    1.20. http_connect_raw() usage
123    1.21. http_get_redirect() usage
124    1.22. http_client_query() usage
125
126 Chapter 1. Admin Guide
127
128    Table of Contents
129
130    1. Overview
131    2. Dependencies
132
133         2.1. Kamailio Modules
134         2.2. External Libraries or Applications
135
136    3. Parameters
137
138         3.1. httpredirect (int)
139         3.2. httpproxy (string)
140         3.3. httpproxyport (string)
141         3.4. useragent (string)
142         3.5. maxdatasize (int)
143         3.6. connection_timeout (int)
144         3.7. client_cert (string)
145         3.8. client_key (string)
146         3.9. cacert (string)
147         3.10. cipher_suites (string)
148         3.11. verify_peer (int)
149         3.12. verify_host (int)
150         3.13. tlsversion (int)
151         3.14. authmethod (int)
152         3.15. keep_connections (int)
153         3.16. httpcon (string)
154         3.17. config_file (string)
155
156    4. Functions
157
158         4.1. http_connect(connection, url, [content_type, data,] result)
159         4.2. http_connect_raw(connection, url, content_type, data, result)
160
161         4.3. http_get_redirect(connection, result)
162         4.4. http_client_query(url, [post-data], [hdrs], result)
163
164    5. Pseudovariables
165
166         5.1. $curlerror(error)
167
168    6. RPC Commands
169
170         6.1. httpclient.listcon
171
172    7. Counters
173
174         7.1. httpclient.connections
175         7.2. httpclient.connok
176         7.3. httpclient.connfail
177
178    8. Remarks
179
180 1. Overview
181
182    This module implements protocol functions that use the libcurl library
183    to fetch data from external HTTP servers or post data to HTTP servers.
184    The module is using a concept of "connections" to define properties of
185    HTTP sessions in a simple way. A connection has one or multiple servers
186    and a set of settings that apply to the specific connection.
187
188    The http_client module has multiple settings, some of them applies to a
189    defined connection. You can set timeouts, max data sizes for download
190    and much more either using modparam settings or parameters to the
191    connection definition.
192
193    The connections can either be defined with the "httpcon" module
194    parameter or in a separate configuration file, as specified by the
195    "config_file" module parameter.
196
197    Like in SIP, the HTTP URL may need encoding to be transported safely
198    over the network. Check the string encoding functions in the
199    Transformation Cookbook (as used in the http_client_query example
200    below).
201
202    The function http_client_query allows Kamailio to issue an HTTP GET
203    request and get access to parts of the reply. This function has been
204    ported from the utils module and now use the same libcurl functions. We
205    recommend using the new functionality provided by this module.
206
207    The http_client module use the CURL library setting up connections. The
208    CURL library by default use the system configured DNS resolvers, not
209    the Kamailio resolver.
210
211    The module is limited to using HTTP and HTTPS protocols.
212
213 2. Dependencies
214
215    2.1. Kamailio Modules
216    2.2. External Libraries or Applications
217
218 2.1. Kamailio Modules
219
220    The following modules must be loaded before this module:
221      * TLS - if you use TLS connections (https) the tls module should be
222        loaded first in order to initialize OpenSSL properly.
223
224 2.2. External Libraries or Applications
225
226    The following libraries or applications must be installed before
227    running Kamailio with this module loaded:
228      * libcurl.
229
230 3. Parameters
231
232    3.1. httpredirect (int)
233    3.2. httpproxy (string)
234    3.3. httpproxyport (string)
235    3.4. useragent (string)
236    3.5. maxdatasize (int)
237    3.6. connection_timeout (int)
238    3.7. client_cert (string)
239    3.8. client_key (string)
240    3.9. cacert (string)
241    3.10. cipher_suites (string)
242    3.11. verify_peer (int)
243    3.12. verify_host (int)
244    3.13. tlsversion (int)
245    3.14. authmethod (int)
246    3.15. keep_connections (int)
247    3.16. httpcon (string)
248    3.17. config_file (string)
249
250 3.1. httpredirect (int)
251
252    If set to 1, enabled, http_client will follow HTTP 302 Redirects. If
253    set to 0, http_client will not follow redirects. Default is 1, enabled.
254
255    The latest redirect URL will be stored in the $curlredirect
256    pseudovariable.
257
258    Example 1.1. Set httpredirect parameter
259 ...
260 modparam("http_client", "httpredirect", 0)
261 ...
262
263 3.2. httpproxy (string)
264
265    URL for a HTTP proxy to use as a default proxy for all connections.
266
267    This setting is also available on a per connection basis in the
268    http_client configuration file.
269
270    Example 1.2. Set httpproxy parameter
271 ...
272 modparam("http_client", "httpproxy", "https://superproxy.example.com")
273 ...
274
275 3.3. httpproxyport (string)
276
277    Port number for a HTTP proxy to use as a default proxy port for all
278    connections.
279
280    This setting is also available on a per connection basis in the
281    http_client configuration file.
282
283    Example 1.3. Set httpproxyport parameter
284 ...
285 modparam("http_client", "httpproxyport", 8042)
286 ...
287
288 3.4. useragent (string)
289
290    Useragent to use in the HTTP protocol for requests. Defaults to the
291    Kamailio SIP useragent string - including software version and
292    platform.
293
294    Example 1.4. Set useragent parameter
295 ...
296 modparam("http_client", "useragent", "Secret HTTP REST grabber 0.42")
297 ...
298
299 3.5. maxdatasize (int)
300
301    Defines the maximum size in bytes for a response. Note that this is
302    allocated from pkg memory (process memory) dynamically.
303
304    Default value is zero, i.e., the limit on the datasize is disabled.
305
306    Example 1.5. Set maxdatasize parameter
307 ...
308 modparam("http_client", "maxdatasize", 2000)
309 ...
310
311 3.6. connection_timeout (int)
312
313    Defines in seconds how long Kamailio waits for response from servers.
314
315    Default value is zero, i.e., the timeout function is disabled.
316
317    Example 1.6. Set connection_timeout parameter
318 ...
319 modparam("http_client", "connection_timeout", 2)
320 ...
321
322 3.7. client_cert (string)
323
324    File name for a TLS client certificate. The certificate needs to be
325    encoded in PEM format.
326
327    Default value is empty string, i.e. no client certificate used. Note
328    that if you specify a client cert, you also need to specify the
329    client_key.
330
331    Example 1.7. Set client_cert parameter
332 ...
333 modparam("http_client", "client_cert", "/var/certs/sollentuna.example.com.cert")
334 ...
335
336 3.8. client_key (string)
337
338    File name for a TLS client key. The key needs to be encoded in PEM
339    format.
340
341    Default value is empty string, i.e. no client certificate or key is
342    used. Note that if you specify a client key, you also need to specify
343    the client_cert.
344
345    Example 1.8. Set client_key parameter
346 ...
347 modparam("http_client", "client_key", "/var/certs/sollentuna.example.com.key")
348 ...
349
350 3.9. cacert (string)
351
352    File name for the trusted TLS CA cert used to verify servers. The
353    certificates need to be encoded in PEM format.
354
355    Default value is empty string, i.e. no CA certificate is used to verify
356    the host. If tlsverifyhost is on, all TLS connections will fail without
357    any CA certificate to validate with.
358
359    Example 1.9. Set cacert parameter
360 ...
361 modparam("http_client", "cacert", "/var/certs/ca/edvina-sip-ca.pem")
362 ...
363
364 3.10. cipher_suites (string)
365
366    List of allowed cipher suites. See
367    http://curl.haxx.se/libcurl/c/CURLOPT_SSL_CIPHER_LIST.html for details
368    of the cipher list curl option.
369
370    Default value is empty string, i.e. the default list of ciphers in
371    libcurl will be used.
372
373    Example 1.10. Set cipher_suites parameter
374 ...
375 modparam("http_client", "cipher_suites", "ecdhe_ecdsa_aes_128_gcm_sha_256,rsa_ae
376 s_128_gcm_sha_256")
377 ...
378
379 3.11. verify_peer (int)
380
381    If set to 0, TLS verification of the server certificate is disabled.
382    This means that the connection will get encrypted, but there's no
383    authentication. There's no proof that the transmission of data is to
384    the host that is meant to receive data.
385
386    If set to 1, default setting, and one or more CA certificates is
387    configured, the server TLS certificate will be validated. If validation
388    fails, the connection fails.
389
390    See the curl documentation for more details.
391    http://curl.haxx.se/libcurl/c/CURLOPT_SSL_VERIFYPEER.html
392
393    Example 1.11. Set verify_peer parameter
394 ...
395 modparam("http_client", "verify_peer", 1)
396 ...
397
398 3.12. verify_host (int)
399
400    If set to 0, domain verification of the server certificate is disabled.
401    This means that the connection will get encrypted but there is no check
402    that data will be sent to the host that is meant to receive it. Disable
403    with caution.
404
405    If set to 2, default setting, the hostname in the URL will be verified
406    against the Common Name or Subject Alt Name in the certificate. If
407    validation fails, the connection fails.
408
409    See the curl documentation for more details.
410    http://curl.haxx.se/libcurl/c/CURLOPT_SSL_VERIFYHOST.html
411
412    Example 1.12. Set verify_host parameter
413 ...
414 modparam("http_client", "verify_host", 2)
415 ...
416
417 3.13. tlsversion (int)
418
419    Sets the preferred TLS/SSL version.
420
421    Valid values are:
422      * 0 - Use libcurl default
423      * 1 - "TLSv1"
424      * 2 - "SSLv2"
425      * 3 - "SSLv3"
426      * 4 - "TLSv1.0"
427      * 5 - "TLSv1.1"
428      * 6 - "TLSv1.2"
429
430    SSL versions are now disabled by default. See the curl documentation
431    for more details. http://curl.haxx.se/libcurl/c/CURLOPT_SSLVERSION.html
432
433    Example 1.13. Set tlsversion parameter
434 ...
435 modparam("http_client", "tlsversion", 6)
436 ...
437
438 3.14. authmethod (int)
439
440    Sets the preferred authentication mode for HTTP/HTTPS requests. The
441    value is a bitmap and multiple methods can be used. Note that in this
442    case, the CURL library will make an extra request to discover
443    server-supported authentication methods. You may want to use a specific
444    value.
445
446    Valid values are:
447      * 1 - BASIC authentication
448      * 2 - HTTP Digest authentication
449      * 4 - GSS-Negotiate authentication
450      * 8 - NTLM authentication
451      * 16 - HTTP Digest with IE flavour
452
453    Default value is 3 - BASIC and Digest authentication.
454
455    This is also configurable per connection in the http_client
456    configuration file.
457
458    Example 1.14. Set authmethod parameter
459 ...
460 # Use the best of BASIC and Digest authentication.
461 modparam("http_client", "authmethod", 3)
462 ...
463
464 3.15. keep_connections (int)
465
466    If an HTTP server is accessed multiple times keeping the connection
467    open for reuse saves a significant amount of time, especially if TLS is
468    used. If this function is enabled, the Curl library will try to reuse
469    existing open connections. The HTTP server will have to support this
470    feature and keep connections open for it to work properly.
471
472    Valid values are:
473      * 0 - Close connections after request (default)
474      * 1 - Reuse connections
475
476    This is also configurable per connection in the http_client
477    configuration file.
478
479    Example 1.15. Set keep_connections parameter
480 ...
481 modparam("http_client", "keep_connections", 1)
482 ...
483
484 3.16. httpcon (string)
485
486    Defines a connection and credentials for the connection for use in a
487    connection-oriented function call in this module.
488
489    Syntax:
490    <connection-name>=><schema>://[<username>:<password>@]<hostname/address
491    >[;param=value]
492
493    The address in the URL is the base for the URL in the http_connect()
494    call. The address given in the function call will be appended to the
495    base URL in the connection definition.
496
497    The HTTP connection will be defined using default values in modparam's
498    above the definition of the httpcon in the configuration file. Also
499    note that connections can be defined in a separate text file if you
500    have many parameters per connection, or want to use a per-connection
501    setting that can be set in that file but not in the httpcon modparam,
502    like authmethod.
503
504    By default, no connections are defined.
505
506    Parameters
507      * useragent Useragent used for HTTP requests. Overrides useragent
508        modparam.
509      * verify_peer Set to 1 to enable or 0 to disable server certificate
510        verification. Overrides verify_peer modparam.
511      * verify_host Set to 2 to enable or 0 to disable server hostname
512        verification. Overrides verify_host modparam.
513      * client_cert Client certificate used for this connection. Overrides
514        the default client_cert modparam.
515      * client_key Client key used for this connection. Overrides the
516        default client_key modparam.
517      * cipher_suites Client certificate used for this connection.
518        Overrides the default cipher_suite modparam.
519      * timeout Timeout used for this connection. Overrides the default
520        connection_timeout for the module.
521      * tlsversion TLS version used for this connection. Overrides the
522        default tlsversion for the module.
523      * maxdatasize The maximum datasize for a response. Overrides the
524        maxdatasize modparam setting.
525      * httpredirect Set to 1 for following HTTP 302 redirect. 0 to
526        disable. Overrides the default httpredirect modparam.
527      * failover The name of another httpcon connection to use with the
528        same arguments in case a connection with this http_con fails.
529        Failure is either a connection failure or a response code of 500 or
530        above.
531
532    Example 1.16. Set httpcon parameter
533 ...
534 modparam("http_client", "httpcon", "apione=>http://atlanta.example.com")
535 modparam("http_client", "httpcon", "apitwo=>http://atlanta.example.com/api/12")
536 modparam("http_client", "httpcon", "apithree=>http://annabella:mysecret@atlanta.
537 example.com/api/12")
538 modparam("http_client", "httpcon", "apifour=>http://stockholm.example.com/api/ge
539 tstuff;timeout=12;failover=apione")
540 ...
541
542 3.17. config_file (string)
543
544    The file name of a configuration file containing definitions of http
545    connections. This is an alternative to the "httpcon" module parameter -
546    especially when the number of options per line gets too big.
547
548    If the file or directory name starts with a '.' the path will be
549    relative to the working directory (at runtime). If it starts with a '/'
550    it will be an absolute path and if it starts with anything else the
551    path will be relative to the main config file directory (e.g.: for
552    kamailio -f /etc/kamailio/kamailio.cfg it will be relative to
553    /etc/kamailio/).
554
555    The following parameters can be set in the config file, for each
556    connection. If a parameter is not specified, the default values set by
557    the modparams will be used.
558      * url
559      * username
560      * password
561      * authmethod
562      * keep_connections
563      * useragent
564      * verify_peer
565      * verify_host
566      * client_cert
567      * client_key
568      * cipher_suites
569      * tlsversion - Valid values are:
570           + "DEFAULT"
571           + "TLSv1"
572           + "SSLv22
573           + "SSLv3"
574           + "TLSv1.0"
575           + "TLSv1.1"
576           + "TLSv1.2"
577      * timeout
578      * maxdatasize
579      * http_follow_redirect
580      * httpproxy
581      * httpproxyport
582      * failover
583
584    See the "httpcon" module parameter for explanation of these settings.
585
586    By default no config file is specified.
587
588    All the parameters that take filenames as values will be resolved using
589    the same rules as for the tls config filename itself: starting with a
590    '.' means relative to the working directory, a '/' means an absolute
591    path and anything else a path relative to the directory of the current
592    Kamailio main config file.
593
594    To set a string value to null, in order to override default settings,
595    you can specify an value of "" - two quotation marks. In order to
596    disable a http proxy setting you can set the port to zero.
597
598    Example 1.17. Set config_file parameter
599 ...
600 modparam("http_client", "config_file", "httpconnections.cfg)
601 ...
602
603    Example 1.18. Short http_client config file
604 [authapiserver]
605 url = https://api.runbo.example.com/v4.2/auth
606 timeout = 1
607 maxdatasize = 4
608 tlsversion = TLSv1.2
609 verify_peer = yes
610 client_key = default_key.pem
611 client_cert = default_cert.pem
612 http_follow_redirect = no
613
614 4. Functions
615
616    4.1. http_connect(connection, url, [content_type, data,] result)
617    4.2. http_connect_raw(connection, url, content_type, data, result)
618    4.3. http_get_redirect(connection, result)
619    4.4. http_client_query(url, [post-data], [hdrs], result)
620
621 4.1.  http_connect(connection, url, [content_type, data,] result)
622
623    Sends HTTP GET or POST request to a given connection. For a POST
624    request, content-type can be specified.
625      * connection - the name of an existing HTTP connection, defined by a
626        httpcon modparam.
627        url - the part of the URL to add to the predefined URL in the
628        connection definition.
629        content_type - Used only when posting data with HTTP POST. An
630        Internet Media type, like "application/json" or "text/plain". Will
631        be added to the HTTP request as a header.
632        data - Data or a pseudo variable holding data to be posted. (may
633        contain pseudo variable)
634        result - The name of a pseudo variable that will have the data of
635        the response from the HTTP server.
636
637    The return value is the HTTP return code (if >=100) or the CURL error
638    code if below 100. See the $curlerror pseudovariable below for more
639    information about CURL error codes.
640
641    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
642    FAILURE_ROUTE, and BRANCH_ROUTE.
643
644    Example 1.19. http_connect() usage
645 ...
646 modparam("http_client", "httpcon", "apiserver=>http://kamailio.org/api/");
647 ...
648 # POST Request
649 $var(res) = http_connect("apiserver", "/mailbox", "application/json", "{ ok, {20
650 0, ok}}", "$avp(gurka)");
651 xlog("L_INFO", "API-server HTTP connection: $avp(gurka) Result code $var(res)\n"
652 );
653
654 $var(res) = http_connect("apiserver", "/callroute", "application/json", "$var(js
655 ondata)", "$avp(route)");
656 xlog("L_INFO", "API-server HTTP connection: $avp(route) Result code $var(res)\n"
657 );
658 ...
659
660 4.2.  http_connect_raw(connection, url, content_type, data, result)
661
662    Sends HTTP POST request to a given connection. Similar to http_connect.
663    The only difference is that the data parameter will not be parsed for
664    pseudo variables, therefore it can safely be used for content that may
665    contain "$" character like JSON.
666      * connection - the name of an existing HTTP connection, defined by a
667        httpcon modparam.
668        url - the part of the URL to add to the predefined URL in the
669        connection definition.
670        content_type - Used only when posting data with HTTP POST. An
671        Internet Media type, like "application/json" or "text/plain". Will
672        be added to the HTTP request as a header.
673        data - Data or a pseudo variable holding data to be posted. (will
674        not be parsed for pseudo variable)
675        result - The name of a pseudo variable that will have the data of
676        the response from the HTTP server.
677
678    The return value is the HTTP return code (if >=100) or the CURL error
679    code if below 100. See the $curlerror pseudovariable below for more
680    information about CURL error codes.
681
682    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
683    FAILURE_ROUTE, and BRANCH_ROUTE.
684
685    Example 1.20. http_connect_raw() usage
686 ...
687 modparam("http_client", "httpcon", "apiserver=>http://kamailio.org/api/");
688 ...
689 # POST Request
690 $var(res) = http_connect_raw("apiserver", "/mailbox", "application/json", "{ ok,
691  {200, ok}}", "$avp(gurka)");
692 xlog("L_INFO", "API-server HTTP connection: $avp(gurka) Result code $var(res)\n"
693 );
694
695 $var(res) = http_connect_war("apiserver", "/callroute", "application/json", "$va
696 r(jsondata)", "$avp(route)");
697 xlog("L_INFO", "API-server HTTP connection: $avp(route) Result code $var(res)\n"
698 );
699 ...
700
701 4.3.  http_get_redirect(connection, result)
702
703    When a http connection gets a redirect and the connection is configured
704    to follow redirects (301,302) then the target URL, the result of the
705    redirects can be retrieved with this function after a successful
706    connection.
707      * connection - the name of an existing HTTP connection, defined by a
708        httpcon modparam.
709        result - The name of a pseudo variable that will contain the last
710        used URL.
711
712    Example 1.21. http_get_redirect() usage
713 ...
714 modparam("http_client", "httpredirect", 1);
715 ...
716 http_get_redirect("apiserver", "$var(targeturl)");
717 ...
718
719 4.4.  http_client_query(url, [post-data], [hdrs], result)
720
721    Sends HTTP GET or POST request according to URL given in “url”
722    parameter, which is a string that may contain pseudo variables.
723
724    If you want to make a POST-Request, you have to define the “post”-data,
725    that should be submitted in that request as the second parameter.
726
727    Custom headers may be specified via “hdrs” parameter (e.g.,
728    Content-Type).
729
730    Either of “post-data” or “hdrs” can be also set to empty string in
731    order to be ignored.
732
733    If HTTP server returns a class 2xx, 3xx or 4xx reply, the first line of
734    the reply's body (if any) is stored in “result” parameter, which must
735    be a writable pseudo variable.
736
737    Function returns reply code of HTTP reply or -1 if something went
738    wrong.
739
740    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
741    FAILURE_ROUTE, and BRANCH_ROUTE.
742
743    Note that this function is based on the http_query function in the
744    utils module. It is changed to use the same base library and settings
745    as the rest of the functions in this module.
746
747    Example 1.22. http_client_query() usage
748 ...
749 # GET-Request
750 http_client_query("http://api.com/index.php?r_uri=$(ru{s.escape.param})&f_uri=$(
751 fu{s.escape.param})",
752            "$var(result)");
753 switch ($rc) {
754     ...
755 }
756 ...
757 # POST-Request
758 http_client_query("http://api.com/index.php",
759     "r_uri=$(ru{s.escape.param})&f_uri=$(fu{s.escape.param})",
760     "$var(result)");
761 }
762 ...
763 # POST-Request
764 http_client_query("http://api.com/index.php", "src=$si",
765     "Content-Type: text/plain", "$var(result)");
766 ...
767
768 5. Pseudovariables
769
770    5.1. $curlerror(error)
771
772 5.1.  $curlerror(error)
773
774    The cURL library returns error codes from the protocol used. If an
775    error happens, a cURL specific error code below 100 is returned. The
776    $curlerror pv returns a text string representing the error. For more
777    information on cURL error codes, please visit
778    http://curl.haxx.se/libcurl/c/libcurl-errors.html
779
780 6. RPC Commands
781
782    6.1. httpclient.listcon
783
784 6.1. httpclient.listcon
785
786    Lists all defined httpcon connections
787
788    Parameters:
789      * No parameters
790
791 7. Counters
792
793    7.1. httpclient.connections
794    7.2. httpclient.connok
795    7.3. httpclient.connfail
796
797 7.1.  httpclient.connections
798
799    The number of connection definitions that are in-memory.
800
801 7.2.  httpclient.connok
802
803    The number of successful connections since Kamailio start
804
805 7.3.  httpclient.connfail
806
807    The number of failed connections since Kamailio start
808
809 8. Remarks
810
811    Note: libcurl leak in CentOS 6 - this module uses libcurl library and
812    in case if you are using CentOS 6, be aware that standard
813    libcurl-7.19.7-52 has a memory leak. To fix this memory, install
814    libcurl from city-fan repository. More details at:
815    https://www.digitalocean.com/community/questions/how-to-upgrade-curl-in
816    -centos6
817
818 Chapter 2. Developer Guide
819
820    Table of Contents
821
822    1.
823    2. Available Functions
824
825         2.1. int http_connect(msg, connection, url, result, content_type,
826                 post)
827
828         2.2. int http_connection_exists(str *connection)
829         2.3. int http_query(msg, url, dest, post)
830         2.4. http_get_content_type(str connection)
831
832    This module provides a set of API functions that other modules can use
833    in order to integrate with HTTP services.
834
835 2. Available Functions
836
837    2.1. int http_connect(msg, connection, url, result, content_type, post)
838
839    2.2. int http_connection_exists(str *connection)
840    2.3. int http_query(msg, url, dest, post)
841    2.4. http_get_content_type(str connection)
842
843 2.1.  int http_connect(msg, connection, url, result, content_type, post)
844
845    Sends HTTP GET or POST request to a given connection. If content_type
846    and post are NULL GET will be used. If post is not null the data will
847    be POSTed using the specified content_type.
848
849    Returns the status code of the HTTP response (if >= 100), or a curl
850    error code (if < 100)
851
852    Meaning of the parameters is as follows:
853      * struct sip_msg *msg
854        The current sip message structure.
855      * const str *connection
856        The name of a preset http_con connection to use for this query.
857      * const str *url
858        A string that will be appended to the base URL specified in the
859        connection. This parameter can be NULL, which means nothing will be
860        appended to the base URL.
861      * str *result
862        A pointer to a string that will contain the response body. On
863        success, the data is allocated in pkg memory by the http_client
864        module and must be freed by the caller.
865      * const char *content_type
866        A null-terminated string specifying the content type to place in a
867        Content-Type header. Use NULL when a message body is not required.
868      * const str *post
869        A string containing the message body to send. Use NULL when a
870        message body is not required.
871
872 2.2.  int http_connection_exists(str *connection)
873
874    Check if a connection definition exists. Connections are defined as
875    modparam's in the http_client modules.
876
877    Returns 1 if the connection exists, 0 if a connection with the given
878    name can't be found.
879
880 2.3.  int http_query(msg, url, dest, post)
881
882    Sends a HTTP GET or POST request to a given connection. If post data is
883    defined, POST will be used, otherwise GET. The default settings defined
884    as module params of the http_client module will be used for the
885    connection.
886
887    Meaning of the parameters is as follows:
888      * struct sip_msg *msg
889        The current SIP message structure.
890      * const char *url
891        A string that will be used as the URL specified in the connection.
892      * str *dest
893        A pointer to a string that will contain the first line of the
894        response body. On success, the data is allocated in pkg memory by
895        the http_client module and must be freed by the caller.
896      * const char *post
897        If not null, the data will be posted to the URL.
898
899 2.4.  http_get_content_type(str connection)
900
901    Get the content-type of the last result for this connection. This will
902    be something like "text/html" for html or "application/json" for JSON
903    data.
904
905    Result will be a pointer to a char string (char *). This is per
906    process, so the connection will have to be done in the same process.
907    Returns a NULL pointer if the connection does not exist or there's no
908    previous connection data delivered.