contrib/llvm/tools/lldb/include/lldb/Core/Connection.h

   1 //===-- Connection.h --------------------------------------------*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9
  10 #ifndef liblldb_Connection_h_
  11 #define liblldb_Connection_h_
  12
  13 // C Includes
  14 // C++ Includes
  15 #include <string>
  16 // Other libraries and framework includes
  17 // Project includes
  18 #include "lldb/lldb-private.h"
  19
  20 namespace lldb_private {
  21
  22 //----------------------------------------------------------------------
  23 /// @class Connection Connection.h "lldb/Core/Connection.h"
  24 /// @brief A communication connection class.
  25 ///
  26 /// A class that implements that actual communication functions for
  27 /// connecting/disconnecting, reading/writing, and waiting for bytes
  28 /// to become available from a two way communication connection.
  29 ///
  30 /// This class is designed to only do very simple communication
  31 /// functions. Instances can be instantiated and given to a
  32 /// Communication class to perform communications where clients can
  33 /// listen for broadcasts, and perform other higher level communications.
  34 //----------------------------------------------------------------------
  35 class Connection
  36 {
  37 public:
  38     //------------------------------------------------------------------
  39     /// Default constructor
  40     //------------------------------------------------------------------
  41     Connection ();
  42
  43     //------------------------------------------------------------------
  44     /// Virtual destructor since this class gets subclassed and handed
  45     /// to a Communication object.
  46     //------------------------------------------------------------------
  47     virtual
  48     ~Connection ();
  49
  50     static Connection *CreateDefaultConnection(const char *url);
  51
  52     //------------------------------------------------------------------
  53     /// Connect using the connect string \a url.
  54     ///
  55     /// @param[in] url
  56     ///     A string that contains all information needed by the
  57     ///     subclass to connect to another client.
  58     ///
  59     /// @param[out] error_ptr
  60     ///     A pointer to an error object that should be given an
  61     ///     approriate error value if this method returns false. This
  62     ///     value can be NULL if the error value should be ignored.
  63     ///
  64     /// @return
  65     ///     \b True if the connect succeeded, \b false otherwise. The
  66     ///     internal error object should be filled in with an
  67     ///     appropriate value based on the result of this function.
  68     ///
  69     /// @see Error& Communication::GetError ();
  70     //------------------------------------------------------------------
  71     virtual lldb::ConnectionStatus
  72     Connect (const char *url, Error *error_ptr) = 0;
  73
  74     //------------------------------------------------------------------
  75     /// Disconnect the communications connection if one is currently
  76     /// connected.
  77     ///
  78     /// @param[out] error_ptr
  79     ///     A pointer to an error object that should be given an
  80     ///     approriate error value if this method returns false. This
  81     ///     value can be NULL if the error value should be ignored.
  82     ///
  83     /// @return
  84     ///     \b True if the disconnect succeeded, \b false otherwise. The
  85     ///     internal error object should be filled in with an
  86     ///     appropriate value based on the result of this function.
  87     ///
  88     /// @see Error& Communication::GetError ();
  89     //------------------------------------------------------------------
  90     virtual lldb::ConnectionStatus
  91     Disconnect (Error *error_ptr) = 0;
  92
  93     //------------------------------------------------------------------
  94     /// Check if the connection is valid.
  95     ///
  96     /// @return
  97     ///     \b True if this object is currently connected, \b false
  98     ///     otherwise.
  99     //------------------------------------------------------------------
 100     virtual bool
 101     IsConnected () const = 0;
 102
 103     //------------------------------------------------------------------
 104     /// The read function that attempts to read from the connection.
 105     ///
 106     /// @param[in] dst
 107     ///     A destination buffer that must be at least \a dst_len bytes
 108     ///     long.
 109     ///
 110     /// @param[in] dst_len
 111     ///     The number of bytes to attempt to read, and also the max
 112     ///     number of bytes that can be placed into \a dst.
 113     ///
 114     /// @param[in] timeout_usec
 115     ///     The number of microseconds to wait for the data.
 116     ///
 117     /// @param[out] status
 118     ///     On return, indicates whether the call was sucessful or terminated
 119     ///     due to some error condition.
 120     ///
 121     /// @param[out] error_ptr
 122     ///     A pointer to an error object that should be given an
 123     ///     approriate error value if this method returns zero. This
 124     ///     value can be NULL if the error value should be ignored.
 125     ///
 126     /// @return
 127     ///     The number of bytes actually read.
 128     ///
 129     /// @see size_t Communication::Read (void *, size_t, uint32_t);
 130     //------------------------------------------------------------------
 131     virtual size_t
 132     Read (void *dst,
 133           size_t dst_len,
 134           uint32_t timeout_usec,
 135           lldb::ConnectionStatus &status,
 136           Error *error_ptr) = 0;
 137
 138     //------------------------------------------------------------------
 139     /// The actual write function that attempts to write to the
 140     /// communications protocol.
 141     ///
 142     /// Subclasses must override this function.
 143     ///
 144     /// @param[in] dst
 145     ///     A desination buffer that must be at least \a dst_len bytes
 146     ///     long.
 147     ///
 148     /// @param[in] dst_len
 149     ///     The number of bytes to attempt to write, and also the
 150     ///     number of bytes are currently available in \a dst.
 151     ///
 152     /// @param[out] error_ptr
 153     ///     A pointer to an error object that should be given an
 154     ///     approriate error value if this method returns zero. This
 155     ///     value can be NULL if the error value should be ignored.
 156     ///
 157     /// @return
 158     ///     The number of bytes actually Written.
 159     //------------------------------------------------------------------
 160     virtual size_t
 161     Write (const void *dst, size_t dst_len, lldb::ConnectionStatus &status, Error *error_ptr) = 0;
 162
 163     //------------------------------------------------------------------
 164     /// Returns a URI that describes this connection object
 165     ///
 166     /// Subclasses may override this function.
 167     ///
 168     /// @return
 169     ///     Returns URI or an empty string if disconnecteds
 170     //------------------------------------------------------------------
 171     virtual std::string
 172     GetURI() = 0;
 173
 174     //------------------------------------------------------------------
 175     /// Interrupts an ongoing Read() operation.
 176     ///
 177     /// If there is an ongoing read operation in another thread, this operation
 178     /// return with status == eConnectionStatusInterrupted. Note that if there
 179     /// data waiting to be read and an interrupt request is issued, the Read()
 180     /// function will return the data immediately without processing the
 181     /// interrupt request (which will remain queued for the next Read()
 182     /// operation).
 183     ///
 184     /// @return
 185     ///     Returns true is the interrupt request was sucessful.
 186     //------------------------------------------------------------------
 187     virtual bool
 188     InterruptRead() = 0;
 189
 190     //------------------------------------------------------------------
 191     /// Returns the underlying IOObject used by the Connection.
 192     ///
 193     /// The IOObject can be used to wait for data to become available
 194     /// on the connection. If the Connection does not use IOObjects (and
 195     /// hence does not support waiting) this function should return a
 196     /// null pointer.
 197     ///
 198     /// @return
 199     ///     The underlying IOObject used for reading.
 200     //------------------------------------------------------------------
 201     virtual lldb::IOObjectSP
 202     GetReadObject() { return lldb::IOObjectSP(); }
 203
 204 private:
 205     //------------------------------------------------------------------
 206     // For Connection only
 207     //------------------------------------------------------------------
 208     DISALLOW_COPY_AND_ASSIGN (Connection);
 209 };
 210
 211 } // namespace lldb_private
 212
 213 #endif  // liblldb_Connection_h_