nng_http_handler_collect

diff --git a/man/tip/nng_dial.3.html b/man/tip/nng_dial.3.html index b0a09546..14c6d876 100644 --- a/man/tip/nng_dial.3.html +++ b/man/tip/nng_dial.3.html @@ -536,7 +536,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b

DESCRIPTION

The nng_dialer() function creates a newly initialized +

The nng_dial() function creates a newly initialized nng_dialer object, associated with socket s, and configured to listen at the address specified by url, and starts it. @@ -654,7 +654,7 @@ using nng_dialer_create() an NNG_EINVAL -

An invalid set of flags was specified.

An invalid set of flags or an invalid url was specified.

diff --git a/man/tip/nng_dialer_setopt.3.html b/man/tip/nng_dialer_setopt.3.html index bb09f650..a0b8731e 100644 --- a/man/tip/nng_dialer_setopt.3.html +++ b/man/tip/nng_dialer_setopt.3.html @@ -573,7 +573,7 @@ transports themselves.

Once a dialer has started, it is generally not possible to change -it’s configuration. +its configuration. diff --git a/man/tip/nng_http_handler_alloc.3http.html b/man/tip/nng_http_handler_alloc.3http.html index bac2c023..c2965f8c 100644 --- a/man/tip/nng_http_handler_alloc.3http.html +++ b/man/tip/nng_http_handler_alloc.3http.html @@ -742,6 +742,7 @@ sent the data, with Content-Length of size bytes, nng_aio_finish(3), nng_aio_get_input(3), nng_aio_set_output(3), +nng_http_handler_collect_body(3http), nng_http_handler_free(3http), nng_http_handler_set_host(3http), nng_http_handler_set_method(3http), diff --git a/man/tip/nng_http_handler_collect_body.3http.html b/man/tip/nng_http_handler_collect_body.3http.html new file mode 100644 index 00000000..dea2ce32 --- /dev/null +++ b/man/tip/nng_http_handler_collect_body.3http.html @@ -0,0 +1,649 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_http_handler_collect_body(3http) + + + + + + + +

SYNOPSIS

#include <nng/nng.h>
+#include <nng/supplemental/http/http.h>
+
+int nng_http_handler_collect_body(nng_http_handler *handler, bool want, size_t maxsz);

DESCRIPTION

The nng_http_handler_collect_data() function causes the handler to +collect any request body that was submitted with the request, and attach +it to the nng_http_req before the handler is called.

Subsequently the data can be retrieved by the handler from the request with the +nng_http_req_get_data() function.

The collection is enabled if want is true. +Furthermore, the data that the client may sent is limited by the +value of maxsz. +If the client attempts to send more data than maxsz, then the +request will be terminated with a 400 “Bad Request” status.

+ + + + + +

+ +	+Limiting the size of incoming request data can provide protection +against denial of service attacks, as a buffer of the client-supplied +size must be allocated to receive the data. +

In order to provide an unlimited size, use (size_t)-1 for maxsz. +The value 0 for maxsz can be used to prevent any data from being passed +by the client.

The built-in handlers for files, directories, and static data limit the +maxsz to zero by default. +Otherwise the default setting is to enable this capability with a default +value of maxsz of 1 megabyte.

+ + + + + +

+ +	+The handler looks for data indicated by the `Content-Length:` HTTP +header. +If this header is absent, the request is assumed not to contain any data. +

+ + + + + +

+ +	+This specifically does not support the `Chunked` transfer-encoding. +This is considered a bug, and is a deficiency for full HTTP/1.1 compliance. +However, few clients send data in this format, so in practice this should +not create few limitations. +

RETURN VALUES

This function returns 0 on success, and non-zero otherwise.

ERRORS

+ + + + + +

+NNG_ENOTSUP +

No support for HTTP in the library.

RETURN VALUES

This function returns 0 on success, and non-zero otherwise.

These functions return 0 on success, and non-zero otherwise.

diff --git a/man/tip/nng_msg_trim.3.html b/man/tip/nng_msg_trim.3.html index 3a67da93..9613ad73 100644 --- a/man/tip/nng_msg_trim.3.html +++ b/man/tip/nng_msg_trim.3.html @@ -516,7 +516,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b

NAME

nng_msg_trim, nng_msg_trim_u32 - remove data from start of message body

nng_msg_trim - remove data from start of message body

@@ -528,8 +528,9 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b

#include <nng/nng.h>
 
 int nng_msg_trim(nng_msg *msg, size_t size);
-
-int nng_msg_trim_u32(nng_msg *msg, uint32_t *val32);

+int nng_msg_trim_u16(nng_msg *msg, uint16_t *val16); +int nng_msg_trim_u32(nng_msg *msg, uint32_t *val32); +int nng_msg_trim_u64(nng_msg *msg, uint64_t *val64);

@@ -538,10 +539,11 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b

