xrootd
Loading...
Searching...
No Matches
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
43class XrdSysError;
44union XrdNetSockAddr;
45class XrdOucEnv;
46class XrdOucString;
47class XrdBuffManager;
48class XrdInet;
49class XrdScheduler;
50class XrdStats;
51class XrdTlsContext;
52
53struct sockaddr;
54
56{
57public:
58
59// The following pointers may be copied; they are stable.
60//
61XrdSysError *eDest; // Stable -> Error Message/Logging Handler
62XrdInet *NetTCP; // Stable -> Network Object (@ XrdgetProtocol)
63XrdBuffManager *BPool; // Stable -> Buffer Pool Manager
64XrdScheduler *Sched; // Stable -> System Scheduler
65XrdStats *Stats; // Stable -> System Statistics (@ XrdgetProtocol)
66XrdOucEnv *theEnv; // Stable -> Additional environmental information
67void *rsvd0;
68
69// The following information must be duplicated; it is unstable.
70//
71char *ConfigFN; // -> Configuration file
72int Format; // Binary format of this server
73int Port; // Port number
74int WSize; // Window size for Port
76const char *AdmPath; // Admin path
77int AdmMode; // Admin path mode
79static const int admPSet = 0x00000001; // The adminppath was set via cli
80
81const char *myInst; // Instance name
82const char *myName; // Host name
83const char *myProg; // Program name
84union {
85const
86XrdNetSockAddr *urAddr; // Host Address (the actual structure/union)
87const
88struct sockaddr *myAddr; // Host address
89 };
90int ConnMax; // Max connections
91int readWait; // Max milliseconds to wait for data
92int idleWait; // Max milliseconds connection may be idle
93int argc; // Number of arguments
94char **argv; // Argument array (prescreened)
95char DebugON; // True if started with -d option
96char rsvd3[7];
97int hailWait; // Max milliseconds to wait for data after accept
98int tlsPort; // Default TLS port (0 if not specified)
99XrdTlsContext *tlsCtx; // Stable -> TLS Context (0 if not initialized)
100XrdOucString *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
122class XrdLink;
123
124class XrdProtocol : public XrdJob
125{
126public:
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//
132virtual XrdProtocol *Match(XrdLink *lp) = 0;
133
134// Process() is invoked when a link has data waiting to be read
135//
136virtual 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//
142virtual 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//
154virtual int Stats(char *buff, int blen, int do_sync=0) = 0;
155
156 XrdProtocol(const char *jname): XrdJob(jname) {}
157virtual ~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
176extern "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
215extern "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 XrdBuffer.hh:72
Definition XrdInet.hh:48
Definition XrdJob.hh:43
Definition XrdOucEnv.hh:42
Definition XrdOucString.hh:254
Definition XrdProtocol.hh:56
int tlsPort
Definition XrdProtocol.hh:98
char rsvd3[7]
Definition XrdProtocol.hh:96
static const int admPSet
Definition XrdProtocol.hh:79
XrdProtocol_Config()
Definition XrdProtocol.hh:103
const char * myName
Definition XrdProtocol.hh:82
XrdBuffManager * BPool
Definition XrdProtocol.hh:63
XrdScheduler * Sched
Definition XrdProtocol.hh:64
XrdInet * NetTCP
Definition XrdProtocol.hh:62
const struct sockaddr * myAddr
Definition XrdProtocol.hh:87
int WSize
Definition XrdProtocol.hh:74
int Format
Definition XrdProtocol.hh:72
int Port
Definition XrdProtocol.hh:73
const XrdNetSockAddr * urAddr
Definition XrdProtocol.hh:86
XrdTlsContext * tlsCtx
Definition XrdProtocol.hh:99
int AdmMode
Definition XrdProtocol.hh:77
int xrdFlags
Definition XrdProtocol.hh:78
~XrdProtocol_Config()
Definition XrdProtocol.hh:105
int idleWait
Definition XrdProtocol.hh:92
const char * AdmPath
Definition XrdProtocol.hh:76
int ConnMax
Definition XrdProtocol.hh:90
XrdSysError * eDest
Definition XrdProtocol.hh:61
XrdOucString * totalCF
Definition XrdProtocol.hh:100
XrdOucEnv * theEnv
Definition XrdProtocol.hh:66
const char * myProg
Definition XrdProtocol.hh:83
const char * myInst
Definition XrdProtocol.hh:81
char * ConfigFN
Definition XrdProtocol.hh:71
int argc
Definition XrdProtocol.hh:93
int readWait
Definition XrdProtocol.hh:91
int rsvd1
Definition XrdProtocol.hh:75
int hailWait
Definition XrdProtocol.hh:97
XrdStats * Stats
Definition XrdProtocol.hh:65
char ** argv
Definition XrdProtocol.hh:94
char DebugON
Definition XrdProtocol.hh:95
void * rsvd0
Definition XrdProtocol.hh:67
XrdProtocol_Config(XrdProtocol_Config &rhs)=delete
Definition XrdProtocol.hh:125
virtual ~XrdProtocol()
Definition XrdProtocol.hh:157
XrdProtocol(const char *jname)
Definition XrdProtocol.hh:156
virtual void Recycle(XrdLink *lp=0, int consec=0, const char *reason=0)=0
virtual int Stats(char *buff, int blen, int do_sync=0)=0
virtual int Process(XrdLink *lp)=0
virtual XrdProtocol * Match(XrdLink *lp)=0
Definition XrdScheduler.hh:46
Definition XrdStats.hh:52
Definition XrdSysError.hh:90
Definition XrdTlsContext.hh:37
Definition XrdNetSockAddr.hh:43