library: libCore #include "TSocket.h"

# TSocket

class description - source file - inheritance tree (.pdf)

## class TSocket : public TNamed

| Inheritance Chart:
`TObject`
| <- | `TNamed`
| <- | `TSocket` |
<- |
`TPSocket` |
`TServerSocket` | <- |
`TPServerSocket` |
`TXSocket` |

        private:

          virtual Option_t* GetOption() const
                       void operator=(const TSocket&)
                      Int_t RecvHostAuth(Option_t* opt, const char* proofconf = "0")
                      Int_t SecureRecv(TString& out, Int_t dec, Int_t key = 1)
                      Int_t SecureSend(const char* in, Int_t enc, Int_t keyType = 1)
                      Int_t SendHostAuth()

        protected:

                  TSocket()
           Bool_t Authenticate(const char* user)
             void SetDescriptor(Int_t desc)

        public:

                               TSocket(TInetAddress address, const char* service, Int_t tcpwindowsize = -1)
                               TSocket(TInetAddress address, Int_t port, Int_t tcpwindowsize = -1)
                               TSocket(const char* host, const char* service, Int_t tcpwindowsize = -1)
                               TSocket(const char* host, Int_t port, Int_t tcpwindowsize = -1)
                               TSocket(Int_t descriptor)
                               TSocket(const TSocket& s)
                       virtual ~TSocket()
                static TClass* Class()
                  virtual void Close(Option_t* opt = "")
               static TSocket* CreateAuthSocket(const char* user, const char* host, Int_t port, Int_t size = 0, Int_t tcpwindowsize = -1, TSocket* s = 0)
               static TSocket* CreateAuthSocket(const char* url, Int_t size = 0, Int_t tcpwindowsize = -1, TSocket* s = 0)
                        UInt_t GetBytesRecv() const
                        UInt_t GetBytesSent() const
                         Int_t GetCompressionLevel() const
                 virtual Int_t GetDescriptor() const
                         Int_t GetErrorCode() const
                  TInetAddress GetInetAddress() const
          virtual TInetAddress GetLocalInetAddress()
                 virtual Int_t GetLocalPort()
                 virtual Int_t GetOption(ESockOptions opt, Int_t& val)
                         Int_t GetPort() const
                         Int_t GetRemoteProtocol() const
                  TSecContext* GetSecContext() const
                   const char* GetService() const
                         Int_t GetServType() const
              static ULong64_t GetSocketBytesRecv()
              static ULong64_t GetSocketBytesSent()
                         Int_t GetTcpWindowSize() const
                   const char* GetUrl() const
               virtual TClass* IsA() const
                virtual Bool_t IsAuthenticated() const
                virtual Bool_t IsValid() const
                 virtual Int_t Recv(TMessage*& mess)
                 virtual Int_t Recv(Int_t& status, Int_t& kind)
                 virtual Int_t Recv(char* mess, Int_t max)
                 virtual Int_t Recv(char* mess, Int_t max, Int_t& kind)
                 virtual Int_t RecvRaw(void* buffer, Int_t length, ESendRecvOptions opt = kDefault)
                 virtual Int_t Select(Int_t interest = kRead, Long_t timeout = -1)
                 virtual Int_t Send(const TMessage& mess)
                 virtual Int_t Send(Int_t kind)
                 virtual Int_t Send(Int_t status, Int_t kind)
                 virtual Int_t Send(const char* mess, Int_t kind = kMESS_STRING)
                 virtual Int_t SendObject(const TObject* obj, Int_t kind = kMESS_OBJECT)
                 virtual Int_t SendRaw(const void* buffer, Int_t length, ESendRecvOptions opt = kDefault)
                          void SetCompressionLevel(Int_t level = 1)
                 virtual Int_t SetOption(ESockOptions opt, Int_t val)
                          void SetRemoteProtocol(Int_t rproto)
                          void SetSecContext(TSecContext* ctx)
                          void SetService(const char* service)
                          void SetUrl(const char* url)
                  virtual void ShowMembers(TMemberInspector& insp, char* parent)
                  virtual void Streamer(TBuffer& b)
                          void StreamerNVirtual(TBuffer& b)

