efl

1
/**
2
 * @page eio_examples Eio Examples
3
 *
4
 * Here is a page with some Eio examples explained:
5
 *
6
 * @li @ref eio_file_ls.c
7
 *
8
 * Tutorials:
9
 * @li @ref tutorial_dir_copy
10
 * @li @ref tutorial_dir_stat_ls
11
 * @li @ref tutorial_file_ls
12
 * @li @ref tutorial_dir_direct_ls
13
 * @li @ref tutorial_monitor_add
14
 *
15
 * @example eio_file_ls.c
16
 */
17

18
/**
19
 * @page tutorial_dir_copy eio_dir_copy() tutorial
20
 *
21
 * To use eio_dir_copy(), you basically need the source and
22
 * destination files (or directories), and set three callbacks:
23
 *
24
 * @li The notification callback, which allows you to know if a file or
25
 * a directory is copied, and the progress of the copy.
26
 * @li The end callback, which is called when the copy is finished.
27
 * @li The error callback, which is called if an error occurred. You
28
 * can then retrieve the error type as an errno error.
29
 *
30
 * @warning It is the user's duty to provide the "right target". It
31
 * means that copying to '.' will copy the content directly inside '.'
32
 * and not in a subdirectory.
33
 *
34
 * Here is a simple example:
35
 *
36
 * @code
37
 * #include <Ecore.h>
38
 * #include <Eio.h>
39
 *
40
 * static void
41
 * _test_notify_cb(void *data, Eio_File *handler, const Eio_Progress *info)
42
 * {
43
 *    switch (info->op)
44
 *       {
45
 *       case EIO_FILE_COPY:
46
 *          printf("[%s] %f%%\n", info->dest, info->percent);
47
 *          break;
48
 *       case EIO_DIR_COPY:
49
 *          printf("global [%li/%li] %f%%\n", info->current, info->max, info->percent);
50
 *          break;
51
 *       }
52
 * }
53
 *
54
 * static void
55
 * _test_done_cb(void *data, Eio_File *handler)
56
 * {
57
 *    printf("copy done\n");
58
 *    ecore_main_loop_quit();
59
 * }
60
 *
61
 * static void
62
 * _test_error_cb(int error, Eio_File *handler, void *data)
63
 * {
64
 *    fprintf(stderr, "error: [%s]\n", strerror(error));
65
 *     ecore_main_loop_quit();
66
 * }
67
 *
68
 * int
69
 * main(int argc, char **argv)
70
 * {
71
 *    Eio_File *cp;
72
 *
73
 *    if (argc != 3)
74
 *      {
75
 *         fprintf(stderr, "eio_cp source_file destination_file\n");
76
 *         return -1;
77
 *      }
78
 *
79
 *    ecore_init();
80
 *    eio_init();
81
 *
82
 *    cp = eio_dir_copy(argv[1], argv[2],
83
 *                      _test_notify_cb,
84
 *                      _test_done_cb,
85
 *                      _test_error_cb,
86
 *                      NULL);
87
 *
88
 *    ecore_main_loop_begin();
89
 *
90
 *    eio_shutdown();
91
 *    ecore_shutdown();
92
 *
93
 *    return 0;
94
 * }
95
 * @endcode
96
 */
97

