XrdProtocol.hh

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

Generated on 13 Mar 2017 for xrootd by  doxygen 1.4.7