hyper/capi/include/hyper.h

/*
 * Copyright 2026 Sean McArthur. MIT License.
 * Generated by gen_header.sh. Do not edit directly.
 *
 * Full docs at: https://docs.rs/hyper/latest/hyper/ffi/index.html
 */

#ifndef _HYPER_H
#define _HYPER_H

#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>

/*
 Return in iter functions to continue iterating.
 */
#define HYPER_ITER_CONTINUE 0

/*
 Return in iter functions to stop iterating.
 */
#define HYPER_ITER_BREAK 1

/*
 An HTTP Version that is unspecified.
 */
#define HYPER_HTTP_VERSION_NONE 0

/*
 The HTTP/1.0 version.
 */
#define HYPER_HTTP_VERSION_1_0 10

/*
 The HTTP/1.1 version.
 */
#define HYPER_HTTP_VERSION_1_1 11

/*
 The HTTP/2 version.
 */
#define HYPER_HTTP_VERSION_2 20

/*
 Sentinel value to return from a read or write callback that the operation
 */
#define HYPER_IO_PENDING 4294967295

/*
 Sentinel value to return from a read or write callback that the operation
 */
#define HYPER_IO_ERROR 4294967294

/*
 Return in a poll function to indicate it was ready.
 */
#define HYPER_POLL_READY 0

/*
 Return in a poll function to indicate it is still pending.
 */
#define HYPER_POLL_PENDING 1

/*
 Return in a poll function indicate an error.
 */
#define HYPER_POLL_ERROR 3

/*
 A return code for many of hyper's methods.
 */
typedef enum hyper_code {
  /*
   All is well.
   */
  HYPERE_OK,
  /*
   General error, details in the `hyper_error *`.
   */
  HYPERE_ERROR,
  /*
   A function argument was invalid.
   */
  HYPERE_INVALID_ARG,
  /*
   The IO transport returned an EOF when one wasn't expected.
   */
  HYPERE_UNEXPECTED_EOF,
  /*
   Aborted by a user supplied callback.
   */
  HYPERE_ABORTED_BY_CALLBACK,
  /*
   An optional hyper feature was not enabled.
   */
  HYPERE_FEATURE_NOT_ENABLED,
  /*
   The peer sent an HTTP message that could not be parsed.
   */
  HYPERE_INVALID_PEER_MESSAGE,
} hyper_code;

/*
 A descriptor for what type a `hyper_task` value is.
 */
typedef enum hyper_task_return_type {
  /*
   The value of this task is null (does not imply an error).
   */
  HYPER_TASK_EMPTY,
  /*
   The value of this task is `hyper_error *`.
   */
  HYPER_TASK_ERROR,
  /*
   The value of this task is `hyper_clientconn *`.
   */
  HYPER_TASK_CLIENTCONN,
  /*
   The value of this task is `hyper_response *`.
   */
  HYPER_TASK_RESPONSE,
  /*
   The value of this task is `hyper_buf *`.
   */
  HYPER_TASK_BUF,
} hyper_task_return_type;

/*
 A streaming HTTP body.
 */
typedef struct hyper_body hyper_body;

/*
 A buffer of bytes that is sent or received on a `hyper_body`.
 */
typedef struct hyper_buf hyper_buf;

/*
 An HTTP client connection handle.
 */
typedef struct hyper_clientconn hyper_clientconn;

/*
 An options builder to configure an HTTP client connection.
 */
typedef struct hyper_clientconn_options hyper_clientconn_options;

/*
 An async context for a task that contains the related waker.
 */
typedef struct hyper_context hyper_context;

/*
 A more detailed error object returned by some hyper functions.
 */
typedef struct hyper_error hyper_error;

/*
 A task executor for `hyper_task`s.
 */
typedef struct hyper_executor hyper_executor;

/*
 An HTTP header map.
 */
typedef struct hyper_headers hyper_headers;

/*
 A read/write handle for a specific connection.
 */
typedef struct hyper_io hyper_io;

/*
 An HTTP request.
 */
typedef struct hyper_request hyper_request;

/*
 An HTTP response.
 */
typedef struct hyper_response hyper_response;

/*
 An async task.
 */
typedef struct hyper_task hyper_task;

/*
 A waker that is saved and used to waken a pending task.
 */
typedef struct hyper_waker hyper_waker;

typedef int (*hyper_body_foreach_callback)(void*, const struct hyper_buf*);

typedef int (*hyper_body_data_callback)(void*, struct hyper_context*, struct hyper_buf**);

typedef void (*hyper_request_on_informational_callback)(void*, struct hyper_response*);