98
/**
99
 * @page tutorial_dir_stat_ls eio_dir_stat_ls() tutorial
100
 *
101
 * @li The filter callback, which allow or not a file to be seen
102
 * by the main loop handler. This callback run in a separated thread.
103
 * @li The main callback, which receive in the main loop all the file
104
 * that are allowed by the filter. If you are updating a user interface
105
 * it make sense to delay the insertion a little, so you get a chance
106
 * to update the canvas for a bunch of file instead of one by one.
107
 * @li The end callback, which is called in the main loop when the
108
 * content of the directory has been correctly scanned and all the
109
 * file notified to the main loop.
110
 * @li The error callback, which is called if an error occurred or
111
 * if the listing was cancelled during it's run. You can then retrieve
112
 * the error type as an errno error.
113
 *
114
 * Here is a simple example that implement a stupidly simple replacement for find:
115
 *
116
 * @code
117
 * #include <Ecore.h>
118
 * #include <Eio.h>
119
 *
120
 * static Eina_Bool
121
 * _test_filter_cb(void *data, Eio_File *handler, const Eina_File_Direct_Info *info)
122
 * {
123
 *    fprintf(stderr, "ACCEPTING: %s\n", info->path);
124
 *    return EINA_TRUE;
125
 * }
126
 *
127
 * static void
128
 * _test_main_cb(void *data, Eio_File *handler, const Eina_File_Direct_Info *info)
129
 * {
130
 *    fprintf(stderr, "PROCESS: %s\n", info->path);
131
 * }
132
 *
133
 * static void
134
 * _test_done_cb(void *data, Eio_File *handler)
135
 * {
136
 *    printf("ls done\n");
137
 *    ecore_main_loop_quit();
138
 * }
139
 *
140
 * static void
141
 * _test_error_cb(void *data, Eio_File *handler, int error)
142
 * {
143
 *    fprintf(stderr, "error: [%s]\n", strerror(error));
144
 *    ecore_main_loop_quit();
145
 * }
146
 *
147
 * int
148
 * main(int argc, char **argv)
149
 * {
150
 *    Eio_File *cp;
151
 *
152
 *    if (argc != 2)
153
 *      {
154
 * 	fprintf(stderr, "eio_ls directory\n");
155
 * 	return -1;
156
 *      }
157
 *
158
 *    ecore_init();
159
 *    eio_init();
160
 *
161
 *    cp = eio_dir_stat_ls(argv[1],
162
 *                         _test_filter_cb,
163
 *                         _test_main_cb,
164
 *                         _test_done_cb,
165
 *                         _test_error_cb,
166
 *                         NULL);
167
 *
168
 *    ecore_main_loop_begin();
169
 *
170
 *    eio_shutdown();
171
 *    ecore_shutdown();
172
 *
173
 *    return 0;
174
 * }
175
 *
176
 * @endcode
177
 */
178

179
/**
180
 * @page tutorial_file_ls eio_file_ls() tutorial
181
 *
182
 * To use eio_file_ls(), you just need to define four callbacks:
183
 *
184
 * @li The filter callback, which allows a file to be seen (or not)
185
 * by the main loop handler. This callback runs in a separate thread.
186
 * @li The main callback, which receive in the main loop all the file
187
 * that are allowed by the filter. If you are updating a user interface
188
 * it makes sense to delay the insertion a little, so you get a chance
189
 * to update the canvas for a bunch of files instead of one by one.
190
 * @li The end callback, which is called in the main loop when the
191
 * content of the directory has been correctly scanned and all the
192
 * file notified to the main loop.
193
 * @li The error callback, which is called if an error occurred or
194
 * if the listing was cancelled during its run. You can then retrieve
195
 * the error type as an errno error.
196
 *
197
 * Here is a simple example:
198
 *
199
 * @code
200
 * #include <Ecore.h>
201
 * #include <Eio.h>
202
 *
203
 * static Eina_Bool
204
 * _test_filter_cb(void *data, Eio_File *handler, const char *file)
205
 * {
206
 *    fprintf(stderr, "ACCEPTING: %s\n", file);
207
 *    return EINA_TRUE;
208
 * }
209
 *
210
 * static void
211
 * _test_main_cb(void *data, Eio_File *handler, const char *file)
212
 * {
213
 *    fprintf(stderr, "PROCESS: %s\n", file);
214
 * }
215
 *
216
 * static void
217
 * _test_done_cb(void *data, Eio_File *handler)
218
 * {
219
 *    printf("ls done\n");
220
 *    ecore_main_loop_quit();
221
 * }
222
 *
223
 * static void
224
 * _test_error_cb(void *data, Eio_File *handler, int error)
225
 * {
226
 *    fprintf(stderr, "error: [%s]\n", strerror(error));
227
 *    ecore_main_loop_quit();
228
 * }
229
 *
230
 * int
231
 * main(int argc, char **argv)
232
 * {
233
 *    Eio_File *cp;
234
 *
235
 *    if (argc != 2)
236
 *      {
237
 * 	fprintf(stderr, "eio_ls directory\n");
238
 * 	return -1;
239
 *      }
240
 *
241
 *    ecore_init();
242
 *    eio_init();
243
 *
244
 *    cp = eio_file_ls(argv[1],
245
 *                     _test_filter_cb,
246
 *                     _test_main_cb,
247
 *                     _test_done_cb,
248
 *                     _test_error_cb,
249
 *                     NULL);
250
 *
251
 *    ecore_main_loop_begin();
252
 *
253
 *    eio_shutdown();
254
 *    ecore_shutdown();
255
 *
256
 *    return 0;
257
 * }
258
 *
259
 * @endcode
260
 */
