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-18 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 XrdOucEnv;
46 class XrdOucString;
47 class XrdBuffManager;
48 class XrdInet;
49 class XrdScheduler;
50 class XrdStats;
51 class XrdTlsContext;
52 
53 struct sockaddr;
54 
56 {
57 public:
58 
59 // The following pointers may be copied; they are stable.
60 //
61 XrdSysError *eDest; // Stable -> Error Message/Logging Handler
62 XrdInet *NetTCP; // Stable -> Network Object (@ XrdgetProtocol)
63 XrdBuffManager *BPool; // Stable -> Buffer Pool Manager
64 XrdScheduler *Sched; // Stable -> System Scheduler
65 XrdStats *Stats; // Stable -> System Statistics (@ XrdgetProtocol)
66 XrdOucEnv *theEnv; // Stable -> Additional environmental information
67 void *rsvd0;
68 
69 // The following information must be duplicated; it is unstable.
70 //
71 char *ConfigFN; // -> Configuration file
72 int Format; // Binary format of this server
73 int Port; // Port number
74 int WSize; // Window size for Port
75 int rsvd1;
76 const char *AdmPath; // Admin path
77 int AdmMode; // Admin path mode
79 static const int admPSet = 0x00000001; // The adminppath was set via cli
80 
81 const char *myInst; // Instance name
82 const char *myName; // Host name
83 const char *myProg; // Program name
84 union {
85 const
86 XrdNetSockAddr *urAddr; // Host Address (the actual structure/union)
87 const
88 struct sockaddr *myAddr; // Host address
89  };
90 int ConnMax; // Max connections
91 int readWait; // Max milliseconds to wait for data
92 int idleWait; // Max milliseconds connection may be idle
93 int argc; // Number of arguments
94 char **argv; // Argument array (prescreened)
95 char DebugON; // True if started with -d option
96 char rsvd3[7];
97 int hailWait; // Max milliseconds to wait for data after accept
98 int tlsPort; // Default TLS port (0 if not specified)
99 XrdTlsContext *tlsCtx; // Stable -> TLS Context (0 if not initialized)
100 XrdOucString *totalCF; // Stable -> total config after full init
101 
104  {memset(rsvd3, 0, sizeof(rsvd3));}
106 };
107 
108 /******************************************************************************/
109 /* X r d P r o t o c o l */
110 /******************************************************************************/
111 
112 // This class is used by the Link object to process the input stream on a link.
113 // At least one protocol object exists per Link object. Specific protocols are
114 // derived from this pure abstract class since a link can use one of several
115 // protocols. Indeed, startup and shutdown are handled by specialized protocols.
116 
117 // System configuration obtains an instance of a protocol by calling
118 // XrdgetProtocol(), which must exist in the shared library.
119 // This instance is used as the base pointer for Alloc(), Configure(), and
120 // Match(). Unfortuantely, they cannot be static given the silly C++ rules.
121 
122 class XrdLink;
123 
124 class XrdProtocol : public XrdJob
125 {
126 public:
127 
128 // Match() is invoked when a new link is created and we are trying
129 // to determine if this protocol can handle the link. It must
130 // return a protocol object if it can and NULL (0), otherwise.
131 //
132 virtual XrdProtocol *Match(XrdLink *lp) = 0;
133 
134 // Process() is invoked when a link has data waiting to be read
135 //
136 virtual int Process(XrdLink *lp) = 0;
137 
138 // Recycle() is invoked when this object is no longer needed. The method is
139 // passed the number of seconds the protocol was connected to the
140 // link and the reason for the disconnection, if any.
141 //
142 virtual void Recycle(XrdLink *lp=0,int consec=0,const char *reason=0)=0;
143 
144 // Stats() is invoked when we need statistics about all instances of the
145 // protocol. If a buffer is supplied, it must return a null
146 // terminated string in the supplied buffer and the return value
147 // is the number of bytes placed in the buffer defined by C99 for
148 // snprintf(). If no buffer is supplied, the method should return
149 // the maximum number of characters that could have been returned.
150 // Regardless of the buffer value, if do_sync is true, the method
151 // should include any local statistics in the global data (if any)
152 // prior to performing any action.
153 //
154 virtual int Stats(char *buff, int blen, int do_sync=0) = 0;
155 
156  XrdProtocol(const char *jname): XrdJob(jname) {}
157 virtual ~XrdProtocol() {}
158 };
159 
160 /******************************************************************************/
161 /* X r d g e t P r o t o c o l */
162 /******************************************************************************/
163 
164 /* This extern "C" function must be defined in the shared library plug-in
165  implementing your protocol. It is called to obtain an instance of your
166  protocol. This allows protocols to live outside of the protocol driver
167  (i.e., to be loaded at run-time). The call is made after the call to
168  XrdgetProtocolPort() to determine the port to be used (see below) which
169  allows e network object (NetTCP) to be proerly defined and it's pointer
170  is passed in the XrdProtocol_Config object for your use.
171 
172  Required return values:
173  Success: Pointer to XrdProtocol object.
174  Failure: Null pointer (i.e. 0) which causes the program to exit.
175 
176 extern "C" // This is in a comment!
177 {
178  XrdProtocol *XrdgetProtocol(const char *protocol_name, char *parms,
179  XrdProtocol_Config *pi) {....}
180 }
181 */
182 
183 /******************************************************************************/
184 /* X r d g e t P r o t o c o l P o r t */
185 /******************************************************************************/
186 
187 /* This extern "C" function must be defined for statically linked protocols
188  but is optional for protocols defined as a shared library plug-in if the
189  rules determining which port number to use is sufficient for your protocol.
190  The function is called to obtain the actual port number to be used by the
191  the protocol. The default port number is noted in XrdProtocol_Config Port.
192  Initially, it has one of the fllowing values:
193  <0 -> No port was specified.
194  =0 -> An erbitrary port will be assigned.
195  >0 -> This port number was specified.
196 
197  XrdgetProtoclPort() must return:
198  <0 -> Failure is indicated and we terminate
199  =0 -> Use an arbitrary port (even if this equals Port)
200  >0 -> The returned port number must be used (even if it equals Port)
201 
202  When we finally call XrdgetProtocol(), the actual port number is indicated
203  in Port and the network object is defined in NetTCP and bound to the port.
204 
205  Final Caveats: 1. The network object (NetTCP) is not defined until
206  XrdgetProtocol() is called.
207 
208  2. The statistics object (Stats) is not defined until
209  XrdgetProtocol() is called.
210 
211  3. When the protocol is loaded from a shared library, you need
212  need not define XrdgetProtocolPort() if the standard port
213  determination scheme is sufficient.
214 
215 extern "C" // This is in a comment!
216 {
217  int XrdgetProtocolPort(const char *protocol_name, char *parms,
218  XrdProtocol_Config *pi) {....}
219 }
220 */
221 #endif
Definition: XrdStats.hh:51
char rsvd3[7]
Definition: XrdProtocol.hh:96
int idleWait
Definition: XrdProtocol.hh:92
const XrdNetSockAddr * urAddr
Definition: XrdProtocol.hh:86
virtual int Process(XrdLink *lp)=0
const char * myProg
Definition: XrdProtocol.hh:83
const char * myInst
Definition: XrdProtocol.hh:81
char ** argv
Definition: XrdProtocol.hh:94
int ConnMax
Definition: XrdProtocol.hh:90
const char * myName
Definition: XrdProtocol.hh:82
XrdProtocol(const char *jname)
Definition: XrdProtocol.hh:156
XrdTlsContext * tlsCtx
Definition: XrdProtocol.hh:99
Definition: XrdProtocol.hh:124
Definition: XrdBuffer.hh:71
Definition: XrdSysError.hh:89
Definition: XrdNetSockAddr.hh:43
virtual int Stats(char *buff, int blen, int do_sync=0)=0
int readWait
Definition: XrdProtocol.hh:91
Definition: XrdScheduler.hh:44
char * ConfigFN
Definition: XrdProtocol.hh:71
int AdmMode
Definition: XrdProtocol.hh:77
void * rsvd0
Definition: XrdProtocol.hh:67
int Format
Definition: XrdProtocol.hh:72
XrdBuffManager * BPool
Definition: XrdProtocol.hh:63
XrdOucEnv * theEnv
Definition: XrdProtocol.hh:66
XrdScheduler * Sched
Definition: XrdProtocol.hh:64
Definition: XrdProtocol.hh:55
Definition: XrdOucEnv.hh:41
static const int admPSet
Definition: XrdProtocol.hh:79
int argc
Definition: XrdProtocol.hh:93
XrdOucString * totalCF
Definition: XrdProtocol.hh:100
int xrdFlags
Definition: XrdProtocol.hh:78
const struct sockaddr * myAddr
Definition: XrdProtocol.hh:87
virtual void Recycle(XrdLink *lp=0, int consec=0, const char *reason=0)=0
Definition: XrdTlsContext.hh:36
int hailWait
Definition: XrdProtocol.hh:97
XrdSysError * eDest
Definition: XrdProtocol.hh:61
XrdStats * Stats
Definition: XrdProtocol.hh:65
~XrdProtocol_Config()
Definition: XrdProtocol.hh:105
virtual ~XrdProtocol()
Definition: XrdProtocol.hh:157
XrdProtocol_Config()
Definition: XrdProtocol.hh:103
virtual XrdProtocol * Match(XrdLink *lp)=0
XrdInet * NetTCP
Definition: XrdProtocol.hh:62
int Port
Definition: XrdProtocol.hh:73
int tlsPort
Definition: XrdProtocol.hh:98
char DebugON
Definition: XrdProtocol.hh:95
int rsvd1
Definition: XrdProtocol.hh:75
Definition: XrdOucString.hh:254
Definition: XrdInet.hh:47
Definition: XrdJob.hh:42
int WSize
Definition: XrdProtocol.hh:74
const char * AdmPath
Definition: XrdProtocol.hh:76