xrootd
XrdCmsClient.hh
Go to the documentation of this file.
1 #ifndef __CMS_CLIENT__
2 #define __CMS_CLIENT__
3 /******************************************************************************/
4 /* */
5 /* X r d C m s C l i e n t . h h */
6 /* */
7 /* (c) 2007 by the Board of Trustees of the Leland Stanford, Jr., University */
8 /* All Rights Reserved */
9 /* Produced by Andrew Hanushevsky for Stanford University under contract */
10 /* DE-AC02-76-SFO0515 with the Department of Energy */
11 /* */
12 /* This file is part of the XRootD software suite. */
13 /* */
14 /* XRootD is free software: you can redistribute it and/or modify it under */
15 /* the terms of the GNU Lesser General Public License as published by the */
16 /* Free Software Foundation, either version 3 of the License, or (at your */
17 /* option) any later version. */
18 /* */
19 /* XRootD is distributed in the hope that it will be useful, but WITHOUT */
20 /* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or */
21 /* FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public */
22 /* License for more details. */
23 /* */
24 /* You should have received a copy of the GNU Lesser General Public License */
25 /* along with XRootD in a file called COPYING.LESSER (LGPL license) and file */
26 /* COPYING (GPL license). If not, see <http://www.gnu.org/licenses/>. */
27 /* */
28 /* The copyright holder's institutional names and contributor's names may not */
29 /* be used to endorse or promote products derived from this software without */
30 /* specific prior written permission of the institution or contributor. */
31 /******************************************************************************/
32 
33 class XrdOucEnv;
34 class XrdOucErrInfo;
35 class XrdOucLogger;
36 class XrdOucTList;
37 struct XrdSfsPrep;
38 class XrdSysLogger;
39 
40 /******************************************************************************/
41 /* R e t u r n C o n v e n t i o n s */
42 /******************************************************************************/
43 
44 /* The following return conventions are use by Forward(), Locate(), & Prepare()
45  Return Val Resp.errcode Resp.errtext
46  --------- ------------------- --------
47  SFS_DATA Length of data. Data to be returned to caller.
48  Action: Caller is provided data as successful response.
49 
50  SFS_ERROR errno Error message text.
51  Action: Caller given error response.
52 
53  SFS_REDIRECT port (0 for default) Host name
54  Action: Caller is redirected to <host>:<port>
55 
56  SFS_STARTED Expected seconds n/a
57  Action: Caller is told to wait for the "expected seconds" for a
58  callback with the result. A callback must follow.
59  See how to do callbacks below.
60 
61  > 0 Wait time (= retval) Reason for wait
62  Action: Caller told to wait retval seconds and retry request.
63 
64  < 0 Error number Error message
65  Action: Same as SFS_ERROR. You should *always* use SFS_ERROR.
66 
67  = 0 Not applicable Not applicable (see below)
68  Action: Forward() -> Return success; request forwarded.
69  Locate() -> Redirection does not apply, operation
70  should be done against local file system.
71  Prepare() -> Return success, request submitted.
72 */
73 
74 /******************************************************************************/
75 /* C a l l b a c k C o n v e n t i o n s */
76 /******************************************************************************/
77 
78 /* Most operations allow you to return SFS_STARTED to setup a callback.
79  Callback information is contained in the XrdOucErrInfo object passed to
80  Forward(), Locate() and Prepare(); the only methods that can apply callbacks.
81  Use a callback when the operation will take at least several seconds so as
82  to not occupy the calling thread for an excessive amount of time.
83 
84  The actual mechanics of a callback are rather complicated because callbacks
85  are subject to non-causaility if not correctly handled. In order to avoid
86  such issues, you should use the XrdOucCallBack object (see XrdOucCallBack.hh)
87  to test for applicability, setup, and effect a callback.
88 
89  When calling back, you return the same information you would have returned
90  had the execution path been synchronous. From that standpoint callbacks are
91  relatively easy to understand. All you are doing is defering the return of
92  information without occupying a thread while waiting to do so.
93 
94  A typical scenario, using Resp and the original ErrInfo object, would be....
95 
96  XrdOucCallBack cbObject; // Must be persistent for the callback duration
97 
98  if (XrdOucCallBack::Allowed(Resp))
99  {cbObject.Init(Resp);
100  <hand off the cbObject to a thread that will perform the work>
101  Resp.setErrCode(<seconds end-point should wait>);
102  return SFS_STARTED; // Effect callback response!
103  }
104 
105  Once the thread doing the work has a result, send it via a callback as if
106  the work was done in a synchronous fashion.
107 
108  cbObject->Reply(retValue, ErrCodeValue, ErrTextValue);
109 */
110 
111 /******************************************************************************/
112 /* C l a s s X r d C m s C l i e n t */
113 /******************************************************************************/
114 
116 {
117 public:
118 
119 //------------------------------------------------------------------------------
126 //------------------------------------------------------------------------------
127 
128 virtual void Added(const char *path, int Pend=0) {}
129 
130 //------------------------------------------------------------------------------
140 //------------------------------------------------------------------------------
141 
142 virtual int Configure(const char *cfn, char *Parms, XrdOucEnv *EnvInfo) = 0;
143 
144 //------------------------------------------------------------------------------
170 //------------------------------------------------------------------------------
171 
172 virtual int Forward(XrdOucErrInfo &Resp, const char *cmd,
173  const char *arg1=0, const char *arg2=0,
174  XrdOucEnv *Env1=0, XrdOucEnv *Env2=0) {return 0;}
175 
176 //------------------------------------------------------------------------------
181 //------------------------------------------------------------------------------
182 
183 virtual int isRemote() {return myPersona == XrdCmsClient::amRemote;}
184 
185 //------------------------------------------------------------------------------
212 //------------------------------------------------------------------------------
213 
214 virtual int Locate(XrdOucErrInfo &Resp, const char *path, int flags,
215  XrdOucEnv *Info=0) = 0;
216 
217 //------------------------------------------------------------------------------
223 // Return: A list of managers or null if none exist.
224 //------------------------------------------------------------------------------
225 
226 virtual
227 XrdOucTList *Managers() {return 0;}
228 
229 //------------------------------------------------------------------------------
237 //------------------------------------------------------------------------------
238 
239 virtual int Prepare(XrdOucErrInfo &Resp, XrdSfsPrep &pargs,
240  XrdOucEnv *Info=0) {return 0;}
241 
242 //------------------------------------------------------------------------------
247 //------------------------------------------------------------------------------
248 
249 virtual void Removed(const char *path) {}
250 
251 //------------------------------------------------------------------------------
256 //------------------------------------------------------------------------------
257 
258 virtual void Resume (int Perm=1) {}
259 
260 //------------------------------------------------------------------------------
265 //------------------------------------------------------------------------------
266 
267 virtual void Suspend(int Perm=1) {}
268 
269 // The following set of functions can be used to control whether or not clients
270 // are dispatched to this data server based on a virtual resource. The default
271 // implementations do nothing.
272 //
273 //------------------------------------------------------------------------------
280 //------------------------------------------------------------------------------
281 
282 virtual int Resource(int n) {return 0;}
283 
284 //------------------------------------------------------------------------------
292 //------------------------------------------------------------------------------
293 
294 virtual int Reserve (int n=1) {return 0;}
295 
296 //------------------------------------------------------------------------------
305 //------------------------------------------------------------------------------
306 
307 virtual int Release (int n=1) {return 0;}
308 
309 //------------------------------------------------------------------------------
318 //------------------------------------------------------------------------------
319 
320 virtual int Space(XrdOucErrInfo &Resp, const char *path,
321  XrdOucEnv *Info=0) = 0;
322 
323 //------------------------------------------------------------------------------
327 //------------------------------------------------------------------------------
328 
329  enum Persona {amLocal,
332  };
333 
334  XrdCmsClient(Persona acting) : myPersona(acting) {}
335 
336 //------------------------------------------------------------------------------
338 //------------------------------------------------------------------------------
339 
340 virtual ~XrdCmsClient() {}
341 
342 protected:
343 
345 };
346 
347 /******************************************************************************/
348 /* I n s t a n t i a t i o n M o d e F l a g s */
349 /******************************************************************************/
350 
355 namespace XrdCms
356 {
357 enum {IsProxy = 1,
358  IsRedir = 2,
359  IsTarget = 4,
360  IsMeta = 8
361  };
362 }
363 
364 /******************************************************************************/
365 /* C M S C l i e n t I n s t a n t i a t o r */
366 /******************************************************************************/
367 
368 //------------------------------------------------------------------------------
400 //------------------------------------------------------------------------------
401 
408 //------------------------------------------------------------------------------
421 //------------------------------------------------------------------------------
422 
423 namespace XrdCms
424 {
426  int opMode,
427  int myPort
428  );
429 }
430 
431 //------------------------------------------------------------------------------
437 //------------------------------------------------------------------------------
438 
443 #endif