# Module scgi

This module implements helper procs for SCGI applications. Example:

    import strtabs, sockets, scgi

    var counter = 0
    proc handleRequest(client: TSocket, input: string,
                       headers: PStringTable): bool {.procvar.} =
      inc(counter)
      client.writeStatusOkTextContent()
      client.send("Hello for the $#th time." % $counter & "\c\L")
      return false # do not stop processing

    run(handleRequest)

Warning: The API of this module is unstable, and therefore is subject to change.

# Imports

sockets, strutils, os, strtabs, asyncio

# Types

    EScgi = object of EIO

  the exception that is raised, if a SCGI error occurs

    TScgiState = object of TObject
      server: TSocket
      bufLen: int
      client*: TSocket            ## the client socket to send data to
      headers*: PStringTable      ## the parsed headers
      input*: string              ## the input buffer

  SCGI state object

    PAsyncScgiState = ref TAsyncScgiState

# Procs

    proc scgiError(msg: string) {.noreturn, raises: [EScgi], tags: [].}

  raises an EScgi exception with message msg.

    proc open(s: var TScgiState; port = TPort(4000); address = "127.0.0.1") {.
        raises: [EScgi, EOS], tags: [FReadIO].}

  opens a connection.

    proc close(s: var TScgiState) {.raises: [], tags: [].}

  closes the connection.

    proc next(s: var TScgiState; timeout: int = - 1): bool {.
        raises: [EOS, EScgi, EOverflow, EInvalidValue], tags: [FReadIO].}

  proceed to the first/next request. Waits `timeout` miliseconds for a request, if `timeout` is -1 then this function will never time out. Returns True if a new request has been processed.

    proc writeStatusOkTextContent(c: TSocket; contentType = "text/html") {.
        raises: [EOS, EInvalidValue], tags: [FWriteIO].}

  sends the following string to the socket c:

      Status: 200 OK\r\LContent-Type: text/html\r\L\r\L

  You should send this before sending your HTML page, for example.

    proc run(handleRequest: proc (client: TSocket; input: string;
                                  headers: PStringTable): bool {.nimcall.};
             port = TPort(4000)) {.raises: [EScgi, EOS, EOverflow, EInvalidValue],
                                   tags: [FReadIO].}

  encapsulates the SCGI object and main loop.

    proc open(handleRequest: proc (client: PAsyncSocket; input: string;
                                   headers: PStringTable) {.closure.};
              port = TPort(4000); address = "127.0.0.1"): PAsyncScgiState {.
        raises: [EOS, EScgi, EOverflow, EInvalidValue, E_Base],
        tags: [FReadIO, TEffect].}

  Creates an `PAsyncScgiState` object which serves as a SCGI server.

  After the execution of `handleRequest` the client socket will be closed automatically unless it has already been closed.

    proc register(d: PDispatcher; s: PAsyncScgiState): PDelegate {.discardable,
        raises: [], tags: [].}

  Registers `s` with dispatcher `d`.

    proc close(s: PAsyncScgiState) {.raises: [], tags: [].}

  Closes the `PAsyncScgiState`.

Generated: 2013-05-21 09:55:19 UTC