mirror of
https://github.com/obgm/libcoap.git
synced 2026-11-21 06:49:05 +03:00
Create a new include/coap2/coap_resource_internal.h to hold all the information not available to applications. Makefile.am: Include coap_resource_internal.h in EXTRA_DIST. Remove functions no longer visible from CTAGS_IGNORE. examples/coap-rd.c: examples/contiki/server.c: examples/etsi_iot_01.c: tests/test_wellknown.c Replace direct access to coap_resource_t variables with functions as appropriate. include/coap2/resource.h: include/coap2/subscribe.h: include/coap2/coap_resource_internal.h: (New) include/coap2/coap_subscribe_internal.h: Move coap_resource_t, coap_addr_t, non API #defines and non API functions from resource.h into coap_resource_internal.h, coap_subscribe_internal.h and subscribe.h. Replace inline functions accessing coap_resource_t with actual function definitions. Add new functions coap_resource_release_userdata_handler() and coap_attr_get_value(). include/coap2/block.h: Use coap_resource_t typedef. include/coap2/coap_forward_decls.h: Include coap_resource_t and coap_addr_t typedefs. Also typedef coap_context_t to get rid of #include circular requirements. include/coap2/coap_internal.h: win32/libcoap.vcxproj: win32/libcoap.vcxproj.filters: Include coap_resource_internal.h. include/coap2/net.h: Remove "typedef struct coap_context_t" and do this in coap_forward_decls.h. src/resource.c: Update with the replaced inline functions. Add in the new functions coap_resource_release_userdata_handler() and coap_attr_get_value(). libcoap-2.map: libcoap-2.sym: Update with new function visibility. man/Makefile.am: man/coap_attribute.txt.in: man/coap_observe.txt.in: man/coap_resource.txt.in: Update with the new coap_resource_t and coap_attr_t usage.
157 lines
4.8 KiB
Plaintext
157 lines
4.8 KiB
Plaintext
// -*- mode:doc; -*-
|
|
// vim: set syntax=asciidoc,tw=0:
|
|
|
|
coap_attribute(3)
|
|
=================
|
|
:doctype: manpage
|
|
:man source: coap_attribute
|
|
:man version: @PACKAGE_VERSION@
|
|
:man manual: libcoap Manual
|
|
|
|
NAME
|
|
----
|
|
coap_attribute,
|
|
coap_add_attr,
|
|
coap_find_attr
|
|
- Work with CoAP attributes
|
|
|
|
SYNOPSIS
|
|
--------
|
|
*#include <coap@LIBCOAP_API_VERSION@/coap.h>*
|
|
|
|
*coap_attr_t *coap_add_attr(coap_resource_t *_resource_, coap_str_const_t
|
|
*_name_, coap_str_const_t *_value_, int _flags_);*
|
|
|
|
*coap_attr_t *coap_find_attr(coap_resource_t *_resource_, coap_str_const_t
|
|
*_name_);*
|
|
|
|
*coap_str_const_t *coap_attr_get_value(coap_attr_t *_attribute_);*
|
|
|
|
Link with *-lcoap-@LIBCOAP_API_VERSION@*, *-lcoap-@LIBCOAP_API_VERSION@-gnutls*,
|
|
*-lcoap-@LIBCOAP_API_VERSION@-openssl*, *-lcoap-@LIBCOAP_API_VERSION@-mbedtls*
|
|
or *-lcoap-@LIBCOAP_API_VERSION@-tinydtls* depending on your (D)TLS library
|
|
type.
|
|
|
|
DESCRIPTION
|
|
-----------
|
|
CoAP Resources on a CoAP Server need to be created, updated etc. The URI in
|
|
the request packet defines the resource to work with, with possibly the Query
|
|
referring to a sub-resource.
|
|
|
|
When resources are configured on the CoAP server, the URI to match against
|
|
is specified.
|
|
Callback Handlers are then added to the resource to handle the different
|
|
request methods.
|
|
|
|
Adding Attributes allows textual information to be added to the resource
|
|
which can then be reported back to any client doing a Resource Discovery using
|
|
a "GET /.well-known/core" request with an optional query.
|
|
See https://tools.ietf.org/html/rfc6690#section-5 for some examples of
|
|
resource discovery usage. Common attribute names are rt, if, sz, ct, obs, rel,
|
|
anchor, rev, hreflang, media, title and type. href cannot be an attribute name.
|
|
|
|
Attributes are automatically deleted when a Resource is deleted.
|
|
|
|
The *coap_add_attr*() function
|
|
registers a new attribute called _name_ for the _resource_.
|
|
The value of the attribute is _value_ which can be NULL.
|
|
|
|
_flags_ can be one or more of the following, which, if set, defines what is
|
|
to be internally freed off when the attribute is deleted with
|
|
*coap_delete_resource*().
|
|
|
|
[horizontal]
|
|
*COAP_ATTR_FLAGS_RELEASE_NAME*::
|
|
Free off _name_ when attribute is deleted with *coap_delete_resource*().
|
|
|
|
*COAP_ATTR_FLAGS_RELEASE_VALUE*::
|
|
Free off _value_ when attribute is deleted with *coap_delete_resource*().
|
|
|
|
The *coap_find_attr*() function returns the attribute with the _name_,
|
|
if found, associated with _resource_.
|
|
|
|
The *coap_attr_get_value*() function returns the _value_ associated with the
|
|
specified _attribute_.
|
|
|
|
RETURN VALUES
|
|
-------------
|
|
*coap_add_attr*() function returns a pointer to
|
|
the attribute that was created or NULL if there is a malloc failure.
|
|
|
|
*coap_find_attr*() function returns a pointer to the first matching
|
|
attribute or NULL if the _name_ was not found.
|
|
|
|
*coap_attr_get_value*() function returns a pointer to the value held within
|
|
the attribute. The pointer can be NULL if the _value_ id NULL, or NULL if
|
|
_attribute_ does not exist.
|
|
|
|
EXAMPLE
|
|
-------
|
|
*Initialize Resources*
|
|
|
|
[source, c]
|
|
--
|
|
#include <coap@LIBCOAP_API_VERSION@/coap.h>
|
|
|
|
static void
|
|
init_resources(coap_context_t *ctx) {
|
|
|
|
coap_resource_t *r;
|
|
|
|
/* Create a resource to return general information */
|
|
r = coap_resource_init(NULL, 0);
|
|
coap_register_handler(r, COAP_REQUEST_GET, hnd_get_index);
|
|
|
|
/* Document resource for '.well-known/core' request */
|
|
coap_add_attr(r, coap_make_str_const("ct"), coap_make_str_const("0"), 0);
|
|
coap_add_attr(r, coap_make_str_const("title"),
|
|
coap_make_str_const("\"General Info\""), 0);
|
|
|
|
coap_add_resource(ctx, r);
|
|
|
|
/* Create a resource to return return or update time */
|
|
r = coap_resource_init(coap_make_str_const("time"),
|
|
COAP_RESOURCE_FLAGS_NOTIFY_CON);
|
|
coap_resource_set_get_observable(r, 1);
|
|
coap_register_handler(r, COAP_REQUEST_GET, hnd_get_time);
|
|
coap_register_handler(r, COAP_REQUEST_PUT, hnd_put_time);
|
|
coap_register_handler(r, COAP_REQUEST_DELETE, hnd_delete_time);
|
|
|
|
/* Document resource for 'time' request */
|
|
coap_add_attr(r, coap_make_str_const("ct"), coap_make_str_const("0"), 0);
|
|
coap_add_attr(r, coap_make_str_const("title"),
|
|
coap_make_str_const("\"Internal Clock\""), 0);
|
|
coap_add_attr(r, coap_make_str_const("rt"), coap_make_str_const("\"secs\""),
|
|
0);
|
|
coap_add_attr(r, coap_make_str_const("if"), coap_make_str_const("\"clock\""),
|
|
0);
|
|
|
|
coap_add_resource(ctx, r);
|
|
|
|
}
|
|
--
|
|
|
|
SEE ALSO
|
|
--------
|
|
*coap_resource*(3) and *coap_handler*(3)
|
|
|
|
FURTHER INFORMATION
|
|
-------------------
|
|
See
|
|
|
|
"RFC7252: The Constrained Application Protocol (CoAP)"
|
|
|
|
"RFC6690: Constrained RESTful Environments (CoRE) Link Format"
|
|
|
|
for further information.
|
|
|
|
BUGS
|
|
----
|
|
Please report bugs on the mailing list for libcoap:
|
|
libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at
|
|
https://github.com/obgm/libcoap/issues
|
|
|
|
AUTHORS
|
|
-------
|
|
The libcoap project <libcoap-developers@lists.sourceforge.net>
|