returnstatus-cmds - Return a complete HTTP status message
These commands sends a complete response to the client using a variety of different HTTP status codes. On contrary to the lower level commands like ns_respond or ns_return these commands are designed to ease consistent behavior in common success, redirect or error situations. Like with all response commands, all queued headers, such as those set by ns_setcookie (see ns_cookie) or via 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., when they are called from a background thread without connection, or when a response has already been sent.
After these command finish 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.
NOTE: A script calling one of the response sending commands does not end at the time these commands are invoked. When used in an ADP page, ns_adp_abort or ns_adp_return should be called to end script processing after e.g. ns_returnredirect. Some frameworks based on NaviServer have custom commands for this purpose. OpenACS uses ad_script_abort.
Sends a response with status code 200, OK to the client with an empty body. Use ns_returnnotice, ns_response, or ns_return to send results with this status code to the client.
Sends a response with status code 301, Moved to the client. The response header field Location is supplied with the value the provided location. The location can be a relative or absolute URI. When ns_locationproc is configured, its result will be used.
Use this response to signal that the resource was permanently moved to a new location. For temporary redirects, use ns_returnredirect.
Sends a response with status code 302, Found to the client. The response header field Location is supplied with the value the provided location. The location can be a relative or absolute URI. When ns_locationproc is configured, its result will be used.
Use this response to signal that the resource has temporarily moved to a new location. For permanent redirects, use ns_returnmoved.
Sends 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.
Sends 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.
Sends 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.
Sends 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.
Sends 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.
Sends a response with the given status code and the error message wrapped in HTML.
Use this command to return an HTTP status response to the client which is not covered by the above commands, or to customize the HTML message.
Sends 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 its place. The new resource may be a static, Tcl or ADP page, or a registered procedure or ADP. These redirects are used for providing customized (templated) error pages.
ns_section "ns/server/server1/redirects" {
ns_param 404 /notfound.adp
ns_param 503 /busy.html
}
The realm used for HTTP Basic authentication is set server-wide:
ns_section "ns/server" {
ns_param realm "Example"
}
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
}