2
* @page eet_examples EET Examples
4
* Here is a page with examples.
6
* @ref Example_Eet_Data_Simple
8
* @ref Example_Eet_Data_Nested
10
* @ref Example_Eet_Data_File_Descriptor_01
12
* @ref Example_Eet_Data_File_Descriptor_02
14
* @ref Example_Eet_Data_Cipher_Decipher
18
* @page Example_Eet_Basic Very basic Eet example
20
* @includelineno eet-basic.c
21
* @example eet-basic.c
25
* @page Example_Eet_File Example of the various ways to interface with an Eet File
27
* @includelineno eet-file.c
32
* @page Example_Eet_Data_Simple Simple data example
34
* @includelineno eet-data-simple.c
35
* @example eet-data-simple.c
39
* @page Example_Eet_Data_Nested Nested data example
41
* @includelineno eet-data-nested.c
42
* @example eet-data-nested.c
46
* @page Example_Eet_Data_File_Descriptor_01 File descriptor data example
48
* @includelineno eet-data-file_descriptor_01.c
49
* @example eet-data-file_descriptor_01.c
53
* @page Example_Eet_Data_File_Descriptor_02 File descriptor data example, with Eet unions and variants
55
* This is an example much like the one shown in @ref
56
* eet_data_file_descriptor. The difference is that here we're
57
* attaining ourselves to two new data types to store in an Eet file
58
* -- @b unions and @b variants. We don't try to come with data
59
* mapping to real world use cases, here. Instead, we're defining
60
* 3 different simple structures to be used throughout the example:
61
* @dontinclude eet-data-file_descriptor_02.c
62
* @skip typedef struct _Example_Struct1
63
* @until typedef struct _Example_Struct3
64
* @skip struct _Example_Struct1
68
* To identify, for both union and variant data cases, the type of
69
* each chunk of data, we're defining types to point to each of those
71
* @dontinclude eet-data-file_descriptor_02.c
72
* @skip typedef enum _Example_Data_Type
74
* @skip enum _Example_Data_Type
77
* We have also a mapping from those types to name strings, to be used
78
* in the Eet unions and variants @c type_get() and @c type_set() type
79
* identifying callbacks:
83
* In this example, we have no fancy hash to store our data into
84
* profiles/accounts, but just two lists for union and variant data
86
* @dontinclude eet-data-file_descriptor_02.c
87
* @skip typedef struct _Example_Lists
88
* @until typedef struct _Example_Lists
89
* @skip struct _Example_Lists
92
* Let's begin with our unions, then, which look like:
93
* @dontinclude eet-data-file_descriptor_02.c
94
* @skip typedef struct _Example_Union
95
* @until typedef struct _Example_Union
96
* @skip struct _Example_Union
99
* The first interesting part of the code is where we define our data
100
* descriptors for the main lists, the unions and all of structures
101
* upon which those two depend.
102
* @dontinclude eet-data-file_descriptor_02.c
103
* @skip declaring types
104
* @until _union_descriptor);
105
* The code for descriptors on @c Example_Struct1, @c Example_Struct2
106
* and @c Example_Struct3 is straightforward, a matter already covered
107
* on @ref eet_data_file_descriptor. What is new, here, are the two
108
* type matching functions for our unions. There, we must set the @c
109
* data pointer to its matching type, on @c _union_type_set and return
110
* the correct matching type, on @c _union_type_get:
111
* @dontinclude eet-data-file_descriptor_02.c
112
* @skip union type_get()
113
* @until _union_type_set
114
* @until _union_type_set
116
* With the #EET_DATA_DESCRIPTOR_ADD_MAPPING calls, which follow, we
117
* make the the link between our type names and their respective
118
* structs. The code handling actual data is pretty much the same as in
119
* @ref eet_data_file_descriptor -- one uses command line arguments to
120
* enter new data chunks (or just to visualize the contents of an Eet
121
* file), signalling if they are unions or variants. One must also
122
* pass the type of the data chuck to enter, with integers 1, 2 or
123
* 3. Then, come the fields for each type:
124
* @dontinclude eet-data-file_descriptor_02.c
128
* Variants are very similar to unions, except that data chunks need
129
* @b not contain previously allocated space for each of the possible
130
* types of data going in them:
131
* @dontinclude eet-data-file_descriptor_02.c
132
* @skip typedef struct _Example_Variant
133
* @until typedef struct _Example_Variant
134
* @skip struct _Example_Variant_Type
138
* The code declaring the data descriptors and handling the data is
139
* very similar to the unions part, and is left for the reader to
140
* check for him/herself. The complete code of the example follows.
142
* @includelineno eet-data-file_descriptor_02.c
143
* @example eet-data-file_descriptor_02.c
147
* @page Example_Eet_Data_Cipher_Decipher Eet data cipher/decipher example
149
* In this example, we exemplify the usage of eet_write_cipher() and
150
* eet_read_cipher(). For it to work, <b>make sure</b> to have your
151
* Eet installation with a ciphering backend enabled.
153
* We start by defining the information to record in an Eet file (@c
154
* buffer), the key to cipher that (@c key) and a dummy wrong key to
155
* try to access that information, later (@c key_bad).
156
* @dontinclude eet-data-cipher_decipher.c
160
* After opening our file, we simply use the first cited function to
161
* write our string ciphered:
162
* @dontinclude eet-data-cipher_decipher.c
166
* Then, after closing it on purpose, we open it again, to retrieve
167
* the encrypted information back, in a readable format:
172
* Note that we do it twice, being the last time with the wrong
173
* key. In this last case, if the information is read back and matches
174
* the original @c buffer, something wrong is going on (we made it to
175
* fail on purpose). The former access is OK, and must work.
177
* What we do in sequence is just to delete the file. The complete
178
* code of the example follows.
180
* @includelineno eet-data-cipher_decipher.c
181
* @example eet-data-cipher_decipher.c