Annotation of fam/include/fam.h, Revision 1.1.1.1
1.1 trev 1: /*
2: Copyright (C) 1999 Silicon Graphics, Inc. All Rights Reserved.
3:
4: This program is free software; you can redistribute it and/or modify it
5: under the terms of version 2.1 of the GNU Lesser General Public License
6: as published by the Free Software Foundation.
7:
8: This program is distributed in the hope that it would be useful, but
9: WITHOUT ANY WARRANTY; without even the implied warranty of
10: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. Further, any
11: license provided herein, whether implied or otherwise, is limited to
12: this program in accordance with the express provisions of the GNU Lesser
13: General Public License. Patent licenses, if any, provided herein do not
14: apply to combinations of this program with other product or programs, or
15: any other product whatsoever. This program is distributed without any
16: warranty that the program is delivered free of the rightful claim of any
17: third person by way of infringement or the like. See the GNU Lesser
18: General Public License for more details.
19:
20: You should have received a copy of the GNU General Public License along
21: with this program; if not, write the Free Software Foundation, Inc., 59
22: Temple Place - Suite 330, Boston MA 02111-1307, USA.
23: */
24:
25: #ifndef _FAM_
26: #define _FAM_
27: #ifdef __cplusplus
28: extern "C" {
29: #endif
30:
31:
32: /*****************************************************************************
33: *
34: * MODULE: Fam.h - File Alteration Monitor
35: *
36: * Fam allows applications to monitor files - receiving events when they
37: * change. The scheme is simple: Applications register which
38: * files/directories they are interested, and fam will notify the
39: * application when any of these files are changed.
40: *
41: *****************************************************************************/
42:
43: /* For NAME_MAX - maximum # of chars in a filename */
44: #include "limits.h"
45:
46:
47:
48:
49:
50: /*****************************************************************************
51: * DATA STRUCTURES
52: *
53: *
54: * FAMConnection Structure:
55: *
56: * The FAMConnection Data structure is created when opening a connection
57: * to fam. After that, it is passed into all fam procedures. This
58: * structure has all the information in it to talk to fam (Currently,
59: * the only data inside this structure is a file descriptor for
60: * the socket to fam).
61: *****************************************************************************/
62:
63: typedef struct FAMConnection {
64: int fd;
65: void *client;
66: } FAMConnection;
67:
68:
69: /*****************************************************************************
70: * To access the fd inside this structure (so the application writer can
71: * use select for fam events), the following macro is defined (this will
72: * allow us to change the implementation without users having to change
73: * their code):
74: *****************************************************************************/
75: #define FAMCONNECTION_GETFD(fc) ((fc)->fd)
76:
77:
78:
79:
80:
81: /*****************************************************************************
82: * FAMRequest Structure:
83: *
84: * Every time fam is called on to monitor a file, it passes back a
85: * FAMRequest structure. The main piece of data that this structure
86: * contans is a reqnum. This reqnum is guaranteed to be unique. When
87: * cancelling or suspending a monitor request, you must pass this
88: * data structure into FAMCancelMonitor or FAMSuspendMonitor to
89: * make sure that you are cancelling/suspending the correct request
90: * (You can monitor the same file/directory more than once).
91: *****************************************************************************/
92:
93: typedef struct FAMRequest {
94: int reqnum;
95: } FAMRequest;
96:
97:
98: /*****************************************************************************
99: * Once again, to access the reqnum inside this structure, use the
100: * following macro:
101: *****************************************************************************/
102: #define FAMREQUEST_GETREQNUM(fc) ((fc)->reqnum)
103:
104:
105:
106: /*****************************************************************************
107: * FAMEvent Structure:
108: *
109: * When a file/directory has been modified/deleted, fam will pass
110: * a FAMEvent structure to the application (through the callback
111: * in the FAMMonitorFile/Directory routines). This structure will
112: * describe what event happened to the file. The different events
113: * that can happen to a file are listed in the FAMCodes enum.
114: *****************************************************************************/
115: enum FAMCodes { FAMChanged=1, FAMDeleted=2, FAMStartExecuting=3,
116: FAMStopExecuting=4, FAMCreated=5, FAMMoved=6,
117: FAMAcknowledge=7, FAMExists=8, FAMEndExist=9 };
118:
119: typedef struct FAMEvent {
120: FAMConnection* fc; /* The fam connection that event occurred on */
121: FAMRequest fr; /* Corresponds to the FamRequest from monitor */
122: char *hostname; /* host and filename - pointer to which */
123: char filename[PATH_MAX]; /* file changed */
124: void *userdata; /* userdata associated with this monitor req. */
125: enum FAMCodes code; /* What happened to file - see above */
126: } FAMEvent;
127:
128:
129:
130:
131:
132: /*****************************************************************************
133: * ERROR HANDLING
134: *
135: * If an error occurs inside of libfam, a global named FAMErrno is set
136: * to a non-zero value and the routine that the error occurred in will
137: * return an error value (usually NULL). FAMErrlist is a global
138: * string array (indexed by FAMErrno) that describes the last error
139: * that happened;
140: *
141: * NOTE: currently FAMErrno and FamErrList are unused
142: *****************************************************************************/
143:
144: extern int FAMErrno;
145: extern char *FamErrlist[];
146:
147: /*
148: *[NOTE: Eventually, there will be a bunch of defines right here defining what
149: * errors can happen in using libfam ]
150: */
151:
152:
153:
154:
155:
156:
157: /*****************************************************************************
158: * PROCEDURES:
159: *
160: * FAMOpen, FAMClose
161: *
162: * The first step that an application has to do is open a connection to
163: * fam. This is done through the FAMOpen. FAMOpen returns a FAMConnection
164: * data structure which is passed to all fam procedures. FAMClose closes
165: * a fam connection.
166: *
167: * On error, FAMOpen will return NULL and FAMClose will return -1 (and
168: * FAMErrno will be set to the value of the error).
169: *****************************************************************************/
170:
171: extern int FAMOpen(FAMConnection* fc);
172: extern int FAMOpen2(FAMConnection* fc, const char* appName);
173: extern int FAMClose(FAMConnection* fc);
174:
175:
176:
177: /*****************************************************************************
178: * FAMMonitorDirectory, FAMMonitorFile
179: *
180: * These routines tell fam to start monitoring a file/directory. The
181: * parameters to this function are a FAMConnection (received from FAMOpen),
182: * a filename and a user data ptr. A FAMRequest structure is returned.
183: * When the file/directory changes, a fam event structure will be
184: * generated. The application can retrieve this structure by calling
185: * FAMNextEvent (see description under FAMNextEvent).
186: *
187: * The difference between these two routines is that FAMMonitorDirectory
188: * monitors any changes that happens to the contents of the directory
189: * (as well as the directory file itself) and FAMMonitorFile monitors
190: * only what happens to a particular file.
191: *
192: * On error FAMMonitorDirectory/File will return NULL (and FAMErrno will
193: * be set to the value of the error).
194: *****************************************************************************/
195:
196: extern int FAMMonitorDirectory(FAMConnection *fc,
197: const char *filename,
198: FAMRequest* fr,
199: void* userData);
200: extern int FAMMonitorFile(FAMConnection *fc,
201: const char *filename,
202: FAMRequest* fr,
203: void* userData);
204: extern int FAMMonitorCollection(FAMConnection *fc,
205: const char *filename,
206: FAMRequest* fr,
207: void* userData,
208: int depth,
209: const char* mask);
210:
211: extern int FAMMonitorDirectory2(FAMConnection *fc,
212: const char *filename,
213: FAMRequest* fr);
214: extern int FAMMonitorFile2(FAMConnection *fc,
215: const char *filename,
216: FAMRequest* fr);
217:
218:
219: /*****************************************************************************
220: * FAMSuspendMonitor, FAMResumeMonitor
221: *
222: * FAMSuspendMonitor enables applications to suspend
223: * receive events about files/directories that are changing. This can
224: * be useful in situations when an application is stowed and does not
225: * want to receive events until it is unstowed. FAMResumeMonitor
226: * signals fam to start monitoring the file/directory again.
227: *
228: * Both of these routines take a FAMConnection and a FAMRequest structure.
229: * The FAMRequest Structure is returned from the FAMMonitorFile/Directory
230: * routines.
231: *
232: * On error, FAMResume/SuspendMonitor will return -1 (and the global
233: * FAMErrno will be set to the value of the error).
234: *****************************************************************************/
235:
236: int FAMSuspendMonitor(FAMConnection *fc, const FAMRequest *fr);
237: int FAMResumeMonitor(FAMConnection *fc, const FAMRequest *fr);
238:
239:
240:
241:
242:
243:
244: /*****************************************************************************
245: * FAMCancelMonitor
246: *
247: * When an application is done monitoring a file/directory, it should
248: * call FAMCancelMonitor. This routine will signal fam not to watch
249: * this directory anymore. Once again, the FAMRequest structure is
250: * returned from the FAMMonitorFile/Directory routines.
251: *
252: * On error, FAMCancelMonitor will return -1 (and the global
253: * FAMErrno will be set to the value of the error). This routine will free
254: * the FAMRequest structure that is passed in.
255: *****************************************************************************/
256:
257: int FAMCancelMonitor(FAMConnection *fc, const FAMRequest *fr);
258:
259:
260:
261:
262: /*****************************************************************************
263: * FAMNextEvent, FAMPending
264: *
265: * FAMNextEvent will get the next fam event (file/directory change). If
266: * there are no fam events waiting, then FAMNextEvent will wait
267: * until a fam event has been received (from fam).
268: *
269: * FAMPending will return the number of fam events that are waiting.
270: * This routine always returns immediately to the caller.
271: *
272: * Essentially, there are two ways to for applications to receive fam
273: * events:
274: *
275: * 1. The "Polling" approach - Just call FAMPending periodically;
276: * like when the system is waiting for input. If FAMPending returns
277: * with a positive return value, then there are fam events waiting.
278: * Call FAMNextEvent to receive the events.
279: *
280: * 2. The "Select" approach - Use the fd returned from famOpen (in the
281: * FAMConnection structure) as one of the fds that the application
282: * selects on. When select returns saying that data is on the fam
283: * fd, call FAMNextEvent.
284: *
285: * FAMNextEvent reads any information that is on the fam socket,
286: * and returns it to the application (in the form of a FAMEvent).
287: *
288: * On error, FAMNextEvent and FAMPendingEvent will return -1 (and the global
289: * FAMErrno will be set to the value of the error).
290: *****************************************************************************/
291:
292: int FAMNextEvent(FAMConnection *fc, FAMEvent *fe);
293: int FAMPending(FAMConnection* fc);
294:
295:
296:
297:
298: /*****************************************************************************
299: * FAMDebugLevel
300: *
301: * This doesn't do anything.
302: *
303: *****************************************************************************/
304:
305: #define FAM_DEBUG_OFF 0
306: #define FAM_DEBUG_ON 1
307: #define FAM_DEBUG_VERBOSE 2
308:
309: int FAMDebugLevel(FAMConnection *fc, int debugLevel);
310:
311: #ifdef __cplusplus
312: }
313: #endif
314: #endif /* _FAM_ */
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to fam.h CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [Development] / fam / include