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