//===-- Connection.h --------------------------------------------*- C++ -*-===//

//

// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.

// See https://llvm.org/LICENSE.txt for license information.

// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception

//

//===----------------------------------------------------------------------===//

#ifndef LLDB_UTILITY_CONNECTION_H

#define LLDB_UTILITY_CONNECTION_H

#include "lldb/lldb-defines.h"

#include "lldb/lldb-enumerations.h"

#include "lldb/lldb-forward.h"

#include "llvm/ADT/StringRef.h"

#include <ratio>

#include <string>

#include <cstddef>

namespace lldb_private {

class Status;

template <typename Ratio> class Timeout;

}

namespace lldb_private {

/// \class Connection Connection.h "lldb/Utility/Connection.h"

/// A communication connection class.

///

/// A class that implements that actual communication functions for

/// connecting/disconnecting, reading/writing, and waiting for bytes to become

/// available from a two way communication connection.

///

/// This class is designed to only do very simple communication functions.

/// Instances can be instantiated and given to a Communication class to

/// perform communications where clients can listen for broadcasts, and

/// perform other higher level communications.

class Connection {

public:

  /// Default constructor

  Connection() = default;

  /// Virtual destructor since this class gets subclassed and handed to a

  /// Communication object.

  virtual ~Connection();

  /// Connect using the connect string \a url.

  ///

  /// \param[in] url

  ///     A string that contains all information needed by the

  ///     subclass to connect to another client.

  ///

  /// \param[out] error_ptr

  ///     A pointer to an error object that should be given an

  ///     appropriate error value if this method returns false. This

  ///     value can be NULL if the error value should be ignored.

  ///

  /// \return

  ///     \b True if the connect succeeded, \b false otherwise. The

  ///     internal error object should be filled in with an

  ///     appropriate value based on the result of this function.

  ///

  /// \see Status& Communication::GetError ();

  virtual lldb::ConnectionStatus Connect(llvm::StringRef url,

                                         Status *error_ptr) = 0;

  /// Disconnect the communications connection if one is currently connected.

  ///

  /// \param[out] error_ptr

  ///     A pointer to an error object that should be given an

  ///     appropriate error value if this method returns false. This

  ///     value can be NULL if the error value should be ignored.

  ///

  /// \return

  ///     \b True if the disconnect succeeded, \b false otherwise. The

  ///     internal error object should be filled in with an

  ///     appropriate value based on the result of this function.

  ///

  /// \see Status& Communication::GetError ();

  virtual lldb::ConnectionStatus Disconnect(Status *error_ptr) = 0;

  /// Check if the connection is valid.

  ///

  /// \return

  ///     \b True if this object is currently connected, \b false

  ///     otherwise.

  virtual bool IsConnected() const = 0;

  /// The read function that attempts to read from the connection.

  ///

  /// \param[in] dst

  ///     A destination buffer that must be at least \a dst_len bytes

  ///     long.

  ///

  /// \param[in] dst_len

  ///     The number of bytes to attempt to read, and also the max

  ///     number of bytes that can be placed into \a dst.

  ///

  /// \param[in] timeout

  ///     The number of microseconds to wait for the data.

  ///

  /// \param[out] status

  ///     On return, indicates whether the call was successful or terminated

  ///     due to some error condition.

  ///

  /// \param[out] error_ptr

  ///     A pointer to an error object that should be given an

  ///     appropriate error value if this method returns zero. This

  ///     value can be NULL if the error value should be ignored.

  ///

  /// \return

  ///     The number of bytes actually read.

  ///

  /// \see size_t Communication::Read (void *, size_t, uint32_t);

  virtual size_t Read(void *dst, size_t dst_len,

                      const Timeout<std::micro> &timeout,

                      lldb::ConnectionStatus &status, Status *error_ptr) = 0;

  /// The actual write function that attempts to write to the communications

  /// protocol.

  ///

  /// Subclasses must override this function.

  ///

  /// \param[in] dst

  ///     A destination buffer that must be at least \a dst_len bytes

  ///     long.

  ///

  /// \param[in] dst_len

  ///     The number of bytes to attempt to write, and also the

  ///     number of bytes are currently available in \a dst.

  ///

  /// \param[out] error_ptr

  ///     A pointer to an error object that should be given an

  ///     appropriate error value if this method returns zero. This

  ///     value can be NULL if the error value should be ignored.

  ///

  /// \return

  ///     The number of bytes actually Written.

  virtual size_t Write(const void *dst, size_t dst_len,

                       lldb::ConnectionStatus &status, Status *error_ptr) = 0;

  /// Returns a URI that describes this connection object

  ///

  /// Subclasses may override this function.

  ///

  /// \return

  ///     Returns URI or an empty string if disconnecteds

  virtual std::string GetURI() = 0;

  /// Interrupts an ongoing Read() operation.

  ///

  /// If there is an ongoing read operation in another thread, this operation

  /// return with status == eConnectionStatusInterrupted. Note that if there

  /// data waiting to be read and an interrupt request is issued, the Read()

  /// function will return the data immediately without processing the

  /// interrupt request (which will remain queued for the next Read()

  /// operation).

  ///

  /// \return

  ///     Returns true is the interrupt request was successful.

  virtual bool InterruptRead() = 0;

  /// Returns the underlying IOObject used by the Connection.

  ///

  /// The IOObject can be used to wait for data to become available on the

  /// connection. If the Connection does not use IOObjects (and hence does not

  /// support waiting) this function should return a null pointer.

  ///

  /// \return

  ///     The underlying IOObject used for reading.

  virtual lldb::IOObjectSP GetReadObject() { return lldb::IOObjectSP(); };

private:

  // For Connection only

  Connection(const Connection &) = delete;

  const Connection &operator=(const Connection &) = delete;

};

} // namespace lldb_private

#endif // LLDB_UTILITY_CONNECTION_H