typedef int (*hyper_headers_foreach_callback)(void*, const uint8_t*, size_t, const uint8_t*, size_t);

typedef size_t (*hyper_io_read_callback)(void*, struct hyper_context*, uint8_t*, size_t);

typedef size_t (*hyper_io_write_callback)(void*, struct hyper_context*, const uint8_t*, size_t);

#ifdef __cplusplus
extern "C" {
#endif // __cplusplus

/*
 Returns a static ASCII (null terminated) string of the hyper version.
 */
const char *hyper_version(void);

/*
 Creates a new "empty" body.
 */
struct hyper_body *hyper_body_new(void);

/*
 Free a body.
 */
void hyper_body_free(struct hyper_body *body);

/*
 Creates a task that will poll a response body for the next buffer of data.
 */
struct hyper_task *hyper_body_data(struct hyper_body *body);

/*
 Creates a task to execute the callback with each body chunk received.
 */
struct hyper_task *hyper_body_foreach(struct hyper_body *body,
                                      hyper_body_foreach_callback func,
                                      void *userdata);

/*
 Set userdata on this body, which will be passed to callback functions.
 */
void hyper_body_set_userdata(struct hyper_body *body, void *userdata);

/*
 Set the outgoing data callback for this body.
 */
void hyper_body_set_data_func(struct hyper_body *body, hyper_body_data_callback func);

/*
 Create a new `hyper_buf *` by copying the provided bytes.
 */
struct hyper_buf *hyper_buf_copy(const uint8_t *buf, size_t len);

/*
 Get a pointer to the bytes in this buffer.
 */
const uint8_t *hyper_buf_bytes(const struct hyper_buf *buf);

/*
 Get the length of the bytes this buffer contains.
 */
size_t hyper_buf_len(const struct hyper_buf *buf);

/*
 Free this buffer.
 */
void hyper_buf_free(struct hyper_buf *buf);

/*
 Creates an HTTP client handshake task.
 */
struct hyper_task *hyper_clientconn_handshake(struct hyper_io *io,
                                              struct hyper_clientconn_options *options);

/*
 Creates a task to send a request on the client connection.
 */
struct hyper_task *hyper_clientconn_send(struct hyper_clientconn *conn, struct hyper_request *req);

/*
 Free a `hyper_clientconn *`.
 */
void hyper_clientconn_free(struct hyper_clientconn *conn);

/*
 Creates a new set of HTTP clientconn options to be used in a handshake.
 */
struct hyper_clientconn_options *hyper_clientconn_options_new(void);

/*
 Set whether header case is preserved.
 */
void hyper_clientconn_options_set_preserve_header_case(struct hyper_clientconn_options *opts,
                                                       int enabled);

/*
 Set whether header order is preserved.
 */
void hyper_clientconn_options_set_preserve_header_order(struct hyper_clientconn_options *opts,
                                                        int enabled);

/*
 Free a set of HTTP clientconn options.
 */
void hyper_clientconn_options_free(struct hyper_clientconn_options *opts);

/*
 Set the client background task executor.
 */
void hyper_clientconn_options_exec(struct hyper_clientconn_options *opts,
                                   const struct hyper_executor *exec);

/*
 Set whether to use HTTP2.
 */
enum hyper_code hyper_clientconn_options_http2(struct hyper_clientconn_options *opts, int enabled);

/*
 Set whether HTTP/1 connections accept obsolete line folding for header values.
 */
enum hyper_code hyper_clientconn_options_http1_allow_multiline_headers(struct hyper_clientconn_options *opts,
                                                                       int enabled);

/*
 Frees a `hyper_error`.
 */
void hyper_error_free(struct hyper_error *err);

/*
 Get an equivalent `hyper_code` from this error.
 */
enum hyper_code hyper_error_code(const struct hyper_error *err);

/*
 Print the details of this error to a buffer.
 */
size_t hyper_error_print(const struct hyper_error *err, uint8_t *dst, size_t dst_len);

/*
 Construct a new HTTP request.
 */
struct hyper_request *hyper_request_new(void);

/*
 Free an HTTP request.
 */
void hyper_request_free(struct hyper_request *req);

/*
 Set the HTTP Method of the request.
 */
enum hyper_code hyper_request_set_method(struct hyper_request *req,
                                         const uint8_t *method,
                                         size_t method_len);

/*
 Set the URI of the request.
 */
enum hyper_code hyper_request_set_uri(struct hyper_request *req,
                                      const uint8_t *uri,
                                      size_t uri_len);

/*
 Set the URI of the request with separate scheme, authority, and
 */
enum hyper_code hyper_request_set_uri_parts(struct hyper_request *req,
                                            const uint8_t *scheme,
                                            size_t scheme_len,
                                            const uint8_t *authority,
                                            size_t authority_len,
                                            const uint8_t *path_and_query,
                                            size_t path_and_query_len);

/*
 Set the preferred HTTP version of the request.
 */
enum hyper_code hyper_request_set_version(struct hyper_request *req, int version);

/*
 Gets a mutable reference to the HTTP headers of this request
 */
struct hyper_headers *hyper_request_headers(struct hyper_request *req);

/*
 Set the body of the request.
 */
enum hyper_code hyper_request_set_body(struct hyper_request *req, struct hyper_body *body);

/*
 Set an informational (1xx) response callback.
 */
enum hyper_code hyper_request_on_informational(struct hyper_request *req,
                                               hyper_request_on_informational_callback callback,
                                               void *data);

/*
 Free an HTTP response.
 */
void hyper_response_free(struct hyper_response *resp);

/*
 Get the HTTP-Status code of this response.
 */
uint16_t hyper_response_status(const struct hyper_response *resp);

/*
 Get a pointer to the reason-phrase of this response.
 */
const uint8_t *hyper_response_reason_phrase(const struct hyper_response *resp);

/*
 Get the length of the reason-phrase of this response.
 */
size_t hyper_response_reason_phrase_len(const struct hyper_response *resp);

/*
 Get the HTTP version used by this response.
 */
int hyper_response_version(const struct hyper_response *resp);

/*
 Gets a reference to the HTTP headers of this response.
 */
struct hyper_headers *hyper_response_headers(struct hyper_response *resp);

/*
 Take ownership of the body of this response.
 */
struct hyper_body *hyper_response_body(struct hyper_response *resp);

/*
 Iterates the headers passing each name and value pair to the callback.
 */
void hyper_headers_foreach(const struct hyper_headers *headers,
                           hyper_headers_foreach_callback func,
                           void *userdata);

/*
 Sets the header with the provided name to the provided value.
 */
enum hyper_code hyper_headers_set(struct hyper_headers *headers,
                                  const uint8_t *name,
                                  size_t name_len,
                                  const uint8_t *value,
                                  size_t value_len);

/*
 Adds the provided value to the list of the provided name.
 */
enum hyper_code hyper_headers_add(struct hyper_headers *headers,
                                  const uint8_t *name,
                                  size_t name_len,
                                  const uint8_t *value,
                                  size_t value_len);

/*
 Create a new IO type used to represent a transport.
 */
struct hyper_io *hyper_io_new(void);

/*
 Free an IO handle.
 */
void hyper_io_free(struct hyper_io *io);

/*
 Set the user data pointer for this IO to some value.
 */
void hyper_io_set_userdata(struct hyper_io *io, void *data);

/*
 Set the read function for this IO transport.
 */
void hyper_io_set_read(struct hyper_io *io, hyper_io_read_callback func);

/*
 Set the write function for this IO transport.
 */
void hyper_io_set_write(struct hyper_io *io, hyper_io_write_callback func);

/*
 Creates a new task executor.
 */
const struct hyper_executor *hyper_executor_new(void);

/*
 Frees an executor and any incomplete tasks still part of it.
 */
void hyper_executor_free(const struct hyper_executor *exec);

/*
 Push a task onto the executor.
 */
enum hyper_code hyper_executor_push(const struct hyper_executor *exec, struct hyper_task *task);

/*
 Polls the executor, trying to make progress on any tasks that can do so.
 */
struct hyper_task *hyper_executor_poll(const struct hyper_executor *exec);

/*
 Free a task.
 */
void hyper_task_free(struct hyper_task *task);

/*
 Takes the output value of this task.
 */
void *hyper_task_value(struct hyper_task *task);

/*
 Query the return type of this task.
 */
enum hyper_task_return_type hyper_task_type(struct hyper_task *task);

/*
 Set a user data pointer to be associated with this task.
 */
void hyper_task_set_userdata(struct hyper_task *task, void *userdata);

/*
 Retrieve the userdata that has been set via `hyper_task_set_userdata`.
 */
void *hyper_task_userdata(struct hyper_task *task);

/*
 Creates a waker associated with the task context.
 */
struct hyper_waker *hyper_context_waker(struct hyper_context *cx);

/*
 Free a waker.
 */
void hyper_waker_free(struct hyper_waker *waker);

/*
 Wake up the task associated with a waker.
 */
void hyper_waker_wake(struct hyper_waker *waker);

#ifdef __cplusplus
}  // extern "C"
#endif  // __cplusplus

#endif  /* _HYPER_H */