00001 #ifndef __CMS_CLIENT__ 00002 #define __CMS_CLIENT__ 00003 /******************************************************************************/ 00004 /* */ 00005 /* X r d C m s C l i e n t . h h */ 00006 /* */ 00007 /* (c) 2007 by the Board of Trustees of the Leland Stanford, Jr., University */ 00008 /* All Rights Reserved */ 00009 /* Produced by Andrew Hanushevsky for Stanford University under contract */ 00010 /* DE-AC02-76-SFO0515 with the Department of Energy */ 00011 /* */ 00012 /* This file is part of the XRootD software suite. */ 00013 /* */ 00014 /* XRootD is free software: you can redistribute it and/or modify it under */ 00015 /* the terms of the GNU Lesser General Public License as published by the */ 00016 /* Free Software Foundation, either version 3 of the License, or (at your */ 00017 /* option) any later version. */ 00018 /* */ 00019 /* XRootD is distributed in the hope that it will be useful, but WITHOUT */ 00020 /* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or */ 00021 /* FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public */ 00022 /* License for more details. */ 00023 /* */ 00024 /* You should have received a copy of the GNU Lesser General Public License */ 00025 /* along with XRootD in a file called COPYING.LESSER (LGPL license) and file */ 00026 /* COPYING (GPL license). If not, see <http://www.gnu.org/licenses/>. */ 00027 /* */ 00028 /* The copyright holder's institutional names and contributor's names may not */ 00029 /* be used to endorse or promote products derived from this software without */ 00030 /* specific prior written permission of the institution or contributor. */ 00031 /******************************************************************************/ 00032 00033 class XrdOucEnv; 00034 class XrdOucErrInfo; 00035 class XrdOucLogger; 00036 class XrdOucTList; 00037 struct XrdSfsPrep; 00038 class XrdSysLogger; 00039 00040 /******************************************************************************/ 00041 /* R e t u r n C o n v e n t i o n s */ 00042 /******************************************************************************/ 00043 00044 /* The following return conventions are use by Forward(), Locate(), & Prepare() 00045 Return Val Resp.errcode Resp.errtext 00046 --------- ------------------- -------- 00047 SFS_DATA Length of data. Data to be returned to caller. 00048 Action: Caller is provided data as successful response. 00049 00050 SFS_ERROR errno Error message text. 00051 Action: Caller given error response. 00052 00053 SFS_REDIRECT port (0 for default) Host name 00054 Action: Caller is redirected to <host>:<port> 00055 00056 SFS_STARTED Expected seconds n/a 00057 Action: Caller is told to wait for the "expected seconds" for a 00058 callback with the result. A callback must follow. 00059 See how to do callbacks below. 00060 00061 > 0 Wait time (= retval) Reason for wait 00062 Action: Caller told to wait retval seconds and retry request. 00063 00064 < 0 Error number Error message 00065 Action: Same as SFS_ERROR. You should *always* use SFS_ERROR. 00066 00067 = 0 Not applicable Not applicable (see below) 00068 Action: Forward() -> Return success; request forwarded. 00069 Locate() -> Redirection does not apply, operation 00070 should be done against local file system. 00071 Prepare() -> Return success, request submitted. 00072 */ 00073 00074 /******************************************************************************/ 00075 /* C a l l b a c k C o n v e n t i o n s */ 00076 /******************************************************************************/ 00077 00078 /* Most operations allow you to return SFS_STARTED to setup a callback. 00079 Callback information is contained in the XrdOucErrInfo object passed to 00080 Forward(), Locate() and Prepare(); the only methods that can apply callbacks. 00081 Use a callback when the operation will take at least several seconds so as 00082 to not occupy the calling thread for an excessive amount of time. 00083 00084 The actual mechanics of a callback are rather complicated because callbacks 00085 are subject to non-causaility if not correctly handled. In order to avoid 00086 such issues, you should use the XrdOucCallBack object (see XrdOucCallBack.hh) 00087 to test for applicability, setup, and effect a callback. 00088 00089 When calling back, you return the same information you would have returned 00090 had the execution path been synchronous. From that standpoint callbacks are 00091 relatively easy to understand. All you are doing is defering the return of 00092 information without occupying a thread while waiting to do so. 00093 00094 A typical scenario, using Resp and the original ErrInfo object, would be.... 00095 00096 XrdOucCallBack cbObject; // Must be persistent for the callback duration 00097 00098 if (XrdOucCallBack::Allowed(Resp)) 00099 {cbObject.Init(Resp); 00100 <hand off the cbObject to a thread that will perform the work> 00101 Resp.setErrCode(<seconds end-point should wait>); 00102 return SFS_STARTED; // Effect callback response! 00103 } 00104 00105 Once the thread doing the work has a result, send it via a callback as if 00106 the work was done in a synchronous fashion. 00107 00108 cbObject->Reply(retValue, ErrCodeValue, ErrTextValue); 00109 */ 00110 00111 /******************************************************************************/ 00112 /* C l a s s X r d C m s C l i e n t */ 00113 /******************************************************************************/ 00114 00115 class XrdCmsClient 00116 { 00117 public: 00118 00119 //------------------------------------------------------------------------------ 00126 //------------------------------------------------------------------------------ 00127 00128 virtual void Added(const char *path, int Pend=0) { (void)path; (void)Pend; } 00129 00130 //------------------------------------------------------------------------------ 00140 //------------------------------------------------------------------------------ 00141 00142 virtual int Configure(const char *cfn, char *Parms, XrdOucEnv *EnvInfo) = 0; 00143 00144 //------------------------------------------------------------------------------ 00170 //------------------------------------------------------------------------------ 00171 00172 virtual int Forward(XrdOucErrInfo &Resp, const char *cmd, 00173 const char *arg1=0, const char *arg2=0, 00174 XrdOucEnv *Env1=0, XrdOucEnv *Env2=0) 00175 { 00176 (void)Resp; (void)cmd; (void)arg1; (void)arg2; (void)Env1; (void)Env2; 00177 return 0; 00178 } 00179 00180 //------------------------------------------------------------------------------ 00185 //------------------------------------------------------------------------------ 00186 00187 virtual int isRemote() {return myPersona == XrdCmsClient::amRemote;} 00188 00189 //------------------------------------------------------------------------------ 00216 //------------------------------------------------------------------------------ 00217 00218 virtual int Locate(XrdOucErrInfo &Resp, const char *path, int flags, 00219 XrdOucEnv *Info=0) = 0; 00220 00221 //------------------------------------------------------------------------------ 00227 // Return: A list of managers or null if none exist. 00228 //------------------------------------------------------------------------------ 00229 00230 virtual 00231 XrdOucTList *Managers() {return 0;} 00232 00233 //------------------------------------------------------------------------------ 00241 //------------------------------------------------------------------------------ 00242 00243 virtual int Prepare(XrdOucErrInfo &Resp, XrdSfsPrep &pargs, 00244 XrdOucEnv *Info=0) 00245 { 00246 (void)Resp; (void)pargs; (void)Info; 00247 return 0; 00248 } 00249 00250 //------------------------------------------------------------------------------ 00255 //------------------------------------------------------------------------------ 00256 00257 virtual void Removed(const char *path) { (void)path; } 00258 00259 //------------------------------------------------------------------------------ 00264 //------------------------------------------------------------------------------ 00265 00266 virtual void Resume (int Perm=1) { (void)Perm; } 00267 00268 //------------------------------------------------------------------------------ 00273 //------------------------------------------------------------------------------ 00274 00275 virtual void Suspend(int Perm=1) { (void)Perm; } 00276 00277 // The following set of functions can be used to control whether or not clients 00278 // are dispatched to this data server based on a virtual resource. The default 00279 // implementations do nothing. 00280 // 00281 //------------------------------------------------------------------------------ 00288 //------------------------------------------------------------------------------ 00289 00290 virtual int Resource(int n) { (void)n; return 0;} 00291 00292 //------------------------------------------------------------------------------ 00300 //------------------------------------------------------------------------------ 00301 00302 virtual int Reserve (int n=1) { (void)n; return 0;} 00303 00304 //------------------------------------------------------------------------------ 00313 //------------------------------------------------------------------------------ 00314 00315 virtual int Release (int n=1) { (void)n; return 0;} 00316 00317 //------------------------------------------------------------------------------ 00326 //------------------------------------------------------------------------------ 00327 00328 virtual int Space(XrdOucErrInfo &Resp, const char *path, 00329 XrdOucEnv *Info=0) = 0; 00330 00331 //------------------------------------------------------------------------------ 00335 //------------------------------------------------------------------------------ 00336 00337 enum Persona {amLocal, 00338 amRemote, 00339 amTarget 00340 }; 00341 00342 XrdCmsClient(Persona acting) : myPersona(acting) {} 00343 00344 //------------------------------------------------------------------------------ 00346 //------------------------------------------------------------------------------ 00347 00348 virtual ~XrdCmsClient() {} 00349 00350 protected: 00351 00352 Persona myPersona; 00353 }; 00354 00355 /******************************************************************************/ 00356 /* I n s t a n t i a t i o n M o d e F l a g s */ 00357 /******************************************************************************/ 00358 00363 namespace XrdCms 00364 { 00365 enum {IsProxy = 1, 00366 IsRedir = 2, 00367 IsTarget = 4, 00368 IsMeta = 8 00369 }; 00370 } 00371 00372 /******************************************************************************/ 00373 /* C M S C l i e n t I n s t a n t i a t o r */ 00374 /******************************************************************************/ 00375 00376 //------------------------------------------------------------------------------ 00408 //------------------------------------------------------------------------------ 00409 00416 //------------------------------------------------------------------------------ 00429 //------------------------------------------------------------------------------ 00430 00431 namespace XrdCms 00432 { 00433 XrdCmsClient *GetDefaultClient(XrdSysLogger *Logger, 00434 int opMode, 00435 int myPort 00436 ); 00437 } 00438 00439 //------------------------------------------------------------------------------ 00444 //------------------------------------------------------------------------------ 00445 00450 #endif