h3q_conn.h¶

Structs¶

	Name
struct	h3q_tls_info Negotiated TLS parameters of one connection.

Types¶

	Name
typedef struct h3q_tls_info	h3q_tls_info Negotiated TLS parameters of one connection.

Functions¶

	Name
int	h3q_conn_tls_info(h3q_conn * conn, h3q_tls_info * out)
int	h3q_conn_prepare(h3q_conn * conn, uint32_t idle_timeout_secs)
h3q_stream *	h3q_conn_open_uni_stream(h3q_conn * conn, int64_t * out_id)
h3q_stream *	h3q_conn_accept_stream(h3q_conn * conn)
int	h3q_conn_is_handshake_done(h3q_conn * conn)
int	h3q_conn_is_closed(h3q_conn * conn)
int	h3q_conn_shutdown(h3q_conn * conn, int is_rapid, uint64_t app_error, const char * reason)
void	h3q_conn_free(h3q_conn * conn)
void	h3q_conn_close_reason(h3q_conn * conn, char * buf, size_t buflen)

Types Documentation¶

typedef h3q_tls_info¶

typedef struct h3q_tls_info h3q_tls_info;

Negotiated TLS parameters of one connection.

Functions Documentation¶

function h3q_conn_tls_info¶

int h3q_conn_tls_info(
    h3q_conn * conn,
    h3q_tls_info * out
)

Parameters:

conn Connection to query; NULL reports failure.
out Filled in on success; untouched otherwise.

Return: 1 when out was filled, 0 when the cipher is not yet known.

Read the negotiated TLS parameters of a connection.

function h3q_conn_prepare¶

int h3q_conn_prepare(
    h3q_conn * conn,
    uint32_t idle_timeout_secs
)

Parameters:

conn Connection to prepare; NULL reports failure.
idle_timeout_secs Idle timeout to apply, in seconds.

Return: 1 on success, 0 on failure.

Apply the stream modes, incoming-stream policy and idle timeout a freshly accepted connection needs before its handshake is driven.

function h3q_conn_open_uni_stream¶

h3q_stream * h3q_conn_open_uni_stream(
    h3q_conn * conn,
    int64_t * out_id
)

Parameters:

conn Connection to open on.
out_id Out: the new stream's id.

Return: New stream, or NULL on failure.

Open a server-initiated unidirectional stream.

function h3q_conn_accept_stream¶

h3q_stream * h3q_conn_accept_stream(
    h3q_conn * conn
)

Parameters:

conn Connection to accept from; NULL yields NULL.

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

Take the next peer-initiated stream.

function h3q_conn_is_handshake_done¶

int h3q_conn_is_handshake_done(
    h3q_conn * conn
)

Parameters:

conn Connection to query; NULL counts as unfinished.

Return: Non-zero once the handshake is done.

Whether the TLS handshake has completed.

function h3q_conn_is_closed¶

int h3q_conn_is_closed(
    h3q_conn * conn
)

Parameters:

conn Connection to query; NULL counts as closed.

Return: Non-zero once closed.

Whether the connection has finished closing.

function h3q_conn_shutdown¶

int h3q_conn_shutdown(
    h3q_conn * conn,
    int is_rapid,
    uint64_t app_error,
    const char * reason
)

Parameters:

conn Connection to close; NULL counts as already closed.
is_rapid Non-zero to skip the drain, as on server exit.
app_error Application error code to report to the peer.
reason Text accompanying app_error, or NULL to close cleanly.

Return: 1 when shutdown has completed, 0 while still in progress.

Begin or continue connection shutdown.

function h3q_conn_free¶

void h3q_conn_free(
    h3q_conn * conn
)

Parameters:

conn Connection to free; NULL is ignored.

Release a connection handle.

function h3q_conn_close_reason¶

void h3q_conn_close_reason(
    h3q_conn * conn,
    char * buf,
    size_t buflen
)

Parameters:

conn Connection to inspect; NULL reports the error queue alone.
buf Buffer receiving the description, always NUL-terminated.
buflen Capacity of buf; zero is ignored.

Describe why a connection closed, for logging. Reports the peer's error code, frame type and reason string where OpenSSL has them, and whatever the error queue holds otherwise.

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_CONN_H
#define H3Q_CONN_H

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

#include "quic/h3q.h"

typedef struct h3q_tls_info
{
    const char* protocol;
    const char* cipher;
    int cipher_bits;
    int cipher_alg_bits;
    unsigned resumed : 1;
} h3q_tls_info;

int h3q_conn_tls_info(h3q_conn* conn, h3q_tls_info* out);

int h3q_conn_prepare(h3q_conn* conn, uint32_t idle_timeout_secs);

h3q_stream* h3q_conn_open_uni_stream(h3q_conn* conn, int64_t* out_id);

h3q_stream* h3q_conn_accept_stream(h3q_conn* conn);

int h3q_conn_is_handshake_done(h3q_conn* conn);

int h3q_conn_is_closed(h3q_conn* conn);

int h3q_conn_shutdown(h3q_conn* conn, int is_rapid, uint64_t app_error, const char* reason);

void h3q_conn_free(h3q_conn* conn);

void h3q_conn_close_reason(h3q_conn* conn, char* buf, size_t buflen);

#endif /* H3Q_CONN_H */