# 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.

http-proto-p
Object
reset
none
none

The `reset` method resets the http protocol object by clearing the protocol version and header.

parse
none
none

The `parse` method parse the input stream bound to the http protocol. In order to operate, an input stream must be associated with the protocol object or an exception is raised. After a stream has been parsed, the protocol version and the header are set.

set-input-stream
none
InputStream

The `set-input-stream` method binds an input stream to the http protocol object. Once the stream is bound, the input stream is parsed and the protocol version as well as the header are set.

write
none
none|OutputStream|Buffer

The `write` method formats and writes the http protocol object to an output stream or a buffer. Without argument, the default output stream is used. With an argument, an output stream or a buffer object can be used.

header-length
Integer
none

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

header-exists-p
Boolean
String

The `header-exists-p` predicate returns true if the property exists in the header. The string argument is the property name.

header-set
none
String Literal

The `header-set` method sets 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.

header-get
Property
Integer

The `header-get` method returns a property object by index.

header-map
String
String

The `header-map` method returns a property value by name. The string argument is the property name.

header-find
Property
String

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

header-lookup
Property
String

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

HttpRequest

The `HttpRequest` class is a base class designed to handle a http request. The class operates with the protocol version 1.1 as defined by RFC 2616. For a server request, the request is built by reading an input stream and setting the request command with its associated header. For a client request, the request is formatted with a request command and a eventually a uri. In both cases, the header is filled automatically depending on the request side.

http-request-p
HttpProto
HttpRequest
none

The `HttpRequest` constructor creates a default http request. By default, the request object is built with the GET method and the request uri set to the root value.

HttpRequest
String

The `HttpRequest` constructor creates a http request object with a specific command. By default, the request uri is set to root, except for the OPTIONS method

HttpRequest
Uri

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

HttpRequest
InputStream

The `HttpRequest` constructor creates a http request object with a specific input stream. At construction, the request header is cleared and the input stream is bound to the object.

HttpRequest
String String

The `HttpRequest` constructor creates a http request object with a specific method and a uri name. The first string argument is the request methid 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.

HttpRequest
String Uri

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

set-method
none
String

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

get-method
String
none

The `get-method` method returns the request method 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 is a base class designed to handle a http response. The class operates with the protocol version 1.1 as defined by RFC 2616. For a client response, the response is built by reading an input stream and setting the response status code with its associated header. For a server response, the response is formatted with a response status and additional header information. In both cases, the header is filled automatically depending on the response side. On the other hand, trying to set some header with an input stream bound to the response object might render the response object unsable.

http-response-p
HttpProto
HttpResponse
none

The `HttpResponse` constructor creates a default http response object. The response is marked valid with a default text/plain media type.

HttpResponse
Integer

The `HttpResponse` constructor creates a http response object with a status code. The response code is associated with the default text/plain media type.

HttpResponse
InputStream

The `HttpResponse` constructor creates a http response object with a specific input stream. At construction, the response header is cleared and the input stream is bound to the object.

HttpResponse
Integer String

The `HttpResponse` constructor creates a http response object with a status code and a media type. The first argument is the status code. The second argument is the associated media type.

set-status-code
none
Integer

The `set-status-code` method sets the response status code.

get-status-code
Integer
none

The `get-status-code` method returns the response status code.

status-ok-p
Boolean
none

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

media-type-p
Boolean
none

The `media-type-p` predicate returns true if the content type is defined in the response header.

get-media-type
String
none

The `get-media-type` method returns the media type defined in the response header.

encoding-mode-p
Boolean
none

The `encoding-mode-p` predicate returns true if the encoding mode is defined in the header.

get-encoding-mode
String
none

The `get-encoding-mode` method returns the response encoding mode. The encoding mode is normally found in the header. If the `get-response-stream` method is called, the response encoding mode is automatically sets to the response input stream.

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 location uri found in the response header. This method is equivalent to a header query.

set-location
none
String

The `set-location` method set the redirect location in the response header. The string argument is the location uri.

get-response-stream
InputStream
none

The `get-response-stream` method returns an input stream object that can be used to read the reponse content. The response stream object is normaly limited by the content length. For this reason, the returned stream is of type `InputBound`.

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.

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.

Session

The `Session` class that defines a session to be associated with an http transaction. The session object is designed to be persistent so that its data information can be retreived at any time. A session object has also the particularity to have a limited lifetime. A session object is created by name with an identifier. If a path is given, such path will be used as the session file name.

session-p
Serial
Session
String

The `Session` constructor creates a session by name. The string argument is the session name.

Session
String String

The `Session` constructor creates a session with a name and a user. The first argument is the session name. The second argument is the user name.

Session
String String String

The `Session` constructor creates a session with a name, a user and a path. The first argument is the session name. The second argument is the session user name. The third argument is the session path.

expire-p
Boolean
none

The `expire-p` predicate returns true if the session has expired.

get-name
String
none

The `get-name` method returns the session name.

set-hash-id
none
String

The `set-hash-id` method sets the session hash identifier. The session hash id must be unique and secured enough so that the session name cannot be derived from it.

get-hash-id
String
none

The `get-hash-id` method returns the session hash identifier.

set-user
none
String

The `set-user` method sets the session user name.

get-user
String
none

The `get-user` method returns the session user name.

set-path
none
String

The `set-path` method sets the session path.

get-path
String
none

The `get-path` method returns the session path.

set-maximum-age
none
Integer

The `set-max-age` method sets the session maximum age. The maximum age is an integer in seconds relative to the current time.

mark-expired
none
none

The `mark-expired` method marks the session as expired. This is done by forcing the expiration time to the creation time.q

get-valid-time
Integer
none

The `get-valid-time` method returns the remaining valid session time.

get-expire-time
Integer
none

The `get-expire-time` method returns the session expiration time in seconds. The expiration time is an absolute time.

set-expire-time
none
Integer

The `set-expire-time` method sets the session expiration time. The expiration time is an absolute time in seconds.

get-creation-time
Integer
none

The `get-creation-time` method returns the session creation time. The creation time is an absolute time in seconds.

get-modification-time
Integer
none

The `get-modification-time` method returns the session creation time. The modification time is an absolute time in seconds.