// -*- mode:doc; -*- // vim: set syntax=asciidoc,tw=0: coap_string(3) ============== :doctype: manpage :man source: coap_string :man version: @PACKAGE_VERSION@ :man manual: libcoap Manual NAME ---- coap_string, coap_new_string, coap_delete_string, coap_new_str_const, coap_delete_str_const, coap_new_binary, coap_delete_binary, coap_resize_binary, coap_new_bin_const, coap_delete_bin_const, coap_make_str_const, coap_string_equal, coap_binary_equal - Work with CoAP string functions SYNOPSIS -------- *#include * *coap_string_t *coap_new_string(size_t _size_);* *void coap_delete_string(coap_string_t *_string_);* *coap_str_const_t *coap_new_str_const(const uint8_t *_data_, size_t _size_);* *void coap_delete_str_const(coap_str_const_t *_string_);* *coap_str_const_t *coap_make_str_const(const char *_string_);* *int coap_string_equal(coap_string_t *_string1_, coap_string_t *_string2_);* *coap_binary_t *coap_new_binary(size_t _size_);* *void coap_delete_binary(coap_binary_t *_binary_);* *coap_binary_t *coap_resize_binary(coap_binary_t *_binary_, size_t _new_size_);* *coap_bin_const_t *coap_new_bin_const(const uint8_t *_data_, size_t _size_);* *void coap_delete_bin_const(coap_bin_const_t *_binary_);* *int coap_binary_equal(coap_binary_t *_binary1_, coap_binary_t *_binary2_);* For specific (D)TLS library support, link with *-lcoap-@LIBCOAP_API_VERSION@-notls*, *-lcoap-@LIBCOAP_API_VERSION@-gnutls*, *-lcoap-@LIBCOAP_API_VERSION@-openssl*, *-lcoap-@LIBCOAP_API_VERSION@-mbedtls* or *-lcoap-@LIBCOAP_API_VERSION@-tinydtls*. Otherwise, link with *-lcoap-@LIBCOAP_API_VERSION@* to get the default (D)TLS library support. DESCRIPTION ----------- There is support for storing strings (usually readable data) and for storing binary data. These are used by a number of functions and provide the information in some of the callbacks. There are 4 supported string/binary types as follows [source, c] ---- /* * Coap string data definition */ typedef struct coap_string_t { size_t length; /* length of string */ uint8_t *s; /* string data */ } coap_string_t; /* * Coap string data definition with const data */ typedef struct coap_str_const_t { size_t length; /* length of string */ const uint8_t *s; /* read-only string data */ } coap_str_const_t; /* * Coap binary data definition */ typedef struct coap_binary_t { size_t length; /* length of binary data */ uint8_t *s; /* binary data */ } coap_binary_t; /* * Coap binary data definition with const data */ typedef struct coap_bin_const_t { size_t length; /* length of binary data */ const uint8_t *s; /* read-only binary data */ } coap_bin_const_t; ---- The *coap_new_string*() function allocates a new coap_string_t of _size_ where _s_ points to uninitialized data of length _size_ with an extra trailing NULL at _size_ + 1. _length_ is set to _size_. The *coap_delete_string*() function is used to delete the coap_string_t created by *coap_new_string*(). The *coap_new_str_const*() function allocates a coap_str_const_t of _size_ where _s_ is filled in with _data_ and has a trailing NULL added. _length_ is set to _size_. _s_ is read-only. The *coap_delete_str_const*() function is used to delete the coap_str_const_t created by *coap_new_str_const*(). The *coap_make_str_const*() function is used to take some read-only text and uses a static coap_str_const_t for use in different function calls. There are two static entries that are cycled through so that a single function call can call *coap_make_str_const*() twice. The *coap_string_equal*() function is used to compare two different string objects _string1_ and _string2_. The *coap_new_binary*() function allocates a new coap_binary_t of _size_ where _s_ points to uninitialized data of length _size_. _length_ is set to _size_. The *coap_resize_binary*() function is used resize the size of _s_ to the new size of _new_size_. The data between the old _length_ and the _new_size_ is unitialized. _length_ is set to _new_size_. The *coap_delete_binary*() function is used to delete the coap_binary_t created by *coap_new_binary*(). The *coap_new_bin_const*() function allocates a coap_bin_const_t of _size_ where _s_ is filled in with in with _data_ and has a trailing NULL added. _length_ is set to _size_. _s_ is read-only. The *coap_delete_bin_const*() function is used to delete the coap_bin_const_t created by *coap_new_bin_const*(). The *coap_binary_equal*() function is used to compare two different binary objects _binary1_ and _binary2_. RETURN VALUES ------------- The *coap_new_string*() function returns a pointer to an allocated coap_string_t or NULL if there was a failure. The *coap_new_str_const*() function returns a pointer to an allocated coap_str_const_t or NULL if there was a failure. The *coap_new_binary*() function returns a pointer to an allocated coap_binary_t or NULL if there was a failure. The *coap_resize_binary*() function returns a pointer to an re-allocated coap_binary_t or NULL if there was a failure. The *coap_new_bin_const*() function returns a pointer to an allocated coap_bin_const_t or NULL if there was a failure. SEE ALSO -------- *coap_attribute*(3), *coap_context*(3), *coap_handler*(3), *coap_pdu_setup*(3) and *coap_resource*(3) FURTHER INFORMATION ------------------- "RFC7252: The Constrained Application Protocol (CoAP)" 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