1// -*- mode:doc; -*- 2// vim: set syntax=asciidoc,tw=0: 3 4coap_string(3) 5============== 6:doctype: manpage 7:man source: coap_string 8:man version: @PACKAGE_VERSION@ 9:man manual: libcoap Manual 10 11NAME 12---- 13coap_string, 14coap_new_string, 15coap_delete_string, 16coap_new_str_const, 17coap_delete_str_const, 18coap_new_binary, 19coap_delete_binary, 20coap_resize_binary, 21coap_new_bin_const, 22coap_delete_bin_const, 23coap_make_str_const, 24coap_string_equal, 25coap_binary_equal 26- Work with CoAP string functions 27 28SYNOPSIS 29-------- 30*#include <coap@LIBCOAP_API_VERSION@/coap.h>* 31 32*coap_string_t *coap_new_string(size_t _size_);* 33 34*void coap_delete_string(coap_string_t *_string_);* 35 36*coap_str_const_t *coap_new_str_const(const uint8_t *_data_, size_t _size_);* 37 38*void coap_delete_str_const(coap_str_const_t *_string_);* 39 40*coap_str_const_t *coap_make_str_const(const char *_string_);* 41 42*int coap_string_equal(coap_string_t *_string1_, coap_string_t *_string2_);* 43 44*coap_binary_t *coap_new_binary(size_t _size_);* 45 46*void coap_delete_binary(coap_binary_t *_binary_);* 47 48*coap_binary_t *coap_resize_binary(coap_binary_t *_binary_, size_t _new_size_);* 49 50*coap_bin_const_t *coap_new_bin_const(const uint8_t *_data_, size_t _size_);* 51 52*void coap_delete_bin_const(coap_bin_const_t *_binary_);* 53 54*int coap_binary_equal(coap_binary_t *_binary1_, coap_binary_t *_binary2_);* 55 56For specific (D)TLS library support, link with 57*-lcoap-@LIBCOAP_API_VERSION@-notls*, *-lcoap-@LIBCOAP_API_VERSION@-gnutls*, 58*-lcoap-@LIBCOAP_API_VERSION@-openssl*, *-lcoap-@LIBCOAP_API_VERSION@-mbedtls* 59or *-lcoap-@LIBCOAP_API_VERSION@-tinydtls*. Otherwise, link with 60*-lcoap-@LIBCOAP_API_VERSION@* to get the default (D)TLS library support. 61 62DESCRIPTION 63----------- 64There is support for storing strings (usually readable data) and for storing 65binary data. These are used by a number of functions and provide the 66information in some of the callbacks. 67 68There are 4 supported string/binary types as follows 69 70[source, c] 71---- 72/* 73 * Coap string data definition 74 */ 75typedef struct coap_string_t { 76 size_t length; /* length of string */ 77 uint8_t *s; /* string data */ 78} coap_string_t; 79 80/* 81 * Coap string data definition with const data 82 */ 83typedef struct coap_str_const_t { 84 size_t length; /* length of string */ 85 const uint8_t *s; /* read-only string data */ 86} coap_str_const_t; 87 88/* 89 * Coap binary data definition 90 */ 91typedef struct coap_binary_t { 92 size_t length; /* length of binary data */ 93 uint8_t *s; /* binary data */ 94} coap_binary_t; 95 96/* 97 * Coap binary data definition with const data 98 */ 99typedef struct coap_bin_const_t { 100 size_t length; /* length of binary data */ 101 const uint8_t *s; /* read-only binary data */ 102} coap_bin_const_t; 103---- 104 105The *coap_new_string*() function allocates a new coap_string_t of _size_ 106where _s_ points to uninitialized data of length _size_ with an extra trailing 107NULL at _size_ + 1. _length_ is set to _size_. 108 109The *coap_delete_string*() function is used to delete the coap_string_t 110created by *coap_new_string*(). 111 112The *coap_new_str_const*() function allocates a coap_str_const_t of _size_ 113where _s_ is filled in with _data_ and has a trailing NULL added. 114_length_ is set to _size_. _s_ is read-only. 115 116The *coap_delete_str_const*() function is used to delete the coap_str_const_t 117created by *coap_new_str_const*(). 118 119The *coap_make_str_const*() function is used to take some read-only text and 120uses a static coap_str_const_t for use in different function calls. There are 121two static entries that are cycled through so that a single function call can 122call *coap_make_str_const*() twice. 123 124The *coap_string_equal*() function is used to compare two different string 125objects _string1_ and _string2_. 126 127The *coap_new_binary*() function allocates a new coap_binary_t of _size_ 128where _s_ points to uninitialized data of length _size_. _length_ is set 129to _size_. 130 131The *coap_resize_binary*() function is used resize the size of _s_ to the new 132size of _new_size_. The data between the old _length_ and the _new_size_ is 133unitialized. _length_ is set to _new_size_. 134 135The *coap_delete_binary*() function is used to delete the coap_binary_t 136created by *coap_new_binary*(). 137 138The *coap_new_bin_const*() function allocates a coap_bin_const_t of _size_ 139where _s_ is filled in with in with _data_ and has a trailing NULL added. 140_length_ is set to _size_. _s_ is read-only. 141 142The *coap_delete_bin_const*() function is used to delete the coap_bin_const_t 143created by *coap_new_bin_const*(). 144 145The *coap_binary_equal*() function is used to compare two different binary 146objects _binary1_ and _binary2_. 147 148RETURN VALUES 149------------- 150The *coap_new_string*() function returns a pointer to an allocated 151coap_string_t or NULL if there was a failure. 152 153The *coap_new_str_const*() function returns a pointer to an allocated 154coap_str_const_t or NULL if there was a failure. 155 156The *coap_new_binary*() function returns a pointer to an allocated 157coap_binary_t or NULL if there was a failure. 158 159The *coap_resize_binary*() function returns a pointer to an re-allocated 160coap_binary_t or NULL if there was a failure. 161 162The *coap_new_bin_const*() function returns a pointer to an allocated 163coap_bin_const_t or NULL if there was a failure. 164 165SEE ALSO 166-------- 167*coap_attribute*(3), *coap_context*(3), *coap_handler*(3), *coap_pdu_setup*(3) 168and *coap_resource*(3) 169 170FURTHER INFORMATION 171------------------- 172"RFC7252: The Constrained Application Protocol (CoAP)" 173 174BUGS 175---- 176Please report bugs on the mailing list for libcoap: 177libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at 178https://github.com/obgm/libcoap/issues 179 180AUTHORS 181------- 182The libcoap project <libcoap-developers@lists.sourceforge.net> 183