h3q.h¶

Structs¶

	Name
struct	h3q_config

Types¶

	Name
typedef struct h3q_engine	h3q_engine
typedef struct h3q_conn	h3q_conn
typedef struct h3q_stream	h3q_stream
typedef struct h3q_config	h3q_config

Functions¶

	Name
h3q_engine *	h3q_engine_create(const h3q_config * cfg, int udp_fd, char * err, size_t errlen)
void	h3q_engine_destroy(h3q_engine * engine)
int	h3q_engine_pump(h3q_engine * engine)
void	h3q_engine_want(h3q_engine * engine, int * want_read, int * want_write, int * timeout_ms)
h3q_conn *	h3q_engine_accept_conn(h3q_engine * engine)
int	h3q_engine_peer_addr(h3q_engine * engine, h3q_conn * conn, struct sockaddr_storage * addr, socklen_t * addr_len)

Defines¶

	Name
	H3Q_ERRLEN

Types Documentation¶

typedef h3q_engine¶

typedef struct h3q_engine h3q_engine;

typedef h3q_conn¶

typedef struct h3q_conn h3q_conn;

typedef h3q_stream¶

typedef struct h3q_stream h3q_stream;

typedef h3q_config¶

typedef struct h3q_config h3q_config;

Everything the listener needs to exist. The idle timeout is not here: it is a per-connection setting, applied by h3q_conn_prepare().

Functions Documentation¶

function h3q_engine_create¶

h3q_engine * h3q_engine_create(
    const h3q_config * cfg,
    int udp_fd,
    char * err,
    size_t errlen
)

Parameters:

cfg Certificate, key and address validation.
udp_fd Pre-opened non-blocking UDP socket bound to the listen port, borrowed for the engine's lifetime.
err Buffer receiving the reason on failure; may be NULL.
errlen Capacity of err.

Return: New engine, or NULL on failure.

Build the QUIC listener on udp_fd, together with the filter BIO that recovers peer addresses from OpenSSL's accept queue.

function h3q_engine_destroy¶

void h3q_engine_destroy(
    h3q_engine * engine
)

Parameters:

engine Engine to destroy; NULL is ignored.

Tear down the listener, its TLS context and any datagrams still queued.

function h3q_engine_pump¶

int h3q_engine_pump(
    h3q_engine * engine
)

Parameters:

engine Engine to pump; NULL reports no work.

Return: 1 if work was done and another pass may be useful, 0 if idle, and -1 if the listener stopped processing events.

Drive one round of listener work: read datagrams, run timers, send.

function h3q_engine_want¶

void h3q_engine_want(
    h3q_engine * engine,
    int * want_read,
    int * want_write,
    int * timeout_ms
)

Parameters:

engine Engine to query; NULL asks for neither, on a one-second wait.
want_read Out: non-zero if the socket should be polled for reads.
want_write Out: non-zero if the socket should be polled for writes.
timeout_ms In/out: lowered to the next timer when one is due sooner, never below one millisecond.

Report what the engine needs from the next event-loop wait.

function h3q_engine_accept_conn¶

h3q_conn * h3q_engine_accept_conn(
    h3q_engine * engine
)

Parameters:

engine Engine to accept from; NULL yields NULL.

Return: Accepted connection, or NULL if none is ready.

Take the next handshaken connection off the accept queue.

function h3q_engine_peer_addr¶

int h3q_engine_peer_addr(
    h3q_engine * engine,
    h3q_conn * conn,
    struct sockaddr_storage * addr,
    socklen_t * addr_len
)

Parameters:

engine Engine owning conn; NULL reports failure.
conn Connection to inspect.
addr Out: peer socket address.
addr_len Out: bytes of addr that are meaningful.

Return: 1 if the address was recovered, 0 otherwise.

Recover the peer address the filter BIO recorded for conn.

Macros Documentation¶

define H3Q_ERRLEN¶

#define H3Q_ERRLEN 256

Source code¶

/*
 * Copyright (c) 2026 The mod_http3 Project Authors. All rights reserved.
 *
 * SPDX-License-Identifier: Apache-2.0
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#ifndef H3Q_H
#define H3Q_H

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

#include "h3_os.h"

typedef struct h3q_engine h3q_engine;
typedef struct h3q_conn h3q_conn;
typedef struct h3q_stream h3q_stream;

#define H3Q_ERRLEN 256

typedef struct h3q_config
{
    const char* cert_path;
    const char* key_path;
    unsigned address_validation : 1;
    unsigned session_tickets : 1;
} h3q_config;

h3q_engine* h3q_engine_create(const h3q_config* cfg, int udp_fd, char* err, size_t errlen);

void h3q_engine_destroy(h3q_engine* engine);

int h3q_engine_pump(h3q_engine* engine);

void h3q_engine_want(h3q_engine* engine, int* want_read, int* want_write, int* timeout_ms);

h3q_conn* h3q_engine_accept_conn(h3q_engine* engine);

int h3q_engine_peer_addr(h3q_engine* engine, h3q_conn* conn, struct sockaddr_storage* addr, socklen_t* addr_len);

#endif /* H3Q_H */