native_connection.h

Go to the documentation of this file.

/**
 * @file
 * @brief Declares the native connection abstraction and transport metadata helpers.
 */
 
#ifndef PHAROS_NATIVE_CONNECTION_H
#define PHAROS_NATIVE_CONNECTION_H
 
#include <signal.h>
#include <stddef.h>
 
/**
 * @brief Transport type used by a native connection.
 */
typedef enum {
  NATIVE_TRANSPORT_UNKNOWN = 0, /**< Transport metadata is not yet known. */
  NATIVE_TRANSPORT_TCP = 1,     /**< Connection is backed by a TCP socket. */
  NATIVE_TRANSPORT_UNIX = 2     /**< Connection is backed by a Unix domain socket. */
} NativeTransportType;
 
/**
 * @brief Accepted client connection and its resolved transport metadata.
 */
typedef struct {
  int fd;                        /**< Connected socket file descriptor. */
  NativeTransportType transport_type; /**< Resolved socket transport type. */
  char *peer_info;               /**< Printable remote endpoint description. */
  char *local_info;              /**< Printable local endpoint description. */
} NativeConnection;
 
/** @name Native connection helpers
 * @{
 */
/**
 * @brief Initializes a native connection record to an empty state.
 * @param connection Connection record to initialize.
 */
void native_connection_init(NativeConnection *connection);
/**
 * @brief Releases owned transport metadata and resets a connection record.
 * @param connection Connection record to clear.
 */
void native_connection_reset(NativeConnection *connection);
/**
 * @brief Accepts the next client connection and records its transport metadata.
 * @param server_fd Listening socket descriptor.
 * @param shutdown_requested Shared shutdown flag checked while accepting.
 * @param connection Destination connection record.
 * @return Positive when a client was accepted, 0 when shutdown was requested, or a negative value on error.
 */
int native_connection_accept_next(int server_fd, volatile sig_atomic_t *shutdown_requested, NativeConnection *connection);
/**
 * @brief Reads bytes from a native connection.
 * @param connection Open connection to read from.
 * @param buffer Destination buffer.
 * @param len Maximum number of bytes to read.
 * @return Number of bytes read, or a negative value on error.
 */
int native_connection_read(NativeConnection *connection, void *buffer, size_t len);
/**
 * @brief Writes bytes to a native connection.
 * @param connection Open connection to write to.
 * @param buffer Source bytes to send.
 * @param len Number of bytes to send.
 * @return Number of bytes written, or a negative value on error.
 */
int native_connection_write(NativeConnection *connection, const void *buffer, size_t len);
/**
 * @brief Flushes any buffered connection output when the transport requires it.
 * @param connection Connection to flush.
 * @return 0 on success, or a negative value on error.
 */
int native_connection_flush(NativeConnection *connection);
/**
 * @brief Closes a native connection and releases its owned metadata.
 * @param connection Connection to close.
 * @return 0 on success, or a negative value on error.
 */
int native_connection_close(NativeConnection *connection);
/**
 * @brief Shuts down a native connection without discarding the record itself.
 * @param connection Connection to shut down.
 * @return 0 on success, or a negative value on error.
 */
int native_connection_shutdown(NativeConnection *connection);
/**
 * @brief Returns the printable remote endpoint description for a connection.
 * @param connection Connection to inspect.
 * @return Pointer to owned peer-info text, or NULL when unavailable.
 */
const char *native_connection_peer_info(const NativeConnection *connection);
/**
 * @brief Returns the printable local endpoint description for a connection.
 * @param connection Connection to inspect.
 * @return Pointer to owned local-info text, or NULL when unavailable.
 */
const char *native_connection_local_info(const NativeConnection *connection);
/**
 * @brief Returns the resolved transport type for a connection.
 * @param connection Connection to inspect.
 * @return Transport type recorded for the connection.
 */
NativeTransportType native_connection_transport_type(const NativeConnection *connection);
/**
 * @brief Returns a human-readable transport type name for a connection.
 * @param connection Connection to inspect.
 * @return Static transport type name string.
 */
const char *native_connection_transport_type_name(const NativeConnection *connection);
 
 
/** @} */
#endif