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 30 extern "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 */ 44 typedef struct FAMConnection FAMConnection; 45 typedef FAMConnection *FAMConnectionPtr; 46 47 struct 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 */ 67 typedef struct FAMRequest FAMRequest; 68 typedef FAMRequest *FAMRequestPtr; 69 70 struct 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 */ 88 typedef 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 100 typedef 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 */ 113 extern int FAMOpen(FAMConnection* fc); 114 extern int FAMOpen2(FAMConnection* fc, const char* appName); 115 extern 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 123 extern int FAMMonitorDirectory (FAMConnection *fc, 124 const char *filename, 125 FAMRequest* fr, 126 void* userData); 127 extern int FAMMonitorFile (FAMConnection *fc, 128 const char *filename, 129 FAMRequest* fr, 130 void* userData); 131 extern int FAMMonitorDirectory2(FAMConnection *fc, 132 const char *filename, 133 FAMRequest* fr); 134 extern 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 */ 144 extern 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 */ 157 extern int FAMSuspendMonitor (FAMConnection *fc, 158 const FAMRequest *fr); 159 extern 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 */ 167 extern 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 */ 180 extern int FAMNextEvent (FAMConnection *fc, 181 FAMEvent *fe); 182 extern 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 */ 190 extern int FAMErrno; 191 192 /** 193 * FAMDebugLevel: 194 * 195 * Currently unimplemented as in the SGI FAM. Exists only for 196 * compatibility. 197 */ 198 extern 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 */ 224 extern 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 */ 236 extern int FAMNoExists (FAMConnection *fc); 237 238 #ifdef __cplusplus 239 } 240 #endif 241 242 #endif /* __GAMIN_FAM_H__ */ 243