# Module httpclient

This module implements a simple HTTP client that can be used to retrieve webpages/other data.

# Retrieving a website

This example uses HTTP GET to retrieve `http://google.com`

    echo(getContent("http://google.com"))

# Using HTTP POST

This example demonstrates the usage of the W3 HTML Validator, it uses `multipart/form-data` as the `Content-Type` to send the HTML to the server.

    var headers: string = "Content-Type: multipart/form-data; boundary=xyz\c\L"
    var body: string = "--xyz\c\L"
    # soap 1.2 output
    body.add("Content-Disposition: form-data; name=\"output\"\c\L")
    body.add("\c\Lsoap12\c\L")

    # html
    body.add("--xyz\c\L")
    body.add("Content-Disposition: form-data; name=\"uploaded_file\";" &
             " filename=\"test.html\"\c\L")
    body.add("Content-Type: text/html\c\L")
    body.add("\c\L<html><head></head><body><p>test</p></body></html>\c\L")
    body.add("--xyz--")

    echo(postContent("http://validator.w3.org/check", headers, body))

# SSL/TLS support

This requires the OpenSSL library, fortunately it's widely used and installed on many operating systems. httpclient will use SSL automatically if you give any of the functions a url with the `https` schema, for example: `https://github.com/`, you also have to compile with `ssl` defined like so: `nimrod c -d:ssl ...`.

# Imports

sockets, strutils, parseurl, parseutils, strtabs

# Types

    TResponse* = tuple[version: string, status: string, headers: PStringTable,
                       body: string]

    EInvalidProtocol* = object of ESynch

  exception that is raised when server does not conform to the implemented protocol

    EHttpRequestErr* = object of ESynch

  Thrown in the `getContent` proc and `postContent` proc, when the server returns an error

    THttpMethod* = enum
      httpHEAD, ## Asks for the response identical to the one that would
                ## correspond to a GET request, but without the response
                ## body.
      httpGET,                    ## Retrieves the specified resource.
      httpPOST, ## Submits data to be processed to the identified
                ## resource. The data is included in the body of the
                ## request.
      httpPUT,                    ## Uploads a representation of the specified resource.
      httpDELETE,                 ## Deletes the specified resource.
      httpTRACE, ## Echoes back the received request, so that a client
                 ## can see what intermediate servers are adding or
                 ## changing in the request.
      httpOPTIONS, ## Returns the HTTP methods that the server supports
                   ## for specified address.
      httpCONNECT ## Converts the request connection to a transparent
                  ## TCP/IP tunnel, usually used for proxies.

  the requested HttpMethod

# Procs

    proc request*(url: string; httpMethod = httpGET; extraHeaders = ""; body = ""): TResponse

  Requests `url` with the specified `httpMethod`.
  Extra headers can be specified and must be seperated by `\c\L`

    proc get*(url: string; maxRedirects = 5): TResponse

  GET's the `url` and returns a `TResponse` object
  This proc also handles redirection

    proc getContent*(url: string): string

  GET's the body and returns it as a string.
  Raises exceptions for the status codes `4xx` and `5xx`

    proc post*(url: string; extraHeaders = ""; body = ""; maxRedirects = 5): TResponse

  POST's `body` to the `url` and returns a `TResponse` object.
  This proc adds the necessary Content-Length header.
  This proc also handles redirection.

    proc postContent*(url: string; extraHeaders = ""; body = ""): string

  POST's `body` to `url` and returns the response's body as a string
  Raises exceptions for the status codes `4xx` and `5xx`

    proc downloadFile*(url: string; outputFilename: string)

  Downloads `url` and saves it to `outputFilename`

Generated: 2012-09-23 21:47:54 UTC