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
105FUNCTIONS
106---------
107
108*Function: coap_new_string()*
109
110The *coap_new_string*() function allocates a new coap_string_t of _size_
111where _s_ points to uninitialized data of length _size_ with an extra trailing
112NULL at _size_ + 1. _length_ is set to _size_.
113
114*Function: coap_delete_string()*
115
116The *coap_delete_string*() function is used to delete the coap_string_t
117created by *coap_new_string*().
118
119*Function: coap_new_str_const()*
120
121The *coap_new_str_const*() function allocates a coap_str_const_t of _size_
122where _s_ is filled in with _data_ and has a trailing NULL added.
123_length_ is set to _size_. _s_ is read-only.
124
125*Function: coap_delete_str_const()*
126
127The *coap_delete_str_const*() function is used to delete the coap_str_const_t
128created by *coap_new_str_const*().
129
130*Function: coap_make_str_const()*
131
132The *coap_make_str_const*() function is used to take some read-only text and
133uses a static coap_str_const_t for use in different function calls. There are
134two static entries that are cycled through so that a single function call can
135call *coap_make_str_const*() twice.
136
137*Function: coap_string_equal()*
138
139The *coap_string_equal*() function is used to compare two different string
140objects _string1_ and _string2_.
141
142*Function: coap_new_binary()*
143
144The *coap_new_binary*() function allocates a new coap_binary_t of _size_
145where _s_ points to uninitialized data of length _size_. _length_ is set
146to _size_.
147
148*Function: coap_resize_binary()*
149
150The *coap_resize_binary*() function is used resize the size of _s_ to the new
151size of _new_size_.  The data between the old _length_ and the _new_size_ is
152unitialized.  _length_ is set to _new_size_.
153
154*Function: coap_delete_binary()*
155
156The *coap_delete_binary*() function is used to delete the coap_binary_t
157created by *coap_new_binary*().
158
159*Function: coap_new_bin_const()*
160
161The *coap_new_bin_const*() function allocates a coap_bin_const_t of _size_
162where _s_ is filled in with in with _data_ and has a trailing NULL added.
163_length_ is set to _size_. _s_ is read-only.
164
165*Function: coap_delete_bin_const()*
166
167The *coap_delete_bin_const*() function is used to delete the coap_bin_const_t
168created by *coap_new_bin_const*().
169
170*Function: coap_binary_equal()*
171
172The *coap_binary_equal*() function is used to compare two different binary
173objects _binary1_ and _binary2_.
174
175RETURN VALUES
176-------------
177*coap_new_string*() returns a pointer to an allocated
178coap_string_t or NULL if there was a failure.
179
180*coap_new_str_const*() returns a pointer to an allocated
181coap_str_const_t or NULL if there was a failure.
182
183*coap_make_str_const*() returns a pointer to a structure in
184static memory that has a pointer to the provided string.
185
186*coap_new_binary*() returns a pointer to an allocated
187coap_binary_t or NULL if there was a failure.
188
189*coap_resize_binary*() returns a pointer to an re-allocated
190coap_binary_t or NULL if there was a failure.
191
192*coap_new_bin_const*() returns a pointer to an allocated
193coap_bin_const_t or NULL if there was a failure.
194
195*coap_string_equal*() and *coap_binary_equal*() return 1 on
196a precise match, else 0.
197
198SEE ALSO
199--------
200*coap_attribute*(3), *coap_context*(3), *coap_handler*(3), *coap_pdu_setup*(3)
201and *coap_resource*(3)
202
203FURTHER INFORMATION
204-------------------
205See
206
207"https://rfc-editor.org/rfc/rfc7252[RFC7252: The Constrained Application Protocol (CoAP)]"
208
209for further information.
210
211BUGS
212----
213Please report bugs on the mailing list for libcoap:
214libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at
215https://github.com/obgm/libcoap/issues
216
217AUTHORS
218-------
219The libcoap project <libcoap-developers@lists.sourceforge.net>
220