# Standard nwg services reference

This appendix is a reference of the http protocol service, a sub-group of the standard nwg services module.

HttpProto

The `HttpProto` class is a base class that ease the deployment of the http protocol. The base class is built with a property list which is used to define the message header. The class also defines the write methods which are used to write a message either on an output stream or into a buffer.

Object
set-header
none
String Literal

The `set-header` method adds a new property to the http header. The first argument is the property name. The second argument is a literal object which is internally converted to a string.

write
none
none|Output|Buffer

The `write` method formats and writes the http header to an output stream or a buffer. Without argument, the default output stream is used.

HttpRequest

The `HttpRequest` class class is a base class designed to format a http request. The class operates with the protocol version 1.1 as defined by RFC 2616. A request is formatted with a request command and a uri.

http-request-p
HttpProto
HttpRequest
String

The `HttpRequest` constructor creates a http request object with a specific command. The string argument is the request command to use.

HttpRequest
Uri

The `HttpRequest` constructor creates a http request object with a uri. The default request command is "GET".

HttpRequest
String String

The `HttpRequest` constructor creates a http request object with a specific command and a uri name. The first string argument is the request command to use. The second string argument is the uri attached to the command. Note that the term uri should be understood as a request uri those scope applies to the whole server with certain commands such like the option command.

HttpRequest
String Uri

The `HttpRequest` constructor creates a http request object with a specific command and a uri. The first string argument is the request command to use. The second argument is the uri attached to the command.

write
none
none|Output|Buffer

The `write` method formats and writes the request to an output stream or a buffer. Without argument, the default output stream is used.

set-command
none
String

The `set-command` method sets the command request. This method does not check that the command is a valid HTTP command; thus leaving plenty of room for server development. As a matter of fact, RFC 2616 does not prohibit the existence of such extension.

get-command
String
none

The `get-command` method returns the request command string.

set-uri
none
String

The `set-uri` method sets the request uri. The argument string does not have to be a valid uri string since some commands might accept special string such like "*" to indicate all applicable uri.

get-uri
String
none

The `get-uri` method returns the request uri string.

HttpResponse

The `HttpResponse` class class is a http protocol class that handle the response following a http request. The response from a request generally contains a status line followed by a header and the body. The class is bound to an input stream which is used to read characters. The object encoding mode is set automatically from the header if it is available.

http-response-p
Input
HttpResponse
none

The `HttpResponse` constructor creates a default http response object. Without an input stream bound to it, the class operates like an input stream which operate on a character buffer.

HttpResponse
Input

The `HttpResponse` constructor creates a http response object with a specific input stream. At construction, the local buffer is reset and the input stream is bound to the object. The input stream is subsequently read to determine the response nature.

reset
none
none

The `reset` method reset the http response stream by clearing the local input buffer and the response header. The bound input stream is not touched.

get-status-code
Integer
none

The `get-status-code` method returns the response status code. If the response was not succesfully read, the status code is 0.

ok-p
Boolean
none

The `ok-p` predicate returns true is the response status code is valid (aka status 200).

encoding-mode-p
Boolean
none

The `encoding-mode-p` predicate returns true is encoding mode is defined in the header. If not, it might be desirabe to set the stream encoding mode.

location-p
Boolean
none

The `location-p` predicate returns true is the response status code indicates that a request should be made at another location. The location can be found with the `get-location` method.

get-location
String
none

The `get-location` method returns the loction uri found in the response header. This method is equivalent to a header query.

get-media-type
String
none

The `get-media-type` method returns the media type found in the response header. This method is equivalent to a header query.

set-input-stream
none
Input

The `set-input-stream` method binds an input stream to the http response object. Once the stream is bound, the input stream is read to determine the nature of the response. In particular, the response header is parsed automatically and the stream is ready to operate like any other input stream. If the header contains a length attribute, the `read` method and the associated predicate will behave like a stream which has reached its end when the number of characters read reach the content length.

header-length
Integer
none

The `header-length` method returns the number of entries in the response header.

header-get
Property
Integer

The `header-get` method returns a header entry by index. The integer argument is the header index. The result is in the form of a property object.

header-find
Property
String

The `header-find` method returns a header entry by name. The string argument is the property name. The result is in the form of a property object. If the entry is not found, the nil object is returned.

header-lookup
Property
String

The `header-lookup` method returns a header entry by name. The string argument is the property name. The result is in the form of a property object. If the entry is not found, an exception is raised.

header-get-value
String
String

The `header-get-value` method returns a header value by name. The string argument is the header property name. If the entry is not found, an exception is raised.

HttpReply

The `HttpReply` class is a simple designed to format a http reply. The class holds a property list which is used to format the header and a buffer which is the reply content. When the write method is called, the header and the buffer is formatted to the output stream argument. The class creates initially the content-type property which is initialized to the text/plain mime value.

