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 */ 38 typedef 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 */ 46 typedef 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 */ 56 typedef 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 */ 64 typedef 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 */ 79 coap_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 */ 86 void 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 */ 98 coap_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 */ 105 void 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 */ 117 coap_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 */ 124 void 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 */ 139 coap_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 */ 152 coap_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 */ 159 void 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 */ 178 coap_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