1/*
2 Copyright (C) 1999 Silicon Graphics, Inc. All Rights Reserved.
3 Copyright (C) 2004 Red Hat, Inc.
4
5 This program is free software; you can redistribute it and/or modify it
6 under the terms of version 2.1 of the GNU Lesser General Public License
7 as published by the Free Software Foundation.
8
9 This program is distributed in the hope that it would be useful, but
10 WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. Further, any
12 license provided herein, whether implied or otherwise, is limited to
13 this program in accordance with the express provisions of the GNU Lesser
14 General Public License. Patent licenses, if any, provided herein do not
15 apply to combinations of this program with other product or programs, or
16 any other product whatsoever. This program is distributed without any
17 warranty that the program is delivered free of the rightful claim of any
18 third person by way of infringement or the like. See the GNU Lesser
19 General Public License for more details.
20
21 You should have received a copy of the GNU General Public License along
22 with this program; if not, write the Free Software Foundation, Inc., 59
23 Temple Place - Suite 330, Boston MA 02111-1307, USA.
24*/
25
26#ifndef __GAMIN_FAM_H__
27#define __GAMIN_FAM_H__ 1
28
29#ifdef __cplusplus
30extern "C" {
31#endif
32
33/* For NAME_MAX - maximum # of chars in a filename */
34#include <limits.h>
35
36/* PATH_MAX is not defined in limits.h on some platforms */
37#ifndef PATH_MAX
38#define PATH_MAX 4096
39#endif
40
41/**
42 * Structure associated to a FAM connection
43 */
44typedef struct FAMConnection FAMConnection;
45typedef FAMConnection *FAMConnectionPtr;
46
47struct FAMConnection {
48 int fd;
49 void *client;
50};
51
52/**
53 * FAMCONNECTION_GETFD:
54 *
55 * The only field available from the connection is the file
56 * descriptor and it should be accessed though the macro
57 */
58#define FAMCONNECTION_GETFD(fc) ((fc)->fd)
59
60/***
61 * FAMRequest:
62 *
63 * Structure associated to a FAM request
64 * it should not be public but unfortunately it is included int the
65 * FAMEvent structure.
66 */
67typedef struct FAMRequest FAMRequest;
68typedef FAMRequest *FAMRequestPtr;
69
70struct FAMRequest {
71 int reqnum;
72};
73
74/**
75 * FAMREQUEST_GETREQNUM:
76 *
77 * The only field available from the request is the request
78 * number and it should be accessed though the macro
79 */
80#define FAMREQUEST_GETREQNUM(fr) ((fr)->reqnum)
81
82/**
83 * FAMEvent Structure, it is a public structure provided back to the
84 * application, this part is part of the API/ABI.
85 * The FAMCodes indicates what kind of event happened that raised
86 * the callback at the application level.
87 */
88typedef enum FAMCodes {
89 FAMChanged=1,
90 FAMDeleted=2,
91 FAMStartExecuting=3,
92 FAMStopExecuting=4,
93 FAMCreated=5,
94 FAMMoved=6,
95 FAMAcknowledge=7,
96 FAMExists=8,
97 FAMEndExist=9
98} FAMCodes;
99
100typedef struct FAMEvent {
101 FAMConnection* fc; /* The fam connection that event occurred on */
102 FAMRequest fr; /* Corresponds to the FamRequest from monitor */
103 char *hostname; /* host and filename - pointer to which */
104 char filename[PATH_MAX]; /* file changed */
105 void *userdata; /* userdata associated with this monitor req. */
106 FAMCodes code; /* What happened to file - see above */
107} FAMEvent;
108
109/**
110 * FAMOpen/FAMClose:
111 * those are the functions used to connect and disconnect to the FAM service
112 */
113extern int FAMOpen(FAMConnection* fc);
114extern int FAMOpen2(FAMConnection* fc, const char* appName);
115extern int FAMClose(FAMConnection* fc);
116
117/**
118 * FAMMonitorDirectory/FAMMonitorFile/FAMMonitorCollection:
119 * Those functions are used to register monitoring requests for
120 * files or directories.
121 */
122
123extern int FAMMonitorDirectory (FAMConnection *fc,
124 const char *filename,
125 FAMRequest* fr,
126 void* userData);
127extern int FAMMonitorFile (FAMConnection *fc,
128 const char *filename,
129 FAMRequest* fr,
130 void* userData);
131extern int FAMMonitorDirectory2(FAMConnection *fc,
132 const char *filename,
133 FAMRequest* fr);
134extern int FAMMonitorFile2 (FAMConnection *fc,
135 const char *filename,
136 FAMRequest* fr);
137
138/**
139 * FAMMonitorCollection:
140 *
141 * Seems an attempt at changing the scope of the API,
142 * not supported, it's not described in the man pages anyway.
143 */
144extern int FAMMonitorCollection (FAMConnection *fc,
145 const char *filename,
146 FAMRequest* fr,
147 void* userData,
148 int depth,
149 const char* mask);
150
151/**
152 * FAMSuspendMonitor/FAMResumeMonitor:
153 *
154 * Those two functions are used to momentarily suspend and later resume
155 * a given monitoring request.
156 */
157extern int FAMSuspendMonitor (FAMConnection *fc,
158 const FAMRequest *fr);
159extern int FAMResumeMonitor (FAMConnection *fc,
160 const FAMRequest *fr);
161
162/**
163 * FAMCancelMonitor:
164 *
165 * This function is used to permanently stop a monitoring request.
166 */
167extern int FAMCancelMonitor (FAMConnection *fc,
168 const FAMRequest *fr);
169
170/**
171 * FAMNextEvent/FAMPending:
172 *
173 * FAMNextEvent will get the next fam event (file/directory change). If
174 * there are no fam events waiting, then FAMNextEvent will wait
175 * until a fam event has been received (from fam).
176 *
177 * FAMPending will return the number of fam events that are waiting.
178 * This routine always returns immediately to the caller.
179 */
180extern int FAMNextEvent (FAMConnection *fc,
181 FAMEvent *fe);
182extern int FAMPending (FAMConnection* fc);
183
184/**
185 * FAMErrno:
186 *
187 * If an error occurs within libgamin FAMErrno should be set to a
188 * non-zero value.
189 */
190extern int FAMErrno;
191
192/**
193 * FAMDebugLevel:
194 *
195 * Currently unimplemented as in the SGI FAM. Exists only for
196 * compatibility.
197 */
198extern int FAMDebugLevel (FAMConnection *fc,
199 int level);
200/**
201 * FAM_DEBUG_OFF:
202 * Unused macro, compatibility for SGI FAM API.
203 */
204#define FAM_DEBUG_OFF 0
205/**
206 * FAM_DEBUG_ON:
207 * Unused macro, compatibility for SGI FAM API.
208 */
209#define FAM_DEBUG_ON 1
210/**
211 * FAM_DEBUG_VERBOSE:
212 * Unused macro, compatibility for SGI FAM API.
213 */
214#define FAM_DEBUG_VERBOSE 2
215
216/**
217 * FamErrList:
218 *
219 * In case FAMErrno is set, FAMErrlist is a global string array indexed
220 * by FAMErrno that describes the last error that happened.
221 * NOTE: this is not a good mechanism, it's present here only to provide
222 * API and ABI compatibility with FAM.
223 */
224extern const char *FamErrlist[];
225
226/**
227 * FAMNoExists:
228 *
229 * Specific extension for the core FAM API where Exists event are not
230 * propagated on directory monitory listing startup. This speeds up
231 * watching large directories but can introduce a mismatch between the FAM
232 * view of the directory and the program own view.
233 *
234 * Returns 0 in case of success and -1 in case of error.
235 */
236extern int FAMNoExists (FAMConnection *fc);
237
238#ifdef __cplusplus
239}
240#endif
241
242#endif /* __GAMIN_FAM_H__ */
243