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 //------------------------------------------------------------------------------ 00171 //------------------------------------------------------------------------------ 00172 00173 virtual int Forward(XrdOucErrInfo &Resp, const char *cmd, 00174 const char *arg1=0, const char *arg2=0, 00175 XrdOucEnv *Env1=0, XrdOucEnv *Env2=0) 00176 { 00177 (void)Resp; (void)cmd; (void)arg1; (void)arg2; (void)Env1; (void)Env2; 00178 return 0; 00179 } 00180 00181 //------------------------------------------------------------------------------ 00186 //------------------------------------------------------------------------------ 00187 00188 virtual int isRemote() {return myPersona == XrdCmsClient::amRemote;} 00189 00190 //------------------------------------------------------------------------------ 00217 //------------------------------------------------------------------------------ 00218 00219 virtual int Locate(XrdOucErrInfo &Resp, const char *path, int flags, 00220 XrdOucEnv *Info=0) = 0; 00221 00222 //------------------------------------------------------------------------------ 00228 // Return: A list of managers or null if none exist. 00229 //------------------------------------------------------------------------------ 00230 00231 virtual 00232 XrdOucTList *Managers() {return 0;} 00233 00234 //------------------------------------------------------------------------------ 00242 //------------------------------------------------------------------------------ 00243 00244 virtual int Prepare(XrdOucErrInfo &Resp, XrdSfsPrep &pargs, 00245 XrdOucEnv *Info=0) 00246 { 00247 (void)Resp; (void)pargs; (void)Info; 00248 return 0; 00249 } 00250 00251 //------------------------------------------------------------------------------ 00256 //------------------------------------------------------------------------------ 00257 00258 virtual void Removed(const char *path) { (void)path; } 00259 00260 //------------------------------------------------------------------------------ 00265 //------------------------------------------------------------------------------ 00266 00267 virtual void Resume (int Perm=1) { (void)Perm; } 00268 00269 //------------------------------------------------------------------------------ 00274 //------------------------------------------------------------------------------ 00275 00276 virtual void Suspend(int Perm=1) { (void)Perm; } 00277 00278 // The following set of functions can be used to control whether or not clients 00279 // are dispatched to this data server based on a virtual resource. The default 00280 // implementations do nothing. 00281 // 00282 //------------------------------------------------------------------------------ 00289 //------------------------------------------------------------------------------ 00290 00291 virtual int Resource(int n) { (void)n; return 0;} 00292 00293 //------------------------------------------------------------------------------ 00301 //------------------------------------------------------------------------------ 00302 00303 virtual int Reserve (int n=1) { (void)n; return 0;} 00304 00305 //------------------------------------------------------------------------------ 00314 //------------------------------------------------------------------------------ 00315 00316 virtual int Release (int n=1) { (void)n; return 0;} 00317 00318 //------------------------------------------------------------------------------ 00327 //------------------------------------------------------------------------------ 00328 00329 virtual int Space(XrdOucErrInfo &Resp, const char *path, 00330 XrdOucEnv *Info=0) = 0; 00331 00332 //------------------------------------------------------------------------------ 00341 //------------------------------------------------------------------------------ 00342 00343 virtual void Utilization(unsigned int util, bool alert=false) 00344 {(void)util; (void)alert;} 00345 00346 //------------------------------------------------------------------------------ 00350 //------------------------------------------------------------------------------ 00351 00352 enum Persona {amLocal, 00353 amRemote, 00354 amTarget 00355 }; 00356 00357 XrdCmsClient(Persona acting) : myPersona(acting) {} 00358 00359 //------------------------------------------------------------------------------ 00361 //------------------------------------------------------------------------------ 00362 00363 virtual ~XrdCmsClient() {} 00364 00365 protected: 00366 00367 Persona myPersona; 00368 }; 00369 00370 /******************************************************************************/ 00371 /* I n s t a n t i a t i o n M o d e F l a g s */ 00372 /******************************************************************************/ 00373 00378 namespace XrdCms 00379 { 00380 enum {IsProxy = 1, 00381 IsRedir = 2, 00382 IsTarget = 4, 00383 IsMeta = 8 00384 }; 00385 } 00386 00387 /******************************************************************************/ 00388 /* C M S C l i e n t I n s t a n t i a t o r */ 00389 /******************************************************************************/ 00390 00391 //------------------------------------------------------------------------------ 00423 //------------------------------------------------------------------------------ 00424 00425 class XrdOss; 00426 00427 typedef XrdCmsClient *(*XrdCmsClient_t)(XrdSysLogger *, int, int, XrdOss *); 00428 00435 //------------------------------------------------------------------------------ 00448 //------------------------------------------------------------------------------ 00449 00450 namespace XrdCms 00451 { 00452 XrdCmsClient *GetDefaultClient(XrdSysLogger *Logger, 00453 int opMode, 00454 int myPort 00455 ); 00456 } 00457 00458 //------------------------------------------------------------------------------ 00463 //------------------------------------------------------------------------------ 00464 00469 #endif