xrootd
XrdProtocol.hh
Go to the documentation of this file.
1 #ifndef __XrdProtocol_H__
2 #define __XrdProtocol_H__
3 /******************************************************************************/
4 /* */
5 /* X r d P r o t o c o l . h h */
6 /* */
7 /* (c) 2004 by the Board of Trustees of the Leland Stanford, Jr., University */
8 /* Produced by Andrew Hanushevsky for Stanford University under contract */
9 /* DE-AC02-76-SFO0515 with the Department of Energy */
10 /* */
11 /* This file is part of the XRootD software suite. */
12 /* */
13 /* XRootD is free software: you can redistribute it and/or modify it under */
14 /* the terms of the GNU Lesser General Public License as published by the */
15 /* Free Software Foundation, either version 3 of the License, or (at your */
16 /* option) any later version. */
17 /* */
18 /* XRootD is distributed in the hope that it will be useful, but WITHOUT */
19 /* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or */
20 /* FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public */
21 /* License for more details. */
22 /* */
23 /* You should have received a copy of the GNU Lesser General Public License */
24 /* along with XRootD in a file called COPYING.LESSER (LGPL license) and file */
25 /* COPYING (GPL license). If not, see <http://www.gnu.org/licenses/>. */
26 /* */
27 /* The copyright holder's institutional names and contributor's names may not */
28 /* be used to endorse or promote products derived from this software without */
29 /* specific prior written permission of the institution or contributor. */
30 /******************************************************************************/
31 
32 #include "Xrd/XrdJob.hh"
33 
34 /******************************************************************************/
35 /* X r d P r o t o c o l _ C o n f i g */
36 /******************************************************************************/
37 
38 // The following class is passed to the XrdgetProtocol() and XrdgetProtocolPort()
39 // functions to properly configure the protocol. This object is not stable and
40 // the protocol must copy out any values it desires to keep. It may copy the
41 // whole object using the supplied copy constructor.
42 
43 class XrdSysError;
44 union XrdNetSockAddr;
45 class XrdOucTrace;
46 class XrdBuffManager;
47 class XrdInet;
48 class XrdScheduler;
49 class XrdStats;
50 
51 struct sockaddr;
52 
54 {
55 public:
56 
57 // The following pointers may be copied; they are stable.
58 //
59 XrdSysError *eDest; // Stable -> Error Message/Logging Handler
60 XrdInet *NetTCP; // Stable -> Network Object (@ XrdgetProtocol)
61 XrdBuffManager *BPool; // Stable -> Buffer Pool Manager
62 XrdScheduler *Sched; // Stable -> System Scheduler
63 XrdStats *Stats; // Stable -> System Statistics (@ XrdgetProtocol)
64 void *Reserved; // Stable -> Previously, the thread manager
65 XrdOucTrace *Trace; // Stable -> Trace Information
66 
67 // The following information must be duplicated; it is unstable.
68 //
69 char *ConfigFN; // -> Configuration file
70 int Format; // Binary format of this server
71 int Port; // Port number
72 int WSize; // Window size for Port
73 const char *AdmPath; // Admin path
74 int AdmMode; // Admin path mode
75 const char *myInst; // Instance name
76 const char *myName; // Host name
77 const char *myProg; // Program name
78 union {
79 const
80 XrdNetSockAddr *urAddr; // Host Address (the actual structure/union)
81 const
82 struct sockaddr *myAddr; // Host address
83  };
84 int ConnMax; // Max connections
85 int readWait; // Max milliseconds to wait for data
86 int idleWait; // Max milliseconds connection may be idle
87 int argc; // Number of arguments
88 char **argv; // Argument array (prescreened)
89 char DebugON; // True if started with -d option
90 int WANPort; // Port prefered for WAN connections (0 if none)
91 int WANWSize; // Window size for the WANPort
92 int hailWait; // Max milliseconds to wait for data after accept
93 
97 };
98 
99 /******************************************************************************/
100 /* X r d P r o t o c o l */
101 /******************************************************************************/
102 
103 // This class is used by the Link object to process the input stream on a link.
104 // At least one protocol object exists per Link object. Specific protocols are
105 // derived from this pure abstract class since a link can use one of several
106 // protocols. Indeed, startup and shutdown are handled by specialized protocols.
107 
108 // System configuration obtains an instance of a protocol by calling
109 // XrdgetProtocol(), which must exist in the shared library.
110 // This instance is used as the base pointer for Alloc(), Configure(), and
111 // Match(). Unfortuantely, they cannot be static given the silly C++ rules.
112 
113 class XrdLink;
114 
115 class XrdProtocol : public XrdJob
116 {
117 public:
118 
119 // Match() is invoked when a new link is created and we are trying
120 // to determine if this protocol can handle the link. It must
121 // return a protocol object if it can and NULL (0), otherwise.
122 //
123 virtual XrdProtocol *Match(XrdLink *lp) = 0;
124 
125 // Process() is invoked when a link has data waiting to be read
126 //
127 virtual int Process(XrdLink *lp) = 0;
128 
129 // Recycle() is invoked when this object is no longer needed. The method is
130 // passed the number of seconds the protocol was connected to the
131 // link and the reason for the disconnection, if any.
132 //
133 virtual void Recycle(XrdLink *lp=0,int consec=0,const char *reason=0)=0;
134 
135 // Stats() is invoked when we need statistics about all instances of the
136 // protocol. If a buffer is supplied, it must return a null
137 // terminated string in the supplied buffer and the return value
138 // is the number of bytes placed in the buffer defined by C99 for
139 // snprintf(). If no buffer is supplied, the method should return
140 // the maximum number of characters that could have been returned.
141 // Regardless of the buffer value, if do_sync is true, the method
142 // should include any local statistics in the global data (if any)
143 // prior to performing any action.
144 //
145 virtual int Stats(char *buff, int blen, int do_sync=0) = 0;
146 
147  XrdProtocol(const char *jname): XrdJob(jname) {}
148 virtual ~XrdProtocol() {}
149 };
150 
151 /******************************************************************************/
152 /* X r d g e t P r o t o c o l */
153 /******************************************************************************/
154 
155 /* This extern "C" function must be defined in the shared library plug-in
156  implementing your protocol. It is called to obtain an instance of your
157  protocol. This allows protocols to live outside of the protocol driver
158  (i.e., to be loaded at run-time). The call is made after the call to
159  XrdgetProtocolPort() to determine the port to be used (see below) which
160  allows e network object (NetTCP) to be proerly defined and it's pointer
161  is passed in the XrdProtocol_Config object for your use.
162 
163  Required return values:
164  Success: Pointer to XrdProtocol object.
165  Failure: Null pointer (i.e. 0) which causes the program to exit.
166 
167 extern "C" // This is in a comment!
168 {
169  XrdProtocol *XrdgetProtocol(const char *protocol_name, char *parms,
170  XrdProtocol_Config *pi) {....}
171 }
172 */
173 
174 /******************************************************************************/
175 /* X r d g e t P r o t o c o l P o r t */
176 /******************************************************************************/
177 
178 /* This extern "C" function must be defined for statically linked protocols
179  but is optional for protocols defined as a shared library plug-in if the
180  rules determining which port number to use is sufficient for your protocol.
181  The function is called to obtain the actual port number to be used by the
182  the protocol. The default port number is noted in XrdProtocol_Config Port.
183  Initially, it has one of the fllowing values:
184  <0 -> No port was specified.
185  =0 -> An erbitrary port will be assigned.
186  >0 -> This port number was specified.
187 
188  XrdgetProtoclPort() must return:
189  <0 -> Failure is indicated and we terminate
190  =0 -> Use an arbitrary port (even if this equals Port)
191  >0 -> The returned port number must be used (even if it equals Port)
192 
193  When we finally call XrdgetProtocol(), the actual port number is indicated
194  in Port and the network object is defined in NetTCP and bound to the port.
195 
196  Final Caveats: 1. The network object (NetTCP) is not defined until
197  XrdgetProtocol() is called.
198 
199  2. The statistics object (Stats) is not defined until
200  XrdgetProtocol() is called.
201 
202  3. When the protocol is loaded from a shared library, you need
203  need not define XrdgetProtocolPort() if the standard port
204  determination scheme is sufficient.
205 
206 extern "C" // This is in a comment!
207 {
208  int XrdgetProtocolPort(const char *protocol_name, char *parms,
209  XrdProtocol_Config *pi) {....}
210 }
211 */
212 #endif
int idleWait
Definition: XrdProtocol.hh:86
const XrdNetSockAddr * urAddr
Definition: XrdProtocol.hh:80
virtual int Process(XrdLink *lp)=0
const char * myProg
Definition: XrdProtocol.hh:77
const char * myInst
Definition: XrdProtocol.hh:75
char ** argv
Definition: XrdProtocol.hh:88
int ConnMax
Definition: XrdProtocol.hh:84
const char * myName
Definition: XrdProtocol.hh:76
XrdProtocol(const char *jname)
Definition: XrdProtocol.hh:147
int WANPort
Definition: XrdProtocol.hh:90
Definition: XrdProtocol.hh:115
Definition: XrdBuffer.hh:73
Definition: XrdOucTrace.hh:35
Definition: XrdSysError.hh:87
virtual int Stats(char *buff, int blen, int do_sync=0)=0
int readWait
Definition: XrdProtocol.hh:85
Definition: XrdScheduler.hh:42
void * Reserved
Definition: XrdProtocol.hh:64
char * ConfigFN
Definition: XrdProtocol.hh:69
int AdmMode
Definition: XrdProtocol.hh:74
int Format
Definition: XrdProtocol.hh:70
XrdBuffManager * BPool
Definition: XrdProtocol.hh:61
XrdScheduler * Sched
Definition: XrdProtocol.hh:62
Definition: XrdProtocol.hh:53
int argc
Definition: XrdProtocol.hh:87
const struct sockaddr * myAddr
Definition: XrdProtocol.hh:81
virtual void Recycle(XrdLink *lp=0, int consec=0, const char *reason=0)=0
int hailWait
Definition: XrdProtocol.hh:92
XrdSysError * eDest
Definition: XrdProtocol.hh:59
XrdStats * Stats
Definition: XrdProtocol.hh:63
~XrdProtocol_Config()
Definition: XrdProtocol.hh:96
virtual ~XrdProtocol()
Definition: XrdProtocol.hh:148
int WANWSize
Definition: XrdProtocol.hh:91
XrdProtocol_Config()
Definition: XrdProtocol.hh:95
virtual XrdProtocol * Match(XrdLink *lp)=0
XrdInet * NetTCP
Definition: XrdProtocol.hh:60
int Port
Definition: XrdProtocol.hh:71
char DebugON
Definition: XrdProtocol.hh:89
XrdOucTrace * Trace
Definition: XrdProtocol.hh:65
Definition: XrdJob.hh:42
int WSize
Definition: XrdProtocol.hh:72
const char * AdmPath
Definition: XrdProtocol.hh:73