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