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_ 163