102 lines
3.3 KiB
Text
102 lines
3.3 KiB
Text
-----------------------------------
|
|
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.
|
|
|
|
Note that the design is only tested with inotify and may
|
|
need to change in the future to support more subsystems that may have some limitations.
|
|
|
|
-- Data structures
|
|
|
|
notify_event:
|
|
|
|
|
|
members:
|
|
|
|
type - the type of event (NOTIFY_* constants)
|
|
dir - non zero if event is triggered on a directory
|
|
path - path of the triggered event
|
|
filename - the filename event was triggered on
|
|
|
|
types:
|
|
|
|
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, note that 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.
|
|
|
|
-- 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 that 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));
|