XrdProtocol.hh

Go to the documentation of this file.

#ifndef __XrdProtocol_H__
#define __XrdProtocol_H__
/******************************************************************************/
/*                                                                            */
/*                        X r d P r o t o c o l . h h                         */
/*                                                                            */
/* (c) 2004 by the Board of Trustees of the Leland Stanford, Jr., University  */
/*       All Rights Reserved. See XrdInfo.cc for complete License Terms       */
/*   Produced by Andrew Hanushevsky for Stanford University under contract    */
/*              DE-AC03-76-SFO0515 with the Department of Energy              */
/******************************************************************************/

#include "Xrd/XrdJob.hh"
 
/******************************************************************************/
/*                    X r d P r o t o c o l _ C o n f i g                     */
/******************************************************************************/
  
// The following class is passed to the XrdgetProtocol() and XrdgetProtocolPort()
// functions to properly configure the protocol. This object is not stable and 
// the protocol must copy out any values it desires to keep. It may copy the 
// whole object using the supplied copy constructor.

class XrdSysError;
class XrdOucTrace;
class XrdBuffManager;
class XrdInet;
class XrdScheduler;
class XrdStats;

struct sockaddr;

class XrdProtocol_Config
{
public:

// The following pointers may be copied; they are stable.
//
XrdSysError    *eDest;       // Stable -> Error Message/Logging Handler
XrdInet        *NetTCP;      // Stable -> Network Object    (@ XrdgetProtocol)
XrdBuffManager *BPool;       // Stable -> Buffer Pool Manager
XrdScheduler   *Sched;       // Stable -> System Scheduler
XrdStats       *Stats;       // Stable -> System Statistics (@ XrdgetProtocol)
void           *Reserved;    // Stable -> Previously, the thread manager
XrdOucTrace    *Trace;       // Stable -> Trace Information

// The following information must be duplicated; it is unstable.
//
char            *ConfigFN;     // -> Configuration file
int              Format;       // Binary format of this server
int              Port;         // Port number
int              WSize;        // Window size for Port
const char      *AdmPath;      // Admin path
int              AdmMode;      // Admin path mode
const char      *myInst;       // Instance name
const char      *myName;       // Host name
const char      *myProg;       // Program name
struct sockaddr *myAddr;       // Host address
int              ConnMax;      // Max connections
int              readWait;     // Max milliseconds to wait for data
int              idleWait;     // Max milliseconds connection may be idle
int              argc;         // Number of arguments
char           **argv;         // Argument array (prescreened)
char             DebugON;      // True if started with -d option
int              WANPort;      // Port prefered for WAN connections (0 if none)
int              WANWSize;     // Window size for the WANPort
int              hailWait;     // Max milliseconds to wait for data after accept

                 XrdProtocol_Config(XrdProtocol_Config &rhs);
                 XrdProtocol_Config() {}
                ~XrdProtocol_Config() {}
};

/******************************************************************************/
/*                           X r d P r o t o c o l                            */
/******************************************************************************/

// This class is used by the Link object to process the input stream on a link.
// At least one protocol object exists per Link object. Specific protocols are 
// derived from this pure abstract class since a link can use one of several 
// protocols. Indeed, startup and shutdown are handled by specialized protocols.

// System configuration obtains an instance of a protocol by calling
// XrdgetProtocol(), which must exist in the shared library.
// This instance is used as the base pointer for Alloc(), Configure(), and
// Match(). Unfortuantely, they cannot be static given the silly C++ rules.

class XrdLink;
  
class XrdProtocol : public XrdJob
{
public:

// Match()     is invoked when a new link is created and we are trying
//             to determine if this protocol can handle the link. It must
//             return a protocol object if it can and NULL (0), otherwise.
//
virtual XrdProtocol  *Match(XrdLink *lp) = 0;

// Process()   is invoked when a link has data waiting to be read
//
virtual int           Process(XrdLink *lp) = 0;

// Recycle()   is invoked when this object is no longer needed. The method is
//             passed the number of seconds the protocol was connected to the
//             link and the reason for the disconnection, if any.
//
virtual void          Recycle(XrdLink *lp=0,int consec=0,const char *reason=0)=0;

// Stats()     is invoked when we need statistics about all instances of the
//             protocol. If a buffer is supplied, it must return a null 
//             terminated string in the supplied buffer and the return value
//             is the number of bytes placed in the buffer defined by C99 for 
//             snprintf(). If no buffer is supplied, the method should return
//             the maximum number of characters that could have been returned.
//             Regardless of the buffer value, if do_sync is true, the method
//             should include any local statistics in the global data (if any)
//             prior to performing any action.
//
virtual int           Stats(char *buff, int blen, int do_sync=0) = 0;

            XrdProtocol(const char *jname): XrdJob(jname) {}
virtual    ~XrdProtocol() {}
};

/******************************************************************************/
/*                        X r d g e t P r o t o c o l                         */
/******************************************************************************/
  
/* This extern "C" function must be defined in the shared library plug-in
   implementing your protocol. It is called to obtain an instance of your
   protocol. This allows protocols to live outside of the protocol driver
   (i.e., to be loaded at run-time). The call is made after the call to
   XrdgetProtocolPort() to determine the port to be used (see below) which
   allows e network object (NetTCP) to be proerly defined and it's pointer
   is passed in the XrdProtocol_Config object for your use.

   Required return values:
   Success: Pointer to XrdProtocol object.
   Failure: Null pointer (i.e. 0) which causes the program to exit.

extern "C"  // This is in a comment!
{
       XrdProtocol *XrdgetProtocol(const char *protocol_name, char *parms,
                                   XrdProtocol_Config *pi) {....}
}
*/
  
/******************************************************************************/
/*                    X r d g e t P r o t o c o l P o r t                     */
/******************************************************************************/
  
/* This extern "C" function must be defined for statically linked protocols
   but is optional for protocols defined as a shared library plug-in if the
   rules determining which port number to use is sufficient for your protocol.
   The function is called to obtain the actual port number to be used by the
   the protocol. The default port number is noted in XrdProtocol_Config Port.
   Initially, it has one of the fllowing values:
   <0 -> No port was specified.
   =0 -> An erbitrary port will be assigned.
   >0 -> This port number was specified.

   XrdgetProtoclPort() must return:
   <0 -> Failure is indicated and we terminate
   =0 -> Use an arbitrary port (even if this equals Port)
   >0 -> The returned port number must be used (even if it equals Port)

   When we finally call XrdgetProtocol(), the actual port number is indicated
   in Port and the network object is defined in NetTCP and bound to the port.

   Final Caveats: 1.  The network object (NetTCP) is not defined until
                      XrdgetProtocol() is called.

                  2.  The statistics object (Stats) is not defined until
                      XrdgetProtocol() is called.

                  3.  When the protocol is loaded from a shared library, you need
                      need not define XrdgetProtocolPort() if the standard port
                      determination scheme is sufficient.

extern "C"  // This is in a comment!
{
       int XrdgetProtocolPort(const char *protocol_name, char *parms,
                              XrdProtocol_Config *pi) {....}
}
*/
#endif