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 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 class XrdOucTrace; 00045 class XrdBuffManager; 00046 class XrdInet; 00047 class XrdScheduler; 00048 class XrdStats; 00049 00050 struct sockaddr; 00051 00052 class XrdProtocol_Config 00053 { 00054 public: 00055 00056 // The following pointers may be copied; they are stable. 00057 // 00058 XrdSysError *eDest; // Stable -> Error Message/Logging Handler 00059 XrdInet *NetTCP; // Stable -> Network Object (@ XrdgetProtocol) 00060 XrdBuffManager *BPool; // Stable -> Buffer Pool Manager 00061 XrdScheduler *Sched; // Stable -> System Scheduler 00062 XrdStats *Stats; // Stable -> System Statistics (@ XrdgetProtocol) 00063 void *Reserved; // Stable -> Previously, the thread manager 00064 XrdOucTrace *Trace; // Stable -> Trace Information 00065 00066 // The following information must be duplicated; it is unstable. 00067 // 00068 char *ConfigFN; // -> Configuration file 00069 int Format; // Binary format of this server 00070 int Port; // Port number 00071 int WSize; // Window size for Port 00072 const char *AdmPath; // Admin path 00073 int AdmMode; // Admin path mode 00074 const char *myInst; // Instance name 00075 const char *myName; // Host name 00076 const char *myProg; // Program name 00077 struct sockaddr *myAddr; // Host address 00078 int ConnMax; // Max connections 00079 int readWait; // Max milliseconds to wait for data 00080 int idleWait; // Max milliseconds connection may be idle 00081 int argc; // Number of arguments 00082 char **argv; // Argument array (prescreened) 00083 char DebugON; // True if started with -d option 00084 int WANPort; // Port prefered for WAN connections (0 if none) 00085 int WANWSize; // Window size for the WANPort 00086 int hailWait; // Max milliseconds to wait for data after accept 00087 00088 XrdProtocol_Config(XrdProtocol_Config &rhs); 00089 XrdProtocol_Config() {} 00090 ~XrdProtocol_Config() {} 00091 }; 00092 00093 /******************************************************************************/ 00094 /* X r d P r o t o c o l */ 00095 /******************************************************************************/ 00096 00097 // This class is used by the Link object to process the input stream on a link. 00098 // At least one protocol object exists per Link object. Specific protocols are 00099 // derived from this pure abstract class since a link can use one of several 00100 // protocols. Indeed, startup and shutdown are handled by specialized protocols. 00101 00102 // System configuration obtains an instance of a protocol by calling 00103 // XrdgetProtocol(), which must exist in the shared library. 00104 // This instance is used as the base pointer for Alloc(), Configure(), and 00105 // Match(). Unfortuantely, they cannot be static given the silly C++ rules. 00106 00107 class XrdLink; 00108 00109 class XrdProtocol : public XrdJob 00110 { 00111 public: 00112 00113 // Match() is invoked when a new link is created and we are trying 00114 // to determine if this protocol can handle the link. It must 00115 // return a protocol object if it can and NULL (0), otherwise. 00116 // 00117 virtual XrdProtocol *Match(XrdLink *lp) = 0; 00118 00119 // Process() is invoked when a link has data waiting to be read 00120 // 00121 virtual int Process(XrdLink *lp) = 0; 00122 00123 // Recycle() is invoked when this object is no longer needed. The method is 00124 // passed the number of seconds the protocol was connected to the 00125 // link and the reason for the disconnection, if any. 00126 // 00127 virtual void Recycle(XrdLink *lp=0,int consec=0,const char *reason=0)=0; 00128 00129 // Stats() is invoked when we need statistics about all instances of the 00130 // protocol. If a buffer is supplied, it must return a null 00131 // terminated string in the supplied buffer and the return value 00132 // is the number of bytes placed in the buffer defined by C99 for 00133 // snprintf(). If no buffer is supplied, the method should return 00134 // the maximum number of characters that could have been returned. 00135 // Regardless of the buffer value, if do_sync is true, the method 00136 // should include any local statistics in the global data (if any) 00137 // prior to performing any action. 00138 // 00139 virtual int Stats(char *buff, int blen, int do_sync=0) = 0; 00140 00141 XrdProtocol(const char *jname): XrdJob(jname) {} 00142 virtual ~XrdProtocol() {} 00143 }; 00144 00145 /******************************************************************************/ 00146 /* X r d g e t P r o t o c o l */ 00147 /******************************************************************************/ 00148 00149 /* This extern "C" function must be defined in the shared library plug-in 00150 implementing your protocol. It is called to obtain an instance of your 00151 protocol. This allows protocols to live outside of the protocol driver 00152 (i.e., to be loaded at run-time). The call is made after the call to 00153 XrdgetProtocolPort() to determine the port to be used (see below) which 00154 allows e network object (NetTCP) to be proerly defined and it's pointer 00155 is passed in the XrdProtocol_Config object for your use. 00156 00157 Required return values: 00158 Success: Pointer to XrdProtocol object. 00159 Failure: Null pointer (i.e. 0) which causes the program to exit. 00160 00161 extern "C" // This is in a comment! 00162 { 00163 XrdProtocol *XrdgetProtocol(const char *protocol_name, char *parms, 00164 XrdProtocol_Config *pi) {....} 00165 } 00166 */ 00167 00168 /******************************************************************************/ 00169 /* X r d g e t P r o t o c o l P o r t */ 00170 /******************************************************************************/ 00171 00172 /* This extern "C" function must be defined for statically linked protocols 00173 but is optional for protocols defined as a shared library plug-in if the 00174 rules determining which port number to use is sufficient for your protocol. 00175 The function is called to obtain the actual port number to be used by the 00176 the protocol. The default port number is noted in XrdProtocol_Config Port. 00177 Initially, it has one of the fllowing values: 00178 <0 -> No port was specified. 00179 =0 -> An erbitrary port will be assigned. 00180 >0 -> This port number was specified. 00181 00182 XrdgetProtoclPort() must return: 00183 <0 -> Failure is indicated and we terminate 00184 =0 -> Use an arbitrary port (even if this equals Port) 00185 >0 -> The returned port number must be used (even if it equals Port) 00186 00187 When we finally call XrdgetProtocol(), the actual port number is indicated 00188 in Port and the network object is defined in NetTCP and bound to the port. 00189 00190 Final Caveats: 1. The network object (NetTCP) is not defined until 00191 XrdgetProtocol() is called. 00192 00193 2. The statistics object (Stats) is not defined until 00194 XrdgetProtocol() is called. 00195 00196 3. When the protocol is loaded from a shared library, you need 00197 need not define XrdgetProtocolPort() if the standard port 00198 determination scheme is sufficient. 00199 00200 extern "C" // This is in a comment! 00201 { 00202 int XrdgetProtocolPort(const char *protocol_name, char *parms, 00203 XrdProtocol_Config *pi) {....} 00204 } 00205 */ 00206 #endif