http-reply-p
HttpProto
HttpReply
none

The `HttpReply` constructor creates an empty http reply object.

HttpReply
String

The `HttpReply` constructor creates a http reply object with a specific content type. The string argument is the mime content type to set.

add-buffer
none
Literal|Buffer

The `add-buffer` method adds some content to the HTTP reply buffer. The argument can be either a literal r a buffer object.

write
none
none|Output|Buffer

The `write` method formats and writes the reply to an output stream or a buffer. Without argument, the default output stream is used.

set-cookie
none
Cookie

The `set-cookie` method sets a cookie object to the http header. The cookie version is properly handled by the method.

set-status
none
Integer

The `set-status` method sets a reply status code. The code must be a valid http status code. The method takes care to format properly the status message. Note that a reply body can be attached to describe the message status. Note also that RFC 2616 prohibits the presence of a message body with the status code 1xx (informational), 204 (no content) and 304 (not modified). This rule is enforced by the class.

redirect
none
String

The `redirect` method set the message status to indicate that the page should be redirected to the specified uri. The string argument is the target uri. The method operates by setting a status code 303 (see other) in the header. If a temporary redirection is preferable, the implementor is advised to set manually the appropriate status code.

Cookie

The `Cookie` class is a special class designed to handle cookie setting within a http transaction. A cookie is name/value pair that is set by the server and stored by the http client. Further connection with the client will result with the cookie value transmitted by the client to the server. A cookie has various parameters that controls its existence and behavior. The most important one is the cookie maximum age that is defined in seconds. A null value tells the client to discard the cookie. A cookie without maximum age is valid only during the http client session. A cookie can be added to the `HttpReply` object with the `set-cookie` method. A cookie can be constructed with a name/value pair. An optional third argument is the maximum age. The default cookie version is 1 as specified by RFC 2965. With a version 1, the maximum age is interpreted as the number of seconds before the cookie expires. With version 0, the maximum age is the absolute time.

cookie-p
Object
Cookie
String String

The `Cookie` constructor creates a cookie with a name value pair. The first argument is the cookie name. The second argument is the cookie value.

Cookie
String String Integer

The `Cookie` constructor creates a cookie with a name value pair and a maximum age. The first argument is the cookie name. The second argument is the cookie value. The third argument is the cookie maximum age.

get-version
Integer
none

The `get-version` method returns the cookie version.

set-version
none
Integer

The `set-version` method sets the cookie version. The version number can only be 0 or 1.

get-name
String
none

The `get-name` method returns the cookie name. This is the name store on the http client.

set-name
none
String

The `set-name` method sets the cookie name. This is the name store on the http client.

get-value
String
none

The `get-value` method returns the cookie value. This is the value stored on the http client bounded by the cookie name.

set-value
none
String

The `set-value` method sets the cookie value. This is the value store on the http client bounded by the cookie name.

get-maximum-age
Integer
none

The `get-maximum-age` method returns the cookie maximum age. The default value is -1, that is, no maximum age is set and the cookie is valid only for the http client session.

set-maximum-age
none
Integer

The `set-maximum-age` method sets the cookie maximum age. A negative value is reset to -1. A 0 value tells the http client to discard the cookie. A positive value tells the http client to store the cookie for the remaining seconds.

get-path
String
none

The `get-path` method returns the cookie path value. The path determines for which http request the cookie is valid.

set-path
none
String

The `set-path` method sets the cookie path value. The path determines for which http request the cookie is valid.

get-domain
String
none

The `get-domain` method returns the cookie domain value.

set-domain
none
String

The `set-domain` method sets the cookie domain value. It is string recommended to use the originator domain name since many http client can reject cookie those domain name does not match the originator name.

get-port
Integer
none

The `get-port` method returns the cookie port number.

set-port
none
Integer

The `set-port` method sets the cookie port number. This value is not used with a cookie version 0.

get-comment
String
none

The `get-comment` method returns the cookie comment value.

set-comment
none
String

The `set-comment` method sets the cookie comment value.

get-comment-url
String
none

The `get-comment-url` method returns the cookie comment url value.

set-comment-url
none
String

The `set-comment-url` method sets the cookie comment url value. This value is not used with cookie version 0.

get-discard
Boolean
none

The `get-discard` method returns the cookie discard flag.

set-discard
none
Boolean

The `set-discard` method sets the cookie discard flag. The discard flag the tells the user agent to destroy the cookie when it terminates. This value is not used with cookie version 0.

get-secure
Boolean
none

The `get-secure` method returns the cookie secure flag.

set-secure
none
Boolean

The `set-secure` method sets the cookie secure flag. When a cookie is secured, it is only returned by the http client if a connection has been secured (i.e use https).

to-string
String
none

The `to-string` method returns a string formatted for the http reply header. Normally this method should not be called since the `set-cookie` method of the `httpReply` takes care of such thing.