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 // Other libraries and framework includes
  16 // Project includes
  17 #include "lldb/lldb-private.h"
  18
  19 namespace lldb_private {
  20
  21 //----------------------------------------------------------------------
  22 /// @class Connection Connection.h "lldb/Core/Connection.h"
  23 /// @brief A communication connection class.
  24 ///
  25 /// A class that implements that actual communication functions for
  26 /// connecting/disconnecting, reading/writing, and waiting for bytes
  27 /// to become available from a two way communication connection.
  28 ///
  29 /// This class is designed to only do very simple communication
  30 /// functions. Instances can be instantiated and given to a
  31 /// Communication class to perform communications where clients can
  32 /// listen for broadcasts, and perform other higher level communications.
  33 //----------------------------------------------------------------------
  34 class Connection
  35 {
  36 public:
  37     //------------------------------------------------------------------
  38     /// Default constructor
  39     //------------------------------------------------------------------
  40     Connection ();
  41
  42     //------------------------------------------------------------------
  43     /// Virtual destructor since this class gets subclassed and handed
  44     /// to a Communication object.
  45     //------------------------------------------------------------------
  46     virtual
  47     ~Connection ();
  48
  49     //------------------------------------------------------------------
  50     /// Connect using the connect string \a url.
  51     ///
  52     /// @param[in] url
  53     ///     A string that contains all information needed by the
  54     ///     subclass to connect to another client.
  55     ///
  56     /// @param[out] error_ptr
  57     ///     A pointer to an error object that should be given an
  58     ///     approriate error value if this method returns false. This
  59     ///     value can be NULL if the error value should be ignored.
  60     ///
  61     /// @return
  62     ///     \b True if the connect succeeded, \b false otherwise. The
  63     ///     internal error object should be filled in with an
  64     ///     appropriate value based on the result of this function.
  65     ///
  66     /// @see Error& Communication::GetError ();
  67     //------------------------------------------------------------------
  68     virtual lldb::ConnectionStatus
  69     Connect (const char *url, Error *error_ptr) = 0;
  70
  71     //------------------------------------------------------------------
  72     /// Disconnect the communications connection if one is currently
  73     /// connected.
  74     ///
  75     /// @param[out] error_ptr
  76     ///     A pointer to an error object that should be given an
  77     ///     approriate error value if this method returns false. This
  78     ///     value can be NULL if the error value should be ignored.
  79     ///
  80     /// @return
  81     ///     \b True if the disconnect succeeded, \b false otherwise. The
  82     ///     internal error object should be filled in with an
  83     ///     appropriate value based on the result of this function.
  84     ///
  85     /// @see Error& Communication::GetError ();
  86     //------------------------------------------------------------------
  87     virtual lldb::ConnectionStatus
  88     Disconnect (Error *error_ptr) = 0;
  89
  90     //------------------------------------------------------------------
  91     /// Check if the connection is valid.
  92     ///
  93     /// @return
  94     ///     \b True if this object is currently connected, \b false
  95     ///     otherwise.
  96     //------------------------------------------------------------------
  97     virtual bool
  98     IsConnected () const = 0;
  99
 100     //------------------------------------------------------------------
 101     /// The read function that attempts to read from the connection.
 102     ///
 103     /// @param[in] dst
 104     ///     A destination buffer that must be at least \a dst_len bytes
 105     ///     long.
 106     ///
 107     /// @param[in] dst_len
 108     ///     The number of bytes to attempt to read, and also the max
 109     ///     number of bytes that can be placed into \a dst.
 110     ///
 111     /// @param[out] error_ptr
 112     ///     A pointer to an error object that should be given an
 113     ///     approriate error value if this method returns zero. This
 114     ///     value can be NULL if the error value should be ignored.
 115     ///
 116     /// @return
 117     ///     The number of bytes actually read.
 118     ///
 119     /// @see size_t Communication::Read (void *, size_t, uint32_t);
 120     //------------------------------------------------------------------
 121     virtual size_t
 122     Read (void *dst,
 123           size_t dst_len,
 124           uint32_t timeout_usec,
 125           lldb::ConnectionStatus &status,
 126           Error *error_ptr) = 0;
 127
 128     //------------------------------------------------------------------
 129     /// The actual write function that attempts to write to the
 130     /// communications protocol.
 131     ///
 132     /// Subclasses must override this function.
 133     ///
 134     /// @param[in] src
 135     ///     A source buffer that must be at least \a src_len bytes
 136     ///     long.
 137     ///
 138     /// @param[in] src_len
 139     ///     The number of bytes to attempt to write, and also the
 140     ///     number of bytes are currently available in \a src.
 141     ///
 142     /// @param[out] error_ptr
 143     ///     A pointer to an error object that should be given an
 144     ///     approriate error value if this method returns zero. This
 145     ///     value can be NULL if the error value should be ignored.
 146     ///
 147     /// @return
 148     ///     The number of bytes actually Written.
 149     //------------------------------------------------------------------
 150     virtual size_t
 151     Write (const void *buffer, size_t length, lldb::ConnectionStatus &status, Error *error_ptr) = 0;
 152
 153 private:
 154     //------------------------------------------------------------------
 155     // For Connection only
 156     //------------------------------------------------------------------
 157     DISALLOW_COPY_AND_ASSIGN (Connection);
 158 };
 159
 160 } // namespace lldb_private
 161
 162 #endif  // liblldb_Connection_h_