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