DESCRIPTION

The nng_msg_trim() and nng_msg_trim_u32() functions remove data from +

The nng_msg_trim() family of functions removes data from the start of the body of message msg. The first function removes size bytes. -The second function removes 4 bytes, and stores them in the value val32, +The remaining functions remove 2, 4, or 8 bytes, and stores them in the value +(such as val32), after converting them from network-byte order (big-endian) to native byte order.

@@ -551,7 +553,7 @@ byte order.

RETURN VALUES

This function returns 0 on success, and non-zero otherwise.

These functions return 0 on success, and non-zero otherwise.

diff --git a/man/tip/nng_options.5.html b/man/tip/nng_options.5.html index 08de92f3..75016132 100644 --- a/man/tip/nng_options.5.html +++ b/man/tip/nng_options.5.html @@ -920,7 +920,7 @@ Those that do generally have a default value of 8.

-Each node along a forwarding path may have it’s own value for the +Each node along a forwarding path may have its own value for the maximum time-to-live, and performs its own checks before forwarding a message. Therefore it is helpful if all nodes in the topology use the same value for this option. diff --git a/man/tip/nng_opts_parse.3supp.html b/man/tip/nng_opts_parse.3supp.html index 7b29437c..bc3e26b4 100644 --- a/man/tip/nng_opts_parse.3supp.html +++ b/man/tip/nng_opts_parse.3supp.html @@ -543,7 +543,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b bool o_arg; // Option takes an argument if true } nng_optspec; -int nng_opts_parse(int argc, const char **argv, const nng_optspec *spec, int *val, const char **arg, int *idx); +int nng_opts_parse(int argc, char *const *argv, const nng_optspec *spec, int *val, char **arg, int *idx); diff --git a/man/tip/nng_sockaddr.5.html b/man/tip/nng_sockaddr.5.html index d5e069a9..9ce09af3 100644 --- a/man/tip/nng_sockaddr.5.html +++ b/man/tip/nng_sockaddr.5.html @@ -558,7 +558,7 @@ addresses, IPC paths, and so forth.

The name sockaddr is based on it’s similarity with POSIX struct sockaddr, +

The name sockaddr is based on its similarity with POSIX struct sockaddr, but in the nng library, these addresses are more closely affiliated with instances of nng_pipe than of nng_socket. diff --git a/man/tip/nng_stat.5.html b/man/tip/nng_stat.5.html new file mode 100644 index 00000000..102bd09e --- /dev/null +++ b/man/tip/nng_stat.5.html @@ -0,0 +1,622 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_socket(5) + + + + + + +

SYNOPSIS

#include <nng/nng.h>
+
+typedef struct nng_stat nng_stat;

DESCRIPTION

An nng_stat represents a statistic. +All statistics have names (nng_stat_name()) and +descriptions (nng_stat_desc()), and are +typed (nng_stat_type()).

Most statistics are numeric, +and thus carry a value (nng_stat_value()) +and frequently also a unit that the value measures (nng_stat_unit()).

Some statistics however, are simply strings (nng_stat_string()), +and thus carry no numeric value.

Statistics are organized as a tree, and any given statistic can have siblings +(nng_stat_next()). +Note however that generally only NNG_STAT_SCOPE statistics, which are +act as placeholders in the tree (and carry no value), +will have children (nng_stat_child()).

A tree of statistics is collected using nng_stats_get(), +and can be freed when no longer needed with nng_stats_free(). +This collection process is generally performed in a way to minimize impact +to running operations, but there is still some impact caused by collection +of statistics.

The time when a statistic’s value is captured can be obtained using +nng_stat_timestap(), which is useful for +measuring rates of change in certain statistics.

+ + + + + +

+ +	+The presence, names, and meanings of any given statistic are +subject to change at any time. These statistics are provided as an aid +for debugging, and should generally not be relied upon for programmatic +behaviors. +

+ + + + + +

+ +	+Statistics may be disabled by build-time configuration options, +in order to reduce program size and run-time overheads. +

SYNOPSIS

#include <nng/nng.h>
+
+typedef struct nng_stat nng_stat;
+
+nng_stat *nng_stat_child(nng_stat *parent);

DESCRIPTION

The nng_stat_child() function returns the first child statistic of the +statistic parent. +If no children are present, then NULL is returned.

+ + + + + +

+ +	+Only statistics with type (see `nng_stat_type()`) +of `NNG_STAT_SCOPE` will have children. +

RETURN VALUES

The first child statistic of parent, or NULL if parent has no children.

ERRORS

None.

SYNOPSIS

#include <nng/nng.h>
+
+typedef struct nng_stat nng_stat;
+
+const char *nng_stat_desc(nng_stat *stat);

DESCRIPTION

The nng_stat_desc() function returns a brief, human-readable description +for the statistic stat.

+ + + + + +