261

262
/**
263
 * @page tutorial_monitor_add eio_monitor_add() tutorial
264
 *
265
 * To use eio_monitor_add(), you have to define callbacks
266
 * for events declared by eio.
267
 * Available events are :
268
 * - EIO_MONITOR_FILE_CREATED
269
 * - EIO_MONITOR_FILE_DELETED
270
 * - EIO_MONITOR_FILE_MODIFIED
271
 * - EIO_MONITOR_FILE_CLOSED
272
 * - EIO_MONITOR_DIRECTORY_CREATED
273
 * - EIO_MONITOR_DIRECTORY_DELETED
274
 * - EIO_MONITOR_DIRECTORY_CLOSED
275
 * - EIO_MONITOR_SELF_RENAME
276
 * - EIO_MONITOR_SELF_DELETED
277
 *
278
 * As nothing is worth an example, here it is :
279
 * @code
280
 * #include <Eina.h>
281
 * #include <Ecore.h>
282
 * #include <Eio.h>
283
 *
284
 * void file_modified(void *data, int type, void *event)
285
 * {
286
 *    const char *filename = (const char *)data;
287
 *    printf("file %s ", filename);
288
 *    if( type == EIO_MONITOR_FILE_MODIFIED )
289
 *       printf("is being modified");
290
 *    else if( type == EIO_MONITOR_FILE_CLOSED )
291
 *       printf("is no longer being modified");
292
 *    else printf("got unexpected changes");
293
 *    printf("\n");
294
 * }
295
 *
296
 * int main(int argc, char **argv) {
297
 *    Eio_Monitor *monitor  = NULL,
298
 *                *monitor2 = NULL;
299
 *    eio_init();
300
 *    const char *filename = eina_stringshare_add("/tmp/eio_notify_testfile");
301
 *
302
 *    monitor  = eio_monitor_add(filename);
303
 *    ecore_event_handler_add(EIO_MONITOR_FILE_MODIFIED, (Ecore_Event_Handler_Cb)file_modified, filename);
304
 *    ecore_event_handler_add(EIO_MONITOR_FILE_CLOSED, (Ecore_Event_Handler_Cb)file_modified, filename);
305
 *
306
 *    ecore_main_loop_begin();
307
 *    eio_shutdown();
308
 *    eina_stringshare_del(filename);
309
 * }
310
 * @endcode
311
 * Build the example doing :
312
 * @verbatim gcc -o tutorial_monitor_add tutorial_monitor_add.c `pkg-config --libs --cflags eio ecore ecore-file eina`
313
 * then create the file /tmp/eio_notify_testfile :
314
 * touch /tmp/eio_notify_testfile
315
 * and launch tutorial_monitor_add, and in another terminal, write into /tmp/eio_notify_testfile, doing for example :
316
 * echo "test" >> /tmp/eio_notify_testfile
317
 * @endverbatim
318
 */
319

