1320543Sdim//===-- Connection.h --------------------------------------------*- C++ -*-===// 2320543Sdim// 3353358Sdim// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 4353358Sdim// See https://llvm.org/LICENSE.txt for license information. 5353358Sdim// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 6320543Sdim// 7320543Sdim//===----------------------------------------------------------------------===// 8320543Sdim 9320543Sdim#ifndef liblldb_Connection_h_ 10320543Sdim#define liblldb_Connection_h_ 11320543Sdim 12344779Sdim#include "lldb/lldb-defines.h" 13344779Sdim#include "lldb/lldb-enumerations.h" 14344779Sdim#include "lldb/lldb-forward.h" 15320543Sdim 16344779Sdim#include "llvm/ADT/StringRef.h" 17320543Sdim 18344779Sdim#include <ratio> 19320543Sdim#include <string> 20320543Sdim 21344779Sdim#include <stddef.h> 22320543Sdim 23320543Sdimnamespace lldb_private { 24320543Sdimclass Status; 25320543Sdimtemplate <typename Ratio> class Timeout; 26320543Sdim} 27320543Sdim 28320543Sdimnamespace lldb_private { 29320543Sdim 30353358Sdim/// \class Connection Connection.h "lldb/Utility/Connection.h" 31341825Sdim/// A communication connection class. 32320543Sdim/// 33320543Sdim/// A class that implements that actual communication functions for 34341825Sdim/// connecting/disconnecting, reading/writing, and waiting for bytes to become 35341825Sdim/// available from a two way communication connection. 36320543Sdim/// 37341825Sdim/// This class is designed to only do very simple communication functions. 38341825Sdim/// Instances can be instantiated and given to a Communication class to 39341825Sdim/// perform communications where clients can listen for broadcasts, and 40341825Sdim/// perform other higher level communications. 41320543Sdimclass Connection { 42320543Sdimpublic: 43320543Sdim /// Default constructor 44320543Sdim Connection() = default; 45320543Sdim 46341825Sdim /// Virtual destructor since this class gets subclassed and handed to a 47341825Sdim /// Communication object. 48320543Sdim virtual ~Connection(); 49320543Sdim 50320543Sdim /// Connect using the connect string \a url. 51320543Sdim /// 52353358Sdim /// \param[in] url 53320543Sdim /// A string that contains all information needed by the 54320543Sdim /// subclass to connect to another client. 55320543Sdim /// 56353358Sdim /// \param[out] error_ptr 57320543Sdim /// A pointer to an error object that should be given an 58320543Sdim /// appropriate error value if this method returns false. This 59320543Sdim /// value can be NULL if the error value should be ignored. 60320543Sdim /// 61353358Sdim /// \return 62320543Sdim /// \b True if the connect succeeded, \b false otherwise. The 63320543Sdim /// internal error object should be filled in with an 64320543Sdim /// appropriate value based on the result of this function. 65320543Sdim /// 66353358Sdim /// \see Status& Communication::GetError (); 67320543Sdim virtual lldb::ConnectionStatus Connect(llvm::StringRef url, 68320543Sdim Status *error_ptr) = 0; 69320543Sdim 70341825Sdim /// Disconnect the communications connection if one is currently connected. 71320543Sdim /// 72353358Sdim /// \param[out] error_ptr 73320543Sdim /// A pointer to an error object that should be given an 74320543Sdim /// appropriate error value if this method returns false. This 75320543Sdim /// value can be NULL if the error value should be ignored. 76320543Sdim /// 77353358Sdim /// \return 78320543Sdim /// \b True if the disconnect succeeded, \b false otherwise. The 79320543Sdim /// internal error object should be filled in with an 80320543Sdim /// appropriate value based on the result of this function. 81320543Sdim /// 82353358Sdim /// \see Status& Communication::GetError (); 83320543Sdim virtual lldb::ConnectionStatus Disconnect(Status *error_ptr) = 0; 84320543Sdim 85320543Sdim /// Check if the connection is valid. 86320543Sdim /// 87353358Sdim /// \return 88320543Sdim /// \b True if this object is currently connected, \b false 89320543Sdim /// otherwise. 90320543Sdim virtual bool IsConnected() const = 0; 91320543Sdim 92320543Sdim /// The read function that attempts to read from the connection. 93320543Sdim /// 94353358Sdim /// \param[in] dst 95320543Sdim /// A destination buffer that must be at least \a dst_len bytes 96320543Sdim /// long. 97320543Sdim /// 98353358Sdim /// \param[in] dst_len 99320543Sdim /// The number of bytes to attempt to read, and also the max 100320543Sdim /// number of bytes that can be placed into \a dst. 101320543Sdim /// 102353358Sdim /// \param[in] timeout 103320543Sdim /// The number of microseconds to wait for the data. 104320543Sdim /// 105353358Sdim /// \param[out] status 106320543Sdim /// On return, indicates whether the call was successful or terminated 107320543Sdim /// due to some error condition. 108320543Sdim /// 109353358Sdim /// \param[out] error_ptr 110320543Sdim /// A pointer to an error object that should be given an 111320543Sdim /// appropriate error value if this method returns zero. This 112320543Sdim /// value can be NULL if the error value should be ignored. 113320543Sdim /// 114353358Sdim /// \return 115320543Sdim /// The number of bytes actually read. 116320543Sdim /// 117353358Sdim /// \see size_t Communication::Read (void *, size_t, uint32_t); 118320543Sdim virtual size_t Read(void *dst, size_t dst_len, 119320543Sdim const Timeout<std::micro> &timeout, 120320543Sdim lldb::ConnectionStatus &status, Status *error_ptr) = 0; 121320543Sdim 122341825Sdim /// The actual write function that attempts to write to the communications 123341825Sdim /// protocol. 124320543Sdim /// 125320543Sdim /// Subclasses must override this function. 126320543Sdim /// 127353358Sdim /// \param[in] dst 128320543Sdim /// A desination buffer that must be at least \a dst_len bytes 129320543Sdim /// long. 130320543Sdim /// 131353358Sdim /// \param[in] dst_len 132320543Sdim /// The number of bytes to attempt to write, and also the 133320543Sdim /// number of bytes are currently available in \a dst. 134320543Sdim /// 135353358Sdim /// \param[out] error_ptr 136320543Sdim /// A pointer to an error object that should be given an 137320543Sdim /// appropriate error value if this method returns zero. This 138320543Sdim /// value can be NULL if the error value should be ignored. 139320543Sdim /// 140353358Sdim /// \return 141320543Sdim /// The number of bytes actually Written. 142320543Sdim virtual size_t Write(const void *dst, size_t dst_len, 143320543Sdim lldb::ConnectionStatus &status, Status *error_ptr) = 0; 144320543Sdim 145320543Sdim /// Returns a URI that describes this connection object 146320543Sdim /// 147320543Sdim /// Subclasses may override this function. 148320543Sdim /// 149353358Sdim /// \return 150320543Sdim /// Returns URI or an empty string if disconnecteds 151320543Sdim virtual std::string GetURI() = 0; 152320543Sdim 153320543Sdim /// Interrupts an ongoing Read() operation. 154320543Sdim /// 155320543Sdim /// If there is an ongoing read operation in another thread, this operation 156320543Sdim /// return with status == eConnectionStatusInterrupted. Note that if there 157320543Sdim /// data waiting to be read and an interrupt request is issued, the Read() 158320543Sdim /// function will return the data immediately without processing the 159320543Sdim /// interrupt request (which will remain queued for the next Read() 160320543Sdim /// operation). 161320543Sdim /// 162353358Sdim /// \return 163320543Sdim /// Returns true is the interrupt request was successful. 164320543Sdim virtual bool InterruptRead() = 0; 165320543Sdim 166320543Sdim /// Returns the underlying IOObject used by the Connection. 167320543Sdim /// 168341825Sdim /// The IOObject can be used to wait for data to become available on the 169341825Sdim /// connection. If the Connection does not use IOObjects (and hence does not 170341825Sdim /// support waiting) this function should return a null pointer. 171320543Sdim /// 172353358Sdim /// \return 173320543Sdim /// The underlying IOObject used for reading. 174360784Sdim virtual lldb::IOObjectSP GetReadObject() { return lldb::IOObjectSP(); }; 175320543Sdim 176320543Sdimprivate: 177320543Sdim // For Connection only 178320543Sdim DISALLOW_COPY_AND_ASSIGN(Connection); 179320543Sdim}; 180320543Sdim 181320543Sdim} // namespace lldb_private 182320543Sdim 183320543Sdim#endif // liblldb_Connection_h_ 184