1 /* 2 QUEUE 3 4 Header file for queue implemented using collection interface. 5 6 Copyright (C) Dmitri Pal <dpal@redhat.com> 2009 7 8 Collection Library is free software: you can redistribute it and/or modify 9 it under the terms of the GNU Lesser General Public License as published by 10 the Free Software Foundation, either version 3 of the License, or 11 (at your option) any later version. 12 13 Collection Library is distributed in the hope that it will be useful, 14 but WITHOUT ANY WARRANTY; without even the implied warranty of 15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 16 GNU Lesser General Public License for more details. 17 18 You should have received a copy of the GNU Lesser General Public License 19 along with Collection Library. If not, see <http://www.gnu.org/licenses/>. 20 */ 21 22 #ifndef COLLECTION_QUEUE_H 23 #define COLLECTION_QUEUE_H 24 25 #include "collection.h" 26 27 /** 28 * @defgroup queue QUEUE interface 29 * 30 * Queue interface is a wrapper on top of the \ref collection 31 * interface. It implements a queue using a collection object. 32 * 33 * @{ 34 */ 35 36 /** @brief Class for the queue object */ 37 #define COL_CLASS_QUEUE 40000 38 /** @brief All queues use this name as the name of the collection */ 39 #define COL_NAME_QUEUE "queue" 40 41 /** 42 * @brief Create queue. 43 * 44 * Function that creates a queue object. 45 * 46 * @param[out] queue Newly created queue object. 47 * 48 * @return 0 - Queue was created successfully. 49 * @return ENOMEM - No memory. 50 * 51 */ 52 int col_create_queue(struct collection_item **queue); 53 54 /** 55 * @brief Destroy queue. 56 * 57 * Function that destroys a queue object. 58 * 59 * @param[in] queue Queue object to destroy. 60 * 61 */ 62 void col_destroy_queue(struct collection_item *queue); 63 64 /** 65 * @brief Add string to the queue. 66 * 67 * @param[in] queue Queue object. 68 * @param[in] property Name of the property.<br> 69 * Name should consist of the ASCII characters 70 * with codes non less than space. 71 * Exclamation mark character is 72 * a special character and can't be used 73 * in name of collection or property.<br> 74 * Maximum allowed length is defined at compile time. 75 * The default value is 64k. 76 * @param[in] string Null terminated string to add. 77 * @param[in] length Length of the string. Should include the length 78 * of the terminating 0. 79 * If the length is shorter than the full string 80 * the string will be truncated. If the length is 81 * longer than the actual string there might be 82 * garbage at end of the actual string. 83 * Library will always properly NULL terminate 84 * the string at the given position dictated 85 * by length but in no way will inspect the validity 86 * of the passed in data. This is left to the calling 87 * application. 88 * 89 * @return 0 - Property was added successfully. 90 * @return ENOMEM - No memory. 91 * @return EINVAL - Invalid characters in the property name. 92 * Value argument is invalid in some way. 93 * @return EMSGSIZE - Property name is too long. 94 * 95 */ 96 int col_enqueue_str_property(struct collection_item *queue, 97 const char *property, 98 const char *string, 99 int length); 100 /** 101 * @brief Add binary value to the queue. 102 * 103 * @param[in] queue Queue object. 104 * @param[in] property Name of the property.<br> 105 * Name should consist of the ASCII characters 106 * with codes non less than space. 107 * Exclamation mark character is 108 * a special character and can't be used 109 * in name of collection or property.<br> 110 * Maximum allowed length is defined at compile time. 111 * The default value is 64k. 112 * @param[in] binary_data Data to add. 113 * @param[in] length Length of the binary data. 114 * 115 * @return 0 - Property was added successfully. 116 * @return ENOMEM - No memory. 117 * @return EINVAL - Invalid argument. 118 * @return EMSGSIZE - Property name is too long. 119 * 120 */ 121 int col_enqueue_binary_property(struct collection_item *queue, 122 const char *property, 123 void *binary_data, 124 int length); 125 /** 126 * @brief Add integer value to the queue. 127 * 128 * @param[in] queue Queue object. 129 * @param[in] property Name of the property.<br> 130 * Name should consist of the ASCII characters 131 * with codes non less than space. 132 * Exclamation mark character is 133 * a special character and can't be used 134 * in name of collection or property.<br> 135 * Maximum allowed length is defined at compile time. 136 * The default value is 64k. 137 * @param[in] number Value to add. 138 * 139 * @return 0 - Property was added successfully. 140 * @return ENOMEM - No memory. 141 * @return EINVAL - Invalid argument. 142 * @return EMSGSIZE - Property name is too long. 143 * 144 */ 145 int col_enqueue_int_property(struct collection_item *queue, 146 const char *property, 147 int32_t number); 148 /** 149 * @brief Add unsigned value to the queue. 150 * 151 * @param[in] queue Queue object. 152 * @param[in] property Name of the property.<br> 153 * Name should consist of the ASCII characters 154 * with codes non less than space. 155 * Exclamation mark character is 156 * a special character and can't be used 157 * in name of collection or property.<br> 158 * Maximum allowed length is defined at compile time. 159 * The default value is 64k. 160 * @param[in] number Value to add. 161 * 162 * @return 0 - Property was added successfully. 163 * @return ENOMEM - No memory. 164 * @return EINVAL - Invalid argument. 165 * @return EMSGSIZE - Property name is too long. 166 * 167 */ 168 int col_enqueue_unsigned_property(struct collection_item *queue, 169 const char *property, 170 uint32_t number); 171 /** 172 * @brief Add long integer value to the queue. 173 * 174 * @param[in] queue Queue object. 175 * @param[in] property Name of the property.<br> 176 * Name should consist of the ASCII characters 177 * with codes non less than space. 178 * Exclamation mark character is 179 * a special character and can't be used 180 * in name of collection or property.<br> 181 * Maximum allowed length is defined at compile time. 182 * The default value is 64k. 183 * @param[in] number Value to add. 184 * 185 * @return 0 - Property was added successfully. 186 * @return ENOMEM - No memory. 187 * @return EINVAL - Invalid argument. 188 * @return EMSGSIZE - Property name is too long. 189 * 190 */ 191 int col_enqueue_long_property(struct collection_item *queue, 192 const char *property, 193 int64_t number); 194 /** 195 * @brief Add unsigned long value to the queue. 196 * 197 * @param[in] queue Queue object. 198 * @param[in] property Name of the property.<br> 199 * Name should consist of the ASCII characters 200 * with codes non less than space. 201 * Exclamation mark character is 202 * a special character and can't be used 203 * in name of collection or property.<br> 204 * Maximum allowed length is defined at compile time. 205 * The default value is 64k. 206 * @param[in] number Value to add. 207 * 208 * @return 0 - Property was added successfully. 209 * @return ENOMEM - No memory. 210 * @return EINVAL - Invalid argument. 211 * @return EMSGSIZE - Property name is too long. 212 * 213 */ 214 int col_enqueue_ulong_property(struct collection_item *queue, 215 const char *property, 216 uint64_t number); 217 /** 218 * @brief Add floating point value to the queue. 219 * 220 * @param[in] queue Queue object. 221 * @param[in] property Name of the property.<br> 222 * Name should consist of the ASCII characters 223 * with codes non less than space. 224 * Exclamation mark character is 225 * a special character and can't be used 226 * in name of collection or property.<br> 227 * Maximum allowed length is defined at compile time. 228 * The default value is 64k. 229 * @param[in] number Value to add. 230 * 231 * @return 0 - Property was added successfully. 232 * @return ENOMEM - No memory. 233 * @return EINVAL - Invalid argument. 234 * @return EMSGSIZE - Property name is too long. 235 * 236 */ 237 int col_enqueue_double_property(struct collection_item *queue, 238 const char *property, 239 double number); 240 /** 241 * @brief Add Boolean value to the queue. 242 * 243 * @param[in] queue Queue object. 244 * @param[in] property Name of the property.<br> 245 * Name should consist of the ASCII characters 246 * with codes non less than space. 247 * Exclamation mark character is 248 * a special character and can't be used 249 * in name of collection or property.<br> 250 * Maximum allowed length is defined at compile time. 251 * The default value is 64k. 252 * @param[in] logical Value to add. 253 * 254 * @return 0 - Property was added successfully. 255 * @return ENOMEM - No memory. 256 * @return EINVAL - Invalid argument. 257 * @return EMSGSIZE - Property name is too long. 258 * 259 */ 260 int col_enqueue_bool_property(struct collection_item *queue, 261 const char *property, 262 unsigned char logical); 263 264 /** 265 * @brief Add value of any type to the queue. 266 * 267 * @param[in] queue Queue object. 268 * @param[in] property Name of the property.<br> 269 * Name should consist of the ASCII characters 270 * with codes non less than space. 271 * Exclamation mark character is 272 * a special character and can't be used 273 * in name of collection or property.<br> 274 * Maximum allowed length is defined at compile time. 275 * The default value is 64k. 276 * @param[in] type Type to use. 277 * @param[in] data Data to add. 278 * @param[in] length Length of the data. 279 * 280 * @return 0 - Property was added successfully. 281 * @return ENOMEM - No memory. 282 * @return EINVAL - Invalid characters in the property name. 283 * Value argument is invalid in some way. 284 * @return EMSGSIZE - Property name is too long. 285 * 286 */ 287 int col_enqueue_any_property(struct collection_item *queue, 288 const char *property, 289 int type, 290 void *data, 291 int length); 292 293 /** 294 * @brief Push item into the queue. 295 * 296 * @param[in] queue Queue object. 297 * @param[in] item Item to push. 298 * 299 * @return 0 - Item was added successfully. 300 * @return ENOMEM - No memory. 301 * @return EINVAL - Invalid argument. 302 */ 303 int col_enqueue_item(struct collection_item *queue, 304 struct collection_item *item); 305 306 /** 307 * @brief Get item from the queue. 308 * 309 * @param[in] queue Queue object. 310 * @param[out] item Variable receives the value 311 * of the retrieved item. 312 * Will be set to NULL if there are 313 * no more items in the queue. 314 * 315 * @return 0 - No internal issues detected. 316 * @return ENOMEM - No memory. 317 * @return EINVAL - Invalid argument. 318 */ 319 int col_dequeue_item(struct collection_item *queue, 320 struct collection_item **item); 321 322 /** 323 * @} 324 */ 325 326 #endif 327