From 5ecea06b1f39a93735e8b2f711b125d0b1a84d16 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Fri, 15 Jun 2018 12:50:03 -0700 Subject: fixes #539 Feature request: customizable http error page --- docs/man/libnng.3.adoc | 3 + docs/man/nng_http_server_res_error.3http.adoc | 63 +++++++++++++++++++ docs/man/nng_http_server_set_error_file.3http.adoc | 73 ++++++++++++++++++++++ docs/man/nng_http_server_set_error_page.3http.adoc | 69 ++++++++++++++++++++ 4 files changed, 208 insertions(+) create mode 100644 docs/man/nng_http_server_res_error.3http.adoc create mode 100644 docs/man/nng_http_server_set_error_file.3http.adoc create mode 100644 docs/man/nng_http_server_set_error_page.3http.adoc (limited to 'docs') diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc index 21a34a6a..70fd3be2 100644 --- a/docs/man/libnng.3.adoc +++ b/docs/man/libnng.3.adoc @@ -341,7 +341,10 @@ These functions are intended for use with HTTP server applications. |<>|get HTTP server TLS configuration |<>|get and hold HTTP server instance |<>|release HTTP server instance +|<>|set custom HTTP error file +|<>|set custom HTTP error page |<>|set HTTP server TLS configuration +|<>|use HTTP server error page |<>|start HTTP server |<>|stop HTTP server |=== diff --git a/docs/man/nng_http_server_res_error.3http.adoc b/docs/man/nng_http_server_res_error.3http.adoc new file mode 100644 index 00000000..a62628f7 --- /dev/null +++ b/docs/man/nng_http_server_res_error.3http.adoc @@ -0,0 +1,63 @@ += nng_http_server_res_error(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_server_res_error - use HTTP server error page + +== SYNOPSIS + +[source, c] +---- +#include +#include + +int nng_http_server_set_error_file(nng_http_server *server, + nng_http_res *response); +---- + +== DESCRIPTION + +The `nng_http_server_res_error()` sets the body of _response_ +to _server_'s error page, which may have been customized using the +`<>` +or +`<>` +functions. + +The status code of the _response_ should have already been set, either +implicitly by allocating it with +`<>`, +or by calling +`<>`. + +Any content body previously set for _response_ will be overridden by +this function. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists. +`NNG_ENOTSUP`:: HTTP not supported. + +== SEE ALSO + +[.text-left] +<>, +<>, +<>, +<>, +<>, +<> diff --git a/docs/man/nng_http_server_set_error_file.3http.adoc b/docs/man/nng_http_server_set_error_file.3http.adoc new file mode 100644 index 00000000..dde8d980 --- /dev/null +++ b/docs/man/nng_http_server_set_error_file.3http.adoc @@ -0,0 +1,73 @@ += nng_http_server_set_error_file(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_server_set_error_file - set custom HTTP error file + +== SYNOPSIS + +[source, c] +---- +#include +#include + +int nng_http_server_set_error_file(nng_http_server *server, + uint16_t code, const char *path); +---- + +== DESCRIPTION + +The `nng_http_server_set_error_file()` sets an error page to be used +for HTTP status _code_ on the server instance _server_. +The body content of the HTTP responses will contain the file contents of +the file located at _path_, which should be an HTML file. + +The custom HTML content will be used when the server is returning an +internally generated error response, or is returning an error response +that was allocated with the +`<>` +function. +This HTML content will also be used if the application calls the +`<>`. +The last custom error page set for _code_ by either this function or +`<>` +will be used. + +NOTE: Error responses that have their body content changed after allocation, +or that are written directly by the application, will not use the body +content supplied here. + +NOTE: The file contents of _path_ are read when this function is called. +Therefore, if the file contents are changed, then this function should +be called again to update the error page. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOENT`:: The file named by _path_ does not exist. +`NNG_EPERM`:: No permission to read the file named by _path_. +`NNG_ENOMEM`:: Insufficient free memory exists. +`NNG_ENOTSUP`:: HTTP not supported. + +== SEE ALSO + +[.text-left] +<>, +<>, +<>, +<>, +<>, +<> diff --git a/docs/man/nng_http_server_set_error_page.3http.adoc b/docs/man/nng_http_server_set_error_page.3http.adoc new file mode 100644 index 00000000..271b9d99 --- /dev/null +++ b/docs/man/nng_http_server_set_error_page.3http.adoc @@ -0,0 +1,69 @@ += nng_http_server_set_error_page(3http) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_server_set_error_page - set custom HTTP error page + +== SYNOPSIS + +[source, c] +---- +#include +#include + +int nng_http_server_set_error_page(nng_http_server *server, + uint16_t code, const char *html); +---- + +== DESCRIPTION + +The `nng_http_server_set_error_page()` sets an error page to be used +for HTTP status _code_ on the server instance _server_. +The body content of the HTTP responses will contain _html_. + +The custom HTML content will be used when the server is returning an +internally generated error response, or is returning an error response +that was allocated with the +`<>` +function. +This HTML content will also be used if the application calls the +`<>`. +The last custom error page set for _code_ by either this function or +`<>` +will be used. + +NOTE: Error responses that have their body content changed after allocation, +or that are written directly by the application, will not use the body +content supplied here. + +The supplied HTML content is copied by this function, and may be reused +after this function returns. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists. +`NNG_ENOTSUP`:: HTTP not supported. + +== SEE ALSO + +[.text-left] +<>, +<>, +<>, +<>, +<>, +<> -- cgit v1.2.3-70-g09d2