XrdCmsClient.hh

Go to the documentation of this file.
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 
00410 class XrdOss;
00411 
00412 typedef XrdCmsClient *(*XrdCmsClient_t)(XrdSysLogger *, int, int, XrdOss *);
00413 
00420 //------------------------------------------------------------------------------
00433 //------------------------------------------------------------------------------
00434 
00435 namespace XrdCms
00436 {
00437           XrdCmsClient *GetDefaultClient(XrdSysLogger *Logger,
00438                                          int           opMode,
00439                                          int           myPort
00440                                         );
00441 }
00442 
00443 //------------------------------------------------------------------------------
00448 //------------------------------------------------------------------------------
00449 
00454 #endif

Generated on 12 Dec 2014 for xrootd by  doxygen 1.4.7