1/*
2 * str.h -- strings to be used in the CoAP library
3 *
4 * Copyright (C) 2010-2011 Olaf Bergmann <bergmann@tzi.org>
5 *
6 * SPDX-License-Identifier: BSD-2-Clause
7 *
8 * This file is part of the CoAP library libcoap. Please see README for terms
9 * of use.
10 */
11
12/**
13 * @file coap_str.h
14 * @brief Strings to be used in the CoAP library
15 */
16
17#ifndef COAP_STR_H_
18#define COAP_STR_H_
19
20#include <string.h>
21
22
23/**
24 * @ingroup application_api
25 * @defgroup string String handling support
26 * API for handling strings and binary data
27 * @{
28 */
29
30/*
31 * Note: string and binary use equivalent objects.
32 * string is likely to contain readable textual information, binary will not.
33 */
34
35/**
36 * CoAP string data definition
37 */
38typedef struct coap_string_t {
39  size_t length;    /**< length of string */
40  uint8_t *s;       /**< string data */
41} coap_string_t;
42
43/**
44 * CoAP string data definition with const data
45 */
46typedef struct coap_str_const_t {
47  size_t length;    /**< length of string */
48  const uint8_t *s; /**< read-only string data */
49} coap_str_const_t;
50
51#define COAP_SET_STR(st,l,v) { (st)->length = (l), (st)->s = (v); }
52
53/**
54 * CoAP binary data definition
55 */
56typedef struct coap_binary_t {
57  size_t length;    /**< length of binary data */
58  uint8_t *s;       /**< binary data */
59} coap_binary_t;
60
61/**
62 * CoAP binary data definition with const data
63 */
64typedef struct coap_bin_const_t {
65  size_t length;    /**< length of binary data */
66  const uint8_t *s; /**< read-only binary data */
67} coap_bin_const_t;
68
69/**
70 * Returns a new string object with at least size+1 bytes storage allocated.
71 * It is the responsibility of the caller to fill in all the appropriate
72 * information.
73 * The string must be released using coap_delete_string().
74 *
75 * @param size The size to allocate for the string data.
76 *
77 * @return       A pointer to the new object or @c NULL on error.
78 */
79coap_string_t *coap_new_string(size_t size);
80
81/**
82 * Deletes the given string and releases any memory allocated.
83 *
84 * @param string The string to free off.
85 */
86void coap_delete_string(coap_string_t *string);
87
88/**
89 * Returns a new const string object with at least size+1 bytes storage
90 * allocated, and the provided data copied into the string object.
91 * The string must be released using coap_delete_str_const().
92 *
93 * @param data The data to put in the new string object.
94 * @param size The size to allocate for the binary string data.
95 *
96 * @return       A pointer to the new object or @c NULL on error.
97 */
98coap_str_const_t *coap_new_str_const(const uint8_t *data, size_t size);
99
100/**
101 * Deletes the given const string and releases any memory allocated.
102 *
103 * @param string The string to free off.
104 */
105void coap_delete_str_const(coap_str_const_t *string);
106
107/**
108 * Returns a new binary object with at least size bytes storage allocated.
109 * It is the responsibility of the caller to fill in all the appropriate
110 * information.
111 * The coap_binary_t object must be released using coap_delete_binary().
112 *
113 * @param size The size to allocate for the binary data.
114 *
115 * @return       A pointer to the new object or @c NULL on error.
116 */
117coap_binary_t *coap_new_binary(size_t size);
118
119/**
120 * Deletes the given coap_binary_t object and releases any memory allocated.
121 *
122 * @param binary The coap_binary_t object to free off.
123 */
124void coap_delete_binary(coap_binary_t *binary);
125
126/**
127 * Resizes the given coap_binary_t object.
128 * It is the responsibility of the caller to fill in all the appropriate
129 * additional information.
130 *
131 * Note: If there is an error, @p binary will separately need to be released by
132 * coap_delete_binary().
133 *
134 * @param binary The coap_binary_t object to resize.
135 * @param new_size The new size to allocate for the binary data.
136 *
137 * @return       A pointer to the new object or @c NULL on error.
138 */
139coap_binary_t *coap_resize_binary(coap_binary_t *binary, size_t new_size);
140
141/**
142 * Take the specified byte array (text) and create a coap_bin_const_t *
143 * Returns a new const binary object with at least size bytes storage
144 * allocated, and the provided data copied into the binary object.
145 * The binary data must be released using coap_delete_bin_const().
146 *
147 * @param data The data to put in the new string object.
148 * @param size The size to allocate for the binary data.
149 *
150 * @return       A pointer to the new object or @c NULL on error.
151 */
152coap_bin_const_t *coap_new_bin_const(const uint8_t *data, size_t size);
153
154/**
155 * Deletes the given const binary data and releases any memory allocated.
156 *
157 * @param binary The binary data to free off.
158 */
159void coap_delete_bin_const(coap_bin_const_t *binary);
160
161#ifndef COAP_MAX_STR_CONST_FUNC
162#define COAP_MAX_STR_CONST_FUNC 2
163#endif /* COAP_MAX_STR_CONST_FUNC */
164
165/**
166 * Take the specified byte array (text) and create a coap_str_const_t *
167 *
168 * Note: the array is 2 deep as there are up to two callings of
169 * coap_make_str_const in a function call. e.g. coap_add_attr().
170 * Caution: If there are local variable assignments, these will cycle around
171 * the var[COAP_MAX_STR_CONST_FUNC] set.  No current examples do this.
172 *
173 * @param string The const string to convert to a coap_str_const_t *
174 *
175 * @return       A pointer to one of two static variables containing the
176 *               coap_str_const_t * result
177 */
178coap_str_const_t *coap_make_str_const(const char *string);
179
180/**
181 * Compares the two strings for equality
182 *
183 * @param string1 The first string.
184 * @param string2 The second string.
185 *
186 * @return         @c 1 if the strings are equal
187 *                 @c 0 otherwise.
188 */
189#define coap_string_equal(string1,string2) \
190  ((string1)->length == (string2)->length && ((string1)->length == 0 || \
191                                              ((string1)->s && (string2)->s && \
192                                               memcmp((string1)->s, (string2)->s, (string1)->length) == 0)))
193
194/**
195 * Compares the two binary data for equality
196 *
197 * @param binary1 The first binary data.
198 * @param binary2 The second binary data.
199 *
200 * @return         @c 1 if the binary data is equal
201 *                 @c 0 otherwise.
202 */
203#define coap_binary_equal(binary1,binary2) \
204  ((binary1)->length == (binary2)->length && ((binary1)->length == 0 || \
205                                              ((binary1)->s && (binary2)->s && \
206                                               memcmp((binary1)->s, (binary2)->s, (binary1)->length) == 0)))
207
208/** @} */
209
210#endif /* COAP_STR_H_ */
211