### Data Members

        protected:

                   TInetAddress fAddress         remote internet address and port #
                         UInt_t fBytesRecv       total bytes received over this socket
                         UInt_t fBytesSent       total bytes sent using this socket
                          Int_t fCompress        compression level from 0 (not compressed)
                   TInetAddress fLocalAddress    local internet address and port #
                          Int_t fRemoteProtocol  protocol of remote daemon
                   TSecContext* fSecContext      after a successful Authenticate call
                        TString fService         name of service (matches remote port #)
          TSocket::EServiceType fServType        remote service type
                          Int_t fSocket          socket descriptor
                          Int_t fTcpWindowSize   TCP window size (default 65535);
                        TString fUrl             needs this for special authentication options
               static ULong64_t fgBytesRecv      total bytes received by all socket objects
               static ULong64_t fgBytesSent      total bytes sent by all socket objects

        public:

             static const TSocket::EInterest kRead
             static const TSocket::EInterest kWrite
          static const TSocket::EServiceType kSOCKD
          static const TSocket::EServiceType kROOTD
          static const TSocket::EServiceType kPROOFD

## Class Description

     TSocket

     This class implements client sockets. A socket is an endpoint for
     communication between two machines.
     The actual work is done via the TSystem class (either TUnixSystem
     or TWinNTSystem).

TSocket(TInetAddress addr, const char *service, Int_t tcpwindowsize) : TNamed(addr.GetHostName(), service)

     Create a socket. Connect to the named service at address addr.
     Use tcpwindowsize to specify the size of the receive buffer, it has
     to be specified here to make sure the window scale option is set (for
     tcpwindowsize > 65KB and for platforms supporting window scaling).
     Returns when connection has been accepted by remote side. Use IsValid()
     to check the validity of the socket. Every socket is added to the TROOT
     sockets list which will make sure that any open sockets are properly
     closed on program termination.

TSocket(TInetAddress addr, Int_t port, Int_t tcpwindowsize) : TNamed(addr.GetHostName(), "")

     Create a socket. Connect to the specified port # at address addr.
     Use tcpwindowsize to specify the size of the receive buffer, it has
     to be specified here to make sure the window scale option is set (for
     tcpwindowsize > 65KB and for platforms supporting window scaling).
     Returns when connection has been accepted by remote side. Use IsValid()
     to check the validity of the socket. Every socket is added to the TROOT
     sockets list which will make sure that any open sockets are properly
     closed on program termination.

TSocket(const char *host, const char *service, Int_t tcpwindowsize) : TNamed(host, service)

     Create a socket. Connect to named service on the remote host.
     Use tcpwindowsize to specify the size of the receive buffer, it has
     to be specified here to make sure the window scale option is set (for
     tcpwindowsize > 65KB and for platforms supporting window scaling).
     Returns when connection has been accepted by remote side. Use IsValid()
     to check the validity of the socket. Every socket is added to the TROOT
     sockets list which will make sure that any open sockets are properly
     closed on program termination.

TSocket(const char *url, Int_t port, Int_t tcpwindowsize) : TNamed(TUrl(url).GetHost(), "")

     Create a socket; see CreateAuthSocket for the form of url.
     Connect to the specified port # on the remote host.
     If user is specified in url, try authentication as user.
     Use tcpwindowsize to specify the size of the receive buffer, it has
     to be specified here to make sure the window scale option is set (for
     tcpwindowsize > 65KB and for platforms supporting window scaling).
     Returns when connection has been accepted by remote side. Use IsValid()
     to check the validity of the socket. Every socket is added to the TROOT
     sockets list which will make sure that any open sockets are properly
     closed on program termination.

TSocket(Int_t desc) : TNamed("", "")

     Create a socket. The socket will use descriptor desc.

TSocket(const TSocket &s) : TNamed(s)

     TSocket copy ctor.

void Close(Option_t *option)

     Close the socket. If option is "force", calls shutdown(id,2) to
     shut down the connection. This will close the connection also
     for the parent of this process. Also called via the dtor (without
     option "force", call explicitely Close("force") if this is desired).

TInetAddress GetLocalInetAddress()

     Return internet address of local host to which the socket is bound.
     In case of error TInetAddress::IsValid() returns kFALSE.

Int_t GetLocalPort()

     Return the local port # to which the socket is bound.
     In case of error return -1.

Int_t Select(Int_t interest, Long_t timeout)

     Waits for this socket to change status. If interest=kRead,
     the socket will be watched to see if characters become available for
     reading; if interest=kWrite the socket will be watched to
     see if a write will not block.
     The argument 'timeout' specifies a maximum time to wait in millisec.
     Default no timeout.
     Returns 1 if a change of status of interest has been detected within
     timeout; 0 in case of timeout; < 0 if an error occured.

Int_t Send(Int_t kind)

     Send a single message opcode. Use kind (opcode) to set the
     TMessage "what" field. Returns the number of bytes that were sent
     (always sizeof(Int_t)) and -1 in case of error. In case the kind has
     been or'ed with kMESS_ACK, the call will only return after having
     received an acknowledgement, making the sending process synchronous.

Int_t Send(Int_t status, Int_t kind)

     Send a status and a single message opcode. Use kind (opcode) to set the
     TMessage "what" field. Returns the number of bytes that were sent
     (always 2*sizeof(Int_t)) and -1 in case of error. In case the kind has
     been or'ed with kMESS_ACK, the call will only return after having
     received an acknowledgement, making the sending process synchronous.

Int_t Send(const char *str, Int_t kind)

     Send a character string buffer. Use kind to set the TMessage "what" field.
     Returns the number of bytes in the string str that were sent and -1 in
     case of error. In case the kind has been or'ed with kMESS_ACK, the call
     will only return after having received an acknowledgement, making the
     sending process synchronous.

Int_t Send(const TMessage &mess)

     Send a TMessage object. Returns the number of bytes in the TMessage
     that were sent and -1 in case of error. In case the TMessage::What
     has been or'ed with kMESS_ACK, the call will only return after having
     received an acknowledgement, making the sending process synchronous.
     Returns -4 in case of kNoBlock and errno == EWOULDBLOCK.
     Returns -5 if pipe broken or reset by peer (EPIPE || ECONNRESET).

Int_t SendObject(const TObject *obj, Int_t kind)

     Send an object. Returns the number of bytes sent and -1 in case of error.
     In case the "kind" has been or'ed with kMESS_ACK, the call will only
     return after having received an acknowledgement, making the sending
     synchronous.

Int_t SendRaw(const void *buffer, Int_t length, ESendRecvOptions opt)

     Send a raw buffer of specified length. Using option kOob one can send
     OOB data. Returns the number of bytes sent or -1 in case of error.
     Returns -4 in case of kNoBlock and errno == EWOULDBLOCK.
     Returns -5 if pipe broken or reset by peer (EPIPE || ECONNRESET).

Int_t Recv(char *str, Int_t max)

     Receive a character string message of maximum max length. The expected
     message must be of type kMESS_STRING. Returns length of received string
     (can be 0 if otherside of connection is closed) or -1 in case of error
     or -4 in case a non-blocking socket would block (i.e. there is nothing
     to be read).

Int_t Recv(char *str, Int_t max, Int_t &kind)

     Receive a character string message of maximum max length. Returns in
     kind the message type. Returns length of received string+4 (can be 0 if
     other side of connection is closed) or -1 in case of error or -4 in
     case a non-blocking socket would block (i.e. there is nothing to be read).

Int_t Recv(Int_t &status, Int_t &kind)

     Receives a status and a message type. Returns length of received
     integers, 2*sizeof(Int_t) (can be 0 if other side of connection
     is closed) or -1 in case of error or -4 in case a non-blocking
     socket would block (i.e. there is nothing to be read).

Int_t Recv(TMessage *&mess)

     Receive a TMessage object. The user must delete the TMessage object.
     Returns length of message in bytes (can be 0 if other side of connection
     is closed) or -1 in case of error or -4 in case a non-blocking socket
     would block (i.e. there is nothing to be read) or -5 if pipe broken
     or reset by peer (EPIPE || ECONNRESET). In those case mess == 0.

Int_t RecvRaw(void *buffer, Int_t length, ESendRecvOptions opt)

     Receive a raw buffer of specified length bytes. Using option kPeek
     one can peek at incoming data. Returns -1 in case of error. In case
     of opt == kOob: -2 means EWOULDBLOCK and -3 EINVAL. In case of non-blocking
     mode (kNoBlock) -4 means EWOULDBLOCK. Returns -5 if pipe broken or
     reset by peer (EPIPE || ECONNRESET).

Int_t SetOption(ESockOptions opt, Int_t val)

     Set socket options.

Int_t GetOption(ESockOptions opt, Int_t &val)

     Get socket options. Returns -1 in case of error.

Int_t GetErrorCode() const

     Returns error code. Meaning depends on context where it is called.
     If no error condition returns 0 else a value < 0.
     For example see TServerSocket ctor.

void SetCompressionLevel(Int_t level)

     Set the message compression level. Can be between 0 and 9 with 0
     being no compression and 9 maximum compression. In general the default
     level of 1 is the best compromise between achieved compression and
     cpu time. Compression will only happen when the message is > 256 bytes.

Bool_t Authenticate(const char *user)

     Authenticated the socket with specified user.

TSocket* CreateAuthSocket(const char *url, Int_t size, Int_t tcpwindowsize, TSocket *opensock)

     Creates a socket or a parallel socket and authenticates to the
     remote server.

     url: [[proto][p][auth]://][user@]host[:port][/service][?options]

     where  proto = "sockd", "rootd", "proofd"
                    indicates the type of remote server;
                    if missing "sockd" is assumed ("sockd" indicates
                    any remote server session using TServerSocket)
              [p] = for parallel sockets (forced internally for
                    rootd; ignored for proofd)
           [auth] = "up", "s", "k", "g", "h", "ug" to force UsrPwd,
                    SRP, Krb5, Globus, SSH or UidGid authentication
           [port] = is the remote port number
        [service] = service name used to determine the port
                    (for backward compatibility, specification of
                     port as priority)
         options  = "m" or "s", when proto=proofd indicates whether
                    we are master or slave (used internally by
                    TSlave)

     An already opened connection can be used by passing its socket
     in opensock.

     Example:

       TSocket::CreateAuthSocket("rootds://qwerty@machine.fq.dn:5051")

       creates an authenticated socket to a rootd server running
       on remote machine machine.fq.dn on port 5051; "parallel" sockets
       are forced internally because rootd expects
       parallel sockets; however a simple socket will be created
       in this case because the size is 0 (the default);
       authentication will attempt protocol SRP first.

       TSocket::CreateAuthSocket("pk://qwerty@machine.fq.dn:5052",3)

       creates an authenticated parallel socket of size 3 to a sockd
       server running on remote machine machine.fq.dn on port 5052;
       authentication will attempt protocol Kerberos first.

     NB: may hang if the remote server is not of the correct type;
         at present TSocket has no way to find out the type of the
         remote server automatically

     Returns pointer to an authenticated socket or 0 if creation or
     authentication is unsuccessful.

TSocket* CreateAuthSocket(const char *user, const char *url, Int_t port, Int_t size, Int_t tcpwindowsize, TSocket *opensock)

     Creates a socket or a parallel socket and authenticates to the
     remote server specified in 'url' on remote 'port' as 'user'.

     url: [[proto][p][auth]://]host[/?options]

     where  proto = "sockd", "rootd", "proofd"
                    indicates the type of remote server
                    if missing "sockd" is assumed ("sockd" indicates
                    any remote server session using TServerSocket)
              [p] = for parallel sockets (forced internally for
                    rootd)
           [auth] = "up", "s", "k", "g", "h", "ug" to force UsrPwd,
                    SRP, Krb5, Globus, SSH or UidGid authentication
        [options] = "m" or "s", when proto=proofd indicates whether
                    we are master or slave (used internally by TSlave)

     An already opened connection can be used by passing its socket
     in opensock.

     Example:

       TSocket::CreateAuthSocket("qwerty","rootdps://machine.fq.dn",5051)

       creates an authenticated socket to a rootd server running
       on remote machine machine.fq.dn on port 5051; "parallel"
       sockets are forced internally because rootd expects
       parallel sockets; however a simple socket will be created
       in this case because the size is 0 (the default);
       authentication will attempt protocol SRP first.

       TSocket::CreateAuthSocket("qwerty","pk://machine.fq.dn:5052",3)

       creates an authenticated parallel socket of size 3 to a sockd
       server running on remote machine machine.fq.dn on port 5052;
       authentication will attempt protocol Kerberos first.

     NB: may hang if the remote server is not of the correct type;
         at present TSocket has no way to find out the type of the
         remote server automatically

     Returns pointer to an authenticated socket or 0 if creation or
     authentication is unsuccessful.

Int_t SecureSend(const char *in, Int_t enc, Int_t ktyp)

     If authenticated and related SecContext is active
     secure-sends "in" to host using RSA "keyType" stored in TAuthenticate.
     Returns # bytes send or -1 in case of error.

Int_t SendHostAuth()

     Sends the list of the relevant THostAuth objects to the master or
     to the active slaves, typically data servers external to the proof
     cluster. The list is of THostAuth to be sent is specified by
     TAuthenticate::fgProofAuthInfo after directives found in the
     .rootauthrc family files ('proofserv' key)
     Returns -1 if a problem sending THostAuth has occured, -2 in case
     of problems closing the transmission.

Int_t RecvHostAuth(Option_t *opt, const char *proofconf)

     Receive from client/master directives for authentications, create
     related THostAuth and add them to the TAuthenticate::ProofAuthInfo
     list. Opt = "M" or "m" if Master, "S" or "s" if Proof slave.
     The 'proofconf' file is read only if Master

Int_t SecureRecv(TString &str, Int_t dec, Int_t key)

     Receive encoded string and decode it with 'key' type

### Inline Functions

                    void ~TSocket()
                    void SetDescriptor(Int_t desc)
                    void operator=(const TSocket&)
                 TSocket TSocket(const TSocket& s)
                   Int_t GetDescriptor() const
            TInetAddress GetInetAddress() const
                   Int_t GetPort() const
             const char* GetService() const
                   Int_t GetServType() const
                  UInt_t GetBytesSent() const
                  UInt_t GetBytesRecv() const
                   Int_t GetCompressionLevel() const
                   Int_t GetOption(ESockOptions opt, Int_t& val)
                   Int_t GetRemoteProtocol() const
            TSecContext* GetSecContext() const
                   Int_t GetTcpWindowSize() const
             const char* GetUrl() const
                  Bool_t IsAuthenticated() const
                  Bool_t IsValid() const
                    void SetRemoteProtocol(Int_t rproto)
                    void SetSecContext(TSecContext* ctx)
                    void SetService(const char* service)
                    void SetUrl(const char* url)
               ULong64_t GetSocketBytesSent()
               ULong64_t GetSocketBytesRecv()
                 TClass* Class()
                 TClass* IsA() const
                    void ShowMembers(TMemberInspector& insp, char* parent)
                    void Streamer(TBuffer& b)
                    void StreamerNVirtual(TBuffer& b)

Author: Fons Rademakers 18/12/96
Last update: root/net:$Name: $:$Id: TSocket.cxx,v 1.33 2005/06/23 06:24:27 brun Exp $
Copyright (C) 1995-2000, Rene Brun and Fons Rademakers. *