Changed the documentation structure

2011-01-22 14:37:14 +01:00 · 2011-01-22 14:37:14 +01:00 · 3c0e4e6470
commit 3c0e4e6470
parent 8be6c69e97
13 changed files with 34 additions and 8 deletions
--- a/docs/technical/api-notify.txt
+++ b/docs/technical/api-notify.txt
@ -0,0 +1,106 @@
+Notify API
+----------
+
+This API is here to provide an abstraction to the underlaying low-level filesystem notification mechanism
+to try to make applications portable but also throw away detail from client-code.
+
+IMPORTANT: The design is only tested with inotify and the API may
+need to change in the future to support more subsystems that may have some limitations. 
+
+Data structures
+~~~~~~~~~~~~~~~
+
+* `notify_event`
+
+Holds information about one perticular event
+
+`type`::
+    The type of event, can hold one and only one of these flags
+
+NOTIFY_UNKNOWN;;
+    Events that do occur but can't be mapped to a more relevant type ends up being marked as
+    an unknown event, you can most likely only tell that "something" happened on
+    the given path (so unless your application wants to know that "something" happened, ignore this)
+
+NOTIFY_CREATE;;
+    A file/directory was created on the filesystem.
+
+NOTIFY_DELETE;;
+    A file/directory was deleted from the filesystem
+
+IMPORTANT: It is possible to get just one event for a directory that has files/subdirectorys,
+    so when getting this event you should always make sure your actions does handle the possible recursion.
+
+NOTIFY_MOVE_FROM;;
+NOTIFY_MOVE_TO;;
+    As of the time of writing no implementation support these types and uses create/delete types instead.
+    A drastic design change to the `notify_event` structure should be made before this type of events
+    will be usefull.
+
+`dir`::
+    non zero if event is triggered on a directory
+    
+`path`::
+    path of the triggered event
+    
+`filename`::
+    the filename the event was triggered on
+
+Functions
+~~~~~~~~~
+
+`notify_init()`::
+
+    instantiate notify. making it ready for further `notify_*` calls. +
+    returns a positive number if everything went OK. +
+    returns zero if notify has already been instantiated. +
+    And returns -1 and sets `errno` if an error occur.
+
+`notify_add_watch()`::
+
+    tells notify to start listening on 'path'. +
+    one create event will be genereted for every file under 'path' +
+    and all subdirectorys will be watched. +
+    returns 1 if everything went ok and returns -1 and sets `errno` if an error occure.
+
+`notify_rm_watch()`::
+
+    'path' will be removed from notify and all events triggered on this path
+    will be ignored from now on.
+
+`notify_read()`::
+
+    fetches and returns one event from the subsystem. A `NULL` pointer is returned if no events
+    is available at the given moment.
+
+NOTE: The implementation may read and process the data from whatever source it has
+in this function, the only requirement is that the function never blocks.
+
+`notify_exit()`::
+
+    free's all memory associated with notify and other cleanup routines.
+
+`notify_event_new()`::
+
+    allocates memory and initilize values for a new `notify_event` structure
+
+`notify_event_clear()`::
+
+    free's all the memory and sets values back to default.
+
+`notify_event_set_*()`::
+
+    use these functions to set members of the `notify_event` structure.
+    
+`notify_event_del()`::
+
+    free's all the memory from the `notify_event` structure.
+
+`notify_event_typetostr()`::
+
+returns a string representation of a event's type. the pointer should +
+not be free'ed, so its safe to be used like this:
+
+----
+printf("type: %s\n", notify_event_typetostr(event));
+----