mod_http3/include/h3_callbacks.h¶

Functions¶

Functions Documentation¶

function on_begin_headers¶

int on_begin_headers(
    nghttp3_conn * conn,
    int64_t stream_id,
    void * user_data,
    void * stream_user_data
)

Parameters:

• conn The nghttp3 connection.
• stream_id QUIC stream id the headers are arriving on.
• user_data The h3_session (set via nghttp3_conn_set_user_data).
• stream_user_data Pre-allocated h3_stream from the session's pending slot, or NULL.

Return: 0 on success, NGHTTP3_ERR_CALLBACK_FAILURE on missing session.

nghttp3 begin_headers callback. Allocates the h3_stream tracking structure for stream_id (or binds the session's pending one) and records it as nghttp3's stream user data.

function on_recv_header¶

int on_recv_header(
    nghttp3_conn * conn,
    int64_t stream_id,
    int32_t token,
    nghttp3_rcbuf * name,
    nghttp3_rcbuf * value,
    uint8_t flags,
    void * user_data,
    void * stream_user_data
)

Parameters:

• conn The nghttp3 connection.
• stream_id QUIC stream id the header belongs to.
• token QPACK token id, or -1 for a non-indexed field.
• name Header name (raw, for non-indexed fields).
• value Header value bytes.
• flags nghttp3 header flags (e.g. NGHTTP3_NVA_FLAG_NEVER_INDEX).
• user_data The h3_session.
• stream_user_data The h3_stream.

Return: 0 on success, NGHTTP3_ERR_MALFORMED_HTTP_HEADER on a bad pseudo-header, NGHTTP3_ERR_CALLBACK_FAILURE on missing stream.

nghttp3 recv_header callback. Stores a single header field on the stream. Pseudo-headers (:method, :scheme, :path, :authority) go into dedicated slots; other headers go into the stream's headers table.

function on_end_headers¶

int on_end_headers(
    nghttp3_conn * conn,
    int64_t stream_id,
    int fin,
    void * user_data,
    void * stream_user_data
)

Parameters:

• conn The nghttp3 connection.
• stream_id QUIC stream id whose headers just ended.
• fin Non-zero if request has no body.
• user_data The h3_session.
• stream_user_data The h3_stream.

Return: 0 on success, NGHTTP3_ERR_CALLBACK_FAILURE on missing stream.

nghttp3 end_headers callback. Marks the stream as having complete request headers and body if FIN is set.

function on_recv_data¶

int on_recv_data(
    nghttp3_conn * conn,
    int64_t stream_id,
    const uint8_t * data,
    size_t datalen,
    void * user_data,
    void * stream_user_data
)

Parameters:

• conn The nghttp3 connection.
• stream_id QUIC stream id receiving data.
• data The DATA payload bytes.
• datalen Length of data in bytes.
• user_data The h3_session.
• stream_user_data The h3_stream.

Return: 0 on success, NGHTTP3_ERR_CALLBACK_FAILURE on missing stream.

nghttp3 recv_data callback. Appends request body for stream_id.

function on_acked_stream_data¶

int on_acked_stream_data(
    nghttp3_conn * conn,
    int64_t stream_id,
    uint64_t datalen,
    void * user_data,
    void * stream_user_data
)

Parameters:

• conn The nghttp3 connection.
• stream_id QUIC stream id whose response data was acked.
• datalen Number of body bytes acknowledged.
• user_data The h3_session.
• stream_user_data The h3_stream.

Return: 0 on success, NGHTTP3_ERR_CALLBACK_FAILURE on nghttp3 error.

nghttp3 acked_stream_data callback. datalen bytes of response body are acknowledged; release that much of the stream's bounded response queue and wake the producer blocked in h3_stream_response_append.

function on_deferred_consume¶

int on_deferred_consume(
    nghttp3_conn * conn,
    int64_t stream_id,
    size_t consumed,
    void * user_data,
    void * stream_user_data
)

Return: 0 on success.

nghttp3 callback reporting bytes it consumed for a stream that had been deferred. The engine must be given this many bytes of flow control credit, or the peer stalls once its initial window is spent.

function on_stop_sending¶

int on_stop_sending(
    nghttp3_conn * conn,
    int64_t stream_id,
    uint64_t app_error_code,
    void * user_data,
    void * stream_user_data
)

Parameters:

• conn The nghttp3 connection.
• stream_id QUIC stream id being stopped.
• app_error_code Application error code.
• user_data The h3_session.
• stream_user_data The h3_stream.

Return: 0 on success, NGHTTP3_ERR_CALLBACK_FAILURE on missing stream.

nghttp3 stop_sending callback. Abort stream read side.

function on_reset_stream¶

int on_reset_stream(
    nghttp3_conn * conn,
    int64_t stream_id,
    uint64_t app_error_code,
    void * user_data,
    void * stream_user_data
)

Parameters:

• conn The nghttp3 connection.
• stream_id QUIC stream id being reset.
• app_error_code Application error code to signal.
• user_data The h3_session.
• stream_user_data The h3_stream.

Return: 0 on success, NGHTTP3_ERR_CALLBACK_FAILURE on missing stream.

nghttp3 reset_stream callback. Abort stream write side.

function on_stream_close¶

int on_stream_close(
    nghttp3_conn * conn,
    int64_t stream_id,
    uint64_t app_error_code,
    void * user_data,
    void * stream_user_data
)

Parameters:

• conn The nghttp3 connection.
• stream_id QUIC stream id that closed.
• app_error_code Final application error code (0 for clean close).
• user_data The h3_session.
• stream_user_data The h3_stream.

Return: 0 on success, NGHTTP3_ERR_CALLBACK_FAILURE on missing stream.

nghttp3 stream_close callback. Stream is fully closed; release per-stream resources (SSL object, request_rec pool, etc.).

Source code¶

/*
 * Copyright 2024-2025 The OpenSSL Project Authors. All Rights Reserved.
 * Copyright (c) 2026 The mod_http3 Project Authors. All rights reserved.
 *
 * SPDX-License-Identifier: Apache-2.0
 *
 * This file is derived from code originally distributed as part of
 * the OpenSSL project and has been modified for use in mod_http3.
 *
 * 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 H3_CALLBACKS_H
#define H3_CALLBACKS_H

#include <nghttp3/nghttp3.h>

int on_begin_headers(nghttp3_conn* conn, int64_t stream_id, void* user_data, void* stream_user_data);

int on_recv_header(nghttp3_conn* conn, int64_t stream_id, int32_t token, nghttp3_rcbuf* name, nghttp3_rcbuf* value, uint8_t flags, void* user_data, void* stream_user_data);

int on_end_headers(nghttp3_conn* conn, int64_t stream_id, int fin, void* user_data, void* stream_user_data);

int on_recv_data(nghttp3_conn* conn, int64_t stream_id, const uint8_t* data, size_t datalen, void* user_data, void* stream_user_data);

int on_acked_stream_data(nghttp3_conn* conn, int64_t stream_id, uint64_t datalen, void* user_data, void* stream_user_data);

int on_deferred_consume(nghttp3_conn* conn, int64_t stream_id, size_t consumed, void* user_data, void* stream_user_data);

int on_stop_sending(nghttp3_conn* conn, int64_t stream_id, uint64_t app_error_code, void* user_data, void* stream_user_data);

int on_reset_stream(nghttp3_conn* conn, int64_t stream_id, uint64_t app_error_code, void* user_data, void* stream_user_data);

int on_stream_close(nghttp3_conn* conn, int64_t stream_id, uint64_t app_error_code, void* user_data, void* stream_user_data);

#endif /* H3_CALLBACKS_H */