ns_return(n) 4.99.5 naviserver "NaviServer Built-in Commands"

Name

ns_return - Return a complete HTTP response

Table Of Contents

• Table Of Contents
• Synopsis
• Description
• COMMANDS
• EXAMPLES
• See Also
• Keywords

Synopsis

Description

These commands are used to construct a complete HTTP response and return it to the requesting client. The response may be transcoded into a different encoding, compressed and/or sent in chunks as automatically negotiated by the client and server settings.

Unless otherwise noted, these commands return true if the command failed and false otherwise. All of them can raise an error if their arguments are incorrect.

COMMANDS

ns_return ?-binary? status mime-type body

Return a complete response to the client consisting of the given body and a set of HTTP headers. status is an integer HTTP status code such as 200 (OK) or 404 (Not Found). When the optional flag -binary is used, the content of the tcl bytearray is transmitted.

mime-type is the mime-type of the body. If a charset attribute is included in the mime-type it will be used to set the encoding of the connection. Otherwise, the connection encoding will be used to construct a charset attribute for the mime-type.

If body is Tcl byte-array object then no transcoding will take place. Otherwise, the encoding in effect for the current connection will be used to encode the body.

After the command completes the connection is returned to the driver thread to be closed or monitored for keep-alive and the calling connection thread continues to execute code.

ns_returnfile status mime-type filepath

Return the given file as the complete response body. Headers are constructed using status, mime-type and any pending headers set using ns_conn outputheaders. The bytes of the file are not transformed in any way.

After the command completes the connection is returned to the driver thread to be closed or monitored for keep-alive and the calling connection thread continues to execure code.

ns_returnfp status mime-type channel length

Return length bytes from channel as the response body. The current offset of the channel is the beginning of the body -- the offset will be left at length bytes. The bytes of the file are not transformed in any way.

After the command completes the connection is returned to the driver thread to be closed or monitored for keep-alive and the calling connection thread continues to execure code.

ns_respond ?-status status? ?-type mime-type? ?-length length? ?-headers setid? ?-string body? ?-binary body? ?-file filepath? ?-fileid channel?

Return a complete response to the client using exactly one of -string, -binary, -file or -fileid as the body.

After the command completes the connection is returned to the driver thread to be closed or monitored for keep-alive and the calling connection thread continues to execure code.

-status status

The HTTP status code. Default 200.

-type mime-type

The mime-type of the response body. Default */*.

-headers setid

A set of headers which will replace any pending headers for the response.

-string body

The Tcl string to send as the response body. The body may be encoded into an apprpriate character set if required by the client and server settings.

-binary body

The byte-array representation of the given Tcl object will be used as the reponse body. No character set conversion will be done.

-file filepath

The file identified by the given pathname will be sent as the response body. The bytes of the file will not be transformed in any way.

-fileid channel

length bytes of the given channel will be used as the response body. The bytes of the file will not be transformed in any way.

-length length

Specifies the number of bytes to send from the channel.

EXAMPLES

A traditional geek greeting:

ns_register_proc GET /hello {
    ns_return 200 text/plain "Hello World!"
}

A traditional Albanian greeting, using an explicit charset:

ns_register_proc GET /hello {
    ns_return 200 "text/plain; charset=iso-8859-2" "Përshëndetje të gjithëve!"
}

See Also

ns_adp_puts, ns_conn, ns_guesstype, ns_register_fastpath, ns_write, ns_writer, returnstatus-cmds

Keywords

charset, encoding, response, return, status