320
/**
321
 * @page tutorial_dir_direct_ls eio_dir_direct_ls() tutorial
322
 *
323
 * @li The filter callback, which allow or not a file to be seen
324
 * by the main loop handler. This callback run in a separated thread.
325
 * It also take care of getting a stat buffer needed by the main callback
326
 * to display the file size.
327
 * @li The main callback, which receive in the main loop all the file
328
 * that are allowed by the filter. If you are updating a user interface
329
 * it make sense to delay the insertion a little, so you get a chance
330
 * to update the canvas for a bunch of file instead of one by one.
331
 * @li The end callback, which is called in the main loop when the
332
 * content of the directory has been correctly scanned and all the
333
 * file notified to the main loop.
334
 * @li The error callback, which is called if an error occurred or
335
 * if the listing was cancelled during it's run. You can then retrieve
336
 * the error type as an errno error.
337
 *
338
 * Here is a simple example that implement a stupidly simple recursive ls that display file size:
339
 *
340
 * @code
341
 * #include <Eina.h>
342
 * #include <Ecore.h>
343
 * #include <Eio.h>
344
 *
345
 * static Eina_Bool
346
 * _test_filter_cb(void *data, Eio_File *handler, Eina_File_Direct_Info *info)
347
 * {
348
 *    Eina_Stat *buffer;
349
 *    Eina_Bool isdir;
350
 *
351
 *    isdir = info->type == EINA_FILE_DIR;
352
 *
353
 *    buffer = malloc(sizeof (Eina_Stat));
354
 *    if (eina_file_statat(eio_file_container_get(handler), info, buffer))
355
 *      {
356
 *         free(buffer);
357
 *         return EINA_FALSE;
358
 *      }
359
 *
360
 *    if (!isdir && info->type == EINA_FILE_DIR)
361
 *      {
362
 *         struct stat st;
363
 *         if (lstat(info->path, &st) == 0)
364
 *           {
365
 *              if (S_ISLNK(st.st_mode))
366
 *                info->type = EINA_FILE_LNK;
367
 *           }
368
 *      }
369
 *
370
 *    eio_file_associate_direct_add(handler, "stat", buffer, free);
371
 *    fprintf(stdout, "ACCEPTING: %s\n", info->path);
372
 *    return EINA_TRUE;
373
 * }
374
 *
375
 * static void
376
 * _test_main_cb(void *data, Eio_File *handler, const Eina_File_Direct_Info *info)
377
 * {
378
 *    struct stat *buffer;
379
 *
380
 *    buffer = eio_file_associate_find(handler, "stat");
381
 *    fprintf(stdout, "PROCESS: %s of size %li\n", info->path, buffer->st_size);
382
 * }
383
 *
384
 * static void
385
 * _test_done_cb(void *data, Eio_File *handler)
386
 * {
387
 *    printf("ls done\n");
388
 *    ecore_main_loop_quit();
389
 * }
390
 *
391
 * static void
392
 * _test_error_cb(void *data, Eio_File *handler, int error)
393
 * {
394
 *    fprintf(stdout, "error: [%s]\n", strerror(error));
395
 *    ecore_main_loop_quit();
396
 * }
397
 *
398
 * int
399
 * main(int argc, char **argv)
400
 * {
401
 *    Eio_File *cp;
402
 *
403
 *    if (argc != 2)
404
 *      {
405
 * 	fprintf(stdout, "eio_ls directory\n");
406
 * 	return -1;
407
 *      }
408
 *
409
 *    ecore_init();
410
 *    eio_init();
411
 *
412
 *    cp = eio_dir_direct_ls(argv[1],
413
 * 			  _test_filter_cb,
414
 * 			  _test_main_cb,
415
 * 			  _test_done_cb,
416
 * 			  _test_error_cb,
417
 * 			  NULL);
418
 *
419
 *    ecore_main_loop_begin();
420
 *
421
 *    eio_shutdown();
422
 *    ecore_shutdown();
423
 *
424
 *    return 0;
425
 * }
426
 * @endcode
427
 */
428