NaviServer - programmable web server

[ Main Table Of Contents | Table Of Contents | Keyword Index ]

# ns_http(n) 4.99.8 naviserver "NaviServer Built-in Commands"

## Name

ns_http - Simple HTTP client functionality

## Table Of Contents

## Synopsis

- ns_http cancel id
- ns_http cleanup
- ns_http list
- ns_http queue ?-method M? ?-headers S? ?-body B? ?-timeout T? url
- ns_http run ?-method M? ?-headers S? ?-body B? ?-timeout T? url
- ns_http wait ?-elapsed varName? ?-file varName? ?-headers H? ?-result varName? ?-spoolsize int? ?-status varName? ?-timeout t? ?-decompress? id

## Description

This command provides a simple HTTP client mechanism. For https client requests, use the ns_ssl defined by the nsssl module.

## COMMANDS

ns_http cancel id

  Cancel queued http request by id (ns_set id of request).

ns_http cleanup

  Cancel all pending http requests

ns_http list

  Return the list of currently running or pending requests in format: id url done|running ....

ns_http queue ?-method M? ?-headers S? ?-body B? ?-timeout T? url

  -method use the specified HTTP method such as GET or POST or HEAD

  -headers headers is the ns_set ID containing the additional headers to include in the HTTP request.

  -body body is the value which will be sent as the HTTP request body.

  -timeout Timeout for how long to wait for finishing the whole request (default 2:0, secs:microsesc)

  The command ns_http queue opens a connection to the web server denoted in the url and returns on success the id of the HTTP request, which might be used later in a ns_http wait or ns_http cancel command to refer to this request.

ns_http run ?-method M? ?-headers S? ?-body B? ?-timeout T? url

  Send a HTTP reuqest and wait for the result. The command ns_http run is similar to ns_http queue followed by ns_http wait.

ns_http wait ?-elapsed varName? ?-file varName? ?-headers H? ?-result varName? ?-spoolsize int? ?-status varName? ?-timeout t? ?-decompress? id

  -elapsed varName is the name of a variable that should be used to store the elapsed time for the request from beginning to finish

  -file varName is the name of a variable that will contain the name of the temporary file in case the request was larger than -spoolsize

  -headers headers is the ns_set ID which will receive the headers from the HTTP response.

  -result varName is the name of a variable that should be used to store the HTTP response body.

  -spoolsize In case the result is larger than spoolsize, it will be spooled to a temporary file returned in the variable denoted by -file.

  -status varName is the name of a variable that should be used to store the HTTP response status

  -timeout Optional timeout for the wait subcommand. The task might wait for input until the specified timeout for input. Might be governed by the total timeout specified in the queue subcommand.

  -decompress In case the response has a content encoding of gzip, automatically decompress the result

  id ns_set ID of the HTTP request to wait for.

  The command ns_http wait specifies, how the results of request should be delivered and what information should be obtained from the request in which form. The command waits until the request is finished. For retrieving large content (e.g. .mp4 files) from a server, it is recommended to use the -spoolsize option, since per default the results are received into memory.

## EXAMPLES

First, a minimal example:

     % ns_http queue http://www.google.com
     http0
     % ns_http wait -status S -result R http0
     1

The second example set a larger timeout on the request, provides query-headers and returns reply-headers, and spools results to a file, when the result is larger than 100 bytes.

     set queryHeaders [ns_set create]
     set replyHeaders [ns_set create]
     ns_set update $queryHeaders Host localhost

     set h [ns_http queue -headers $queryHeaders -timeout 10:0 http://www.google.com]
     ns_http wait -result R -headers $replyHeaders -status S -spoolsize 1000 -file F $h

     if {[info exists F]} {
       ns_log notice "Spooled [file size $F] bytes to $F"
       file delete $F
     } else {
       ns_log notice "Got [string length $R] bytes"
     }

## See Also

ns_httpget, ns_httppost, ns_httptime, ns_ssl

## Keywords

http-client, nssock