+ +	+This description can be used for a tool-tip in user interfaces +displaying these statistic values. +

+ + + + + +

+ +	+At this time, only English descriptions are provided. +

RETURN VALUES

The description of statistic stat.

ERRORS

None.

SYNOPSIS

#include <nng/nng.h>
+
+typedef struct nng_stat nng_stat;
+
+const char *nng_stat_name(nng_stat *stat);

DESCRIPTION

The nng_stat_name() function returns the name for the statistic stat.

+ + + + + +

+ +	+The global root statistic will have the empty string ("") as it’s name. +

RETURN VALUES

The name of statistic stat.

ERRORS

None.

SYNOPSIS

#include <nng/nng.h>
+
+typedef struct nng_stat nng_stat;
+
+nng_stat *nng_stat_next(nng_stat *stat);

DESCRIPTION

The nng_stat_next() function returns the next sibling statistic of the +statistic stat. +If no more siblings are present, then NULL is returned.

RETURN VALUES

The next sibling statistic of stat, or NULL if stat is the last sibling.

ERRORS

None.

SYNOPSIS

#include <nng/nng.h>
+
+typedef struct nng_stat nng_stat;
+
+const char *nng_stat_string(nng_stat *stat);

DESCRIPTION

The nng_stat_string() function returns a string value for the statistic stat, +which must be of type NNG_STAT_STRING (see nng_stat_type(3)).

If the statistic is not of type NNG_STAT_STRING, then NULL will be returned.

RETURN VALUES

The string value associated with stat, or NULL if the statistic is not +a string type.

ERRORS

None.

SYNOPSIS

#include <nng/nng.h>
+
+typedef struct nng_stat nng_stat;
+
+uint64_t nng_stat_timestamp(nng_stat *stat);

DESCRIPTION

The nng_stat_timestamp() function returns the a timestamp, which is measured +as a number of milliseconds since some arbitrary value in the past.

Even within the same snapshot, statistics might have different timestamp +values, as the timestamp represents the time when that particular statistic +was captured.

+ + + + + +

+ +	+These values are intended to facilitate calculation of rates, by +comparing values from one snapshot with a subsequent one. +

+ + + + + +

+ +	+The values used here have the same offset as the +`nng_clock()` supplementation function. +This can be useful when converting these values to local clock time. +

RETURN VALUES

The timestamp when stat was captured, measured as a number of +milliseconds since some time in the past.

ERRORS

None.

SYNOPSIS

#include <nng/nng.h>
+
+typedef struct nng_stat nng_stat;
+
+enum {
+        NNG_STAT_SCOPE,
+        NNG_STAT_LEVEL,
+        NNG_STAT_COUNTER,
+        NNG_STAT_STRING,
+        NNG_STAT_BOOLEAN,
+        NNG_STAT_ID
+};
+
+int nng_stat_type(nng_stat *stat);

DESCRIPTION

The nng_stat_type() function returns the type of the statistic stat.

The returned type will be one of the following values:

NNG_STAT_SCOPE: +
This is a placeholder providing scope, and carries no value on its own. +Instead it is a parent node with child statistics (see +nng_stat_child().)
+
NNG_STAT_LEVEL: +
This is a numeric statistic, but its value is a level, so rate calculations +based on changes in this value should not be considered significant.
+
NNG_STAT_COUNTER: +
This is a numeric statistic that represents an increasing count, typically +of events, messages, or bytes. +Frequently, it is interesting to consider changes in this statistic divided +by time to obtain a rate. +(For example, throughput might be calculated as changes in a byte counter +divided by the interval over which the change occurred.)
+
NNG_STAT_STRING: +
This is a string, and carries no numeric value. +Instead the nng_stat_string(3) function +should be used to obtain the value.
+
NNG_STAT_BOOLEAN: +
This is a boolean value. +The nng_stat_value() function will return zero +to represent a false value, and one to represent a true value.
+

NNG_STAT_ID: +The statistic is a numeric ID. +These are generally immutable values that represent an identity that might +be used with another interface.

+ + + + + +

+ +	+For `NNG_STAT_COUNTER` and `NNG_STAT_LEVEL` statistics, the +`nng_stat_unit()` function will provide more +detail about the units measured by the static. +

RETURN VALUES

The statistic type for stat.

ERRORS

None.

SYNOPSIS

#include <nng/nng.h>
+
+typedef struct nng_stat nng_stat;
+
+enum {
+        NNG_UNIT_NONE,
+        NNG_UNIT_BYTES,
+        NNG_UNIT_MESSAGES,
+        NNG_UNIT_MILLIS,
+        NNG_UNIT_EVENTS
+};
+
+int nng_stat_unit(nng_stat *stat);

DESCRIPTION

The nng_stat_unit() function returns the unit of quantity measured +by the statistic stat.

The returned value will be one of the following values:

