build out public api header
This commit is contained in:
@@ -1,4 +1,170 @@
|
||||
// libbravais public api header file
|
||||
|
||||
#ifndef BRAVAIS_H
|
||||
#define BRAVAIS_H
|
||||
|
||||
#include <stddef.h>
|
||||
#include <stdint.h>
|
||||
|
||||
#include "bravais/export.h" // Generated by cmake
|
||||
|
||||
#ifdef __cplusplus
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
#define BRAVAIS_VERSION_MAJOR 0
|
||||
#define BRAVAIS_VERSION_MINOR 1
|
||||
#define BRAVAIS_VERSION_PATCH 0
|
||||
#define BRAVAIS_VERSION ((BRAVAIS_VERSION_MAJOR << 16) | (BRAVAIS_VERSION_MINOR << 8) | BRAVAIS_VERSION_PATCH)
|
||||
|
||||
#define BRAVAIS_NO_TIMEOUT UINT64_MAX
|
||||
|
||||
typedef enum {
|
||||
// Error codes; Generally <0 = error, 0 = success
|
||||
BRAVAIS_EMPTY = 1, // Nothing to emit right now
|
||||
BRAVAIS_OK = 0,
|
||||
BRAVAIS_ERR_INVALID_ARG = -1,
|
||||
BRAVAIS_ERR_BUFFER_TOO_SMALL = -2,
|
||||
BRAVAIS_ERR_MALFORMED = -3,
|
||||
BRAVAIS_ERR_OUT_OF_MEMORY = -4,
|
||||
BRAVAIS_ERR_UNSUPPORTED = -5,
|
||||
|
||||
BRAVAIS_ERR_UNKNOWN = -1000
|
||||
} bravais_result_t;
|
||||
|
||||
typedef enum {
|
||||
BRAVAIS_ROLE_INITIATOR,
|
||||
BRAVAIS_ROLE_RESPONDER
|
||||
} bravais_role_t;
|
||||
|
||||
typedef enum {
|
||||
BRAVAIS_TRANSPORT_MODE_RAW,
|
||||
BRAVAIS_TRANSPORT_MODE_QUIC
|
||||
} bravais_transport_mode_t;
|
||||
|
||||
typedef enum {
|
||||
BRAVAIS_LOG_LEVEL_DEBUG,
|
||||
BRAVAIS_LOG_LEVEL_INFO,
|
||||
BRAVAIS_LOG_LEVEL_WARN,
|
||||
BRAVAIS_LOG_LEVEL_ERROR
|
||||
} bravais_log_level_t;
|
||||
|
||||
/**
|
||||
* @brief Logging callback function type
|
||||
* @param userData User-defined data passed to the logging function
|
||||
* @param level The log level of the message
|
||||
* @param message The log message string
|
||||
*/
|
||||
typedef void (*bravais_log_fn_t)(void* userData, bravais_log_level_t level, const char* message);
|
||||
|
||||
typedef struct {
|
||||
bravais_role_t role;
|
||||
bravais_transport_mode_t transportMode;
|
||||
bravais_log_fn_t logFn;
|
||||
void* logUserData;
|
||||
|
||||
// TODO: Add more configuration options here as needed
|
||||
} bravais_config_t;
|
||||
|
||||
typedef struct bravais_conn bravais_conn_t; // Opaque connection type
|
||||
|
||||
// =============================================================================
|
||||
// Public API functions
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* @brief Runtime library version number, packed as (major << 16) | (minor << 8) | patch
|
||||
* @return The version number, packed as (major << 16) | (minor << 8) | patch
|
||||
*/
|
||||
BRAVAIS_API uint32_t bravais_version(void);
|
||||
|
||||
/**
|
||||
* @brief Initialize the config struct with defaults for all optional fields.
|
||||
* @param config Pointer to a bravais_config_t struct to initialize.
|
||||
* @return BRAVAIS_OK on success, or BRAVAIS_ERR_INVALID_ARG if the config pointer is NULL.
|
||||
* @attention The caller must still set role and transportMode manually.
|
||||
*/
|
||||
BRAVAIS_API bravais_result_t bravais_config_init(const bravais_config_t* config);
|
||||
|
||||
/**
|
||||
* @brief Create a new connection.
|
||||
* @param config The configuration to use for the new connection.
|
||||
* @param outConn A pointer to a bravais_conn_t pointer that will be set to the new connection. Set to NULL on failure.
|
||||
* @return BRAVAIS_OK on success, BRAVAIS_ERR_INVALID_ARG, or BRAVAIS_ERR_OUT_OF_MEMORY.
|
||||
* @attention The config is copied. The caller may reuse or discard it afterwards.
|
||||
*/
|
||||
BRAVAIS_API bravais_result_t bravais_conn_create(const bravais_config_t* config, bravais_conn_t** outConn);
|
||||
|
||||
/**
|
||||
* @brief Destroy a connection.
|
||||
* @param conn The connection to destroy.
|
||||
* @attention NULL is a no-op.
|
||||
*/
|
||||
BRAVAIS_API void bravais_conn_destroy(bravais_conn_t* conn);
|
||||
|
||||
/**
|
||||
* @brief Feed one datagram received from the network.
|
||||
* @param conn The connection to feed the datagram to.
|
||||
* @param data The datagram data received from the network.
|
||||
* @param dataLen The length of the datagram data.
|
||||
* @param nowMs The current time in milliseconds (unix epoch).
|
||||
* @return BRAVAIS_OK on success, BRAVAIS_ERR_INVALID_ARG, or BRAVAIS_ERR_MALFORMED (datagram is malformed).
|
||||
* @attention Any resulting output is queued. Drain it with the poll functions.
|
||||
*/
|
||||
BRAVAIS_API bravais_result_t bravais_recv_datagram(bravais_conn_t* conn, const uint8_t* data, size_t dataLen, uint64_t nowMs);
|
||||
|
||||
/**
|
||||
* @brief Submit one plaintext packet read from the TUN device.
|
||||
* @param conn The connection to submit the packet to.
|
||||
* @param data The packet data read from the TUN device.
|
||||
* @param dataLen The length of the packet data.
|
||||
* @param nowMs The current time in milliseconds (unix epoch).
|
||||
* @return BRAVAIS_OK on success, or BRAVAIS_ERR_INVALID_ARG.
|
||||
* @attention The packet is encrypted and queued for sending. Drain it with bravais_poll_datagram().
|
||||
*/
|
||||
BRAVAIS_API bravais_result_t bravais_send_packet(bravais_conn_t* conn, const uint8_t* data, size_t dataLen, uint64_t nowMs);
|
||||
|
||||
/**
|
||||
* @brief Take the next datagram to send to the network, if any.
|
||||
* @param conn The connection to poll for datagrams.
|
||||
* @param out A buffer to write the datagram to.
|
||||
* @param outCap The capacity of the output buffer.
|
||||
* @param outLen A pointer to a size_t that will be set to the length of the datagram written to the output buffer.
|
||||
* @return BRAVAIS_OK on success, BRAVAIS_EMPTY if no datagram is available (this is NOT an error), or BRAVAIS_ERR_BUFFER_TOO_SMALL.
|
||||
* @attention The caller must provide a buffer large enough to hold the datagram.
|
||||
*/
|
||||
BRAVAIS_API bravais_result_t bravais_poll_datagram(bravais_conn_t* conn, uint8_t* out, size_t outCap, size_t* outLen);
|
||||
|
||||
/**
|
||||
* @brief Take the next decrypted packet to write to the TUN device, if any.
|
||||
* @param conn The connection to poll for packets.
|
||||
* @param out A buffer to write the packet to.
|
||||
* @param outCap The capacity of the output buffer.
|
||||
* @param outLen A pointer to a size_t that will be set to the length of the packet written to the output buffer.
|
||||
* @return BRAVAIS_OK on success, BRAVAIS_EMPTY if no packet is available (this is NOT an error), or BRAVAIS_ERR_BUFFER_TOO_SMALL.
|
||||
* @attention The caller must provide a buffer large enough to hold the packet.
|
||||
* @attention Same buffer semantics as bravais_poll_datagram().
|
||||
*
|
||||
*/
|
||||
BRAVAIS_API bravais_result_t bravais_poll_plaintext(bravais_conn_t* conn, uint8_t* out, size_t outCap, size_t* outLen);
|
||||
|
||||
/**
|
||||
* @brief Earliest time the connection needs bravais_on_timeout() called.
|
||||
* @return Absolute deadline in milliseconds (unix epoch) for the next timeout, or BRAVAIS_NO_TIMEOUT if no timeout is needed.
|
||||
*/
|
||||
BRAVAIS_API uint64_t bravais_get_next_timeout(bravais_conn_t* conn);
|
||||
|
||||
/**
|
||||
* @brief Run any timers due at nowMs.
|
||||
* @param conn The connection to run timers for.
|
||||
* @param nowMs The current time in milliseconds (unix epoch).
|
||||
* @return BRAVAIS_OK on success, or BRAVAIS_ERR_INVALID_ARG.
|
||||
* @attention Safe to call early. No-op if no timers are due yet.
|
||||
*/
|
||||
BRAVAIS_API bravais_result_t bravais_on_timeout(bravais_conn_t* conn, uint64_t nowMs);
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
#endif
|
||||
|
||||
#endif // BRAVAIS_H
|
||||
|
||||
Reference in New Issue
Block a user