Connection.h revision 254721
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 19namespace 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//---------------------------------------------------------------------- 34class Connection 35{ 36public: 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 153private: 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