[
Table Of Contents
| Keyword Index
]
ns_returnerror(n) 4.99.2 "NaviServer Built-In Commands"
ns_returnerror - Return a complete HTTP status message
TABLE OF CONTENTS
SYNOPSIS
DESCRIPTION
COMMANDS
CONFIGURATION
EXAMPLES
SEE ALSO
KEYWORDS
These commands return a complete response to the client using a variety of
different HTTP status codes. Any queued headers, such as those set by
ns_setcookie or manually using ns_conn outputheaders and
ns_set put, are added to the default headers and sent in the response.
These commands return 0 (zero) if the response was successfully
sent to the client and 1 if the write to the connection failed.
They will raise an error if no connection is available, e.g. they are called from
a non-connection thread or the response has already been sent and the connection
closed.
After the command returns the connection is returned to the driver thread to be
closed or monitored for keep-alive. The calling connection thread can then
continue to execute code, e.g. to cleanup resources or for logging.
Custom error pages may be specified in the server configuration file to
override the default HTML message which is returned, for those commands which
return one.
- ns_returnok
-
Return a response with status code 200, OK. No body content is
sent.
- ns_returnmoved url
-
Return a response with status code 301, Moved. A Location
header will be set with the given url.
Use this response to signal that the resource identified by the requested URL
has permanently moved to a new location. The client should request the new URL
instead of the old one in the future.
- ns_returnredirect url
-
Return a response with status code 302, Found. The Location
header will be set to the url if given.
Use this response to signal that the resource identified by the requested URL has
temporarily moved to a new location. The client should continue to request the
old URL.
- ns_returnbadrequest reason
-
Return a response with status code 400, Bad Request using the
given reason in the HTML message.
Use this response to signal that the client sent a malformed request and should
not try again without modifications.
- ns_returnunauthorized
-
Return a response with status code 401, Access Denied. A
WWW-Authenticate header will be set using the realm specified
in the configuration file option ns/server:realm.
Use this response to signal that the user is not authorized to access the URL,
and to trigger HTTP basic authorization. The client may present
a pop-up window for the user to enter their username and password.
NB: The username and password will be sent in plain text.
- ns_returforbidden
-
Return a response with status code 403, Forbidden.
Use this response to signal that the authentication information the client
supplied are insufficient to grant them access to the requested URL.
- ns_returnnotfound
-
Return a response with status code 404, Not Found.
Use this response to signal that the content the client requested could not be
located given the URL that was requested.
- ns_returnunavailable
-
Return a response with status code 503, Unavailable.
Use this response to signal that the server is too busy to deliver the requested
resource or is undergoing maintenance.
- ns_returnerror status message
-
Return a response with the given status code and the error message
wrapped in HTML.
Use this command to return a HTTP status response to the client which is not
covered by the above commands, or to customize the HTML message.
- ns_returnnotice status title message
-
Return a response with the given status code and an HTML message with the
given title and message.
Use this command to return an arbitrary response to the client. Some HTTP
responses are expected not to return body content. Check RFC 2616 for details.
NB: You should be careful what you put in the title and message.
It may be tempting to use data which the client has sent you such as a form
variable, but it may not be what you expect.
The body of the response which is returned for a variety of status codes can be
customized by registering a new resource which should be returned in it's place.
The new resource may be a static, Tcl or ADP page, or a registered procedure
or ADP.
The realm used for HTTP Basic authentication is set server-wide:
Use a custom error message to notify users when the hamsters which turn the
wheels that run the server are on lunch break:
| |
ns_register_proc GET /service {
set hour [clock format [clock seconds] -format %H]
if {$hour >= 12 && $hour <= 13} {
ns_returnerror 503 "Gone for lunch. Back at 2pm."
return
}
ns_returnok
}
|
ns_return
response , return , status