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