1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
|
/*
A small drop-in library for watching the filesystem for changes.
version 0.1, february, 2015
Copyright (C) 2015- Fredrik Kihlander
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
arising from the use of this software.
Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:
1. The origin of this software must not be misrepresented; you must not
claim that you wrote the original software. If you use this software
in a product, an acknowledgment in the product documentation would be
appreciated but is not required.
2. Altered source versions must be plainly marked as such, and must not be
misrepresented as being the original software.
3. This notice may not be removed or altered from any source distribution.
Fredrik Kihlander
*/
#ifndef FSWATCHER_H_INCLUDED
#define FSWATCHER_H_INCLUDED
#include <stddef.h> // for size_t
#ifdef __cplusplus
extern "C" {
#endif // __cplusplus
/**
* A note on paths. All paths in and out of the library is utf8 encoded.
*/
/**
*
*/
enum fswatcher_create_flags
{
FSWATCHER_CREATE_BLOCKING = (1 << 1), ///< calls to fswatcher_poll should block until 1 or more events arrive.
FSWATCHER_CREATE_RECURSIVE = (1 << 2), ///< the directory watch should recursively add all sub-directories to watch.
FSWATCHER_CREATE_DEFAULT = FSWATCHER_CREATE_RECURSIVE
};
/**
*
*/
enum fswatcher_event_type
{
FSWATCHER_EVENT_CREATE = (1 << 1), ///< file in "src" was just created.
FSWATCHER_EVENT_REMOVE = (1 << 2), ///< file in "src" was just removed.
FSWATCHER_EVENT_MODIFY = (1 << 3), ///< file in "src" was just modified.
FSWATCHER_EVENT_MOVE = (1 << 4), ///< file was moved from "src" to "dst", if "src" or "dst" is 0x0 it indicates that the path was outside the current watch.
FSWATCHER_EVENT_ALL = FSWATCHER_EVENT_CREATE |
FSWATCHER_EVENT_REMOVE |
FSWATCHER_EVENT_MODIFY |
FSWATCHER_EVENT_MOVE ,
FSWATCHER_EVENT_BUFFER_OVERFLOW ///< doc me
};
/**
*
*/
typedef struct fswatcher* fswatcher_t;
/**
* Allocator interface used by fswatcher, read function-documentation for allocation pattern descriptions.
*
* @example:
*
* struct my_stack_allocator
* {
* fswatcher_allocator alloc;
*
* size_t allocated;
* char buffer[ 4096 ];
* };
*
* void* my_stack_realloc( fswatcher_allocator* allocator, void* ptr, size_t old_size, size_t new_size )
* {
* my_stack_allocator* salloc = (my_stack_allocator*)allocator;
* if( salloc->allocated + new_size > 4096 )
* return 0x0;
* return salloc->buffer[ salloc->allocated += new_size ];
* }
*
* void run_poll( fswatcher_t w, fswatcher_event_handler* h )
* {
* my_stack_allocator salloc = { { my_stack_realloc, 0x0 }, 0 },
* fswatcher_poll( w, h, &salloc.alloc );
* }
*/
struct fswatcher_allocator
{
/**
* realloc function, should work in the same way as realloc().
*
* @param allocator struct holding the function pointer.
* @param ptr to memory to realloc or 0x0 if not allocated.
* @param old_size size of allocation if ptr != 0x0.
* @param new_size requested allocation size.
*
* @return pointer to newly allocated memory or 0x0 on failure.
*/
void* ( *realloc )( fswatcher_allocator* allocator, void* ptr, size_t old_size, size_t new_size );
/**
* free function, should be used to free memory allocated with realloc().
* This function can be set to 0x0 if no free call is needed.
*
* @param allocator struct holding the function pointer.
* @param ptr pointer to memory to free.
*/
void ( *free )( fswatcher_allocator* allocator, void* ptr );
};
/**
* Struct used together with fswatcher_poll() to fetch events from fswatcher.
*
* @example
*
* struct my_fsevent_handler
* {
* fswatcher_event_handler eh;
*
* // ... some userdata here ...
* };
*
* static bool my_fsevent_func( fswatcher_event_handler* handler, fswatcher_event_type evtype, const char* src, const char* dst )
* {
* my_fsevent_handler* h = (my_fsevent_handler*)handler;
*
* // ... do stuff in handler ...
* }
*
* void poll_it( fswatcher_t w )
* {
* my_fsevent_handler h = { my_fsevent_func };
* fswatcher_poll( w, &h.eh, 0x0 );
* }
*/
struct fswatcher_event_handler
{
/**
* Callback used per event that is queued on the fswatcher.
*
* @param callback called per event.
* @param evtype type of event received.
* @param src path to source file, can be 0x0 if event has no source. ( this can happen for example on a move if file was moved from non-watched folder to watched folder. )
* @param dst path to destination file, can be 0x0 if event has no destination. ( this can happen for example on a move if file was moved from watched folder to non-watched folder. )
*
* @return false if poll should end.
*/
bool ( *callback )( fswatcher_event_handler* handler, fswatcher_event_type evtype, const char* src, const char* dst );
};
/**
* Create a new fswatcher watching a specific directory and potential sub-directories.
*
* @note The allocator passed to this function will all need to persist during the life-time of the fswatcher and might need reallocation.
*
* @param flags ...
* @param types events to watch and get events for.
* @param watch_dir directory to watch.
* @param allocator to use for this fswatcher or 0x0 to use malloc/free
*/
fswatcher_t fswatcher_create( fswatcher_create_flags flags, fswatcher_event_type types, const char* watch_dir, fswatcher_allocator* allocator );
/**
* Destroy fswatcher_t and free all its used resources.
*
* @param watcher to destroy.
*/
void fswatcher_destroy( fswatcher_t watcher );
/**
* Poll an fswatcher for new events, this call is blocking if FSWATCHER_CREATE_BLOCKING was passed to fswatcher_create().
*
* @note This function might allocate data in 2 instances, first if an event was detected that a directory was created,
* in that case the allocator passed to fswatcher_poll() will be used.
* The more usual case is the src/dst parameters to the callback function. These allocations will only be alive during
* the callback and can thusly be allocated with a stack-allocator or other temporary allocator.
*
* @param watcher to poll.
* @param handler to poll events with.
* @param allocator used to allocate temporary data during poll or 0x0 to use malloc/free.
*/
void fswatcher_poll( fswatcher_t watcher, fswatcher_event_handler* handler, fswatcher_allocator* allocator );
#ifdef __cplusplus
}
#endif // __cplusplus
#endif // FSWATCHER_H_INCLUDED
|
