modules: readme files regenerated - http_client ... [skip ci]
[sip-router] / src / modules / http_client / README
index de8b9dd..cbfb61f 100644 (file)
@@ -64,8 +64,11 @@ Hugh Waite
               4.1. http_connect(connection, url, [content_type, data,]
                       result)
 
-              4.2. http_get_redirect(connection, result)
-              4.3. http_client_query(url, [post-data], [hdrs], result)
+              4.2. http_connect_raw(connection, url, content_type, data,
+                      result)
+
+              4.3. http_get_redirect(connection, result)
+              4.4. http_client_query(url, [post-data], [hdrs], result)
 
         5. Pseudovariables
 
@@ -116,8 +119,9 @@ Hugh Waite
    1.17. Set config_file parameter
    1.18. Short http_client config file
    1.19. http_connect() usage
-   1.20. http_get_redirect() usage
-   1.21. http_client_query() usage
+   1.20. http_connect_raw() usage
+   1.21. http_get_redirect() usage
+   1.22. http_client_query() usage
 
 Chapter 1. Admin Guide
 
@@ -152,8 +156,10 @@ Chapter 1. Admin Guide
    4. Functions
 
         4.1. http_connect(connection, url, [content_type, data,] result)
-        4.2. http_get_redirect(connection, result)
-        4.3. http_client_query(url, [post-data], [hdrs], result)
+        4.2. http_connect_raw(connection, url, content_type, data, result)
+
+        4.3. http_get_redirect(connection, result)
+        4.4. http_client_query(url, [post-data], [hdrs], result)
 
    5. Pseudovariables
 
@@ -608,8 +614,9 @@ http_follow_redirect = no
 4. Functions
 
    4.1. http_connect(connection, url, [content_type, data,] result)
-   4.2. http_get_redirect(connection, result)
-   4.3. http_client_query(url, [post-data], [hdrs], result)
+   4.2. http_connect_raw(connection, url, content_type, data, result)
+   4.3. http_get_redirect(connection, result)
+   4.4. http_client_query(url, [post-data], [hdrs], result)
 
 4.1.  http_connect(connection, url, [content_type, data,] result)
 
@@ -622,7 +629,8 @@ http_follow_redirect = no
        content_type - Used only when posting data with HTTP POST. An
        Internet Media type, like "application/json" or "text/plain". Will
        be added to the HTTP request as a header.
-       data - Data or a pseudo variable holding data to be posted.
+       data - Data or a pseudo variable holding data to be posted. (may
+       contain pseudo variable)
        result - The name of a pseudo variable that will have the data of
        the response from the HTTP server.
 
@@ -649,7 +657,48 @@ xlog("L_INFO", "API-server HTTP connection: $avp(route) Result code $var(res)\n"
 );
 ...
 
-4.2.  http_get_redirect(connection, result)
+4.2.  http_connect_raw(connection, url, content_type, data, result)
+
+   Sends HTTP POST request to a given connection. Similar to http_connect.
+   The only difference is that the data parameter will not be parsed for
+   pseudo variables, therefore it can safely be used for content that may
+   contain "$" character like JSON.
+     * connection - the name of an existing HTTP connection, defined by a
+       httpcon modparam.
+       url - the part of the URL to add to the predefined URL in the
+       connection definition.
+       content_type - Used only when posting data with HTTP POST. An
+       Internet Media type, like "application/json" or "text/plain". Will
+       be added to the HTTP request as a header.
+       data - Data or a pseudo variable holding data to be posted. (will
+       not be parsed for pseudo variable)
+       result - The name of a pseudo variable that will have the data of
+       the response from the HTTP server.
+
+   The return value is the HTTP return code (if >=100) or the CURL error
+   code if below 100. See the $curlerror pseudovariable below for more
+   information about CURL error codes.
+
+   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
+   FAILURE_ROUTE, and BRANCH_ROUTE.
+
+   Example 1.20. http_connect_raw() usage
+...
+modparam("http_client", "httpcon", "apiserver=>http://kamailio.org/api/");
+...
+# POST Request
+$var(res) = http_connect_raw("apiserver", "/mailbox", "application/json", "{ ok,
+ {200, ok}}", "$avp(gurka)");
+xlog("L_INFO", "API-server HTTP connection: $avp(gurka) Result code $var(res)\n"
+);
+
+$var(res) = http_connect_war("apiserver", "/callroute", "application/json", "$va
+r(jsondata)", "$avp(route)");
+xlog("L_INFO", "API-server HTTP connection: $avp(route) Result code $var(res)\n"
+);
+...
+
+4.3.  http_get_redirect(connection, result)
 
    When a http connection gets a redirect and the connection is configured
    to follow redirects (301,302) then the target URL, the result of the
@@ -660,14 +709,14 @@ xlog("L_INFO", "API-server HTTP connection: $avp(route) Result code $var(res)\n"
        result - The name of a pseudo variable that will contain the last
        used URL.
 
-   Example 1.20. http_get_redirect() usage
+   Example 1.21. http_get_redirect() usage
 ...
 modparam("http_client", "httpredirect", 1);
 ...
 http_get_redirect("apiserver", "$var(targeturl)");
 ...
 
-4.3.  http_client_query(url, [post-data], [hdrs], result)
+4.4.  http_client_query(url, [post-data], [hdrs], result)
 
    Sends HTTP GET or POST request according to URL given in “url”
    parameter, which is a string that may contain pseudo variables.
@@ -695,7 +744,7 @@ http_get_redirect("apiserver", "$var(targeturl)");
    utils module. It is changed to use the same base library and settings
    as the rest of the functions in this module.
 
-   Example 1.21. http_client_query() usage
+   Example 1.22. http_client_query() usage
 ...
 # GET-Request
 http_client_query("http://api.com/index.php?r_uri=$(ru{s.escape.param})&f_uri=$(