EIC code displayed by LXR master/​include/​xrootd/​XrdXrootd/​XrdXrootdBridge.hh	Source navigation Diff markup Identifier search General search
	Version: master test Revert   Change

File indexing completed on 2025-01-30 10:27:57

 #ifndef __XRDXROOTDBRIDGE_HH_
 #define __XRDXROOTDBRIDGE_HH_
 /******************************************************************************/
 /*                                                                            */
 /*                    X r d X r o o t d B r i d g e . h h                     */
 /*                                                                            */
 /* (c) 2012 by the Board of Trustees of the Leland Stanford, Jr., University  */
 /*                            All Rights Reserved                             */
 /*   Produced by Andrew Hanushevsky for Stanford University under contract    */
 /*              DE-AC02-76-SFO0515 with the Department of Energy              */
 /*                                                                            */
 /* This file is part of the XRootD software suite.                            */
 /*                                                                            */
 /* XRootD is free software: you can redistribute it and/or modify it under    */
 /* the terms of the GNU Lesser General Public License as published by the     */
 /* Free Software Foundation, either version 3 of the License, or (at your     */
 /* option) any later version.                                                 */
 /*                                                                            */
 /* XRootD is distributed in the hope that it will be useful, but WITHOUT      */
 /* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or      */
 /* FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public       */
 /* License for more details.                                                  */
 /*                                                                            */
 /* You should have received a copy of the GNU Lesser General Public License   */
 /* along with XRootD in a file called COPYING.LESSER (LGPL license) and file  */
 /* COPYING (GPL license).  If not, see <http://www.gnu.org/licenses/>.        */
 /*                                                                            */
 /* The copyright holder's institutional names and contributor's names may not */
 /* be used to endorse or promote products derived from this software without  */
 /* specific prior written permission of the institution or contributor.       */
 /******************************************************************************/
 
 #include <cstring>
 
 #include "XProtocol/XPtypes.hh"
 
 //-----------------------------------------------------------------------------
 //! Bridge
 //!
 //! The Bridge object allows other protocols to gain access to the xrootd
 //! protocol stack. Almost any kind of request/response protocol can use this
 //! class to convert its request to an xroot protocol request and rewrite the
 //! xroot protocol response to adhere to its protocol specification. Callers
 //! of these methods must be thread-safe and must not rely on thread-local
 //! storage as bridge requests and responses may or may not be executed using
 //! the initiating thread. Also, see the Result object class below.
 //-----------------------------------------------------------------------------
 
 struct iovec;
 class  XrdLink;
 class  XrdSecEntity;
 class  XrdXrootdProtocol;
 
 namespace XrdXrootd
 {
 
 /******************************************************************************/
 /*                     X r d X r o o t d : : B r i d g e                      */
 /******************************************************************************/
   
 class Bridge
 {
 public:
 class Result;
 
 //-----------------------------------------------------------------------------
 //! Create a Bridge object.
 //!
 //! The first step is to create a Bridge object via a Login() call. The object
 //! should correspond to a session (i.e. tied to a particular client) real or
 //! not. The returned object must be used to inject xrootd requests into the
 //! protocol stack. Response rewrites are handled by the Result object passed as
 //! an argument. A successful Login() takes control of the connection. You can
 //! still write using the Link object but reads may only occur when your
 //! protocol's Process() method is called. Use Disc() to disband the bridge and
 //! free its storage. The bridge is automatically disbanded when your protocol's
 //! Recycle() method is called. This happens when you explicitly close the link
 //! or implicitly when the Process() method returns a negative error code or
 //! a callback method returns false.
 //!
 //! @param  rsltP   a pointer to the result object. This object is used to
 //!                 to rewrite xrootd responses to protocol specific responses.
 //!                 It must be allocated by the caller. One such object can be
 //!                 created for each session or, if the protocol allows, be
 //!                 shared by all sessions. It cannot be deleted until all
 //!                 references to the object disappear (see the Result class).
 //! @param  linkP   a pointer to the link object that the protocol driver
 //!                 created to the client connection.
 //! @param  seceP   a pointer to the XrdSecEntity object that describes the
 //!                 client's identity.
 //! @param  nameP   An arbitrary 1-to-8 character client name. The Bridge will
 //!                 uniquefy this name so that log file messages will track the
 //!                 the associated client. The link's identity is set to
 //!                 correspond to this name with additional information.
 //! @param  protP   a 1-to-7 character name of the protocol using this bridge
 //!                 (e.g. "http").
 //!
 //! @return bridgeP a pointer to a new instance of this class if a bridge
 //!                 could be created, null otherwise. If null is returned, the
 //!                 retc variable holds the errno indicating why it failed.
 //-----------------------------------------------------------------------------
 
 static
 Bridge       *Login(Result       *rsltP, //!< The result callback object
                     XrdLink      *linkP, //!< Client's network connection
                     XrdSecEntity *seceP, //!< Client's identity
                     const char   *nameP, //!< Client's name for tracking
                     const char   *protP  //!< Protocol name for tracking
                    );
 
 //-----------------------------------------------------------------------------
 //! Inject an xrootd request into the protocol stack.
 //!
 //! The Run() method allows you to inject an xrootd-style request into the
 //! stack. It must use the same format as a real xrootd client would use across
 //! the network. The xroot protocol reference describes these requests. The
 //! Run() method handles the request as if it came through the network with
 //! some notable exceptions (see the xdataP and xdataL arguments).
 //!
 //! @param  xreqP   pointer to the xrootd request. This is the standard 24-byte
 //!                 request header common to all xrootd requests in network
 //!                 format. The contents of the buffer may be modified by the
 //!                 this method. The buffer must not be modified by the caller
 //!                 before a response is solicited via the Result object.
 //!
 //! @param  xdataP  the associated data for this request. Full or partial data
 //!                 may be supplied as indicated by the xdataL argument. See
 //!                 explanation of xdataL. For write requests, this buffer may
 //!                 not be altered or deleted until the Result Free() callback
 //!                 is invoked. For other requests, it doesn't matter.
 //!
 //!                 If the pointer is zero but the "dlen" field is not zero,
 //!                 dlen's worth of data is read from the network using the
 //!                 associated XdLink object to complete the request.
 //!
 //! @param  xdataL  specifies the length of data in the buffer pointed to by
 //!                 xdataP. Depending on the value and the value in the "dlen"
 //!                 field, additional data may be read from the network.
 //!
 //!                 xdataL  < "dlen": dlen-xdataL additional bytes will be read
 //!                                   from the network to complete the request.
 //!                 xdataL >= "dlen": no additional bytes will be read from the
 //!                                   network. The request data is complete.
 //!
 //! @return true    the request has been accepted. Processing will start when
 //!                 the caller returns from the Process() method.
 //!                 A response will come via a Result object callback.
 //!         false   the request has been rejected because the bridge is still
 //!                 processing a previous request.
 //-----------------------------------------------------------------------------
 
 virtual bool  Run(const char *xreqP,       //!< xrootd request header
                         char *xdataP=0,    //!< xrootd request data (optional)
                         int   xdataL=0     //!< xrootd request data length
                  ) = 0;
 
 //-----------------------------------------------------------------------------
 //! Disconnect the session from the bridge.
 //!
 //! The Disc() method allows you to disconnect the session from the bridge and
 //! free the storage associated with this object. It may be called when you want
 //! to regain control of the connection and delete the Bridge object (note that
 //! you cannot use delete on Bridge). The Disc() method must not be called in
 //! your protocol Recycle() method as protocol object recycling already implies
 //! a Disc() call (i.e. the connection is disbanding the associated protocol).
 //!
 //! @return true    the bridge has been  dismantled.
 //!         false   the bridge cannot be dismantled because it is still
 //!                 processing a previous request.
 //-----------------------------------------------------------------------------
 
 virtual bool  Disc() = 0;
 
 //-----------------------------------------------------------------------------
 //! Set file's sendfile capability.
 //!
 //! The setSF() method allows you to turn on or off the ability of an open
 //! file to be used with the sendfile() system call. This is useful when you
 //! must see the data prior to sending to the client (e.g. for encryption).
 //!
 //! @param  fhandle the filehandle as returned by kXR_open.
 //! @param  seton   When true, enables sendfile() otherwise it is disabled.
 //!
 //! @return =0      Sucessful.
 //! @return <0      Call failed. The return code is -errno and usually will
 //!                 indicate that the filehandle is not valid.
 //-----------------------------------------------------------------------------
 
 virtual int   setSF(kXR_char *fhandle, bool seton=false) = 0;
 
 //-----------------------------------------------------------------------------
 //! Set the maximum delay.
 //!
 //! The setWait() method allows you to specify the maximum amount of time a
 //! request may be delayed (i.e. via kXR_wait result) before it generates a
 //! kXR_Cancelled error with the associated Error() result callback. The default
 //! maximum time is 1 hour. If you specify a time less than or equal to zero,
 //! wait requests are reflected back via the Wait() result callback method and
 //! you are responsible for handling them. You can request wait notification
 //! while still having the wait internally handled using the second parameter.
 //! Maximum delays are bridge specific. There is no global value. If you desire
 //! something other than the default you must call SetWait for each Login().
 //!
 //! @param  wtime   the maximum wait time in seconds.
 //! @param  notify  When true, issues a Wait callback whenever a wait occurs.
 //!                 This is the default when wtime is <= 0.
 //!
 //-----------------------------------------------------------------------------
 
 virtual void  SetWait(int wtime, bool notify=false) = 0;
 
 /******************************************************************************/
 /*            X r d X r o o t d : : B r i d g e : : C o n t e x t             */
 /******************************************************************************/
   
 //-----------------------------------------------------------------------------
 //! Provide callback context.
 //!
 //! The Context object is passed in all Result object callbacks and contains
 //! information describing the result context. No public members should be
 //! changed by any result callback method. The context object also includes a
 //! method that must be used to complete a pending sendfile() result.
 //-----------------------------------------------------------------------------
   
 class Context
 {
 public:
 
       XrdLink   *linkP; //!< -> associated session link object (i.e. connection)
       kXR_unt16  rCode; //!< associated "kXR" request code in host byte order
 union{kXR_unt16  num;   //!< associated stream ID as a short
       kXR_char   chr[2];//!< associated stream ID as the original char[2]
      }           sID;   //!< associated request stream ID
 
 //-----------------------------------------------------------------------------
 //! Complete a File() callback.
 //!
 //! The Send() method must be called after the File() callback is invoked to
 //! complete data transmission using sendfile(). If Send() is not called the
 //! pending sendfile() call is not made and no data is sent to the client.
 //!
 //! @param  headP   a pointer to the iovec structure containing the data that
 //!                 must be sent before the sendfile() data. If there is none,
 //!                 the pointer can be null.
 //! @param  headN   the number of elements in the headP iovec structure array.
 //! @param  tailP   a pointer to the iovec structure containing the data that
 //!                 must be sent after the sendfile() data. If there is none,
 //!                 the pointer can be null.
 //! @param  tailN   the number of elements in the tailP iovec structure array.
 //!
 //! @return < 0     transmission error has occurred. This can be due to either
 //!                 connection failure or data source error (i.e. I/O error).
 //!         = 0     data has been successfully sent.
 //!         > 0     the supplied context was not generated by a valid File()
 //!                 callback. No data has been sent.
 //-----------------------------------------------------------------------------
 
 virtual int   Send(const
                    struct iovec *headP, //!< pointer to leading  data array
                    int           headN, //!< array count
                    const
                    struct iovec *tailP, //!< pointer to trailing data array
                    int           tailN  //!< array count
                   )
 {
   (void)headP; (void)headN; (void)tailP; (void)tailN;
   return 1;
 }
 
 //-----------------------------------------------------------------------------
 //! Constructor and Destructor
 //-----------------------------------------------------------------------------
 
               Context(XrdLink *lP, kXR_char *sid, kXR_unt16 req)
                      : linkP(lP), rCode(req)
                        {memcpy(sID.chr, sid, sizeof(sID.chr));}
 virtual      ~Context() {}
 };
 
 /******************************************************************************/
 /*             X r d X r o o t d : : B r i d g e : : R e s u l t              */
 /******************************************************************************/
 
 //-----------------------------------------------------------------------------
 //! Handle xroot protocol execution results.
 //!
 //! The Result object is an abstract class that defines the interface used
 //! by the xroot protocol stack to effect a client response using whatever
 //! alternate protocol is needed. You must define an implementation and pass it
 //! as an argument to the Login() Bridge method.
 //-----------------------------------------------------------------------------
 
 class Result
 {
 public:
 
 //-----------------------------------------------------------------------------
 //! Effect a client data response.
 //!
 //! The Data() method is called when Run() resulted in a successful data
 //! response. The method should rewrite the data and send it to the client using
 //! the associated XrdLink object. As an example,
 //! 1) Result::Data(info, iovP, iovN, iovL) is called.
 //! 2) Inspect iovP, rewrite the data.
 //! 3) Send the response: info->linkP->Send(new_iovP, new_iovN, new_iovL);
 //! 4) Handle send errors and cleanup(e.g. deallocate storage).
 //! 5) Return, the exchange is now complete.
 //!
 //! @param  info    the context associated with the result.
 //! @param  iovP    a pointer to the iovec structure containing the xrootd data
 //!                 response about to be sent to the client. The request header
 //!                 is not included in the iovec structure. The elements of this
 //!                 structure must not be modified by the method.
 //! @param  iovN    the number of elements in the iovec structure array.
 //! @param  iovL    total number of data bytes that would be sent to the client.
 //!                 This is simply the sum of all the lengths in the iovec.
 //! @param  final   True is this is the final result. Otherwise, this is a
 //!                 partial result (i.e. kXR_oksofar) and more data will result
 //!                 causing additional callbacks. For write requests, any
 //!                 supplied data buffer may now be reused or freed.
 //!
 //! @return true    continue normal processing.
 //!         false   terminate the bridge and close the link.
 //-----------------------------------------------------------------------------
 
 virtual bool  Data(Bridge::Context &info,   //!< the result context
                    const
                    struct iovec    *iovP,   //!< pointer to data array
                    int              iovN,   //!< array count
                    int              iovL,   //!< byte  count
                    bool             final   //!< true -> final result
                   ) = 0;
 
 //-----------------------------------------------------------------------------
 //! Effect a client acknowledgement.
 //!
 //! The Done() method is called when Run() resulted in success and there is no
 //! associated data for the client (equivalent to a simple kXR_ok response).
 //!
 //! @param  info    the context associated with the result.
 //!
 //! @return true    continue normal processing.
 //!         false   terminate the bridge and close the link.
 //-----------------------------------------------------------------------------
 
 virtual bool  Done(Bridge::Context &info)=0;//!< the result context
 
 //-----------------------------------------------------------------------------
 //! Effect a client error response.
 //!
 //! The Error() method is called when an error was encountered while processing
 //! the Run() request. The error should be reflected to the client.
 //!
 //! @param  info    the context associated with the result.
 //! @param  ecode   the "kXR" error code describing the nature of the error.
 //!                 The code is in host byte format.
 //! @param  etext   a null terminated string describing the error in human terms
 //!
 //! @return true    continue normal processing.
 //!         false   terminate the bridge and close the link.
 //-----------------------------------------------------------------------------
 
 virtual bool  Error(Bridge::Context &info,   //!< the result context
                     int              ecode,  //!< the "kXR" error code
                     const char      *etext   //!< associated error message
                    ) = 0;
 
 //-----------------------------------------------------------------------------
 //! Notify callback that a sendfile() request is pending.
 //!
 //! The File() method is called when Run() resulted in a sendfile response (i.e.
 //! sendfile() would have been used to send data to the client). This allows
 //! the callback to reframe the sendfile() data using the Send() method in the
 //! passed context object (see class Context above).
 //!
 //! @param  info    the context associated with the result.
 //! @param  dlen    total number of data bytes that would be sent to the client.
 //!
 //! @return true    continue normal processing.
 //!         false   terminate the bridge and close the link.
 //-----------------------------------------------------------------------------
 
 virtual int   File(Bridge::Context &info,  //!< the result context
                    int              dlen   //!< byte  count
                   ) = 0;
 
 //-----------------------------------------------------------------------------
 //! Notify callback that a write buffer is now available for reuse.
 //!
 //! The Free() method is called when Run() was called to write data and a buffer
 //! was supplied. Normally, he buffer is pinned and cannot be reused until the
 //! write completes. This callback provides the notification that the buffer is
 //! no longer in use. The callback is invoked prior to any other callbacks and
 //! is only invoked if a buffer was supplied.
 //!
 //! @param  info    the context associated with this call.
 //! @param  buffP   pointer to the buffer.
 //! @param  buffL   the length originally supplied in the Run() call.
 //-----------------------------------------------------------------------------
 
 virtual void  Free(Bridge::Context &info,  //!< the result context
                    char            *buffP, //!< pointer to the buffer
                    int              buffL  //!< original length to Run()
                   )
 {
   (void)info; (void)buffP; (void)buffL;
 }
 
 //-----------------------------------------------------------------------------
 //! Redirect the client to another host:port.
 //!
 //! The Redir() method is called when the client must be redirected to another
 //! host.
 //!
 //! @param  info    the context associated with the result.
 //! @param  port    the port number in host byte format.
 //! @param  hname   the DNS name of the host or IP address is IPV4 or IPV6
 //!                 format (i.e. "n.n.n.n" or "[ipv6_addr]").
 //!
 //! @return true    continue normal processing.
 //!         false   terminate the bridge and close the link.
 //-----------------------------------------------------------------------------
 
 virtual bool  Redir(Bridge::Context &info,   //!< the result context
                     int              port,   //!< the port number
                     const char      *hname   //!< the destination host
                    ) = 0;
 
 //-----------------------------------------------------------------------------
 //! Effect a client wait.
 //!
 //! The Wait() method is called when Run() needs to delay a request. Normally,
 //! delays are internally handled. However, you can request that delays be
 //! reflected via a callback using the Bridge SetWait() method.
 //!
 //! @param  info    the context associated with the result.
 //! @param  wtime   the number of seconds to delay the request.
 //! @param  wtext   a null terminated string describing the wait in human terms
 //!
 //! @return true    continue normal processing.
 //!         false   terminate the bridge and close the link.
 //-----------------------------------------------------------------------------
 
 virtual bool  Wait(Bridge::Context &info,   //!< the result context
                    int              wtime,  //!< the wait time
                    const char      *wtext   //!< associated message
                    )
 {
   (void)info; (void)wtime; (void)wtext;
   return false;
 }
 
 //-----------------------------------------------------------------------------
 //! Effect a client wait response (waitresp) NOT CURRENTLY IMPLEMENTED!
 //!
 //! The WaitResp() method is called when an operation ended with a wait for
 //! response (waitresp) condition. The wait for response condition indicates
 //! that the actual response will be delivered at a later time. You can use
 //! context object to determine the operation being delayed. This callback
 //! provides you the opportunity to say how the waitresp is to be handled.
 //!
 //! @param  info    the context associated with the result.
 //! @param  wtime   the number of seconds in which a response is expected.
 //! @param  wtext   a null terminated string describing the delay in human terms
 //!
 //! @return !0      pointer to the callback object whose appropriate method
 //!                 should be called when the actual response is generated.
 //! @return 0       the waitresp will be handled by the bridge application. The
 //!                 application is responsible for re-issuing the request when
 //!                 the final response is a wait.
 //-----------------------------------------------------------------------------
 virtual
 Bridge::Result *WaitResp(Bridge::Context &info,   //!< the result context
                          int              wtime,  //!< the wait time
                          const char      *wtext   //!< associated message
                         )
 {
   (void)info; (void)wtime; (void)wtext;
   return 0;
 }
 
 //-----------------------------------------------------------------------------
 //! Constructor & Destructor
 //-----------------------------------------------------------------------------
 
               Result() {}
 virtual      ~Result() {}
 };
 
 //-----------------------------------------------------------------------------
 //! Constructor & Destructor
 //-----------------------------------------------------------------------------
 
               Bridge() {}
 protected:
 virtual      ~Bridge() {}
 };
 }
 #endif

This page was automatically generated by the 2.3.7 LXR engine. The LXR team