Connection.h revision 360784
159078Smdodd//===-- Connection.h --------------------------------------------*- C++ -*-===// 259078Smdodd// 359078Smdodd// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 434480Sjulian// See https://llvm.org/LICENSE.txt for license information. 534480Sjulian// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 634480Sjulian// 734480Sjulian//===----------------------------------------------------------------------===// 834480Sjulian 959078Smdodd#ifndef liblldb_Connection_h_ 1034480Sjulian#define liblldb_Connection_h_ 1134480Sjulian 1234480Sjulian#include "lldb/lldb-defines.h" 1334480Sjulian#include "lldb/lldb-enumerations.h" 1434480Sjulian#include "lldb/lldb-forward.h" 1534480Sjulian 1634480Sjulian#include "llvm/ADT/StringRef.h" 1759078Smdodd 1859078Smdodd#include <ratio> 1934480Sjulian#include <string> 2034480Sjulian 2134480Sjulian#include <stddef.h> 2234480Sjulian 2334480Sjuliannamespace lldb_private { 2434480Sjulianclass Status; 2559078Smdoddtemplate <typename Ratio> class Timeout; 2659078Smdodd} 2734480Sjulian 2834480Sjuliannamespace lldb_private { 2934480Sjulian 3034480Sjulian/// \class Connection Connection.h "lldb/Utility/Connection.h" 3134480Sjulian/// A communication connection class. 3245791Speter/// 3345791Speter/// A class that implements that actual communication functions for 3434480Sjulian/// connecting/disconnecting, reading/writing, and waiting for bytes to become 3539234Sgibbs/// available from a two way communication connection. 3639234Sgibbs/// 3745791Speter/// This class is designed to only do very simple communication functions. 3845791Speter/// Instances can be instantiated and given to a Communication class to 3934480Sjulian/// perform communications where clients can listen for broadcasts, and 4059078Smdodd/// perform other higher level communications. 4159078Smdoddclass Connection { 4239234Sgibbspublic: 4339234Sgibbs /// Default constructor 4439234Sgibbs Connection() = default; 4539234Sgibbs 4652042Smdodd /// Virtual destructor since this class gets subclassed and handed to a 4752042Smdodd /// Communication object. 4852042Smdodd virtual ~Connection(); 4952042Smdodd 5059078Smdodd /// Connect using the connect string \a url. 5159078Smdodd /// 5259078Smdodd /// \param[in] url 5359078Smdodd /// A string that contains all information needed by the 5459078Smdodd /// subclass to connect to another client. 5559078Smdodd /// 5659078Smdodd /// \param[out] error_ptr 5759078Smdodd /// A pointer to an error object that should be given an 5859078Smdodd /// appropriate error value if this method returns false. This 5959078Smdodd /// value can be NULL if the error value should be ignored. 6059078Smdodd /// 6159078Smdodd /// \return 6259078Smdodd /// \b True if the connect succeeded, \b false otherwise. The 6352042Smdodd /// internal error object should be filled in with an 6434480Sjulian /// appropriate value based on the result of this function. 6534480Sjulian /// 6659078Smdodd /// \see Status& Communication::GetError (); 6759078Smdodd virtual lldb::ConnectionStatus Connect(llvm::StringRef url, 6859078Smdodd Status *error_ptr) = 0; 6934480Sjulian 7059078Smdodd /// Disconnect the communications connection if one is currently connected. 7139234Sgibbs /// 7259078Smdodd /// \param[out] error_ptr 7334480Sjulian /// A pointer to an error object that should be given an 7452042Smdodd /// appropriate error value if this method returns false. This 7552042Smdodd /// value can be NULL if the error value should be ignored. 7652042Smdodd /// 7734480Sjulian /// \return 7845791Speter /// \b True if the disconnect succeeded, \b false otherwise. The 7945791Speter /// internal error object should be filled in with an 8045791Speter /// appropriate value based on the result of this function. 8145791Speter /// 8234480Sjulian /// \see Status& Communication::GetError (); 8352042Smdodd virtual lldb::ConnectionStatus Disconnect(Status *error_ptr) = 0; 8445791Speter 8552042Smdodd /// Check if the connection is valid. 8652042Smdodd /// 8752042Smdodd /// \return 8852042Smdodd /// \b True if this object is currently connected, \b false 8945791Speter /// otherwise. 9034480Sjulian virtual bool IsConnected() const = 0; 9152042Smdodd 9252042Smdodd /// The read function that attempts to read from the connection. 9352042Smdodd /// 9445791Speter /// \param[in] dst 9545791Speter /// A destination buffer that must be at least \a dst_len bytes 9634480Sjulian /// long. 9734480Sjulian /// 9845791Speter /// \param[in] dst_len 9959078Smdodd /// The number of bytes to attempt to read, and also the max 10034480Sjulian /// number of bytes that can be placed into \a dst. 10159078Smdodd /// 10245791Speter /// \param[in] timeout 10345791Speter /// The number of microseconds to wait for the data. 10439234Sgibbs /// 10545791Speter /// \param[out] status 10659078Smdodd /// On return, indicates whether the call was successful or terminated 10759078Smdodd /// due to some error condition. 10834480Sjulian /// 10945791Speter /// \param[out] error_ptr 11059078Smdodd /// A pointer to an error object that should be given an 11145791Speter /// appropriate error value if this method returns zero. This 11245791Speter /// value can be NULL if the error value should be ignored. 11359078Smdodd /// 11459078Smdodd /// \return 11534480Sjulian /// The number of bytes actually read. 11634480Sjulian /// 11759078Smdodd /// \see size_t Communication::Read (void *, size_t, uint32_t); 11859078Smdodd virtual size_t Read(void *dst, size_t dst_len, 11959078Smdodd const Timeout<std::micro> &timeout, 12059078Smdodd lldb::ConnectionStatus &status, Status *error_ptr) = 0; 12159078Smdodd 12259078Smdodd /// The actual write function that attempts to write to the communications 12359078Smdodd /// protocol. 12459078Smdodd /// 12559078Smdodd /// Subclasses must override this function. 12645791Speter /// 12759078Smdodd /// \param[in] dst 12859078Smdodd /// A desination buffer that must be at least \a dst_len bytes 12945791Speter /// long. 13059078Smdodd /// 13134480Sjulian /// \param[in] dst_len 13239234Sgibbs /// The number of bytes to attempt to write, and also the 13339234Sgibbs /// number of bytes are currently available in \a dst. 13459078Smdodd /// 13559078Smdodd /// \param[out] error_ptr 13659078Smdodd /// A pointer to an error object that should be given an 13759078Smdodd /// appropriate error value if this method returns zero. This 13859078Smdodd /// value can be NULL if the error value should be ignored. 13959078Smdodd /// 14059078Smdodd /// \return 14159078Smdodd /// The number of bytes actually Written. 142104710Speter virtual size_t Write(const void *dst, size_t dst_len, 14359078Smdodd lldb::ConnectionStatus &status, Status *error_ptr) = 0; 14459078Smdodd 14559078Smdodd /// Returns a URI that describes this connection object 14639234Sgibbs /// 14759078Smdodd /// Subclasses may override this function. 14845791Speter /// 14934480Sjulian /// \return 15034480Sjulian /// Returns URI or an empty string if disconnecteds 15159078Smdodd virtual std::string GetURI() = 0; 15234480Sjulian 15339234Sgibbs /// Interrupts an ongoing Read() operation. 15439234Sgibbs /// 15559078Smdodd /// If there is an ongoing read operation in another thread, this operation 15645791Speter /// return with status == eConnectionStatusInterrupted. Note that if there 15734480Sjulian /// data waiting to be read and an interrupt request is issued, the Read() 15834480Sjulian /// function will return the data immediately without processing the 15939234Sgibbs /// interrupt request (which will remain queued for the next Read() 16039234Sgibbs /// operation). 16145791Speter /// 16239234Sgibbs /// \return 16334480Sjulian /// Returns true is the interrupt request was successful. 16473280Smarkm virtual bool InterruptRead() = 0; 16573280Smarkm 16659078Smdodd /// Returns the underlying IOObject used by the Connection. 16759078Smdodd /// 16859078Smdodd /// The IOObject can be used to wait for data to become available on the 16959078Smdodd /// connection. If the Connection does not use IOObjects (and hence does not 17045791Speter /// support waiting) this function should return a null pointer. 17159078Smdodd /// 17259078Smdodd /// \return 17345791Speter /// The underlying IOObject used for reading. 17445791Speter virtual lldb::IOObjectSP GetReadObject() { return lldb::IOObjectSP(); }; 17545791Speter 17645791Speterprivate: 17745791Speter // For Connection only 17859078Smdodd DISALLOW_COPY_AND_ASSIGN(Connection); 17959078Smdodd}; 18034480Sjulian 18134480Sjulian} // namespace lldb_private 18234480Sjulian 18334480Sjulian#endif // liblldb_Connection_h_ 18434480Sjulian