Connection.h revision 24943d2ee8bfaa7cf5893e4709143924157a5c1e 
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    /// Poll for bytes available if the communications supports it.
51    ///
52    /// @param[in] timeout_usec
53    ///     A timeout value in micro-seconds.
54    ///
55    /// @param[out] error
56    ///     A reference to an error object that should be given an
57    ///     approriate error value if this method returns false. This
58    ///     value can be NULL if the error value should be ignored.
59    ///
60    /// @return
61    ///     \b True if the bytes are, or became available within the
62    ///     timeout period, \b false otherwise.
63    //------------------------------------------------------------------
64    virtual lldb::ConnectionStatus
65    BytesAvailable (uint32_t timeout_usec, Error *error_ptr) = 0;
66
67    //------------------------------------------------------------------
68    /// Connect using the connect string \a url.
69    ///
70    /// @param[in] url
71    ///     A string that contains all information needed by the
72    ///     subclass to connect to another client.
73    ///
74    /// @param[out] error_ptr
75    ///     A pointer to an error object that should be given an
76    ///     approriate error value if this method returns false. This
77    ///     value can be NULL if the error value should be ignored.
78    ///
79    /// @return
80    ///     \b True if the connect succeeded, \b false otherwise. The
81    ///     internal error object should be filled in with an
82    ///     appropriate value based on the result of this function.
83    ///
84    /// @see Error& Communication::GetError ();
85    //------------------------------------------------------------------
86    virtual lldb::ConnectionStatus
87    Connect (const char *url, Error *error_ptr) = 0;
88
89    //------------------------------------------------------------------
90    /// Disconnect the communications connection if one is currently
91    /// connected.
92    ///
93    /// @param[out] error_ptr
94    ///     A pointer to an error object that should be given an
95    ///     approriate error value if this method returns false. This
96    ///     value can be NULL if the error value should be ignored.
97    ///
98    /// @return
99    ///     \b True if the disconnect succeeded, \b false otherwise. The
100    ///     internal error object should be filled in with an
101    ///     appropriate value based on the result of this function.
102    ///
103    /// @see Error& Communication::GetError ();
104    //------------------------------------------------------------------
105    virtual lldb::ConnectionStatus
106    Disconnect (Error *error_ptr) = 0;
107
108    //------------------------------------------------------------------
109    /// Check if the connection is valid.
110    ///
111    /// @return
112    ///     \b True if this object is currently connected, \b false
113    ///     otherwise.
114    //------------------------------------------------------------------
115    virtual bool
116    IsConnected () const = 0;
117
118    //------------------------------------------------------------------
119    /// The read function that attempts to read from the connection.
120    ///
121    /// @param[in] dst
122    ///     A destination buffer that must be at least \a dst_len bytes
123    ///     long.
124    ///
125    /// @param[in] dst_len
126    ///     The number of bytes to attempt to read, and also the max
127    ///     number of bytes that can be placed into \a dst.
128    ///
129    /// @param[out] error_ptr
130    ///     A pointer to an error object that should be given an
131    ///     approriate error value if this method returns zero. This
132    ///     value can be NULL if the error value should be ignored.
133    ///
134    /// @return
135    ///     The number of bytes actually read.
136    ///
137    /// @see size_t Communication::Read (void *, size_t, uint32_t);
138    //------------------------------------------------------------------
139    virtual size_t
140    Read (void *dst, size_t dst_len, lldb::ConnectionStatus &status, Error *error_ptr) = 0;
141
142    //------------------------------------------------------------------
143    /// The actual write function that attempts to write to the
144    /// communications protocol.
145    ///
146    /// Subclasses must override this function.
147    ///
148    /// @param[in] src
149    ///     A source buffer that must be at least \a src_len bytes
150    ///     long.
151    ///
152    /// @param[in] src_len
153    ///     The number of bytes to attempt to write, and also the
154    ///     number of bytes are currently available in \a src.
155    ///
156    /// @param[out] error_ptr
157    ///     A pointer to an error object that should be given an
158    ///     approriate error value if this method returns zero. This
159    ///     value can be NULL if the error value should be ignored.
160    ///
161    /// @return
162    ///     The number of bytes actually Written.
163    //------------------------------------------------------------------
164    virtual size_t
165    Write (const void *buffer, size_t length, lldb::ConnectionStatus &status, Error *error_ptr) = 0;
166
167private:
168    //------------------------------------------------------------------
169    // For Connection only
170    //------------------------------------------------------------------
171    DISALLOW_COPY_AND_ASSIGN (Connection);
172};
173
174} // namespace lldb_private
175
176#endif  // liblldb_Connection_h_
177