NNG_UNIT_NONE: +
There are no particular units measured. +In some cases there may be units, but the type of the unit will be obvious +from the name (see nng_stat_name()) of the statistic.
+
NNG_UNIT_BYTES: +
The statistic is a count of bytes.
+
NNG_UNIT_MESSAGES: +
The statistic is a count of messages. +Typically, one message corresponds to a single nng_msg structure.
+
NNG_UNIT_MILLIS: +
The statistic is a count of milliseconds.
+
NNG_STAT_EVENTS: +
The statistic is a count of some other type of event.
+

For statistics that are neither NNG_STAT_COUNTER nor NNG_STAT_LEVEL +type (see nng_stat_type()), the unit will +generally be NNG_UNIT_NONE.

+ + + + + +

+ +	+Normally rates can be calculated for `NNG_STAT_COUNTER` values for +any of these units, but for `NNG_UNIT_MILLIS` rate calculations are generally +meaningless. +

RETURN VALUES

The units measured by stat.

ERRORS

None.

SYNOPSIS

#include <nng/nng.h>
+
+typedef struct nng_stat nng_stat;
+
+uint64_t nng_stat_string(nng_stat *stat);

DESCRIPTION

The nng_stat_value() function returns a numeric value for the statistic stat. +If the statistic has a boolean value, then zero is returned for false, and +one is returned for true. +Otherwise, if the string is not of numeric type, then zero is returned. +See nng_stat_type(3) for a description of statistic types.

RETURN VALUES

The numeric or boolean value associated with stat.

ERRORS

None.

SYNOPSIS

#include <nng/nng.h>
+
+typedef nng_stat nng_stat;
+
+void nng_stats_free(nng_stat *);

DESCRIPTION

The nng_stats_free() function deallocates a statistics snapshot +previously collected with +nng_stats_get(). +After calling this, all values associated with the snapshot are +invalidated.

+ + + + + +

+ +	+Only the top of the collected statistics tree can be +freed using this function. +

RETURN VALUES

None.

ERRORS

None.

SYNOPSIS

#include <nng/nng.h>
+
+typedef struct nng_stat nng_stat;
+
+int nng_stats_get(nng_stat *statsp)

DESCRIPTION

The nng_stat_get() function attempts to obtain a snapshot of all the +various diagnostic statistics that are present in the system.

+ + + + + +

+ +	+The process of collecting statistics is designed to have minimal +impact on the system, but there is still some impact. +

The statistics are organized as a tree, rooted with a parent +statistic of type NNG_STAT_SCOPE that carries no value, and which +has an empty name. +This parent statistic is returned through the statsp pointer.

The nng_stat_child() and +nng_stat_next() function can be used to +iterate over the the tree.

When no longer needed, the statistics can be freed with the +nng_stats_free() function, but that +function must be called only with the root statistic that is returned +through the statsp pointer.

+ + + + + +

+ +

+The values of individual statistics are guaranteed to be atomic, +but due the way statistics are collected there can be discrepancies between them at certain times. +For example, statistics counting bytes and messages received may not +reflect the same number of messages, depending on when the snapshot is taken. +This potential inconsistency arises as a result of optimizations to minimize +the impact of statistics on actual operations. +

+ + + + + +

+ +	+The names, values, and semantics of statistics provided may change +from release to release. +These are provided for informational and debugging use only, and applications +should not rely on the presence, names, or meanings of any individual statistics. +

RETURN VALUES

This function returns a pointer to the allocated memory on success, +and NULL otherwise.

ERRORS

+ + + + + + + + + +

+`NNG_ENOMEM` +	+ Insufficient free memory to collect statistics. +
+`NNG_ENOTSUP` +	+ Statistics are not supported (compile time option). +

Statistics

URL Object

NAME

DESCRIPTION

nng_http_handler_collect_body(3http) Manual Page

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

ERRORS

SEE ALSO

nng_http_req_reset(3http) Manual Page

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

ERRORS

SEE ALSO

SEE ALSO

nng_http_res_reset(3http) Manual Page

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

ERRORS

SEE ALSO

RETURN VALUES

ERRORS

SEE ALSO

NAME

DESCRIPTION

RETURN VALUES

NAME

DESCRIPTION

RETURN VALUES

NAME

DESCRIPTION

RETURN VALUES

NAME

DESCRIPTION

RETURN VALUES

NAME

DESCRIPTION

RETURN VALUES

NAME

DESCRIPTION

NAME

DESCRIPTION

RETURN VALUES

NAME

DESCRIPTION

RETURN VALUES

nng_socket(5) Manual Page

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO

nng_version(3) Manual Page

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

ERRORS

SEE ALSO

nng_version(3) Manual Page

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

ERRORS

SEE ALSO

nng_version(3) Manual Page

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

ERRORS

SEE ALSO

nng_version(3) Manual Page

NAME