Documentation updated for REST_PUT

modules/rest_client/README

@@ -42,7 +42,11 @@ Liviu Chircu
                       recv_body_pv[, [recv_ctype_pv][,
                       [retcode_pv]]])
 
-              1.4.3. rest_append_hf(txt)
+              1.4.3. rest_put(url, send_body_pv, [send_ctype_pv],
+                      recv_body_pv[, [recv_ctype_pv][,
+                      [retcode_pv]]])
+
+              1.4.4. rest_append_hf(txt)
 
         1.5. Exported Asynchronous Functions
 
@@ -53,6 +57,10 @@ Liviu Chircu
                       recv_body_pv[, [recv_ctype_pv][,
                       [retcode_pv]]])
 
+              1.5.3. rest_put(url, send_body_pv, [send_ctype_pv],
+                      recv_body_pv[, [recv_ctype_pv][,
+                      [retcode_pv]]])
+
    List of Examples
 
    1.1. Setting the connection_timeout parameter
@@ -63,16 +71,18 @@ Liviu Chircu
    1.6. Setting the ssl_capath parameter
    1.7. rest_get usage
    1.8. rest_post usage
-   1.9. rest_append_hf usage
-   1.10. async rest_get usage
-   1.11. async rest_post usage
+   1.9. rest_put usage
+   1.10. rest_append_hf usage
+   1.11. async rest_get usage
+   1.12. async rest_post usage
+   1.13. async rest_put usage
 
 Chapter 1. Admin Guide
 
 1.1. Overview
 
    The rest_client module provides a means of interacting with an
-   HTTP server by doing RESTful queries, such as GET and POST.
+   HTTP server by doing RESTful queries, such as GET,PUT and POST.
 
 1.2. Dependencies
 
@@ -237,7 +247,47 @@ if (!rest_post("http://myserver.org/register_user", "$fU", , "$var(body)
 }
 ...
 
-1.4.3.  rest_append_hf(txt)
+
+1.4.3.  rest_put(url, send_body_pv, [send_ctype_pv], recv_body_pv[,
+[recv_ctype_pv][, [retcode_pv]]])
+
+   Issues an HTTP PUT request to the specified url. The request
+   body will be copied from the send_body_pv pseudo-variable. The
+   MIME Content-Type header for the request will be taken from
+   send_ctype_pv (default is "application/x-www-form-urlencoded")
+
+   The mandatory recv_body_pv pseudo-var will hold the body of the
+   HTTP response.
+
+   The optional recv_ctype_pv parameter will contain the value of
+   the "Content-Type" header of the response message.
+
+   The optional retcode_pv pseudo-var parameter can be given in
+   order to retrieve the HTTP status code of the response message.
+   Since the module based on libcurl, a 0 value means no HTTP
+   reply arrived at all.
+
+   Possible parameter types
+     * url, send_body_pv, send_type_pv - String, pseudo-variable,
+       or a String which includes pseudo-variables.
+     * recv_body_pv, recv_ctype_pv, retcode_pv - pseudo-variables
+
+   This function can be used from the startup, branch, failure,
+   request and timer routes.
+
+   Example 1.9. rest_put usage
+...
+# Storing data using a RESTful service with an HTTP PUT request
+
+if (!rest_put("http://myserver.org/register_user", "$fU", , "$var(body)"
+, "$var(ct)", "$var(rcode)")) {
+        xlog("Error code $var(rcode) in HTTP PUT!\n");
+        send_reply("403", "PUT Forbidden");
+        exit;
+}
+...
+
+1.4.4.  rest_append_hf(txt)
 
    Appends 'txt' to the HTTP headers of the subsequent request.
    Multiple headers can be appended by making multiple calls
@@ -254,7 +304,7 @@ if (!rest_post("http://myserver.org/register_user", "$fU", , "$var(body)
    This function can be used from the startup, branch, failure,
    request and timer routes.
 
-   Example 1.9. rest_append_hf usage
+   Example 1.10. rest_append_hf usage
 ...
 # Example of querying a REST service requiring additional headers
 
@@ -273,7 +323,7 @@ if (!rest_get("http://getcredit.org/?ruri=$fU", "$var(credit)")) {
    but in an asynchronous way. Script execution is suspended until
    the entire content of the HTTP response if available.
 
-   Example 1.10. async rest_get usage
+   Example 1.11. async rest_get usage
 route {
         ...
         async(rest_get("http://getcredit.org/?ruri=$fU", "$var(credit)",
@@ -298,7 +348,7 @@ route [resume]
    but in an asynchronous way. Script execution is suspended until
    the entire content of the HTTP response if available.
 
-   Example 1.11. async rest_post usage
+   Example 1.12. async rest_post usage
 route {
         ...
         async(rest_post("http://myserver.org/register_user", "$fU", , "$
@@ -314,3 +364,29 @@ route [resume]
         }
         ......
 }
+
+
+1.5.3.  rest_put(url, send_body_pv, [send_ctype_pv], recv_body_pv[,
+[recv_ctype_pv][, [retcode_pv]]])
+
+   Sends a PUT HTTP request. This function behaves exactly the
+   same as rest_put (in terms of input, output and processing),
+   but in an asynchronous way. Script execution is suspended until
+   the entire content of the HTTP response if available.
+
+   Example 1.13. async rest_put usage
+route {
+        ...
+        async(rest_put("http://myserver.org/register_user", "$fU", , "$v
+ar(body)", "$var(ct)", "$var(rcode)"), resume);
+}
+
+route [resume]
+{
+        if ($rc < 0) {
+                xlog("Error code $var(rcode) in HTTP PUT!\n");
+                send_reply("403", "PUT Forbidden");
+                exit;
+        }
+        ......
+}