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) {} 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) {return 0;} 00175 00176 //------------------------------------------------------------------------------ 00181 //------------------------------------------------------------------------------ 00182 00183 virtual int isRemote() {return myPersona == XrdCmsClient::amRemote;} 00184 00185 //------------------------------------------------------------------------------ 00212 //------------------------------------------------------------------------------ 00213 00214 virtual int Locate(XrdOucErrInfo &Resp, const char *path, int flags, 00215 XrdOucEnv *Info=0) = 0; 00216 00217 //------------------------------------------------------------------------------ 00223 // Return: A list of managers or null if none exist. 00224 //------------------------------------------------------------------------------ 00225 00226 virtual 00227 XrdOucTList *Managers() {return 0;} 00228 00229 //------------------------------------------------------------------------------ 00237 //------------------------------------------------------------------------------ 00238 00239 virtual int Prepare(XrdOucErrInfo &Resp, XrdSfsPrep &pargs, 00240 XrdOucEnv *Info=0) {return 0;} 00241 00242 //------------------------------------------------------------------------------ 00247 //------------------------------------------------------------------------------ 00248 00249 virtual void Removed(const char *path) {} 00250 00251 //------------------------------------------------------------------------------ 00256 //------------------------------------------------------------------------------ 00257 00258 virtual void Resume (int Perm=1) {} 00259 00260 //------------------------------------------------------------------------------ 00265 //------------------------------------------------------------------------------ 00266 00267 virtual void Suspend(int Perm=1) {} 00268 00269 // The following set of functions can be used to control whether or not clients 00270 // are dispatched to this data server based on a virtual resource. The default 00271 // implementations do nothing. 00272 // 00273 //------------------------------------------------------------------------------ 00280 //------------------------------------------------------------------------------ 00281 00282 virtual int Resource(int n) {return 0;} 00283 00284 //------------------------------------------------------------------------------ 00292 //------------------------------------------------------------------------------ 00293 00294 virtual int Reserve (int n=1) {return 0;} 00295 00296 //------------------------------------------------------------------------------ 00305 //------------------------------------------------------------------------------ 00306 00307 virtual int Release (int n=1) {return 0;} 00308 00309 //------------------------------------------------------------------------------ 00318 //------------------------------------------------------------------------------ 00319 00320 virtual int Space(XrdOucErrInfo &Resp, const char *path, 00321 XrdOucEnv *Info=0) = 0; 00322 00323 //------------------------------------------------------------------------------ 00327 //------------------------------------------------------------------------------ 00328 00329 enum Persona {amLocal, 00330 amRemote, 00331 amTarget 00332 }; 00333 00334 XrdCmsClient(Persona acting) : myPersona(acting) {} 00335 00336 //------------------------------------------------------------------------------ 00338 //------------------------------------------------------------------------------ 00339 00340 virtual ~XrdCmsClient() {} 00341 00342 protected: 00343 00344 Persona myPersona; 00345 }; 00346 00347 /******************************************************************************/ 00348 /* I n s t a n t i a t i o n M o d e F l a g s */ 00349 /******************************************************************************/ 00350 00355 namespace XrdCms 00356 { 00357 enum {IsProxy = 1, 00358 IsRedir = 2, 00359 IsTarget = 4, 00360 IsMeta = 8 00361 }; 00362 } 00363 00364 /******************************************************************************/ 00365 /* C M S C l i e n t I n s t a n t i a t o r */ 00366 /******************************************************************************/ 00367 00368 //------------------------------------------------------------------------------ 00400 //------------------------------------------------------------------------------ 00401 00408 //------------------------------------------------------------------------------ 00421 //------------------------------------------------------------------------------ 00422 00423 namespace XrdCms 00424 { 00425 XrdCmsClient *GetDefaultClient(XrdSysLogger *Logger, 00426 int opMode, 00427 int myPort 00428 ); 00429 } 00430 00431 //------------------------------------------------------------------------------ 00437 //------------------------------------------------------------------------------ 00438 00443 #endif