OpenMPI 0.1.1

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- File List
- Globals

OTF_KeyValue.h
Go to the documentation of this file.
1 /*
2 This is part of the OTF library. Copyright by ZIH, TU Dresden 2005-2012.
3 Authors: Andreas Knuepfer, Holger Brunst, Ronny Brendel, Thomas Kriebitzsch, Johannes Spazier
4 */
5
6 /**
7 * @file OTF_KeyValue.h
8 *
9 * @brief Provides an additional list of key value pairs that can be added to records.
10 *
11 * \ingroup keyvalue
12 */
13
14
15 /**
16 * \defgroup keyvalue KeyValueList Interface
17 *
18 * Provides an additional list of key-value pairs that can be added to records.
19 *
20 * \section keyvalue_write_example A short Example of writing a KeyValueList
21 *
22 * You can append key-value pairs to an OTF_KeyValueList instance that can be added to any record.
23 *
24 * After one call to OTF_Writer_writeXxxKV() the given KeyValueList instance will be empty.
25 *
26 * \code
27 * #include <assert.h>
28 * #include "otf.h"
29 *
30 * int main( int argc, char** argv ) {
31 *
32 * OTF_FileManager* manager;
33 * OTF_Writer* writer;
34 * OTF_KeyValueList* KeyValueList;
35 *
36 * manager= OTF_FileManager_open( 100 );
37 * assert( manager );
38 *
39 * writer = OTF_Writer_open( "mytrace", 1, manager );
40 * assert( writer );
41 * \endcode
42 *
43 * Initialize the prior declared OTF_KeyValueList.
44 *
45 * \code
46 * KeyValueList = OTF_KeyValueList_new();
47 * \endcode
48 *
49 * Write a DefKeyValue record that assigns key=1 to name="first_arg" with description="first argument of function" and type=OTF_INT32.
50 * \code
51 * OTF_Writer_writeDefKeyValue( writer, 0, 1, OTF_INT32, "first_arg", "first argument of function" );
52 * \endcode
53 *
54 * Append a signed integer for key=1 to the initialized KeyValueList.
55 * \code
56 * OTF_KeyValueList_appendInt32( KeyValueList, 1, 25);
57 * \endcode
58 *
59 * Write the entries of the KeyValueList together with the enter record.
60 * Afterwards the KeyValueList will be empty!
61 * \code
62 * OTF_Writer_writeEnterKV( writer, 10000, 100, 1, 0, KeyValueList );
63 * \endcode
64 *
65 * Clean up before exiting the program. Close the OTF_KeyValueList.
66 * \code
67 * OTF_KeyValueList_close( KeyValueList );
68 * OTF_Writer_close( writer );
69 * OTF_FileManager_close( manager );
70 *
71 * return 0;
72 * }
73 * \endcode
74 *
75 * Compile this using $ gcc -o write write.c `otfconfig --libs`.
76 *
77 *
78 * \section keyvalue_read_example A short Example of reading from a KeyValueList
79 *
80 * \code
81 * #include <assert.h>
82 * #include <stdio.h>
83 * #include <string.h>
84 * #include "otf.h"
85 *
86 * int global_key = 0;
87 *
88 * \endcode
89 *
90 * Define a callback to read all DefKeyValue records.
91 * \code
92 * int handleDefKeyValue( void* userData, uint32_t stream, uint32_t key, OTF_Type type, const char* name, const char *description ) {
93 * \endcode
94 *
95 * Find out which key you are looking for.
96 * \code
97 * if( strcmp( name, "first_arg") == 0 ) {
98 * global_key = key;
99 * }
100 *
101 * return OTF_RETURN_OK;
102 * }
103 * \endcode
104 *
105 * Define a callback to read all enter records.
106 * \code
107 * int handleEnter (void *userData, uint64_t time, uint32_t function, uint32_t process, uint32_t source, OTF_KeyValueList *list) {
108 *
109 * int value;
110 *
111 * \endcode
112 *
113 * Ask for a key value pair with key=global_key. Save the value in variable "value".
114 * \code
115 * switch( OTF_KeyValueList_getInt32( list, global_key, &value) ) {
116 * case 0:
117 * printf("We entered function %u with argument %d\n", function, value);
118 * break;
119 * case 1:
120 * printf("We entered function %u with no argument.\n", function);
121 * break;
122 * default:
123 * printf("An error occurred while asking for key value pair.\n");
124 * }
125 *
126 * return OTF_RETURN_OK;
127 * }
128 *
129 * \endcode
130 *
131 * main() includes the common instructions to read an .otf-file.
132 * \code
133 * int main( int argc, char** argv ) {
134 *
135 * OTF_FileManager* manager;
136 * OTF_Reader* reader;
137 * OTF_HandlerArray* handlers;
138 *
139 * manager= OTF_FileManager_open( 100 );
140 * assert( manager );
141 *
142 * handlers = OTF_HandlerArray_open();
143 * assert( handlers );
144 *
145 * reader = OTF_Reader_open( "mytrace", manager );
146 * assert( reader );
147 *
148 * OTF_HandlerArray_setHandler( handlers, (OTF_FunctionPointer*) handleDefKeyValue, OTF_DEFKEYVALUE_RECORD );
149 * OTF_HandlerArray_setHandler( handlers, (OTF_FunctionPointer*) handleEnter, OTF_ENTER_RECORD );
150 *
151 * OTF_Reader_readDefinitions( reader, handlers );
152 * OTF_Reader_readEvents( reader, handlers );
153 *
154 * OTF_Reader_close( reader );
155 * OTF_HandlerArray_close( handlers );
156 * OTF_FileManager_close( manager );
157 *
158 * return 0;
159 * }
160 * \endcode
161 *
162 * Compile this using $ gcc -o read read.c `otfconfig --libs`.
163 *
164 */
165
166 #ifndef OTF_KEYVALUE_H
167 #define OTF_KEYVALUE_H
168
169 #include "OTF_inttypes.h"
170 #include "OTF_Definitions.h"
171
172 #ifdef __cplusplus
173 extern "C" {
174 #endif /* __cplusplus */
175
176
177 /** An enum which holds all OTF datatypes that are relevant for OTF_KeyValueList. \ingroup miscellaneous */
178 typedef enum OTF_Type_enum {
179 OTF_UNKNOWN = -1,
180 OTF_CHAR = 0, /**< */
181 OTF_INT8 = 1, /**< */
182 OTF_UINT8 = 2, /**< */
183 OTF_INT16 = 3, /**< */
184 OTF_UINT16 = 4, /**< */
185 OTF_INT32 = 5, /**< */
186 OTF_UINT32 = 6, /**< */
187 OTF_INT64 = 7, /**< */
188 OTF_UINT64 = 8, /**< */
189 OTF_FLOAT = 9, /**< */
190 OTF_DOUBLE = 10, /**< */
191 OTF_BYTE_ARRAY = 11 /**< */
192 } OTF_Type;
193
194 /** @cond OTF_KeyValue */
195
196 /** the following lines are ignored by doxygen */
197
198 typedef struct byte_array_struct {
199 uint8_t array[OTF_KEYVALUE_MAX_ARRAY_LEN];
200 uint32_t len;
201 } byte_array;
202
203 typedef union OTF_Value_union {
204 char otf_char;
205 int8_t otf_int8;
206 uint8_t otf_uint8;
207 int16_t otf_int16;
208 uint16_t otf_uint16;
209 int32_t otf_int32;
210 uint32_t otf_uint32;
211 int64_t otf_int64;
212 uint64_t otf_uint64;
213 float otf_float;
214 double otf_double;
215 byte_array otf_byte_array;
216 } OTF_Value;
217
218 struct OTF_KeyValuePair_struct {
219 uint32_t key;
220 OTF_Type type;
221 OTF_Value value;
222 };
223
224 typedef struct OTF_KeyValuePairList_struct {
225 struct OTF_KeyValuePair_struct kvPair;
226 struct OTF_KeyValuePairList_struct *kvNext;
227 struct OTF_KeyValuePairList_struct *kvPrev;
228 } OTF_KeyValuePairList;
229
230 struct OTF_KeyValueList_struct {
231 uint32_t key_count; /* number of different keys in list --> user-relevant */
232 uint32_t count; /* total number of entries in list (treat byte arrays particular) --> internal use only */
233 uint32_t size; /* number of allocated entries --> internal */
234 OTF_KeyValuePairList *kvBegin;
235 OTF_KeyValuePairList *kvEnd;
236 OTF_KeyValuePairList *kvCurrent;
237 };
238
239 /** @endcond */
240
241 /** Object type which holds a key-value list.*/
242 typedef struct OTF_KeyValueList_struct OTF_KeyValueList;
243
244 /** Object type which holds a key-value pair.*/
245 typedef struct OTF_KeyValuePair_struct OTF_KeyValuePair;
246
247 /**
248 * Create a new OTF_KeyValueList instance.
249 *
250 * @return Initialized OTF_KeyValueList instance or NULL if an error
251 * occurred.
252 *
253 * \ingroup keyvalue
254 */
255 OTF_KeyValueList *OTF_KeyValueList_new(void);
256
257
258 /**
259 * Close an OTF_KeyValueList instance.
260 *
261 * @param list Pointer to an initialized OTF_KeyValueList object. See
262 * also OTF_KeyValueList_new().
263 *
264 * @return 0 if instance was closed successfully and 1 otherwise.
265 *
266 * \ingroup keyvalue
267 */
268 uint8_t OTF_KeyValueList_close(OTF_KeyValueList* list);
269
270
271 /**
272 * Reset an OTF_KeyValueList instance without deallocating memory.
273 *
274 * @param list Pointer to an initialized OTF_KeyValueList object. See
275 * also OTF_KeyValueList_new().
276 *
277 * @return 0 on success, 1 if an error occurs
278 *
279 * \ingroup keyvalue
280 */
281 uint8_t OTF_KeyValueList_reset(OTF_KeyValueList* list);
282
283
284 /**
285 * Expand an OTF_KeyValueList by allocating more memory.
286 *
287 * @param list Pointer to an initialized OTF_KeyValueList object. See
288 * also OTF_KeyValueList_new().
289 *
290 * @param num Number of elements for which memory should be allocated.
291 *
292 * @return 0 on success, 1 if an error occurs
293 *
294 * \ingroup keyvalue
295 */
296 uint8_t OTF_KeyValueList_realloc(OTF_KeyValueList* list, uint32_t num);
297
298
299 /** @cond OTF_KeyValue */
300
301 /** the following lines are ignored by doxygen */
302
303 /**
304 * Append an OTF_KeyValuePair to a given OTF_KeyValueList instance.
305 *
306 * @param list Pointer to an initialized OTF_KeyValueList object. See
307 * also OTF_KeyValueList_new().
308 *
309 * @param pair An initialized OTF_KeyValuePair object.
310 *
311 * @return 0 on success, 1 if pair already in list and 255 if an error occurs
312 *
313 * \ingroup keyvalue
314 */
315 uint8_t OTF_KeyValueList_appendPair(OTF_KeyValueList* list, OTF_KeyValuePair pair);
316
317 /** @endcond */
318
319
320 /**
321 * Append a character to a given OTF_KeyValueList instance.
322 *
323 * @param list Pointer to an initialized OTF_KeyValueList object. See
324 * also OTF_KeyValueList_new().
325 *
326 * @param key An unique id that identifies the value in the KeyValueList.
327 *
328 * @param value A character that should be appended to the KeyValueList.
329 *
330 * @return 0 on success, 1 if key already in list and 255 if an error occurs
331 *
332 * \ingroup keyvalue
333 */
334 uint8_t OTF_KeyValueList_appendChar(OTF_KeyValueList* list, uint32_t key, char value);
335
336
337 /**
338 * Append a signed integer of 8 bit to a OTF_KeyValueList instance.
339 *
340 * @param list Pointer to an initialized OTF_KeyValueList object. See
341 * also OTF_KeyValueList_new().
342 *
343 * @param key An unique id that identifies the value in the KeyValueList.
344 *
345 * @param value A signed integer of 8 bit that should be appended to the KeyValueList.
346 *
347 * @return 0 on success, 1 if key already in list and 255 if an error occurs
348 *
349 * \ingroup keyvalue
350 */
351 uint8_t OTF_KeyValueList_appendInt8(OTF_KeyValueList* list, uint32_t key, int8_t value);
352
353
354 /**
355 * Append an unsigned integer of 8 bit to a OTF_KeyValueList instance.
356 *
357 * @param list Pointer to an initialized OTF_KeyValueList object. See
358 * also OTF_KeyValueList_new().
359 *
360 * @param key An unique id that identifies the value in the KeyValueList.
361 *
362 * @param value An unsigned integer of 8 bit that should be appended to the KeyValueList.
363 *
364 * @return 0 on success, 1 if key already in list and 255 if an error occurs
365 *
366 * \ingroup keyvalue
367 */
368 uint8_t OTF_KeyValueList_appendUint8(OTF_KeyValueList* list, uint32_t key, uint8_t value);
369
370
371 /**
372 * Append a signed integer of 16 bit to a OTF_KeyValueList instance.
373 *
374 * @param list Pointer to an initialized OTF_KeyValueList object. See
375 * also OTF_KeyValueList_new().
376 *
377 * @param key An unique id that identifies the value in the KeyValueList.
378 *
379 * @param value A signed integer of 16 bit that should be appended to the KeyValueList.
380 *
381 * @return 0 on success, 1 if key already in list and 255 if an error occurs
382 *
383 * \ingroup keyvalue
384 */
385 uint8_t OTF_KeyValueList_appendInt16(OTF_KeyValueList* list, uint32_t key, int16_t value);
386
387
388 /**
389 * Append an unsigned integer of 16 bit to a OTF_KeyValueList instance.
390 *
391 * @param list Pointer to an initialized OTF_KeyValueList object. See
392 * also OTF_KeyValueList_new().
393 *
394 * @param key An unique id that identifies the value in the KeyValueList.
395 *
396 * @param value An unsigned integer of 16 bit that should be appended to the KeyValueList.
397 *
398 * @return 0 on success, 1 if key already in list and 255 if an error occurs
399 *
400 * \ingroup keyvalue
401 */
402 uint8_t OTF_KeyValueList_appendUint16(OTF_KeyValueList* list, uint32_t key, uint16_t value);
403
404
405 /**
406 * Append a signed integer of 32 bit to a OTF_KeyValueList instance.
407 *
408 * @param list Pointer to an initialized OTF_KeyValueList object. See
409 * also OTF_KeyValueList_new().
410 *
411 * @param key An unique id that identifies the value in the KeyValueList.
412 *
413 * @param value A signed integer of 32 bit that should be appended to the KeyValueList.
414 *
415 * @return 0 on success, 1 if key already in list and 255 if an error occurs
416 *
417 * \ingroup keyvalue
418 */
419 uint8_t OTF_KeyValueList_appendInt32(OTF_KeyValueList* list, uint32_t key, int32_t value);
420
421
422 /**
423 * Append an unsigned integer of 32 bit to a OTF_KeyValueList instance.
424 *
425 * @param list Pointer to an initialized OTF_KeyValueList object. See
426 * also OTF_KeyValueList_new().
427 *
428 * @param key An unique id that identifies the value in the KeyValueList.
429 *
430 * @param value An unsigned integer of 32 bit that should be appended to the KeyValueList.
431 *
432 * @return 0 on success, 1 if key already in list and 255 if an error occurs
433 *
434 * \ingroup keyvalue
435 */
436 uint8_t OTF_KeyValueList_appendUint32(OTF_KeyValueList* list, uint32_t key, uint32_t value);
437
438
439 /**
440 * Append a signed integer of 64 bit to a OTF_KeyValueList instance.
441 *
442 * @param list Pointer to an initialized OTF_KeyValueList object. See
443 * also OTF_KeyValueList_new().
444 *
445 * @param key An unique id that identifies the value in the KeyValueList.
446 *
447 * @param value A signed integer of 64 bit that should be appended to the KeyValueList.
448 *
449 * @return 0 on success, 1 if key already in list and 255 if an error occurs
450 *
451 * \ingroup keyvalue
452 */
453 uint8_t OTF_KeyValueList_appendInt64(OTF_KeyValueList* list, uint32_t key, int64_t value);
454
455
456 /**
457 * Append an unsigned integer of 64 bit to a given OTF_KeyValueList instance.
458 *
459 * @param list Pointer to an initialized OTF_KeyValueList object. See
460 * also OTF_KeyValueList_new().
461 *
462 * @param key An unique id that identifies the value in the KeyValueList.
463 *
464 * @param value An unsigned integer of 64 bit that should be appended to the KeyValueList.
465 *
466 * @return 0 on success, 1 if key already in list and 255 if an error occurs
467 *
468 * \ingroup keyvalue
469 */
470 uint8_t OTF_KeyValueList_appendUint64(OTF_KeyValueList* list, uint32_t key, uint64_t value);
471
472
473 /**
474 * Append a float to a given OTF_KeyValueList instance.
475 *
476 * @param list Pointer to an initialized OTF_KeyValueList object. See
477 * also OTF_KeyValueList_new().
478 *
479 * @param key An unique id that identifies the value in the KeyValueList.
480 *
481 * @param value A float that should be appended to the KeyValueList.
482 *
483 * @return 0 on success, 1 if key already in list and 255 if an error occurs
484 *
485 * \ingroup keyvalue
486 */
487 uint8_t OTF_KeyValueList_appendFloat(OTF_KeyValueList* list, uint32_t key, float value);
488
489
490 /**
491 * Append a double to a given OTF_KeyValueList instance.
492 *
493 * @param list Pointer to an initialized OTF_KeyValueList object. See
494 * also OTF_KeyValueList_new().
495 *
496 * @param key An unique id that identifies the value in the KeyValueList.
497 *
498 * @param value A double that should be appended to the KeyValueList.
499 *
500 * @return 0 on success, 1 if key already in list and 255 if an error occurs
501 *
502 * \ingroup keyvalue
503 */
504 uint8_t OTF_KeyValueList_appendDouble(OTF_KeyValueList* list, uint32_t key, double value);
505
506
507 /**
508 * Append a byte array to a given OTF_KeyValueList instance.
509 *
510 * @param list Pointer to an initialized OTF_KeyValueList object. See
511 * also OTF_KeyValueList_new().
512 *
513 * @param key An unique id that identifies the value in the KeyValueList.
514 *
515 * @param value Pointer to a byte array that should be appended to the KeyValueList.
516 *
517 * @param len Lenght of byte array.
518 *
519 * @return 0 on success, 1 if key already in list and 255 if an error occurs
520 *
521 * \ingroup keyvalue
522 */
523 uint8_t OTF_KeyValueList_appendByteArray(OTF_KeyValueList* list, uint32_t key, uint8_t *value, uint32_t len);
524
525
526 /**
527 * Append an existing OTF_KeyValueList to a given OTF_KeyValueList instance.
528 *
529 * @param dest_list Pointer to an initialized OTF_KeyValueList object. See
530 * also OTF_KeyValueList_new().
531 *
532 * @param source_list Pointer to an initialized OTF_KeyValueList instance that shall be appended to the given KeyValueList.
533 * See also OTF_KeyValueList_new();
534 *
535 * @return 0 on success, 1 if an error occurs
536 *
537 * \ingroup keyvalue
538 */
539 uint8_t OTF_KeyValueList_appendKeyValueList(OTF_KeyValueList* dest_list, OTF_KeyValueList *source_list);
540
541
542 /**
543 * Read a character from the given OTF_KeyValueList instance.
544 *
545 * @param list Pointer to an initialized OTF_KeyValueList object. See
546 * also OTF_KeyValueList_new().
547 *
548 * @param value Pointer to a char array, where the result is saved.
549 *
550 * @param key An unique id that identifies the value in the OTF_KeyValueList.
551 *
552 * @return 0 on success, 1 if key not found, 2 if type differs
553 * and 255 if an error occurs
554 *
555 * \ingroup keyvalue
556 */
557 uint8_t OTF_KeyValueList_getChar(OTF_KeyValueList *list, uint32_t key, char *value);
558
559
560 /**
561 * Read a signed integer of 8 bit from the given OTF_KeyValueList instance.
562 *
563 * @param list Pointer to an initialized OTF_KeyValueList object. See
564 * also OTF_KeyValueList_new().
565 *
566 * @param key An unique id that identifies the value in the OTF_KeyValueList.
567 *
568 * @param value Pointer to a signed integer of 8 bit, where the result is saved.
569
570 *
571 * @return 0 on success, 1 if key not found, 2 if type differs
572 * and 255 if an error occurs
573 *
574 * \ingroup keyvalue
575 */
576 uint8_t OTF_KeyValueList_getInt8(OTF_KeyValueList *list, uint32_t key, int8_t *value);
577
578
579 /**
580 * Read an unsigned integer of 8 bit from the given OTF_KeyValueList instance.
581 *
582 * @param list Pointer to an initialized OTF_KeyValueList object. See
583 * also OTF_KeyValueList_new().
584 *
585 * @param key An unique id that identifies the value in the OTF_KeyValueList.
586 *
587 * @param value Pointer to an unsigned integer of 8 bit, where the result is saved.
588 *
589 * @return 0 on success, 1 if key not found, 2 if type differs
590 * and 255 if an error occurs
591 *
592 * \ingroup keyvalue
593 */
594 uint8_t OTF_KeyValueList_getUint8(OTF_KeyValueList *list, uint32_t key, uint8_t *value);
595
596
597 /**
598 * Read a signed integer of 16 bit from the given OTF_KeyValueList instance.
599 *
600 * @param list Pointer to an initialized OTF_KeyValueList object. See
601 * also OTF_KeyValueList_new().
602 *
603 * @param key An unique id that identifies the value in the OTF_KeyValueList.
604 *
605 * @param value Pointer to a signed integer of 16 bit, where the result is saved.
606
607 *
608 * @return 0 on success, 1 if key not found, 2 if type differs
609 * and 255 if an error occurs
610 *
611 * \ingroup keyvalue
612 */
613 uint8_t OTF_KeyValueList_getInt16(OTF_KeyValueList *list, uint32_t key, int16_t *value);
614
615
616 /**
617 * Read an unsigned integer of 16 bit from the given OTF_KeyValueList instance.
618 *
619 * @param list Pointer to an initialized OTF_KeyValueList object. See
620 * also OTF_KeyValueList_new().
621 *
622 * @param key An unique id that identifies the value in the OTF_KeyValueList.
623 *
624 * @param value Pointer to an unsigned integer of 16 bit, where the result is saved.
625 *
626 * @return 0 on success, 1 if key not found, 2 if type differs
627 * and 255 if an error occurs
628 *
629 * \ingroup keyvalue
630 */
631 uint8_t OTF_KeyValueList_getUint16(OTF_KeyValueList *list, uint32_t key, uint16_t *value);
632
633
634 /**
635 * Read a signed integer of 32 bit from the given OTF_KeyValueList instance.
636 *
637 * @param list Pointer to an initialized OTF_KeyValueList object. See
638 * also OTF_KeyValueList_new().
639 *
640 * @param key An unique id that identifies the value in the OTF_KeyValueList.
641 *
642 * @param value Pointer to a signed integer of 32 bit, where the result is saved.
643
644 *
645 * @return 0 on success, 1 if key not found, 2 if type differs
646 * and 255 if an error occurs
647 *
648 * \ingroup keyvalue
649 */
650 uint8_t OTF_KeyValueList_getInt32(OTF_KeyValueList *list, uint32_t key, int32_t *value);
651
652
653 /**
654 * Read an unsigned integer of 32 bit from the given OTF_KeyValueList instance.
655 *
656 * @param list Pointer to an initialized OTF_KeyValueList object. See
657 * also OTF_KeyValueList_new().
658 *
659 * @param key An unique id that identifies the value in the OTF_KeyValueList.
660 *
661 * @param value Pointer to an unsigned integer of 32 bit, where the result is saved.
662 *
663 * @return 0 on success, 1 if key not found, 2 if type differs
664 * and 255 if an error occurs
665 *
666 * \ingroup keyvalue
667 */
668 uint8_t OTF_KeyValueList_getUint32(OTF_KeyValueList *list, uint32_t key, uint32_t *value);
669
670
671 /**
672 * Read a signed integer of 64 bit from the given OTF_KeyValueList instance.
673 *
674 * @param list Pointer to an initialized OTF_KeyValueList object. See
675 * also OTF_KeyValueList_new().
676 * @param key An unique id that identifies the value in the OTF_KeyValueList.
677 *
678 *
679 * @param value Pointer to a signed integer of 64 bit, where the result is saved.
680 *
681 * @return 0 on success, 1 if key not found, 2 if type differs
682 * and 255 if an error occurs
683 *
684 * \ingroup keyvalue
685 */
686 uint8_t OTF_KeyValueList_getInt64(OTF_KeyValueList *list, uint32_t key, int64_t *value);
687
688
689 /**
690 * Read an unsigned integer of 64 bit from the given OTF_KeyValueList instance.
691 *
692 * @param list Pointer to an initialized OTF_KeyValueList object. See
693 * also OTF_KeyValueList_new().
694 * @param key An unique id that identifies the value in the OTF_KeyValueList.
695 *
696 *
697 * @param value Pointer to an unsigned integer of 64 bit, where the result is saved.
698 *
699 * @return 0 on success, 1 if key not found, 2 if type differs
700 * and 255 if an error occurs
701 *
702 * \ingroup keyvalue
703 */
704 uint8_t OTF_KeyValueList_getUint64(OTF_KeyValueList *list, uint32_t key, uint64_t *value);
705
706
707 /**
708 * Read a float from the given OTF_KeyValueList instance.
709 *
710 * @param list Pointer to an initialized OTF_KeyValueList object. See
711 * also OTF_KeyValueList_new().
712 *
713 * @param key An unique id that identifies the value in the OTF_KeyValueList.
714 *
715 * @param value Pointer to a float, where the result is saved.
716 *
717 * @return 0 on success, 1 if key not found, 2 if type differs
718 * and 255 if an error occurs
719 *
720 * \ingroup keyvalue
721 */
722 uint8_t OTF_KeyValueList_getFloat(OTF_KeyValueList *list, uint32_t key, float *value);
723
724
725 /**
726 * Read a double from the given OTF_KeyValueList instance.
727 *
728 * @param list Pointer to an initialized OTF_KeyValueList object. See
729 * also OTF_KeyValueList_new().
730 *
731 * @param key An unique id that identifies the value in the OTF_KeyValueList.
732 *
733 * @param value Pointer to a double, where the result is saved.
734 *
735 * @return 0 on success, 1 if key not found, 2 if type differs
736 * and 255 if an error occurs
737 *
738 * \ingroup keyvalue
739 */
740 uint8_t OTF_KeyValueList_getDouble(OTF_KeyValueList *list, uint32_t key, double *value);
741
742
743 /**
744 * Read a byte array from the given OTF_KeyValueList instance.
745 *
746 * @param list Pointer to an initialized OTF_KeyValueList object. See
747 * also OTF_KeyValueList_new().
748 *
749 * @param key An unique id that identifies the value in the OTF_KeyValueList.
750 *
751 * @param value Pointer to an allocated byte array, where the result is saved.
752 *
753 * @param len Input and output parameter: Musst contain the number of bytes
754 * that can be written to the buffer pointed by the parameter \a value.
755 * Therefore at least \a len bytes musst be allocated for this buffer before.
756 * At the end \e len contains the number of bytes written to the buffer.
757 * This can be less or equal to the input of parameter \a len. To get the
758 * total number of bytes stored in the byte-array for the specific \a key you
759 * can use the function OTF_KeyValueList_getArrayLength() before.
760 *
761 * @return 0 on success, 1 if key not found, 2 if type differs
762 * and 255 if an error occurs
763 *
764 * \ingroup keyvalue
765 */
766 uint8_t OTF_KeyValueList_getByteArray(OTF_KeyValueList *list, uint32_t key, uint8_t *value, uint32_t *len);
767
768
769 /**
770 * Provides the lenght of a byte array in an OTF_KeyValueList instance by given key.
771 *
772 * @param list Pointer to an initialized OTF_KeyValueList object. See
773 * also OTF_KeyValueList_new().
774 *
775 * @param key An unique id that identifies the pair in the OTF_KeyValueList.
776 *
777 * @param len Return value for the array length.
778 *
779 * @return 0 on success, 1 if key not found, 2 if type differs
780 * and 255 if an error occurs
781 *
782 * \ingroup keyvalue
783 */
784 uint8_t OTF_KeyValueList_getArrayLength(OTF_KeyValueList *list, uint32_t key, uint32_t *len);
785
786
787 /**
788 * Search for key in given OTF_KeyValueList instance and return its type.
789 *
790 * @param list Pointer to an initialized OTF_KeyValueList object. See
791 * also OTF_KeyValueList_new().
792 *
793 * @param key An unique id that identifies the pair in the OTF_KeyValueList.
794 *
795 * @return OTF_Type on success, OTF_UNKNOWN if key not found or an error occurred.
796 *
797 * \ingroup keyvalue
798 */
799 OTF_Type OTF_KeyValueList_getTypeForKey(OTF_KeyValueList *list, uint32_t key);
800
801
802 /**
803 * Search for key in the given OTF_KeyValueList instance.
804 *
805 * @param list Pointer to an initialized OTF_KeyValueList object. See
806 * also OTF_KeyValueList_new().
807 *
808 * @param key Token that shall be searched in the OTF_KeyValueList.
809 *
810 * @return 0 on success, 1 if key not found or an error occurred.
811 *
812 * \ingroup keyvalue
813 */
814 uint8_t OTF_KeyValueList_hasKey(OTF_KeyValueList *list, uint32_t key);
815
816
817 /**
818 * Remove key from the given OTF_KeyValueList instance.
819 *
820 * @param list Pointer to an initialized OTF_KeyValueList object. See
821 * also OTF_KeyValueList_new().
822 *
823 * @param key Token that shall be removed from the OTF_KeyValueList.
824 *
825 * @return 0 on success, 1 if key not found or an error occurred.
826 *
827 * \ingroup keyvalue
828 */
829 uint8_t OTF_KeyValueList_removeKey(OTF_KeyValueList *list, uint32_t key);
830
831
832 /**
833 * Search for a key at the given index position.
834 *
835 * @param list Pointer to an initialized OTF_KeyValueList object. See
836 * also OTF_KeyValueList_new().
837 * @param index Index position in the OTF_KeyValueList.
838 *
839 * @param key Return value for the found key.
840 *
841 * @return 0 on success, 1 if index not in list
842 *
843 * \ingroup keyvalue
844 */
845 uint8_t OTF_KeyValueList_getKeyByIndex(OTF_KeyValueList *list, uint32_t index, uint32_t *key);
846
847 /**
848 * Search for a key-value pair at the given index position.
849 *
850 * @param list Pointer to an initialized OTF_KeyValueList object. See
851 * also OTF_KeyValueList_new().
852 * @param index Index position in the OTF_KeyValueList.
853 *
854 * @param pair Pointer to the found key-value pair.
855 *
856 * @return 0 on success, 1 if index not in list
857 *
858 * \ingroup keyvalue
859 */
860 uint8_t OTF_KeyValueList_getPairByIndex(OTF_KeyValueList *list, uint32_t index, OTF_KeyValuePair **pair);
861
862 /**
863 * Returns the number of elements in the given OTF_KeyValueList instance.
864 *
865 * @param list Pointer to an initialized OTF_KeyValueList object. See
866 * also OTF_KeyValueList_new().
867 *
868 * @return Number of elements currently in list.
869 *
870 * \ingroup keyvalue
871 */
872 uint32_t OTF_KeyValueList_getCount(OTF_KeyValueList *list);
873
874
875 /**
876 * Convert an integer of 32 bit to a float.
877 *
878 * \ingroup keyvalue
879 */
880 float OTF_Int32ToFloat(uint32_t value);
881
882
883 /**
884 * Convert a float to an integer of 32 bit.
885 *
886 * \ingroup keyvalue
887 */
888 uint32_t OTF_FloatToInt32(float value);
889
890
891 /**
892 * Convert an integer of 64 bit to a double.
893 *
894 * \ingroup keyvalue
895 */
896 double OTF_Int64ToDouble(uint64_t value);
897
898
899 /**
900 * Convert a double to a signed integer of 64 bit.
901 *
902 * \ingroup keyvalue
903 */
904 uint64_t OTF_DoubleToInt64(double value);
905
906
907 #ifdef __cplusplus
908 }
909 #endif /* __cplusplus */
910
911 #endif /* OTF_KEYVALUE_H */
912
913
OTF_KeyValueList_getInt32
uint8_t OTF_KeyValueList_getInt32(OTF_KeyValueList *list, uint32_t key, int32_t *value)
Read a signed integer of 32 bit from the given OTF_KeyValueList instance.
Definition: OTF_KeyValue.c:548
OTF_KeyValueList_getArrayLength
uint8_t OTF_KeyValueList_getArrayLength(OTF_KeyValueList *list, uint32_t key, uint32_t *len)
Provides the lenght of a byte array in an OTF_KeyValueList instance by given key. ...
Definition: OTF_KeyValue.c:714
OTF_KeyValueList_getInt16
uint8_t OTF_KeyValueList_getInt16(OTF_KeyValueList *list, uint32_t key, int16_t *value)
Read a signed integer of 16 bit from the given OTF_KeyValueList instance.
Definition: OTF_KeyValue.c:524
OTF_KeyValueList_close
uint8_t OTF_KeyValueList_close(OTF_KeyValueList *list)
Close an OTF_KeyValueList instance.
Definition: OTF_KeyValue.c:61
OTF_KeyValueList_getFloat
uint8_t OTF_KeyValueList_getFloat(OTF_KeyValueList *list, uint32_t key, float *value)
Read a float from the given OTF_KeyValueList instance.
Definition: OTF_KeyValue.c:596
OTF_KeyValueList_appendChar
uint8_t OTF_KeyValueList_appendChar(OTF_KeyValueList *list, uint32_t key, char value)
Append a character to a given OTF_KeyValueList instance.
Definition: OTF_KeyValue.c:229
OTF_KeyValueList_getInt64
uint8_t OTF_KeyValueList_getInt64(OTF_KeyValueList *list, uint32_t key, int64_t *value)
Read a signed integer of 64 bit from the given OTF_KeyValueList instance.
Definition: OTF_KeyValue.c:572
OTF_KeyValueList_getInt8
uint8_t OTF_KeyValueList_getInt8(OTF_KeyValueList *list, uint32_t key, int8_t *value)
Read a signed integer of 8 bit from the given OTF_KeyValueList instance.
Definition: OTF_KeyValue.c:500
OTF_Type_enum
OTF_Type_enum
An enum which holds all OTF datatypes that are relevant for OTF_KeyValueList.
Definition: OTF_KeyValue.h:178
OTF_KeyValueList_appendInt64
uint8_t OTF_KeyValueList_appendInt64(OTF_KeyValueList *list, uint32_t key, int64_t value)
Append a signed integer of 64 bit to a OTF_KeyValueList instance.
Definition: OTF_KeyValue.c:313
OTF_KeyValueList_appendKeyValueList
uint8_t OTF_KeyValueList_appendKeyValueList(OTF_KeyValueList *dest_list, OTF_KeyValueList *source_list)
Append an existing OTF_KeyValueList to a given OTF_KeyValueList instance.
Definition: OTF_KeyValue.c:401
OTF_KeyValueList_realloc
uint8_t OTF_KeyValueList_realloc(OTF_KeyValueList *list, uint32_t num)
Expand an OTF_KeyValueList by allocating more memory.
Definition: OTF_KeyValue.c:134
OTF_KeyValueList_getDouble
uint8_t OTF_KeyValueList_getDouble(OTF_KeyValueList *list, uint32_t key, double *value)
Read a double from the given OTF_KeyValueList instance.
Definition: OTF_KeyValue.c:608
OTF_KeyValueList_hasKey
uint8_t OTF_KeyValueList_hasKey(OTF_KeyValueList *list, uint32_t key)
Search for key in the given OTF_KeyValueList instance.
Definition: OTF_KeyValue.c:754
OTF_KeyValueList_getByteArray
uint8_t OTF_KeyValueList_getByteArray(OTF_KeyValueList *list, uint32_t key, uint8_t *value, uint32_t *len)
Read a byte array from the given OTF_KeyValueList instance.
Definition: OTF_KeyValue.c:620
OTF_KeyValueList_new
OTF_KeyValueList * OTF_KeyValueList_new(void)
Create a new OTF_KeyValueList instance.
Definition: OTF_KeyValue.c:15
OTF_Int64ToDouble
double OTF_Int64ToDouble(uint64_t value)
Convert an integer of 64 bit to a double.
Definition: OTF_KeyValue.c:430
OTF_KeyValueList_appendDouble
uint8_t OTF_KeyValueList_appendDouble(OTF_KeyValueList *list, uint32_t key, double value)
Append a double to a given OTF_KeyValueList instance.
Definition: OTF_KeyValue.c:349
OTF_KeyValuePair
struct OTF_KeyValuePair_struct OTF_KeyValuePair
Object type which holds a key-value pair.
Definition: OTF_KeyValue.h:245
OTF_KeyValueList_appendUint16
uint8_t OTF_KeyValueList_appendUint16(OTF_KeyValueList *list, uint32_t key, uint16_t value)
Append an unsigned integer of 16 bit to a OTF_KeyValueList instance.
Definition: OTF_KeyValue.c:277
OTF_KeyValueList_getChar
uint8_t OTF_KeyValueList_getChar(OTF_KeyValueList *list, uint32_t key, char *value)
Read a character from the given OTF_KeyValueList instance.
Definition: OTF_KeyValue.c:488
OTF_Int32ToFloat
float OTF_Int32ToFloat(uint32_t value)
Convert an integer of 32 bit to a float.
Definition: OTF_KeyValue.c:442
OTF_KeyValueList_appendInt8
uint8_t OTF_KeyValueList_appendInt8(OTF_KeyValueList *list, uint32_t key, int8_t value)
Append a signed integer of 8 bit to a OTF_KeyValueList instance.
Definition: OTF_KeyValue.c:241
OTF_KeyValueList_getCount
uint32_t OTF_KeyValueList_getCount(OTF_KeyValueList *list)
Returns the number of elements in the given OTF_KeyValueList instance.
Definition: OTF_KeyValue.c:910
OTF_KeyValueList_getPairByIndex
uint8_t OTF_KeyValueList_getPairByIndex(OTF_KeyValueList *list, uint32_t index, OTF_KeyValuePair **pair)
Search for a key-value pair at the given index position.
Definition: OTF_KeyValue.c:866
OTF_KeyValueList_appendUint8
uint8_t OTF_KeyValueList_appendUint8(OTF_KeyValueList *list, uint32_t key, uint8_t value)
Append an unsigned integer of 8 bit to a OTF_KeyValueList instance.
Definition: OTF_KeyValue.c:253
OTF_KeyValueList_appendInt16
uint8_t OTF_KeyValueList_appendInt16(OTF_KeyValueList *list, uint32_t key, int16_t value)
Append a signed integer of 16 bit to a OTF_KeyValueList instance.
Definition: OTF_KeyValue.c:265
OTF_KeyValueList_reset
uint8_t OTF_KeyValueList_reset(OTF_KeyValueList *list)
Reset an OTF_KeyValueList instance without deallocating memory.
Definition: OTF_KeyValue.c:88
OTF_KeyValueList_removeKey
uint8_t OTF_KeyValueList_removeKey(OTF_KeyValueList *list, uint32_t key)
Remove key from the given OTF_KeyValueList instance.
Definition: OTF_KeyValue.c:783
OTF_Type
enum OTF_Type_enum OTF_Type
An enum which holds all OTF datatypes that are relevant for OTF_KeyValueList.
OTF_FloatToInt32
uint32_t OTF_FloatToInt32(float value)
Convert a float to an integer of 32 bit.
Definition: OTF_KeyValue.c:448
OTF_KeyValueList_getKeyByIndex
uint8_t OTF_KeyValueList_getKeyByIndex(OTF_KeyValueList *list, uint32_t index, uint32_t *key)
Search for a key at the given index position.
Definition: OTF_KeyValue.c:822
OTF_DoubleToInt64
uint64_t OTF_DoubleToInt64(double value)
Convert a double to a signed integer of 64 bit.
Definition: OTF_KeyValue.c:436
OTF_KeyValueList_getUint16
uint8_t OTF_KeyValueList_getUint16(OTF_KeyValueList *list, uint32_t key, uint16_t *value)
Read an unsigned integer of 16 bit from the given OTF_KeyValueList instance.
Definition: OTF_KeyValue.c:536
OTF_KeyValueList_getTypeForKey
OTF_Type OTF_KeyValueList_getTypeForKey(OTF_KeyValueList *list, uint32_t key)
Search for key in given OTF_KeyValueList instance and return its type.
Definition: OTF_KeyValue.c:726
OTF_KeyValueList_getUint8
uint8_t OTF_KeyValueList_getUint8(OTF_KeyValueList *list, uint32_t key, uint8_t *value)
Read an unsigned integer of 8 bit from the given OTF_KeyValueList instance.
Definition: OTF_KeyValue.c:512
OTF_KeyValueList_appendInt32
uint8_t OTF_KeyValueList_appendInt32(OTF_KeyValueList *list, uint32_t key, int32_t value)
Append a signed integer of 32 bit to a OTF_KeyValueList instance.
Definition: OTF_KeyValue.c:289
OTF_KeyValueList_getUint32
uint8_t OTF_KeyValueList_getUint32(OTF_KeyValueList *list, uint32_t key, uint32_t *value)
Read an unsigned integer of 32 bit from the given OTF_KeyValueList instance.
Definition: OTF_KeyValue.c:560
OTF_KeyValueList_appendFloat
uint8_t OTF_KeyValueList_appendFloat(OTF_KeyValueList *list, uint32_t key, float value)
Append a float to a given OTF_KeyValueList instance.
Definition: OTF_KeyValue.c:337
OTF_KeyValueList
struct OTF_KeyValueList_struct OTF_KeyValueList
Object type which holds a key-value list.
Definition: OTF_KeyValue.h:242
OTF_Definitions.h
Provides many many macros for different purposes.
OTF_KeyValueList_appendUint32
uint8_t OTF_KeyValueList_appendUint32(OTF_KeyValueList *list, uint32_t key, uint32_t value)
Append an unsigned integer of 32 bit to a OTF_KeyValueList instance.
Definition: OTF_KeyValue.c:301
OTF_inttypes.h
Deals with all data type related issues.
OTF_KeyValueList_appendUint64
uint8_t OTF_KeyValueList_appendUint64(OTF_KeyValueList *list, uint32_t key, uint64_t value)
Append an unsigned integer of 64 bit to a given OTF_KeyValueList instance.
Definition: OTF_KeyValue.c:325
OTF_KeyValueList_getUint64
uint8_t OTF_KeyValueList_getUint64(OTF_KeyValueList *list, uint32_t key, uint64_t *value)
Read an unsigned integer of 64 bit from the given OTF_KeyValueList instance.
Definition: OTF_KeyValue.c:584
OTF_KeyValueList_appendByteArray
uint8_t OTF_KeyValueList_appendByteArray(OTF_KeyValueList *list, uint32_t key, uint8_t *value, uint32_t len)
Append a byte array to a given OTF_KeyValueList instance.
Definition: OTF_KeyValue.c:361