OpenMPI  0.1.1
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  */
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  */
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  */
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  */
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  */
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 */
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 
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
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
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
uint8_t OTF_KeyValueList_close(OTF_KeyValueList *list)
Close an OTF_KeyValueList instance.
Definition: OTF_KeyValue.c:61
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
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
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
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
An enum which holds all OTF datatypes that are relevant for OTF_KeyValueList.
Definition: OTF_KeyValue.h:178
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
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
uint8_t OTF_KeyValueList_realloc(OTF_KeyValueList *list, uint32_t num)
Expand an OTF_KeyValueList by allocating more memory.
Definition: OTF_KeyValue.c:134
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
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
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 * OTF_KeyValueList_new(void)
Create a new OTF_KeyValueList instance.
Definition: OTF_KeyValue.c:15
double OTF_Int64ToDouble(uint64_t value)
Convert an integer of 64 bit to a double.
Definition: OTF_KeyValue.c:430
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
struct OTF_KeyValuePair_struct OTF_KeyValuePair
Object type which holds a key-value pair.
Definition: OTF_KeyValue.h:245
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
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
float OTF_Int32ToFloat(uint32_t value)
Convert an integer of 32 bit to a float.
Definition: OTF_KeyValue.c:442
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
uint32_t OTF_KeyValueList_getCount(OTF_KeyValueList *list)
Returns the number of elements in the given OTF_KeyValueList instance.
Definition: OTF_KeyValue.c:910
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
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
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
uint8_t OTF_KeyValueList_reset(OTF_KeyValueList *list)
Reset an OTF_KeyValueList instance without deallocating memory.
Definition: OTF_KeyValue.c:88
uint8_t OTF_KeyValueList_removeKey(OTF_KeyValueList *list, uint32_t key)
Remove key from the given OTF_KeyValueList instance.
Definition: OTF_KeyValue.c:783
enum OTF_Type_enum OTF_Type
An enum which holds all OTF datatypes that are relevant for OTF_KeyValueList.
uint32_t OTF_FloatToInt32(float value)
Convert a float to an integer of 32 bit.
Definition: OTF_KeyValue.c:448
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
uint64_t OTF_DoubleToInt64(double value)
Convert a double to a signed integer of 64 bit.
Definition: OTF_KeyValue.c:436
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_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
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
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
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
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
struct OTF_KeyValueList_struct OTF_KeyValueList
Object type which holds a key-value list.
Definition: OTF_KeyValue.h:242
Provides many many macros for different purposes.
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
Deals with all data type related issues.
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
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
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