00001 #ifndef __XrdProtocol_H__ 00002 #define __XrdProtocol_H__ 00003 /******************************************************************************/ 00004 /* */ 00005 /* X r d P r o t o c o l . h h */ 00006 /* */ 00007 /*(c) 2004-18 By the Board of Trustees of the Leland Stanford, Jr., University*/ 00008 /* Produced by Andrew Hanushevsky for Stanford University under contract */ 00009 /* DE-AC02-76-SFO0515 with the Department of Energy */ 00010 /* */ 00011 /* This file is part of the XRootD software suite. */ 00012 /* */ 00013 /* XRootD is free software: you can redistribute it and/or modify it under */ 00014 /* the terms of the GNU Lesser General Public License as published by the */ 00015 /* Free Software Foundation, either version 3 of the License, or (at your */ 00016 /* option) any later version. */ 00017 /* */ 00018 /* XRootD is distributed in the hope that it will be useful, but WITHOUT */ 00019 /* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or */ 00020 /* FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public */ 00021 /* License for more details. */ 00022 /* */ 00023 /* You should have received a copy of the GNU Lesser General Public License */ 00024 /* along with XRootD in a file called COPYING.LESSER (LGPL license) and file */ 00025 /* COPYING (GPL license). If not, see <http://www.gnu.org/licenses/>. */ 00026 /* */ 00027 /* The copyright holder's institutional names and contributor's names may not */ 00028 /* be used to endorse or promote products derived from this software without */ 00029 /* specific prior written permission of the institution or contributor. */ 00030 /******************************************************************************/ 00031 00032 #include "Xrd/XrdJob.hh" 00033 00034 /******************************************************************************/ 00035 /* X r d P r o t o c o l _ C o n f i g */ 00036 /******************************************************************************/ 00037 00038 // The following class is passed to the XrdgetProtocol() and XrdgetProtocolPort() 00039 // functions to properly configure the protocol. This object is not stable and 00040 // the protocol must copy out any values it desires to keep. It may copy the 00041 // whole object using the supplied copy constructor. 00042 00043 class XrdSysError; 00044 union XrdNetSockAddr; 00045 class XrdOucEnv; 00046 class XrdOucString; 00047 class XrdBuffManager; 00048 class XrdInet; 00049 class XrdScheduler; 00050 class XrdStats; 00051 class XrdTlsContext; 00052 00053 struct sockaddr; 00054 00055 class XrdProtocol_Config 00056 { 00057 public: 00058 00059 // The following pointers may be copied; they are stable. 00060 // 00061 XrdSysError *eDest; // Stable -> Error Message/Logging Handler 00062 XrdInet *NetTCP; // Stable -> Network Object (@ XrdgetProtocol) 00063 XrdBuffManager *BPool; // Stable -> Buffer Pool Manager 00064 XrdScheduler *Sched; // Stable -> System Scheduler 00065 XrdStats *Stats; // Stable -> System Statistics (@ XrdgetProtocol) 00066 XrdOucEnv *theEnv; // Stable -> Additional environmental information 00067 void *rsvd0; 00068 00069 // The following information must be duplicated; it is unstable. 00070 // 00071 char *ConfigFN; // -> Configuration file 00072 int Format; // Binary format of this server 00073 int Port; // Port number 00074 int WSize; // Window size for Port 00075 int rsvd1; 00076 const char *AdmPath; // Admin path 00077 int AdmMode; // Admin path mode 00078 int xrdFlags; 00079 static const int admPSet = 0x00000001; // The adminppath was set via cli 00080 00081 const char *myInst; // Instance name 00082 const char *myName; // Host name 00083 const char *myProg; // Program name 00084 union { 00085 const 00086 XrdNetSockAddr *urAddr; // Host Address (the actual structure/union) 00087 const 00088 struct sockaddr *myAddr; // Host address 00089 }; 00090 int ConnMax; // Max connections 00091 int readWait; // Max milliseconds to wait for data 00092 int idleWait; // Max milliseconds connection may be idle 00093 int argc; // Number of arguments 00094 char **argv; // Argument array (prescreened) 00095 char DebugON; // True if started with -d option 00096 char rsvd3[7]; 00097 int hailWait; // Max milliseconds to wait for data after accept 00098 int tlsPort; // Default TLS port 00099 XrdTlsContext *tlsCtx; // Stable -> TLS Context (0 if not initialized) 00100 XrdOucString *totalCF; // Stable -> total config after full init 00101 00102 XrdProtocol_Config(XrdProtocol_Config &rhs) =delete; 00103 XrdProtocol_Config() : rsvd0(0), rsvd1(0) 00104 {memset(rsvd3, 0, sizeof(rsvd3));} 00105 ~XrdProtocol_Config() {} 00106 }; 00107 00108 /******************************************************************************/ 00109 /* X r d P r o t o c o l */ 00110 /******************************************************************************/ 00111 00112 // This class is used by the Link object to process the input stream on a link. 00113 // At least one protocol object exists per Link object. Specific protocols are 00114 // derived from this pure abstract class since a link can use one of several 00115 // protocols. Indeed, startup and shutdown are handled by specialized protocols. 00116 00117 // System configuration obtains an instance of a protocol by calling 00118 // XrdgetProtocol(), which must exist in the shared library. 00119 // This instance is used as the base pointer for Alloc(), Configure(), and 00120 // Match(). Unfortuantely, they cannot be static given the silly C++ rules. 00121 00122 class XrdLink; 00123 00124 class XrdProtocol : public XrdJob 00125 { 00126 public: 00127 00128 // Match() is invoked when a new link is created and we are trying 00129 // to determine if this protocol can handle the link. It must 00130 // return a protocol object if it can and NULL (0), otherwise. 00131 // 00132 virtual XrdProtocol *Match(XrdLink *lp) = 0; 00133 00134 // Process() is invoked when a link has data waiting to be read 00135 // 00136 virtual int Process(XrdLink *lp) = 0; 00137 00138 // Recycle() is invoked when this object is no longer needed. The method is 00139 // passed the number of seconds the protocol was connected to the 00140 // link and the reason for the disconnection, if any. 00141 // 00142 virtual void Recycle(XrdLink *lp=0,int consec=0,const char *reason=0)=0; 00143 00144 // Stats() is invoked when we need statistics about all instances of the 00145 // protocol. If a buffer is supplied, it must return a null 00146 // terminated string in the supplied buffer and the return value 00147 // is the number of bytes placed in the buffer defined by C99 for 00148 // snprintf(). If no buffer is supplied, the method should return 00149 // the maximum number of characters that could have been returned. 00150 // Regardless of the buffer value, if do_sync is true, the method 00151 // should include any local statistics in the global data (if any) 00152 // prior to performing any action. 00153 // 00154 virtual int Stats(char *buff, int blen, int do_sync=0) = 0; 00155 00156 XrdProtocol(const char *jname): XrdJob(jname) {} 00157 virtual ~XrdProtocol() {} 00158 }; 00159 00160 /******************************************************************************/ 00161 /* X r d g e t P r o t o c o l */ 00162 /******************************************************************************/ 00163 00164 /* This extern "C" function must be defined in the shared library plug-in 00165 implementing your protocol. It is called to obtain an instance of your 00166 protocol. This allows protocols to live outside of the protocol driver 00167 (i.e., to be loaded at run-time). The call is made after the call to 00168 XrdgetProtocolPort() to determine the port to be used (see below) which 00169 allows e network object (NetTCP) to be proerly defined and it's pointer 00170 is passed in the XrdProtocol_Config object for your use. 00171 00172 Required return values: 00173 Success: Pointer to XrdProtocol object. 00174 Failure: Null pointer (i.e. 0) which causes the program to exit. 00175 00176 extern "C" // This is in a comment! 00177 { 00178 XrdProtocol *XrdgetProtocol(const char *protocol_name, char *parms, 00179 XrdProtocol_Config *pi) {....} 00180 } 00181 */ 00182 00183 /******************************************************************************/ 00184 /* X r d g e t P r o t o c o l P o r t */ 00185 /******************************************************************************/ 00186 00187 /* This extern "C" function must be defined for statically linked protocols 00188 but is optional for protocols defined as a shared library plug-in if the 00189 rules determining which port number to use is sufficient for your protocol. 00190 The function is called to obtain the actual port number to be used by the 00191 the protocol. The default port number is noted in XrdProtocol_Config Port. 00192 Initially, it has one of the fllowing values: 00193 <0 -> No port was specified. 00194 =0 -> An erbitrary port will be assigned. 00195 >0 -> This port number was specified. 00196 00197 XrdgetProtoclPort() must return: 00198 <0 -> Failure is indicated and we terminate 00199 =0 -> Use an arbitrary port (even if this equals Port) 00200 >0 -> The returned port number must be used (even if it equals Port) 00201 00202 When we finally call XrdgetProtocol(), the actual port number is indicated 00203 in Port and the network object is defined in NetTCP and bound to the port. 00204 00205 Final Caveats: 1. The network object (NetTCP) is not defined until 00206 XrdgetProtocol() is called. 00207 00208 2. The statistics object (Stats) is not defined until 00209 XrdgetProtocol() is called. 00210 00211 3. When the protocol is loaded from a shared library, you need 00212 need not define XrdgetProtocolPort() if the standard port 00213 determination scheme is sufficient. 00214 00215 extern "C" // This is in a comment! 00216 { 00217 int XrdgetProtocolPort(const char *protocol_name, char *parms, 00218 XrdProtocol_Config *pi) {....} 00219 } 00220 */ 00221 #endif