summaryrefslogtreecommitdiff
path: root/doc/eet_examples.dox
diff options
context:
space:
mode:
authorJonas M. Gastal <jgastal@profusion.mobi>2012-12-18 16:13:03 +0000
committerJonas M. Gastal <jgastal@profusion.mobi>2012-12-18 16:13:03 +0000
commit0809af70fb0e762a748b5d72ed353971d88bae9b (patch)
treebaf0f67fb24cc8487fa8e2c3f8a5f69a4ce61b04 /doc/eet_examples.dox
parent6ecaa33f2265b7ba0060ffcdc93e96366a49e886 (diff)
efl: Adding *.dox files from various libs.
SVN revision: 81274
Diffstat (limited to 'doc/eet_examples.dox')
-rw-r--r--doc/eet_examples.dox184
1 files changed, 184 insertions, 0 deletions
diff --git a/doc/eet_examples.dox b/doc/eet_examples.dox
new file mode 100644
index 0000000000..b842584466
--- /dev/null
+++ b/doc/eet_examples.dox
@@ -0,0 +1,184 @@
1/**
2 * @page Examples Examples
3 *
4 * Here is a page with examples.
5 *
6 * @ref Example_Eet_Data_Simple
7 *
8 * @ref Example_Eet_Data_Nested
9 *
10 * @ref Example_Eet_Data_File_Descriptor_01
11 *
12 * @ref Example_Eet_Data_File_Descriptor_02
13 *
14 * @ref Example_Eet_Data_Cipher_Decipher
15 *
16 * <a href="examples.html">List of examples</a>
17 */
18
19/**
20 * @page Example_Eet_Basic Very basic Eet example
21 *
22 * @includelineno eet-basic.c
23 * @example eet-basic.c
24 */
25
26/**
27 * @page Example_Eet_File Example of the various ways to interface with an Eet File
28 *
29 * @includelineno eet-file.c
30 * @example eet-file.c
31 */
32
33/**
34 * @page Example_Eet_Data_Simple Simple data example
35 *
36 * @includelineno eet-data-simple.c
37 * @example eet-data-simple.c
38 */
39
40/**
41 * @page Example_Eet_Data_Nested Nested data example
42 *
43 * @includelineno eet-data-nested.c
44 * @example eet-data-nested.c
45 */
46
47/**
48 * @page Example_Eet_Data_File_Descriptor_01 File descriptor data example
49 *
50 * @includelineno eet-data-file_descriptor_01.c
51 * @example eet-data-file_descriptor_01.c
52 */
53
54/**
55 * @page Example_Eet_Data_File_Descriptor_02 File descriptor data example, with Eet unions and variants
56 *
57 * This is an example much like the one shown in @ref
58 * eet_data_file_descriptor. The difference is that here we're
59 * attaining ourselves to two new data types to store in an Eet file
60 * -- @b unions and @b variants. We don't try to come with data
61 * mapping to real world use cases, here. Instead, we're defining
62 * 3 different simple structures to be used throughout the example:
63 * @dontinclude eet-data-file_descriptor_02.c
64 * @skip typedef struct _Example_Struct1
65 * @until typedef struct _Example_Struct3
66 * @skip struct _Example_Struct1
67 * @until int body
68 * @until };
69 *
70 * To identify, for both union and variant data cases, the type of
71 * each chunk of data, we're defining types to point to each of those
72 * structs:
73 * @dontinclude eet-data-file_descriptor_02.c
74 * @skip typedef enum _Example_Data_Type
75 * @until ;
76 * @skip enum _Example_Data_Type
77 * @until };
78 *
79 * We have also a mapping from those types to name strings, to be used
80 * in the Eet unions and variants @c type_get() and @c type_set() type
81 * identifying callbacks:
82 * @skip struct
83 * @until };
84 *
85 * In this example, we have no fancy hash to store our data into
86 * profiles/accounts, but just two lists for union and variant data
87 * nodes:
88 * @dontinclude eet-data-file_descriptor_02.c
89 * @skip typedef struct _Example_Lists
90 * @until typedef struct _Example_Lists
91 * @skip struct _Example_Lists
92 * @until };
93 *
94 * Let's begin with our unions, then, which look like:
95 * @dontinclude eet-data-file_descriptor_02.c
96 * @skip typedef struct _Example_Union
97 * @until typedef struct _Example_Union
98 * @skip struct _Example_Union
99 * @until };
100 *
101 * The first interesting part of the code is where we define our data
102 * descriptors for the main lists, the unions and all of structures
103 * upon which those two depend.
104 * @dontinclude eet-data-file_descriptor_02.c
105 * @skip declaring types
106 * @until _union_descriptor);
107 * The code for descriptors on @c Example_Struct1, @c Example_Struct2
108 * and @c Example_Struct3 is straightforward, a matter already covered
109 * on @ref eet_data_file_descriptor. What is new, here, are the two
110 * type matching functions for our unions. There, we must set the @c
111 * data pointer to its matching type, on @c _union_type_set and return
112 * the correct matching type, on @c _union_type_get:
113 * @dontinclude eet-data-file_descriptor_02.c
114 * @skip union type_get()
115 * @until _union_type_set
116 * @until _union_type_set
117 *
118 * With the #EET_DATA_DESCRIPTOR_ADD_MAPPING calls, which follow, we
119 * make the the link between our type names and their respective
120 * structs. The code handling actual data is pretty much the same as in
121 * @ref eet_data_file_descriptor -- one uses command line arguments to
122 * enter new data chunks (or just to visualize the contents of an Eet
123 * file), signalling if they are unions or variants. One must also
124 * pass the type of the data chuck to enter, with integers 1, 2 or
125 * 3. Then, come the fields for each type:
126 * @dontinclude eet-data-file_descriptor_02.c
127 * @skip Usage
128 * @until argv
129 *
130 * Variants are very similar to unions, except that data chunks need
131 * @b not contain previously allocated space for each of the possible
132 * types of data going in them:
133 * @dontinclude eet-data-file_descriptor_02.c
134 * @skip typedef struct _Example_Variant
135 * @until typedef struct _Example_Variant
136 * @skip struct _Example_Variant_Type
137 * @until };
138 * @until };
139 *
140 * The code declaring the data descriptors and handling the data is
141 * very similar to the unions part, and is left for the reader to
142 * check for him/herself. The complete code of the example follows.
143 *
144 * @includelineno eet-data-file_descriptor_02.c
145 * @example eet-data-file_descriptor_02.c
146 */
147
148/**
149 * @page Example_Eet_Data_Cipher_Decipher Eet data cipher/decipher example
150 *
151 * In this example, we exemplify the usage of eet_write_cipher() and
152 * eet_read_cipher(). For it to work, <b>make sure</b> to have your
153 * Eet installation with a ciphering backend enabled.
154 *
155 * We start by defining the information to record in an Eet file (@c
156 * buffer), the key to cipher that (@c key) and a dummy wrong key to
157 * try to access that information, later (@c key_bad).
158 * @dontinclude eet-data-cipher_decipher.c
159 * @skip buffer =
160 * @until bad =
161 *
162 * After opening our file, we simply use the first cited function to
163 * write our string ciphered:
164 * @dontinclude eet-data-cipher_decipher.c
165 * @skip eet_open
166 * @until eet_close
167 *
168 * Then, after closing it on purpose, we open it again, to retrieve
169 * the encrypted information back, in a readable format:
170 * @skip eet_open
171 * @until eet_close
172 * @until eet_close
173 *
174 * Note that we do it twice, being the last time with the wrong
175 * key. In this last case, if the information is read back and matches
176 * the original @c buffer, something wrong is going on (we made it to
177 * fail on purpose). The former access is OK, and must work.
178 *
179 * What we do in sequence is just to delete the file. The complete
180 * code of the example follows.
181 *
182 * @includelineno eet-data-cipher_decipher.c
183 * @example eet-data-cipher_decipher.c
184 */