*/
static int bidi_stream(int64_t stream_id) { return (stream_id & 0x2) == 0; }
+static void conn_update_timestamp(ngtcp2_conn *conn, ngtcp2_tstamp ts) {
+ assert(conn->log.last_ts <= ts);
+ assert(conn->qlog.last_ts <= ts);
+
+ conn->log.last_ts = ts;
+ conn->qlog.last_ts = ts;
+}
+
/*
* conn_is_tls_handshake_completed returns nonzero if TLS handshake
* has completed and 1 RTT keys are available.
}
static int conn_call_recv_crypto_data(ngtcp2_conn *conn,
- ngtcp2_crypto_level crypto_level,
+ ngtcp2_encryption_level encryption_level,
uint64_t offset, const uint8_t *data,
size_t datalen) {
int rv;
assert(conn->callbacks.recv_crypto_data);
- rv = conn->callbacks.recv_crypto_data(conn, crypto_level, offset, data,
+ rv = conn->callbacks.recv_crypto_data(conn, encryption_level, offset, data,
datalen, conn->user_data);
switch (rv) {
case 0:
}
assert(conn->remote.transport_params);
- assert(conn->remote.transport_params->preferred_address_present);
+ assert(conn->remote.transport_params->preferred_addr_present);
rv = conn->callbacks.select_preferred_addr(
- conn, dest, &conn->remote.transport_params->preferred_address,
+ conn, dest, &conn->remote.transport_params->preferred_addr,
conn->user_data);
if (rv != 0) {
return NGTCP2_ERR_CALLBACK_FAILURE;
}
if (!conn_is_tls_handshake_completed(conn)) {
- flags |= NGTCP2_DATAGRAM_FLAG_EARLY;
+ flags |= NGTCP2_DATAGRAM_FLAG_0RTT;
}
rv = conn->callbacks.recv_datagram(conn, flags, data, datalen,
return 0;
}
-static int conn_call_recv_rx_key(ngtcp2_conn *conn, ngtcp2_crypto_level level) {
+static int conn_call_recv_rx_key(ngtcp2_conn *conn,
+ ngtcp2_encryption_level level) {
int rv;
if (!conn->callbacks.recv_rx_key) {
return 0;
}
-static int conn_call_recv_tx_key(ngtcp2_conn *conn, ngtcp2_crypto_level level) {
+static int conn_call_recv_tx_key(ngtcp2_conn *conn,
+ ngtcp2_encryption_level level) {
int rv;
if (!conn->callbacks.recv_tx_key) {
(!server && !params->original_dcid_present));
assert(!params->initial_scid_present);
assert(server || !params->stateless_reset_token_present);
- assert(server || !params->preferred_address_present);
+ assert(server || !params->preferred_addr_present);
assert(server || !params->retry_scid_present);
assert(server || callbacks->client_initial);
assert(!server || callbacks->recv_client_initial);
ngtcp2_log_init(&(*pconn)->log, scid, settings->log_printf,
settings->initial_ts, user_data);
- ngtcp2_qlog_init(&(*pconn)->qlog, settings->qlog.write, settings->initial_ts,
+ ngtcp2_qlog_init(&(*pconn)->qlog, settings->qlog_write, settings->initial_ts,
user_data);
if ((*pconn)->qlog.write) {
buf = ngtcp2_mem_malloc(mem, NGTCP2_QLOG_BUFLEN);
(*pconn)->vneg.preferred_versionslen = settings->preferred_versionslen;
}
+ (*pconn)->local.settings.preferred_versions = NULL;
+ (*pconn)->local.settings.preferred_versionslen = 0;
+
if (settings->available_versionslen) {
if (!server && !ngtcp2_is_reserved_version(client_chosen_version)) {
for (i = 0; i < settings->available_versionslen; ++i) {
(*pconn)->vneg.available_versionslen = sizeof(uint32_t);
}
+ (*pconn)->local.settings.available_versions = NULL;
+ (*pconn)->local.settings.available_versionslen = 0;
+
(*pconn)->client_chosen_version = client_chosen_version;
conn_set_local_transport_params(*pconn, params);
conn_reset_ecn_validation_state(*pconn);
- ngtcp2_qlog_start(&(*pconn)->qlog, server ? &settings->qlog.odcid : dcid,
- server);
+ ngtcp2_qlog_start(
+ &(*pconn)->qlog,
+ server ? ((*pconn)->local.transport_params.retry_scid_present
+ ? &(*pconn)->local.transport_params.retry_scid
+ : &(*pconn)->local.transport_params.original_dcid)
+ : dcid,
+ server);
return 0;
conn->cstat.smoothed_rtt / 8);
}
-/*
- * conn_create_ack_frame creates ACK frame, and assigns its pointer to
- * |*pfr| if there are any received packets to acknowledge. If there
- * are no packets to acknowledge, this function returns 0, and |*pfr|
- * is untouched. The caller is advised to set |*pfr| to NULL before
- * calling this function, and check it after this function returns.
- * If |nodelay| is nonzero, delayed ACK timer is ignored.
- *
- * The memory for ACK frame is dynamically allocated by this function.
- * A caller is responsible to free it.
- *
- * Call ngtcp2_acktr_commit_ack after a created ACK frame is
- * successfully serialized into a packet.
- *
- * This function returns 0 if it succeeds, or one of the following
- * negative error codes:
- *
- * NGTCP2_ERR_NOMEM
- * Out of memory.
- */
-static int conn_create_ack_frame(ngtcp2_conn *conn, ngtcp2_frame **pfr,
+int ngtcp2_conn_create_ack_frame(ngtcp2_conn *conn, ngtcp2_frame **pfr,
ngtcp2_pktns *pktns, uint8_t type,
ngtcp2_tstamp ts, ngtcp2_duration ack_delay,
uint64_t ack_delay_exponent) {
ack->largest_ack = rpkt->pkt_num;
ack->first_ack_range = rpkt->len - 1;
+ ngtcp2_ksl_it_next(&it);
+ } else if (rpkt->pkt_num + 1 == pktns->rx.max_pkt_num) {
+ last_pkt_num = rpkt->pkt_num - (int64_t)(rpkt->len - 1);
+ largest_ack_ts = pktns->rx.max_pkt_ts;
+ ack->largest_ack = pktns->rx.max_pkt_num;
+ ack->first_ack_range = rpkt->len;
+
ngtcp2_ksl_it_next(&it);
} else {
assert(rpkt->pkt_num < pktns->rx.max_pkt_num);
return 0;
}
- rv = conn_create_ack_frame(conn, &ackfr, pktns, type, ts,
- /* ack_delay = */ 0,
- NGTCP2_DEFAULT_ACK_DELAY_EXPONENT);
+ rv = ngtcp2_conn_create_ack_frame(conn, &ackfr, pktns, type, ts,
+ /* ack_delay = */ 0,
+ NGTCP2_DEFAULT_ACK_DELAY_EXPONENT);
if (rv != 0) {
ngtcp2_frame_chain_list_objalloc_del(frq, &conn->frc_objalloc, conn->mem);
return rv;
}
ackfr = NULL;
- rv = conn_create_ack_frame(conn, &ackfr, pktns, type, ts, ack_delay,
- ack_delay_exponent);
+ rv = ngtcp2_conn_create_ack_frame(conn, &ackfr, pktns, type, ts, ack_delay,
+ ack_delay_exponent);
if (rv != 0) {
return rv;
}
}
}
- rv = conn_create_ack_frame(conn, &ackfr, pktns, type, ts,
- conn_compute_ack_delay(conn),
- conn->local.transport_params.ack_delay_exponent);
+ rv = ngtcp2_conn_create_ack_frame(
+ conn, &ackfr, pktns, type, ts, conn_compute_ack_delay(conn),
+ conn->local.transport_params.ack_delay_exponent);
if (rv != 0) {
assert(ngtcp2_err_is_fatal(rv));
return rv;
* NGTCP2_ERR_CRYPTO
* TLS backend reported error
*/
-static int conn_emit_pending_crypto_data(ngtcp2_conn *conn,
- ngtcp2_crypto_level crypto_level,
- ngtcp2_strm *strm,
- uint64_t rx_offset) {
+static int
+conn_emit_pending_crypto_data(ngtcp2_conn *conn,
+ ngtcp2_encryption_level encryption_level,
+ ngtcp2_strm *strm, uint64_t rx_offset) {
size_t datalen;
const uint8_t *data;
int rv;
offset = rx_offset;
rx_offset += datalen;
- rv = conn_call_recv_crypto_data(conn, crypto_level, offset, data, datalen);
+ rv = conn_call_recv_crypto_data(conn, encryption_level, offset, data,
+ datalen);
if (rv != 0) {
return rv;
}
static int pktns_commit_recv_pkt_num(ngtcp2_pktns *pktns, int64_t pkt_num,
int ack_eliciting, ngtcp2_tstamp ts) {
int rv;
-
- if (ack_eliciting && pktns->rx.max_ack_eliciting_pkt_num + 1 != pkt_num) {
- ngtcp2_acktr_immediate_ack(&pktns->acktr);
- }
- if (pktns->rx.max_pkt_num < pkt_num) {
- pktns->rx.max_pkt_num = pkt_num;
- pktns->rx.max_pkt_ts = ts;
- }
- if (ack_eliciting && pktns->rx.max_ack_eliciting_pkt_num < pkt_num) {
- pktns->rx.max_ack_eliciting_pkt_num = pkt_num;
- }
+ ngtcp2_range r;
rv = ngtcp2_gaptr_push(&pktns->rx.pngap, (uint64_t)pkt_num, 1);
if (rv != 0) {
ngtcp2_gaptr_drop_first_gap(&pktns->rx.pngap);
}
+ if (ack_eliciting) {
+ if (pktns->rx.max_ack_eliciting_pkt_num != -1) {
+ if (pkt_num < pktns->rx.max_ack_eliciting_pkt_num) {
+ ngtcp2_acktr_immediate_ack(&pktns->acktr);
+ } else if (pkt_num > pktns->rx.max_ack_eliciting_pkt_num) {
+ r = ngtcp2_gaptr_get_first_gap_after(
+ &pktns->rx.pngap, (uint64_t)pktns->rx.max_ack_eliciting_pkt_num);
+
+ if (r.begin < (uint64_t)pkt_num) {
+ ngtcp2_acktr_immediate_ack(&pktns->acktr);
+ }
+ }
+ }
+
+ if (pktns->rx.max_ack_eliciting_pkt_num < pkt_num) {
+ pktns->rx.max_ack_eliciting_pkt_num = pkt_num;
+ }
+ }
+
+ if (pktns->rx.max_pkt_num < pkt_num) {
+ pktns->rx.max_pkt_num = pkt_num;
+ pktns->rx.max_pkt_ts = ts;
+ }
+
return 0;
}
return 0;
}
-static int conn_recv_crypto(ngtcp2_conn *conn, ngtcp2_crypto_level crypto_level,
+static int conn_recv_crypto(ngtcp2_conn *conn,
+ ngtcp2_encryption_level encryption_level,
ngtcp2_strm *strm, const ngtcp2_crypto *fr);
static ngtcp2_ssize conn_recv_pkt(ngtcp2_conn *conn, const ngtcp2_path *path,
ngtcp2_decrypt decrypt;
ngtcp2_pktns *pktns;
ngtcp2_strm *crypto;
- ngtcp2_crypto_level crypto_level;
+ ngtcp2_encryption_level encryption_level;
int invalid_reserved_bits = 0;
if (pktlen == 0) {
pktns = conn->in_pktns;
crypto = &pktns->crypto.strm;
- crypto_level = NGTCP2_CRYPTO_LEVEL_INITIAL;
+ encryption_level = NGTCP2_ENCRYPTION_LEVEL_INITIAL;
if (hd.version == conn->client_chosen_version) {
ckm = pktns->crypto.rx.ckm;
pktns = conn->hs_pktns;
crypto = &pktns->crypto.strm;
- crypto_level = NGTCP2_CRYPTO_LEVEL_HANDSHAKE;
+ encryption_level = NGTCP2_ENCRYPTION_LEVEL_HANDSHAKE;
ckm = pktns->crypto.rx.ckm;
hp_ctx = &pktns->crypto.rx.hp_ctx;
conn->negotiated_version);
}
- rv = conn_recv_crypto(conn, crypto_level, crypto, &fr->crypto);
+ rv = conn_recv_crypto(conn, encryption_level, crypto, &fr->crypto);
if (rv != 0) {
return rv;
}
sdflags |= NGTCP2_STREAM_DATA_FLAG_FIN;
}
if (!handshake_completed) {
- sdflags |= NGTCP2_STREAM_DATA_FLAG_EARLY;
+ sdflags |= NGTCP2_STREAM_DATA_FLAG_0RTT;
}
rv = conn_call_recv_stream_data(conn, strm, sdflags, offset, data, datalen);
* |rx_offset_base| is the offset in the entire TLS handshake stream.
* fr->offset specifies the offset in each encryption level.
* |max_rx_offset| is, if it is nonzero, the maximum offset in the
- * entire TLS handshake stream that |fr| can carry. |crypto_level| is
- * the encryption level where this data is received.
+ * entire TLS handshake stream that |fr| can carry.
+ * |encryption_level| is the encryption level where this data is
+ * received.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
* NGTCP2_ERR_CALLBACK_FAILURE
* User-defined callback function failed.
*/
-static int conn_recv_crypto(ngtcp2_conn *conn, ngtcp2_crypto_level crypto_level,
+static int conn_recv_crypto(ngtcp2_conn *conn,
+ ngtcp2_encryption_level encryption_level,
ngtcp2_strm *crypto, const ngtcp2_crypto *fr) {
uint64_t fr_end_offset;
uint64_t rx_offset;
if (fr_end_offset <= rx_offset) {
if (conn->server &&
!(conn->flags & NGTCP2_CONN_FLAG_HANDSHAKE_EARLY_RETRANSMIT) &&
- crypto_level == NGTCP2_CRYPTO_LEVEL_INITIAL) {
+ encryption_level == NGTCP2_ENCRYPTION_LEVEL_INITIAL) {
/* recovery draft: Speeding Up Handshake Completion
When a server receives an Initial packet containing duplicate
return rv;
}
- rv = conn_call_recv_crypto_data(conn, crypto_level, offset, data, datalen);
+ rv = conn_call_recv_crypto_data(conn, encryption_level, offset, data,
+ datalen);
if (rv != 0) {
return rv;
}
- rv = conn_emit_pending_crypto_data(conn, crypto_level, crypto, rx_offset);
+ rv = conn_emit_pending_crypto_data(conn, encryption_level, crypto,
+ rx_offset);
if (rv != 0) {
return rv;
}
sdflags |= NGTCP2_STREAM_DATA_FLAG_FIN;
}
if (!conn_is_tls_handshake_completed(conn)) {
- sdflags |= NGTCP2_STREAM_DATA_FLAG_EARLY;
+ sdflags |= NGTCP2_STREAM_DATA_FLAG_0RTT;
}
rv = conn_call_recv_stream_data(conn, strm, sdflags, offset, data,
(size_t)datalen);
assert(conn->remote.transport_params);
- if (conn->remote.transport_params->preferred_address_present) {
+ if (conn->remote.transport_params->preferred_addr_present) {
rv = conn_select_preferred_addr(conn);
if (rv != 0) {
return rv;
!(hd->flags & NGTCP2_PKT_FLAG_KEY_PHASE);
}
+static int conn_initiate_key_update(ngtcp2_conn *conn, ngtcp2_tstamp ts);
+
/*
* conn_prepare_key_update installs new updated keys.
*/
if ((conn->flags & NGTCP2_CONN_FLAG_HANDSHAKE_CONFIRMED) &&
tx_ckm->use_count >= pktns->crypto.ctx.max_encryption &&
- ngtcp2_conn_initiate_key_update(conn, ts) != 0) {
+ conn_initiate_key_update(conn, ts) != 0) {
return NGTCP2_ERR_AEAD_LIMIT_REACHED;
}
/* If local address changes, it must be one of the preferred
addresses. */
- if (!conn->local.transport_params.preferred_address_present) {
+ if (!conn->local.transport_params.preferred_addr_present) {
return 0;
}
- paddr = &conn->local.transport_params.preferred_address;
+ paddr = &conn->local.transport_params.preferred_addr;
if (paddr->ipv4_present) {
ngtcp2_addr_init(&addr, (const ngtcp2_sockaddr *)&paddr->ipv4,
non_probing_pkt = 1;
break;
case NGTCP2_FRAME_CRYPTO:
- rv = conn_recv_crypto(conn, NGTCP2_CRYPTO_LEVEL_APPLICATION,
+ rv = conn_recv_crypto(conn, NGTCP2_ENCRYPTION_LEVEL_1RTT,
&pktns->crypto.strm, &fr->crypto);
if (rv != 0) {
return rv;
assert(!(conn->flags & NGTCP2_CONN_FLAG_PPE_PENDING));
- conn->log.last_ts = ts;
- conn->qlog.last_ts = ts;
+ conn_update_timestamp(conn, ts);
ngtcp2_log_info(&conn->log, NGTCP2_LOG_EVENT_CON, "recv packet len=%zu",
pktlen);
assert(conn->remote.transport_params);
- if (conn->remote.transport_params->preferred_address_present) {
+ if (conn->remote.transport_params->preferred_addr_present) {
assert(!ngtcp2_ringbuf_full(&conn->dcid.unused.rb));
- paddr = &conn->remote.transport_params->preferred_address;
+ paddr = &conn->remote.transport_params->preferred_addr;
dcid = ngtcp2_ringbuf_push_back(&conn->dcid.unused.rb);
ngtcp2_dcid_init(dcid, 1, &paddr->cid, paddr->stateless_reset_token);
pktns->crypto.rx.hp_ctx = *hp_ctx;
- rv = conn_call_recv_rx_key(conn, NGTCP2_CRYPTO_LEVEL_HANDSHAKE);
+ rv = conn_call_recv_rx_key(conn, NGTCP2_ENCRYPTION_LEVEL_HANDSHAKE);
if (rv != 0) {
ngtcp2_crypto_km_del(pktns->crypto.rx.ckm, conn->mem);
pktns->crypto.rx.ckm = NULL;
}
}
- rv = conn_call_recv_tx_key(conn, NGTCP2_CRYPTO_LEVEL_HANDSHAKE);
+ rv = conn_call_recv_tx_key(conn, NGTCP2_ENCRYPTION_LEVEL_HANDSHAKE);
if (rv != 0) {
ngtcp2_crypto_km_del(pktns->crypto.tx.ckm, conn->mem);
pktns->crypto.tx.ckm = NULL;
return 0;
}
-int ngtcp2_conn_install_early_key(ngtcp2_conn *conn,
- const ngtcp2_crypto_aead_ctx *aead_ctx,
- const uint8_t *iv, size_t ivlen,
- const ngtcp2_crypto_cipher_ctx *hp_ctx) {
+int ngtcp2_conn_install_0rtt_key(ngtcp2_conn *conn,
+ const ngtcp2_crypto_aead_ctx *aead_ctx,
+ const uint8_t *iv, size_t ivlen,
+ const ngtcp2_crypto_cipher_ctx *hp_ctx) {
int rv;
assert(ivlen >= 8);
conn->flags |= NGTCP2_CONN_FLAG_EARLY_KEY_INSTALLED;
if (conn->server) {
- rv = conn_call_recv_rx_key(conn, NGTCP2_CRYPTO_LEVEL_EARLY);
+ rv = conn_call_recv_rx_key(conn, NGTCP2_ENCRYPTION_LEVEL_0RTT);
} else {
- rv = conn_call_recv_tx_key(conn, NGTCP2_CRYPTO_LEVEL_EARLY);
+ rv = conn_call_recv_tx_key(conn, NGTCP2_ENCRYPTION_LEVEL_0RTT);
}
if (rv != 0) {
ngtcp2_crypto_km_del(conn->early.ckm, conn->mem);
}
}
- rv = conn_call_recv_rx_key(conn, NGTCP2_CRYPTO_LEVEL_APPLICATION);
+ rv = conn_call_recv_rx_key(conn, NGTCP2_ENCRYPTION_LEVEL_1RTT);
if (rv != 0) {
ngtcp2_crypto_km_del(pktns->crypto.rx.ckm, conn->mem);
pktns->crypto.rx.ckm = NULL;
conn_discard_early_key(conn);
}
- rv = conn_call_recv_tx_key(conn, NGTCP2_CRYPTO_LEVEL_APPLICATION);
+ rv = conn_call_recv_tx_key(conn, NGTCP2_ENCRYPTION_LEVEL_1RTT);
if (rv != 0) {
ngtcp2_crypto_km_del(pktns->crypto.tx.ckm, conn->mem);
pktns->crypto.tx.ckm = NULL;
return 0;
}
-int ngtcp2_conn_initiate_key_update(ngtcp2_conn *conn, ngtcp2_tstamp ts) {
+static int conn_initiate_key_update(ngtcp2_conn *conn, ngtcp2_tstamp ts) {
ngtcp2_tstamp confirmed_ts = conn->crypto.key_update.confirmed_ts;
ngtcp2_duration pto = conn_compute_pto(conn, &conn->pktns);
return 0;
}
+int ngtcp2_conn_initiate_key_update(ngtcp2_conn *conn, ngtcp2_tstamp ts) {
+ conn_update_timestamp(conn, ts);
+
+ return conn_initiate_key_update(conn, ts);
+}
+
/*
* conn_retire_stale_bound_dcid retires stale destination connection
* ID in conn->dcid.bound to keep some unused destination connection
int ngtcp2_conn_handle_expiry(ngtcp2_conn *conn, ngtcp2_tstamp ts) {
int rv;
- ngtcp2_duration pto = conn_compute_pto(conn, &conn->pktns);
+ ngtcp2_duration pto;
+
+ conn_update_timestamp(conn, ts);
+
+ pto = conn_compute_pto(conn, &conn->pktns);
assert(!(conn->flags & NGTCP2_CONN_FLAG_PPE_PENDING));
return NGTCP2_ERR_TRANSPORT_PARAM;
}
- if (params->preferred_address_present &&
- conn->dcid.current.cid.datalen == 0) {
+ if (params->preferred_addr_present && conn->dcid.current.cid.datalen == 0) {
return NGTCP2_ERR_TRANSPORT_PARAM;
}
/* QUIC v1 (and the supported draft versions) are treated
specially. If version_info is missing, no further validation
- is necessary.
- https://datatracker.ietf.org/doc/html/draft-ietf-quic-version-negotiation-10#section-8
+ is necessary. See
+ https://datatracker.ietf.org/doc/html/rfc9368#section-8
*/
if (conn->client_chosen_version == NGTCP2_PROTO_VER_V1 ||
(NGTCP2_PROTO_VER_DRAFT_MIN <= conn->client_chosen_version &&
return NGTCP2_ERR_VERSION_NEGOTIATION_FAILURE;
}
- /* Server choose original version after Version Negotiation.
- Draft does not say this particular case, but this smells like
+ /* Server choose original version after Version Negotiation. RFC
+ 9368 does not say this particular case, but this smells like
misbehaved server because server should accept original_version
in the original connection. */
if (conn->local.settings.original_version ==
if (conn->server) {
if (params->original_dcid_present ||
params->stateless_reset_token_present ||
- params->preferred_address_present || params->retry_scid_present) {
+ params->preferred_addr_present || params->retry_scid_present) {
return NGTCP2_ERR_TRANSPORT_PARAM;
}
return 0;
}
-int ngtcp2_conn_decode_remote_transport_params(ngtcp2_conn *conn,
- const uint8_t *data,
- size_t datalen) {
+int ngtcp2_conn_decode_and_set_remote_transport_params(ngtcp2_conn *conn,
+ const uint8_t *data,
+ size_t datalen) {
ngtcp2_transport_params params;
int rv;
return conn->remote.transport_params;
}
-ngtcp2_ssize ngtcp2_conn_encode_early_transport_params(ngtcp2_conn *conn,
- uint8_t *dest,
- size_t destlen) {
+ngtcp2_ssize ngtcp2_conn_encode_0rtt_transport_params(ngtcp2_conn *conn,
+ uint8_t *dest,
+ size_t destlen) {
ngtcp2_transport_params params, *src;
if (conn->server) {
return ngtcp2_transport_params_encode(dest, destlen, ¶ms);
}
-int ngtcp2_conn_decode_early_transport_params(ngtcp2_conn *conn,
- const uint8_t *data,
- size_t datalen) {
+int ngtcp2_conn_decode_and_set_0rtt_transport_params(ngtcp2_conn *conn,
+ const uint8_t *data,
+ size_t datalen) {
ngtcp2_transport_params params;
int rv;
return rv;
}
- return ngtcp2_conn_set_early_remote_transport_params(conn, ¶ms);
+ return ngtcp2_conn_set_0rtt_remote_transport_params(conn, ¶ms);
}
-int ngtcp2_conn_set_early_remote_transport_params(
+int ngtcp2_conn_set_0rtt_remote_transport_params(
ngtcp2_conn *conn, const ngtcp2_transport_params *params) {
ngtcp2_transport_params *p;
params->initial_scid_present = 1;
if (conn->oscid.datalen == 0) {
- params->preferred_address_present = 0;
+ params->preferred_addr_present = 0;
}
- if (conn->server && params->preferred_address_present) {
+ if (conn->server && params->preferred_addr_present) {
scident = ngtcp2_mem_malloc(mem, sizeof(*scident));
if (scident == NULL) {
return NGTCP2_ERR_NOMEM;
}
- ngtcp2_scid_init(scident, 1, ¶ms->preferred_address.cid);
+ ngtcp2_scid_init(scident, 1, ¶ms->preferred_addr.cid);
rv = ngtcp2_ksl_insert(&conn->scid.set, NULL, &scident->cid, scident);
if (rv != 0) {
ngtcp2_rtb_entry *rtbent;
(void)pkt_info_version;
- conn->log.last_ts = ts;
- conn->qlog.last_ts = ts;
+ conn_update_timestamp(conn, ts);
if (path) {
ngtcp2_path_copy(path, &conn->dcid.current.ps.path);
ngtcp2_ssize nwrite;
uint64_t server_tx_left;
- conn->log.last_ts = ts;
- conn->qlog.last_ts = ts;
-
if (conn_check_pkt_num_exhausted(conn)) {
return NGTCP2_ERR_PKT_NUM_EXHAUSTED;
}
ngtcp2_frame fr;
uint64_t server_tx_left;
- conn->log.last_ts = ts;
- conn->qlog.last_ts = ts;
-
if (conn_check_pkt_num_exhausted(conn)) {
return NGTCP2_ERR_PKT_NUM_EXHAUSTED;
}
const ngtcp2_ccerr *ccerr, ngtcp2_tstamp ts) {
(void)pkt_info_version;
+ conn_update_timestamp(conn, ts);
+
switch (ccerr->type) {
case NGTCP2_CCERR_TYPE_TRANSPORT:
return ngtcp2_conn_write_connection_close_pkt(
}
}
-int ngtcp2_conn_is_in_closing_period(ngtcp2_conn *conn) {
+int ngtcp2_conn_in_closing_period(ngtcp2_conn *conn) {
return conn->state == NGTCP2_CS_CLOSING;
}
-int ngtcp2_conn_is_in_draining_period(ngtcp2_conn *conn) {
+int ngtcp2_conn_in_draining_period(ngtcp2_conn *conn) {
return conn->state == NGTCP2_CS_DRAINING;
}
return conn_stop_sending(conn, strm, app_error_code);
}
-int ngtcp2_conn_shutdown_stream(ngtcp2_conn *conn, int64_t stream_id,
- uint64_t app_error_code) {
+int ngtcp2_conn_shutdown_stream(ngtcp2_conn *conn, uint32_t flags,
+ int64_t stream_id, uint64_t app_error_code) {
int rv;
ngtcp2_strm *strm;
+ (void)flags;
strm = ngtcp2_conn_find_stream(conn, stream_id);
if (strm == NULL) {
return 0;
}
-int ngtcp2_conn_shutdown_stream_write(ngtcp2_conn *conn, int64_t stream_id,
+int ngtcp2_conn_shutdown_stream_write(ngtcp2_conn *conn, uint32_t flags,
+ int64_t stream_id,
uint64_t app_error_code) {
ngtcp2_strm *strm;
+ (void)flags;
if (!bidi_stream(stream_id) && !conn_local_stream(conn, stream_id)) {
return NGTCP2_ERR_INVALID_ARGUMENT;
return conn_shutdown_stream_write(conn, strm, app_error_code);
}
-int ngtcp2_conn_shutdown_stream_read(ngtcp2_conn *conn, int64_t stream_id,
+int ngtcp2_conn_shutdown_stream_read(ngtcp2_conn *conn, uint32_t flags,
+ int64_t stream_id,
uint64_t app_error_code) {
ngtcp2_strm *strm;
+ (void)flags;
if (!bidi_stream(stream_id) && conn_local_stream(conn, stream_id)) {
return NGTCP2_ERR_INVALID_ARGUMENT;
return 0;
}
+ if (!bidi_stream(stream_id) && conn_local_stream(conn, stream_id)) {
+ return NGTCP2_ERR_INVALID_ARGUMENT;
+ }
+
return conn_extend_max_stream_offset(conn, strm, datalen);
}
}
}
-int ngtcp2_conn_early_data_rejected(ngtcp2_conn *conn) {
+int ngtcp2_conn_tls_early_data_rejected(ngtcp2_conn *conn) {
if (conn->flags & NGTCP2_CONN_FLAG_EARLY_DATA_REJECTED) {
return 0;
}
conn_discard_early_data_state(conn);
- if (conn->callbacks.early_data_rejected) {
- return conn->callbacks.early_data_rejected(conn, conn->user_data);
+ if (conn->callbacks.tls_early_data_rejected) {
+ return conn->callbacks.tls_early_data_rejected(conn, conn->user_data);
}
return 0;
}
-int ngtcp2_conn_get_early_data_rejected(ngtcp2_conn *conn) {
+int ngtcp2_conn_get_tls_early_data_rejected(ngtcp2_conn *conn) {
return (conn->flags & NGTCP2_CONN_FLAG_EARLY_DATA_REJECTED) != 0;
}
ngtcp2_tstamp earliest_loss_time;
ngtcp2_pktns *loss_pktns = NULL;
- conn->log.last_ts = ts;
- conn->qlog.last_ts = ts;
-
switch (conn->state) {
case NGTCP2_CS_CLOSING:
case NGTCP2_CS_DRAINING:
}
int ngtcp2_conn_submit_crypto_data(ngtcp2_conn *conn,
- ngtcp2_crypto_level crypto_level,
+ ngtcp2_encryption_level encryption_level,
const uint8_t *data, const size_t datalen) {
ngtcp2_pktns *pktns;
ngtcp2_frame_chain *frc;
return 0;
}
- switch (crypto_level) {
- case NGTCP2_CRYPTO_LEVEL_INITIAL:
+ switch (encryption_level) {
+ case NGTCP2_ENCRYPTION_LEVEL_INITIAL:
assert(conn->in_pktns);
pktns = conn->in_pktns;
break;
- case NGTCP2_CRYPTO_LEVEL_HANDSHAKE:
+ case NGTCP2_ENCRYPTION_LEVEL_HANDSHAKE:
assert(conn->hs_pktns);
pktns = conn->hs_pktns;
break;
- case NGTCP2_CRYPTO_LEVEL_APPLICATION:
+ case NGTCP2_ENCRYPTION_LEVEL_1RTT:
pktns = &conn->pktns;
break;
default:
return ngtcp2_pq_push(&conn->tx.strmq, &strm->pe);
}
-static int conn_has_uncommited_preferred_address_cid(ngtcp2_conn *conn) {
+static int conn_has_uncommited_preferred_addr_cid(ngtcp2_conn *conn) {
return conn->server &&
!(conn->flags & NGTCP2_CONN_FLAG_LOCAL_TRANSPORT_PARAMS_COMMITTED) &&
conn->oscid.datalen &&
- conn->local.transport_params.preferred_address_present;
+ conn->local.transport_params.preferred_addr_present;
}
size_t ngtcp2_conn_get_num_scid(ngtcp2_conn *conn) {
return ngtcp2_ksl_len(&conn->scid.set) +
- (size_t)conn_has_uncommited_preferred_address_cid(conn);
+ (size_t)conn_has_uncommited_preferred_addr_cid(conn);
}
size_t ngtcp2_conn_get_scid(ngtcp2_conn *conn, ngtcp2_cid *dest) {
*dest++ = scid->cid;
}
- if (conn_has_uncommited_preferred_address_cid(conn)) {
- *dest++ = conn->local.transport_params.preferred_address.cid;
+ if (conn_has_uncommited_preferred_addr_cid(conn)) {
+ *dest++ = conn->local.transport_params.preferred_addr.cid;
}
return (size_t)(dest - origdest);
assert(!conn->server);
- conn->log.last_ts = ts;
- conn->qlog.last_ts = ts;
+ conn_update_timestamp(conn, ts);
rv = conn_initiate_migration_precheck(conn, &path->local);
if (rv != 0) {
assert(!conn->server);
- conn->log.last_ts = ts;
- conn->qlog.last_ts = ts;
+ conn_update_timestamp(conn, ts);
rv = conn_initiate_migration_precheck(conn, &path->local);
if (rv != 0) {
return &conn->pktns.crypto.ctx;
}
-void ngtcp2_conn_set_early_crypto_ctx(ngtcp2_conn *conn,
- const ngtcp2_crypto_ctx *ctx) {
+void ngtcp2_conn_set_0rtt_crypto_ctx(ngtcp2_conn *conn,
+ const ngtcp2_crypto_ctx *ctx) {
conn->early.ctx = *ctx;
}
-const ngtcp2_crypto_ctx *ngtcp2_conn_get_early_crypto_ctx(ngtcp2_conn *conn) {
+const ngtcp2_crypto_ctx *ngtcp2_conn_get_0rtt_crypto_ctx(ngtcp2_conn *conn) {
return &conn->early.ctx;
}
double pacing_rate;
ngtcp2_duration interval;
+ conn_update_timestamp(conn, ts);
+
if (conn->tx.pacing.pktlen == 0) {
return;
}
# ifdef WIN32
# ifndef WIN32_LEAN_AND_MEAN
# define WIN32_LEAN_AND_MEAN
-# endif
+# endif /* WIN32_LEAN_AND_MEAN */
# include <ws2tcpip.h>
-# else
+# else /* !WIN32 */
# include <sys/socket.h>
# include <netinet/in.h>
-# endif
-#endif
+# endif /* !WIN32 */
+#endif /* NGTCP2_USE_GENERIC_SOCKADDR */
#ifdef AF_INET
# define NGTCP2_AF_INET AF_INET
-#else
+#else /* !AF_INET */
# define NGTCP2_AF_INET 2
-#endif
+#endif /* !AF_INET */
#ifdef AF_INET6
# define NGTCP2_AF_INET6 AF_INET6
-#else
+#else /* !AF_INET6 */
# define NGTCP2_AF_INET6 23
# define NGTCP2_USE_GENERIC_IPV6_SOCKADDR
-#endif
+#endif /* !AF_INET6 */
#include <ngtcp2/version.h>
/**
* @macro
*
- * :macro:`NGTCP2_SECONDS` is a count of tick which corresponds to 1 second.
+ * :macro:`NGTCP2_SECONDS` is a count of tick which corresponds to 1
+ * second.
*/
#define NGTCP2_SECONDS ((ngtcp2_duration)1000000000ULL)
/**
* @macro
*
- * :macro:`NGTCP2_PROTO_VER_V2` is the QUIC version 2.
- *
- * https://quicwg.org/quic-v2/draft-ietf-quic-v2.html
+ * :macro:`NGTCP2_PROTO_VER_V2` is the QUIC version 2. See
+ * :rfc:`9369`.
*/
#define NGTCP2_PROTO_VER_V2 ((uint32_t)0x6b3343cfu)
* @macro
*
* :macro:`NGTCP2_MAX_UDP_PAYLOAD_SIZE` is the default maximum UDP
- * datagram payload size that this endpoint transmits.
+ * datagram payload size that the local endpoint transmits.
*/
#define NGTCP2_MAX_UDP_PAYLOAD_SIZE 1200
* @macro
*
* :macro:`NGTCP2_MIN_STATELESS_RESET_RANDLEN` is the minimum length
- * of random bytes (Unpredictable Bits) in Stateless Reset packet
+ * of random bytes (Unpredictable Bits) in Stateless Reset packet.
*/
#define NGTCP2_MIN_STATELESS_RESET_RANDLEN 5
/**
* @macro
*
- * :macro:`NGTCP2_RETRY_NONCE_V1` is nonce used when generating integrity
- * tag of Retry packet. It is used for QUIC v1.
+ * :macro:`NGTCP2_RETRY_NONCE_V1` is nonce used when generating
+ * integrity tag of Retry packet. It is used for QUIC v1.
*/
#define NGTCP2_RETRY_NONCE_V1 "\x46\x15\x99\xd3\x5d\x63\x2b\xf2\x23\x98\x25\xbb"
* @macro
*
* :macro:`NGTCP2_RETRY_KEY_V2` is an encryption key to create
- * integrity tag of Retry packet. It is used for QUIC v2.
- *
- * https://quicwg.org/quic-v2/draft-ietf-quic-v2.html
+ * integrity tag of Retry packet. It is used for QUIC v2. See
+ * :rfc:`9369`.
*/
#define NGTCP2_RETRY_KEY_V2 \
"\x8f\xb4\xb0\x1b\x56\xac\x48\xe2\x60\xfb\xcb\xce\xad\x7c\xcc\x92"
* @macro
*
* :macro:`NGTCP2_RETRY_NONCE_V2` is nonce used when generating
- * integrity tag of Retry packet. It is used for QUIC v2.
- *
- * https://quicwg.org/quic-v2/draft-ietf-quic-v2.html
+ * integrity tag of Retry packet. It is used for QUIC v2. See
+ * :rfc:`9369`.
*/
#define NGTCP2_RETRY_NONCE_V2 "\xd8\x69\x69\xbc\x2d\x7c\x6d\x99\x90\xef\xb0\x4a"
*/
typedef struct NGTCP2_ALIGN(8) ngtcp2_pkt_info {
/**
- * :member:`ecn` is ECN marking and when passing
- * `ngtcp2_conn_read_pkt()`, and it should be either
+ * :member:`ecn` is ECN marking, and when it is passed to
+ * `ngtcp2_conn_read_pkt()`, it should be either
* :macro:`NGTCP2_ECN_NOT_ECT`, :macro:`NGTCP2_ECN_ECT_1`,
* :macro:`NGTCP2_ECN_ECT_0`, or :macro:`NGTCP2_ECN_CE`.
*/
/**
* @macro
*
- * :macro:`NGTCP2_ERR_STREAM_NOT_FOUND` indicates that a stream was not
- * found.
+ * :macro:`NGTCP2_ERR_STREAM_NOT_FOUND` indicates that a stream was
+ * not found.
*/
#define NGTCP2_ERR_STREAM_NOT_FOUND -222
/**
*/
NGTCP2_PKT_INITIAL = 0x10,
/**
- * :enum:`NGTCP2_PKT_0RTT` indicates 0RTT packet.
+ * :enum:`NGTCP2_PKT_0RTT` indicates 0-RTT packet.
*/
NGTCP2_PKT_0RTT = 0x11,
/**
* @macro
*
* :macro:`NGTCP2_VERSION_NEGOTIATION_ERROR` is QUIC transport error
- * code ``VERSION_NEGOTIATION_ERROR``.
- *
- * https://datatracker.ietf.org/doc/html/draft-ietf-quic-version-negotiation-14
+ * code ``VERSION_NEGOTIATION_ERROR``. See :rfc:`9368`.
*/
#define NGTCP2_VERSION_NEGOTIATION_ERROR 0x11
* @typedef
*
* :type:`ngtcp2_tstamp` is a timestamp with nanosecond resolution.
- * ``UINT64_MAX`` is an invalid value.
+ * ``UINT64_MAX`` is an invalid value, and it is often used to
+ * indicate that no value is set.
*/
typedef uint64_t ngtcp2_tstamp;
* @typedef
*
* :type:`ngtcp2_duration` is a period of time in nanosecond
- * resolution. ``UINT64_MAX`` is an invalid value.
+ * resolution. ``UINT64_MAX`` is an invalid value, and it is often
+ * used to indicate that no value is set.
*/
typedef uint64_t ngtcp2_duration;
*/
int64_t pkt_num;
/**
- * :member:`token` contains token for Initial
- * packet.
+ * :member:`token` contains token. Only Initial packet may contain
+ * token. NULL if no token is present.
*/
const uint8_t *token;
/**
- * :member:`tokenlen` is the length of :member:`token`.
+ * :member:`tokenlen` is the length of :member:`token`. 0 if no
+ * token is present.
*/
size_t tokenlen;
/**
*/
uint32_t version;
/**
- * :member:`type` is a type of QUIC packet. See
- * :type:`ngtcp2_pkt_type`.
+ * :member:`type` is a type of QUIC packet. This field does not
+ * have a QUIC packet type defined for a specific QUIC version.
+ * Instead, it contains version independent packet type defined by
+ * this library. See :type:`ngtcp2_pkt_type`.
*/
uint8_t type;
/**
#define NGTCP2_TLSEXT_QUIC_TRANSPORT_PARAMETERS_DRAFT 0xffa5u
#ifdef NGTCP2_USE_GENERIC_SOCKADDR
+typedef unsigned short int ngtcp2_sa_family;
+typedef uint16_t ngtcp2_in_port;
+
typedef struct ngtcp2_sockaddr {
- uint16_t sa_family;
+ ngtcp2_sa_family sa_family;
uint8_t sa_data[14];
} ngtcp2_sockaddr;
} ngtcp2_in_addr;
typedef struct ngtcp2_sockaddr_in {
- uint16_t sin_family;
- uint16_t sin_port;
+ ngtcp2_sa_family sin_family;
+ ngtcp2_in_port sin_port;
ngtcp2_in_addr sin_addr;
uint8_t sin_zero[8];
} ngtcp2_sockaddr_in;
-# define NGTCP2_SS_MAXSIZE 128
-# define NGTCP2_SS_ALIGNSIZE (sizeof(uint64_t))
-# define NGTCP2_SS_PAD1SIZE (NGTCP2_SS_ALIGNSIZE - sizeof(uint16_t))
-# define NGTCP2_SS_PAD2SIZE \
- (NGTCP2_SS_MAXSIZE - \
- (sizeof(uint16_t) + NGTCP2_SS_PAD1SIZE + NGTCP2_SS_ALIGNSIZE))
-
-typedef struct ngtcp2_sockaddr_storage {
- uint16_t ss_family;
- uint8_t _ss_pad1[NGTCP2_SS_PAD1SIZE];
- uint64_t _ss_align;
- uint8_t _ss_pad2[NGTCP2_SS_PAD2SIZE];
-} ngtcp2_sockaddr_storage;
-
-# undef NGTCP2_SS_PAD2SIZE
-# undef NGTCP2_SS_PAD1SIZE
-# undef NGTCP2_SS_ALIGNSIZE
-# undef NGTCP2_SS_MAXSIZE
-
typedef uint32_t ngtcp2_socklen;
-#else
+#else /* !NGTCP2_USE_GENERIC_SOCKADDR */
/**
* @typedef
*
* the generic struct sockaddr defined in ngtcp2.h.
*/
typedef struct sockaddr ngtcp2_sockaddr;
-/**
- * @typedef
- *
- * :type:`ngtcp2_sockaddr_storage` is typedefed to struct
- * sockaddr_storage. If :macro:`NGTCP2_USE_GENERIC_SOCKADDR` is
- * defined, it is typedefed to the generic struct sockaddr_storage
- * defined in ngtcp2.h.
- */
-typedef struct sockaddr_storage ngtcp2_sockaddr_storage;
/**
* @typedef
*
* uint32_t.
*/
typedef socklen_t ngtcp2_socklen;
-#endif
+#endif /* !NGTCP2_USE_GENERIC_SOCKADDR */
#if defined(NGTCP2_USE_GENERIC_SOCKADDR) || \
defined(NGTCP2_USE_GENERIC_IPV6_SOCKADDR)
} ngtcp2_in6_addr;
typedef struct ngtcp2_sockaddr_in6 {
- uint16_t sin6_family;
- uint16_t sin6_port;
+ ngtcp2_sa_family sin6_family;
+ ngtcp2_in_port sin6_port;
uint32_t sin6_flowinfo;
ngtcp2_in6_addr sin6_addr;
uint32_t sin6_scope_id;
} ngtcp2_sockaddr_in6;
-#else
+#else /* !defined(NGTCP2_USE_GENERIC_SOCKADDR) && \
+ !defined(NGTCP2_USE_GENERIC_IPV6_SOCKADDR) */
/**
* @typedef
*
* to the generic struct sockaddr_in6 defined in ngtcp2.h.
*/
typedef struct sockaddr_in6 ngtcp2_sockaddr_in6;
-#endif
+#endif /* !defined(NGTCP2_USE_GENERIC_SOCKADDR) && \
+ !defined(NGTCP2_USE_GENERIC_IPV6_SOCKADDR) */
/**
* @struct
*/
ngtcp2_sockaddr_in ipv4;
/**
- * :member:`ipv6` contains IPv4 address and port.
+ * :member:`ipv6` contains IPv6 address and port.
*/
ngtcp2_sockaddr_in6 ipv6;
/**
* @struct
*
* :type:`ngtcp2_version_info` represents version_information
- * structure.
+ * structure. See :rfc:`9368`.
*/
typedef struct ngtcp2_version_info {
/**
*/
typedef struct ngtcp2_transport_params {
/**
- * :member:`preferred_address` contains preferred address if
- * :member:`preferred_address_present` is nonzero.
+ * :member:`preferred_addr` contains preferred address if
+ * :member:`preferred_addr_present` is nonzero.
*/
- ngtcp2_preferred_addr preferred_address;
+ ngtcp2_preferred_addr preferred_addr;
/**
* :member:`original_dcid` is the Destination Connection ID field
* from the first Initial packet from client. Server must specify
ngtcp2_cid original_dcid;
/**
* :member:`initial_scid` is the Source Connection ID field from the
- * first Initial packet the endpoint sends. Application should not
- * specify this field. If :member:`initial_scid_present` is set to
- * nonzero, it indicates this field is set.
+ * first Initial packet the local endpoint sends. Application
+ * should not specify this field. If :member:`initial_scid_present`
+ * is set to nonzero, it indicates this field is set.
*/
ngtcp2_cid initial_scid;
/**
* :member:`retry_scid` is the Source Connection ID field from Retry
* packet. Only server uses this field. If server application
- * received Initial packet with retry token from client and server
- * verified its token, server application must set Destination
- * Connection ID field from the Initial packet to this field and set
- * :member:`retry_scid_present` to nonzero. Server application must
- * verify that the Destination Connection ID from Initial packet was
- * sent in Retry packet by, for example, including the Connection ID
- * in a token, or including it in AAD when encrypting a token.
+ * received Initial packet with retry token from client, and server
+ * successfully verified its token, server application must set
+ * Destination Connection ID field from the Initial packet to this
+ * field, and set :member:`retry_scid_present` to nonzero. Server
+ * application must verify that the Destination Connection ID from
+ * Initial packet was sent in Retry packet by, for example,
+ * including the Connection ID in a token, or including it in AAD
+ * when encrypting a token.
*/
ngtcp2_cid retry_scid;
/**
* :member:`initial_max_stream_data_bidi_local` is the size of flow
* control window of locally initiated stream. This is the number
- * of bytes that the remote endpoint can send and the local endpoint
- * must ensure that it has enough buffer to receive them.
+ * of bytes that the remote endpoint can send, and the local
+ * endpoint must ensure that it has enough buffer to receive them.
*/
uint64_t initial_max_stream_data_bidi_local;
/**
* :member:`initial_max_stream_data_bidi_remote` is the size of flow
* control window of remotely initiated stream. This is the number
- * of bytes that the remote endpoint can send and the local endpoint
- * must ensure that it has enough buffer to receive them.
+ * of bytes that the remote endpoint can send, and the local
+ * endpoint must ensure that it has enough buffer to receive them.
*/
uint64_t initial_max_stream_data_bidi_remote;
/**
* :member:`initial_max_stream_data_uni` is the size of flow control
* window of remotely initiated unidirectional stream. This is the
- * number of bytes that the remote endpoint can send and the local
+ * number of bytes that the remote endpoint can send, and the local
* endpoint must ensure that it has enough buffer to receive them.
*/
uint64_t initial_max_stream_data_uni;
*/
ngtcp2_duration max_idle_timeout;
/**
- * :member:`max_udp_payload_size` is the maximum datagram size that
- * the endpoint can receive.
+ * :member:`max_udp_payload_size` is the maximum UDP payload size
+ * that the local endpoint can receive.
*/
uint64_t max_udp_payload_size;
/**
uint64_t ack_delay_exponent;
/**
* :member:`max_ack_delay` is the maximum acknowledgement delay by
- * which the endpoint will delay sending acknowledgements.
+ * which the local endpoint will delay sending acknowledgements.
*/
ngtcp2_duration max_ack_delay;
/**
* :member:`max_datagram_frame_size` is the maximum size of DATAGRAM
- * frame that this endpoint willingly receives. Specifying 0
+ * frame that the local endpoint willingly receives. Specifying 0
* disables DATAGRAM support. See :rfc:`9221`.
*/
uint64_t max_datagram_frame_size;
*/
uint8_t stateless_reset_token_present;
/**
- * :member:`disable_active_migration` is nonzero if the endpoint
- * does not support active connection migration.
+ * :member:`disable_active_migration` is nonzero if the local
+ * endpoint does not support active connection migration.
*/
uint8_t disable_active_migration;
/**
*/
uint8_t retry_scid_present;
/**
- * :member:`preferred_address_present` is nonzero if
+ * :member:`preferred_addr_present` is nonzero if
* :member:`preferred_address` is set.
*/
- uint8_t preferred_address_present;
+ uint8_t preferred_addr_present;
/**
* :member:`stateless_reset_token` contains stateless reset token.
*/
uint64_t placeholder_field2;
} ngtcp2_transport_params;
-/**
- * @enum
- *
- * :type:`ngtcp2_pktns_id` defines packet number space identifier.
- */
-typedef enum ngtcp2_pktns_id {
- /**
- * :enum:`NGTCP2_PKTNS_ID_INITIAL` is the Initial packet number
- * space.
- */
- NGTCP2_PKTNS_ID_INITIAL,
- /**
- * :enum:`NGTCP2_PKTNS_ID_HANDSHAKE` is the Handshake packet number
- * space.
- */
- NGTCP2_PKTNS_ID_HANDSHAKE,
- /**
- * :enum:`NGTCP2_PKTNS_ID_APPLICATION` is the Application data
- * packet number space.
- */
- NGTCP2_PKTNS_ID_APPLICATION,
- /**
- * :enum:`NGTCP2_PKTNS_ID_MAX` is defined to get the number of
- * packet number spaces.
- */
- NGTCP2_PKTNS_ID_MAX
-} ngtcp2_pktns_id;
-
#define NGTCP2_CONN_INFO_V1 1
#define NGTCP2_CONN_INFO_VERSION NGTCP2_CONN_INFO_V1
typedef void (*ngtcp2_qlog_write)(void *user_data, uint32_t flags,
const void *data, size_t datalen);
-/**
- * @struct
- *
- * :type:`ngtcp2_qlog_settings` is a set of settings for qlog.
- */
-typedef struct ngtcp2_qlog_settings {
- /**
- * :member:`odcid` is Original Destination Connection ID sent by
- * client. It is used as group_id and ODCID fields. Client ignores
- * this field and uses dcid parameter passed to
- * `ngtcp2_conn_client_new()`.
- */
- ngtcp2_cid odcid;
- /**
- * :member:`write` is a callback function to write qlog. Setting
- * ``NULL`` disables qlog.
- */
- ngtcp2_qlog_write write;
-} ngtcp2_qlog_settings;
-
#define NGTCP2_SETTINGS_V1 1
#define NGTCP2_SETTINGS_VERSION NGTCP2_SETTINGS_V1
*/
typedef struct ngtcp2_settings {
/**
- * :member:`qlog` is qlog settings.
+ * :member:`qlog_write` is a callback function to write qlog.
+ * Setting ``NULL`` disables qlog.
*/
- ngtcp2_qlog_settings qlog;
+ ngtcp2_qlog_write qlog_write;
/**
* :member:`cc_algo` specifies congestion control algorithm.
*/
ngtcp2_printf log_printf;
/**
* :member:`max_tx_udp_payload_size` is the maximum size of UDP
- * datagram payload that this endpoint transmits. It is used by
- * congestion controller to compute congestion window.
+ * datagram payload that the local endpoint transmits. It is used
+ * by congestion controller to compute congestion window.
*/
size_t max_tx_udp_payload_size;
/**
*
* `ngtcp2_conn_server_new` and `ngtcp2_conn_client_new` make a copy
* of token.
+ *
+ * Set NULL if there is no token.
*/
const uint8_t *token;
/**
- * :member:`tokenlen` is the length of :member:`token`.
+ * :member:`tokenlen` is the length of :member:`token`. Set 0 if
+ * there is no token.
*/
size_t tokenlen;
/**
uint64_t max_stream_window;
/**
* :member:`ack_thresh` is the minimum number of the received ACK
- * eliciting packets that triggers the immediate acknowledgement.
+ * eliciting packets that trigger the immediate acknowledgement from
+ * the local endpoint.
*/
size_t ack_thresh;
/**
* :member:`no_tx_udp_payload_size_shaping`, if set to nonzero,
* instructs the library not to limit the UDP payload size to
* :macro:`NGTCP2_MAX_UDP_PAYLOAD_SIZE` (which can be extended by
- * Path MTU Discovery) and instead use the mininum size among the
+ * Path MTU Discovery), and instead use the minimum size among the
* given buffer size, :member:`max_tx_udp_payload_size`, and the
- * received max_udp_payload QUIC transport parameter.
+ * received max_udp_payload_size QUIC transport parameter.
*/
uint8_t no_tx_udp_payload_size_shaping;
/**
* If there is no overlap, but the client chosen version is
* supported by the library, the server chooses the client chosen
* version as the negotiated version. This version set corresponds
- * to Offered Versions in QUIC Version Negotiation draft, and it
- * should be included in Version Negotiation packet.
+ * to Offered Versions described in :rfc:`9368`, and it should be
+ * included in Version Negotiation packet.
*
* Client uses this field and :member:`original_version` to prevent
* version downgrade attack if it reacted upon Version Negotiation
* <ngtcp2_version_info.available_versions>` field of outgoing
* version_information QUIC transport parameter.
*
- * For server, this corresponds to Fully-Deployed Versions in QUIC
- * Version Negotiation draft. If this field is set not, it is set
- * to :member:`preferred_versions` internally if
+ * For server, this corresponds to Fully-Deployed Versions described
+ * in :rfc:`9368`. If this field is not set, it is set to
+ * :member:`preferred_versions` internally if
* :member:`preferred_versionslen` is not zero. If this field is
* not set, and :member:`preferred_versionslen` is zero, this field
* is set to :macro:`NGTCP2_PROTO_VER_V1` internally.
*/
ngtcp2_sockaddr *addr;
/**
- * :member:`addrlen` is the length of addr.
+ * :member:`addrlen` is the length of :member:`addr`. It must not
+ * be longer than sizeof(:type:`ngtcp2_sockaddr_union`).
*/
ngtcp2_socklen addrlen;
} ngtcp2_addr;
* Note that :type:`ngtcp2_path` is generally passed to
* :type:`ngtcp2_conn` by an application, and :type:`ngtcp2_conn`
* stores their copies. Unfortunately, there is no way for the
- * application to know when :type:`ngtcp2_conn` finishes using a
+ * application to know when :type:`ngtcp2_conn` finished using a
* specific :type:`ngtcp2_path` object in mid connection, which
* means that the application cannot free the data pointed by this
* field. Therefore, it is advised to use this field only when the
* :type:`ngtcp2_crypto_ctx` is a convenient structure to bind all
* crypto related objects in one place. Use
* `ngtcp2_crypto_ctx_initial` to initialize this struct for Initial
- * packet encryption. For Handshake and 1RTT packets, use
- * `ngtcp2_crypto_ctx_tls`.
+ * packet encryption. For Handshake and 1-RTT packets, use
+ * `ngtcp2_crypto_ctx_tls`. For 0-RTT packets, use
+ * `ngtcp2_crypto_ctx_tls_early`.
*/
typedef struct ngtcp2_crypto_ctx {
/**
* returns the number of bytes required to store the encoded transport
* parameters.
*
- * This function returns the number of written, or one of the
+ * This function returns the number of bytes written, or one of the
* following negative error codes:
*
* :macro:`NGTCP2_ERR_NOBUF`
* |data| of length |datalen|, and stores the result in the object
* pointed by |params|.
*
- * If the optional parameters are missing, the default value is
- * assigned.
+ * If an optional parameter is missing, the default value is assigned.
*
* The following fields may point to somewhere inside the buffer
* pointed by |data| of length |datalen|:
* QUIC version.
*
* If the given packet is Long header packet, this function extracts
- * the version from the packet and assigns it to
+ * the version from the packet, and assigns it to
* :member:`dest->version <ngtcp2_version_cid.version>`. It also
* extracts the pointer to the Destination Connection ID and its
- * length and assigns them to :member:`dest->dcid
+ * length, and assigns them to :member:`dest->dcid
* <ngtcp2_version_cid.dcid>` and :member:`dest->dcidlen
* <ngtcp2_version_cid.dcidlen>` respectively. Similarly, it extracts
- * the pointer to the Source Connection ID and its length and assigns
+ * the pointer to the Source Connection ID and its length, and assigns
* them to :member:`dest->scid <ngtcp2_version_cid.scid>` and
* :member:`dest->scidlen <ngtcp2_version_cid.scidlen>` respectively.
+ * |short_dcidlen| is ignored.
*
* If the given packet is Short header packet, :member:`dest->version
* <ngtcp2_version_cid.version>` will be 0, :member:`dest->scid
* Because the Short header packet does not have the length of
* Destination Connection ID, the caller has to pass the length in
* |short_dcidlen|. This function extracts the pointer to the
- * Destination Connection ID and assigns it to :member:`dest->dcid
+ * Destination Connection ID, and assigns it to :member:`dest->dcid
* <ngtcp2_version_cid.dcid>`. |short_dcidlen| is assigned to
* :member:`dest->dcidlen <ngtcp2_version_cid.dcidlen>`.
*
/**
* @function
*
- * `ngtcp2_pkt_decode_hd_short` decodes QUIC short header packet
- * header in |pkt| of length |pktlen|. |dcidlen| is the length of
- * DCID in packet header. Short header packet does not encode the
- * length of connection ID, thus we need the input from the outside.
- * This function only parses the input just before packet number
- * field. This function can handle Connection ID up to
+ * `ngtcp2_pkt_decode_hd_short` decodes QUIC short header in |pkt| of
+ * length |pktlen|. Short header packet does not encode the length of
+ * Connection ID, thus we need the input from the outside. |dcidlen|
+ * is the length of Destination Connection ID in packet header. This
+ * function only parses the input just before packet number field.
+ * This function can handle Connection ID up to
* :macro:`NGTCP2_MAX_CIDLEN`. Consider to use
* `ngtcp2_pkt_decode_version_cid` to get longer Connection ID. It
* stores the result in the object pointed by |dest|, and returns the
*
* `ngtcp2_pkt_write_version_negotiation` writes Version Negotiation
* packet in the buffer pointed by |dest| whose length is |destlen|.
- * |unused_random| should be generated randomly. |dcid| is the
- * destination connection ID which appears in a packet as a source
- * connection ID sent by client which caused version negotiation.
- * Similarly, |scid| is the source connection ID which appears in a
- * packet as a destination connection ID sent by client. |sv| is a
- * list of supported versions, and |nsv| specifies the number of
- * supported versions included in |sv|.
+ * |unused_random| should be generated randomly. |dcid| is a
+ * Connection ID which appeared in a packet as a Source Connection ID
+ * sent by client which caused version negotiation. Similarly, |scid|
+ * is a Connection ID which appeared in a packet as a Destination
+ * Connection ID sent by client. |sv| is a list of supported
+ * versions, and |nsv| specifies the number of supported versions
+ * included in |sv|.
*
* This function returns the number of bytes written to the buffer, or
* one of the following negative error codes:
* asks TLS stack to produce first TLS cryptographic handshake data.
*
* This implementation of this callback must get the first handshake
- * data from TLS stack and pass it to ngtcp2 library using
+ * data from TLS stack, and pass it to ngtcp2 library using
* `ngtcp2_conn_submit_crypto_data` function. Make sure that before
* calling `ngtcp2_conn_submit_crypto_data` function, client
* application must create initial packet protection keys and IVs, and
* Initial packet from client. An server application must implement
* this callback, and generate initial keys and IVs for both
* transmission and reception. Install them using
- * `ngtcp2_conn_install_initial_key`. |dcid| is the destination
- * connection ID which client generated randomly. It is used to
- * derive initial packet protection keys.
+ * `ngtcp2_conn_install_initial_key`. |dcid| is the Destination
+ * Connection ID in Initial packet received from client. It is used
+ * to derive initial packet protection keys.
*
* The callback function must return 0 if it succeeds. If an error
* occurs, return :macro:`NGTCP2_ERR_CALLBACK_FAILURE` which makes the
/**
* @enum
*
- * :type:`ngtcp2_crypto_level` is encryption level.
+ * :type:`ngtcp2_encryption_level` is QUIC encryption level.
*/
-typedef enum ngtcp2_crypto_level {
+typedef enum ngtcp2_encryption_level {
/**
- * :enum:`NGTCP2_CRYPTO_LEVEL_INITIAL` is Initial Keys encryption
+ * :enum:`NGTCP2_ENCRYPTION_LEVEL_INITIAL` is Initial encryption
* level.
*/
- NGTCP2_CRYPTO_LEVEL_INITIAL,
+ NGTCP2_ENCRYPTION_LEVEL_INITIAL,
/**
- * :enum:`NGTCP2_CRYPTO_LEVEL_HANDSHAKE` is Handshake Keys
- * encryption level.
+ * :enum:`NGTCP2_ENCRYPTION_LEVEL_HANDSHAKE` is Handshake encryption
+ * level.
*/
- NGTCP2_CRYPTO_LEVEL_HANDSHAKE,
+ NGTCP2_ENCRYPTION_LEVEL_HANDSHAKE,
/**
- * :enum:`NGTCP2_CRYPTO_LEVEL_APPLICATION` is Application Data
- * (1-RTT) Keys encryption level.
+ * :enum:`NGTCP2_ENCRYPTION_LEVEL_1RTT` is 1-RTT encryption level.
*/
- NGTCP2_CRYPTO_LEVEL_APPLICATION,
+ NGTCP2_ENCRYPTION_LEVEL_1RTT,
/**
- * :enum:`NGTCP2_CRYPTO_LEVEL_EARLY` is Early Data (0-RTT) Keys
- * encryption level.
+ * :enum:`NGTCP2_ENCRYPTION_LEVEL_0RTT` is 0-RTT encryption level.
*/
- NGTCP2_CRYPTO_LEVEL_EARLY
-} ngtcp2_crypto_level;
+ NGTCP2_ENCRYPTION_LEVEL_0RTT
+} ngtcp2_encryption_level;
/**
* @functypedef
*
* :type`ngtcp2_recv_crypto_data` is invoked when crypto data is
- * received. The received data is pointed to by |data|, and its
- * length is |datalen|. The |offset| specifies the offset where
- * |data| is positioned. |user_data| is the arbitrary pointer passed
- * to `ngtcp2_conn_client_new` or `ngtcp2_conn_server_new`. The
- * ngtcp2 library ensures that the crypto data is passed to the
- * application in the increasing order of |offset|. |datalen| is
- * always strictly greater than 0. |crypto_level| indicates the
- * encryption level where this data is received. Crypto data can
- * never be received in
- * :enum:`ngtcp2_crypto_level.NGTCP2_CRYPTO_LEVEL_EARLY`.
+ * received. The received data is pointed by |data|, and its length
+ * is |datalen|. The |offset| specifies the offset where |data| is
+ * positioned. |user_data| is the arbitrary pointer passed to
+ * `ngtcp2_conn_client_new` or `ngtcp2_conn_server_new`. The ngtcp2
+ * library ensures that the crypto data is passed to the application
+ * in the increasing order of |offset|. |datalen| is always strictly
+ * greater than 0. |encryption_level| indicates the encryption level
+ * where this data is received. Crypto data can never be received in
+ * :enum:`ngtcp2_encryption_level.NGTCP2_ENCRYPTION_LEVEL_0RTT`.
*
* The application should provide the given data to TLS stack.
*
* return immediately.
*/
typedef int (*ngtcp2_recv_crypto_data)(ngtcp2_conn *conn,
- ngtcp2_crypto_level crypto_level,
+ ngtcp2_encryption_level encryption_level,
uint64_t offset, const uint8_t *data,
size_t datalen, void *user_data);
* This callback is client use only.
*
* Application must regenerate packet protection key, IV, and header
- * protection key for Initial packets using the destination connection
- * ID obtained by :member:`hd->scid <ngtcp2_pkt_hd.scid>` and install
- * them by calling `ngtcp2_conn_install_initial_key()`.
+ * protection key for Initial packets using the Destination Connection
+ * ID obtained by :member:`hd->scid <ngtcp2_pkt_hd.scid>`, and install
+ * them by calling `ngtcp2_conn_install_initial_key`.
*
* 0-RTT data accepted by the ngtcp2 library will be automatically
* retransmitted as 0-RTT data by the library.
* application to encrypt packet payload. The packet payload to
* encrypt is passed as |plaintext| of length |plaintextlen|. The
* AEAD cipher is |aead|. |aead_ctx| is the AEAD cipher context
- * object which is initialized with encryption key. The nonce is
- * passed as |nonce| of length |noncelen|. The Additional
+ * object which is initialized with the specific encryption key. The
+ * nonce is passed as |nonce| of length |noncelen|. The Additional
* Authenticated Data is passed as |aad| of length |aadlen|.
*
* The implementation of this callback must encrypt |plaintext| using
- * the negotiated cipher suite and write the ciphertext into the
+ * the negotiated cipher suite, and write the ciphertext into the
* buffer pointed by |dest|. |dest| has enough capacity to store the
* ciphertext and any additional AEAD tag data.
*
* application to decrypt packet payload. The packet payload to
* decrypt is passed as |ciphertext| of length |ciphertextlen|. The
* AEAD cipher is |aead|. |aead_ctx| is the AEAD cipher context
- * object which is initialized with decryption key. The nonce is
- * passed as |nonce| of length |noncelen|. The Additional
+ * object which is initialized with the specific decryption key. The
+ * nonce is passed as |nonce| of length |noncelen|. The Additional
* Authenticated Data is passed as |aad| of length |aadlen|.
*
* The implementation of this callback must decrypt |ciphertext| using
- * the negotiated cipher suite and write the ciphertext into the
+ * the negotiated cipher suite, and write the ciphertext into the
* buffer pointed by |dest|. |dest| has enough capacity to store the
* cleartext.
*
* :type:`ngtcp2_hp_mask` is invoked when the ngtcp2 library asks the
* application to produce a mask to encrypt or decrypt packet header.
* The encryption cipher is |hp|. |hp_ctx| is the cipher context
- * object which is initialized with header protection key. The sample
- * is passed as |sample| which is :macro:`NGTCP2_HP_SAMPLELEN` bytes
- * long.
+ * object which is initialized with the specific header protection
+ * key. The sample is passed as |sample| which is
+ * :macro:`NGTCP2_HP_SAMPLELEN` bytes long.
*
* The implementation of this callback must produce a mask using the
- * header protection cipher suite specified by QUIC specification and
+ * header protection cipher suite specified by QUIC specification, and
* write the result into the buffer pointed by |dest|. The length of
* the mask must be at least :macro:`NGTCP2_HP_MASKLEN`. The library
* only uses the first :macro:`NGTCP2_HP_MASKLEN` bytes of the
/**
* @macrosection
*
- * Stream data flags
+ * STREAM frame data flags
*/
/**
/**
* @macro
*
- * :macro:`NGTCP2_STREAM_DATA_FLAG_EARLY` indicates that this chunk of
- * data contains data received in 0RTT packet and the handshake has
+ * :macro:`NGTCP2_STREAM_DATA_FLAG_0RTT` indicates that this chunk of
+ * data contains data received in 0-RTT packet, and the handshake has
* not completed yet, which means that the data might be replayed.
*/
-#define NGTCP2_STREAM_DATA_FLAG_EARLY 0x02u
+#define NGTCP2_STREAM_DATA_FLAG_0RTT 0x02u
/**
* @functypedef
* overlap. The data is passed as |data| of length |datalen|.
* |datalen| may be 0 if and only if |fin| is nonzero.
*
- * If :macro:`NGTCP2_STREAM_DATA_FLAG_EARLY` is set in |flags|, it
- * indicates that a part of or whole data was received in 0RTT packet
- * and a handshake has not completed yet.
+ * If :macro:`NGTCP2_STREAM_DATA_FLAG_0RTT` is set in |flags|, it
+ * indicates that a part of or whole data was received in 0-RTT
+ * packet, and a handshake has not completed yet.
*
* The callback function must return 0 if it succeeds, or
* :macro:`NGTCP2_ERR_CALLBACK_FAILURE` which makes the library return
* @functypedef
*
* :type:`ngtcp2_stream_open` is a callback function which is called
- * when remote stream is opened by peer. This function is not called
- * if stream is opened by implicitly (we might reconsider this
- * behaviour).
+ * when remote stream is opened by a remote endpoint. This function
+ * is not called if stream is opened by implicitly (we might
+ * reconsider this behaviour later).
*
* The implementation of this callback should return 0 if it succeeds.
* Returning :macro:`NGTCP2_ERR_CALLBACK_FAILURE` makes the library
* @functypedef
*
* :type:`ngtcp2_acked_stream_data_offset` is a callback function
- * which is called when stream data is acked, and application can free
- * the data. The acked range of data is [offset, offset + datalen).
- * For a given stream_id, this callback is called sequentially in
- * increasing order of |offset| without any overlap. |datalen| is
- * normally strictly greater than 0. One exception is that when a
- * packet which includes STREAM frame which has fin flag set, and 0
- * length data, this callback is invoked with 0 passed as |datalen|.
- *
- * If a stream is closed prematurely and stream data is still
+ * which is called when stream data in range [|offset|, |offset| +
+ * |datalen|) is acknowledged, and application can free the portion of
+ * data. For a given |stream_id|, this callback is called
+ * sequentially in increasing order of |offset| without any overlap.
+ * |datalen| is normally strictly greater than 0. One exception is
+ * that when a STREAM frame has fin flag set and 0 length data, this
+ * callback is invoked with |datalen| == 0.
+ *
+ * If a stream is closed prematurely, and stream data is still
* in-flight, this callback function is not called for those data.
+ * After :member:`ngtcp2_callbacks.stream_close` is called for a
+ * particular stream, |conn| does not touch data for the closed stream
+ * again, and application can free all unacknowledged stream data.
*
* The implementation of this callback should return 0 if it succeeds.
* Returning :macro:`NGTCP2_ERR_CALLBACK_FAILURE` makes the library
* :type:`ngtcp2_extend_max_stream_data` is a callback function which
* is invoked when max stream data is extended. |stream_id|
* identifies the stream. |max_data| is a cumulative number of bytes
- * the endpoint can send on this stream.
+ * an endpoint can send on this stream.
*
* The callback function must return 0 if it succeeds. Returning
* :macro:`NGTCP2_ERR_CALLBACK_FAILURE` makes the library call return
/**
* @functypedef
*
- * :type:`ngtcp2_rand` is a callback function to get randomized byte
- * string from application. Application must fill random |destlen|
- * bytes to the buffer pointed by |dest|. The generated bytes are
- * used only in non-cryptographic context.
+ * :type:`ngtcp2_rand` is a callback function to get random data of
+ * length |destlen|. Application must fill random |destlen| bytes to
+ * the buffer pointed by |dest|. The generated data is used only in
+ * non-cryptographic context.
*/
typedef void (*ngtcp2_rand)(uint8_t *dest, size_t destlen,
const ngtcp2_rand_ctx *rand_ctx);
*
* :type:`ngtcp2_get_new_connection_id` is a callback function to ask
* an application for new connection ID. Application must generate
- * new unused connection ID with the exact |cidlen| bytes and store it
- * in |cid|. It also has to generate stateless reset token into
- * |token|. The length of stateless reset token is
+ * new unused connection ID with the exact |cidlen| bytes, and store
+ * it in |cid|. It also has to generate a stateless reset token, and
+ * store it in |token|. The length of stateless reset token is
* :macro:`NGTCP2_STATELESS_RESET_TOKENLEN` and it is guaranteed that
- * the buffer pointed by |cid| has the sufficient space to store the
+ * the buffer pointed by |token| has the sufficient space to store the
* token.
*
* The callback function must return 0 if it succeeds. Returning
*
* :type:`ngtcp2_remove_connection_id` is a callback function which
* notifies the application that connection ID |cid| is no longer used
- * by remote endpoint.
+ * by a remote endpoint. This Connection ID was previously offered by
+ * a local endpoint, and a remote endpoint could use it as Destination
+ * Connection ID when sending QUIC packet.
*
* The callback function must return 0 if it succeeds. Returning
* :macro:`NGTCP2_ERR_CALLBACK_FAILURE` makes the library call return
* |current_tx_secret| of length |secretlen|. They are decryption and
* encryption secrets respectively.
*
- * The application has to generate new secrets and keys for both
- * encryption and decryption, and write decryption secret and IV to
- * the buffer pointed by |rx_secret| and |rx_iv| respectively. It
- * also has to create new AEAD cipher context object with new
- * decryption key and initialize |rx_aead_ctx| with it. Similarly,
- * write encryption secret and IV to the buffer pointed by |tx_secret|
- * and |tx_iv|. Create new AEAD cipher context object with new
- * encryption key and initialize |tx_aead_ctx| with it. All given
- * buffers have the enough capacity to store secret, key and IV.
+ * The application must generate new secrets and keys for both
+ * encryption and decryption. It must write decryption secret and IV
+ * to the buffer pointed by |rx_secret| and |rx_iv| respectively. It
+ * also must create new AEAD cipher context object with new decryption
+ * key and initialize |rx_aead_ctx| with it. Similarly, write
+ * encryption secret and IV to the buffer pointed by |tx_secret| and
+ * |tx_iv|. Create new AEAD cipher context object with new encryption
+ * key and initialize |tx_aead_ctx| with it. All given buffers have
+ * the enough capacity to store secret, key and IV.
*
* The callback function must return 0 if it succeeds. Returning
* :macro:`NGTCP2_ERR_CALLBACK_FAILURE` makes the library call return
* @macro
*
* :macro:`NGTCP2_PATH_VALIDATION_FLAG_NEW_TOKEN` indicates that
- * server should send NEW_TOKEN for the new remote address. This flag
- * is only set for server.
+ * server should send NEW_TOKEN frame for the new remote address.
+ * This flag is only set for server.
*/
#define NGTCP2_PATH_VALIDATION_FLAG_NEW_TOKEN 0x02u
* @functypedef
*
* :type:`ngtcp2_path_validation` is a callback function which tells
- * the application the outcome of path validation. |flags| is zero or
+ * an application the outcome of path validation. |flags| is zero or
* more of :macro:`NGTCP2_PATH_VALIDATION_FLAG_*
* <NGTCP2_PATH_VALIDATION_FLAG_NONE>`. |path| is the path that was
- * validated. |old_path| is the path that is previsouly used before
- * the endpoint has migrated to |path| if |old_path| is not NULL. If
- * |res| is
+ * validated. |old_path| is the path that is previously used before a
+ * local endpoint has migrated to |path| if |old_path| is not NULL.
+ * If |res| is
* :enum:`ngtcp2_path_validation_result.NGTCP2_PATH_VALIDATION_RESULT_SUCCESS`,
* the path validation succeeded. If |res| is
* :enum:`ngtcp2_path_validation_result.NGTCP2_PATH_VALIDATION_RESULT_FAILURE`,
* from `ngtcp2_conn_get_path()`. Both :member:`dest->local.addr
* <ngtcp2_addr.addr>` and :member:`dest->remote.addr
* <ngtcp2_addr.addr>` point to buffers which are at least
- * ``sizeof(struct sockaddr_storage)`` bytes long, respectively. If
+ * sizeof(:type:`ngtcp2_sockaddr_union`) bytes long, respectively. If
* an application denies the preferred addresses, just leave |dest|
* unmodified (or set :member:`dest->remote.addrlen
- * <ngtcp2_addr.addrlen>` to 0) and return 0.
+ * <ngtcp2_addr.addrlen>` to 0), and return 0.
*
* The callback function must return 0 if it succeeds. Returning
* :macro:`NGTCP2_ERR_CALLBACK_FAILURE` makes the library call return
typedef enum ngtcp2_connection_id_status_type {
/**
* :enum:`NGTCP2_CONNECTION_ID_STATUS_TYPE_ACTIVATE` indicates that
- * a local endpoint starts using new destination Connection ID.
+ * a local endpoint starts using new Destination Connection ID.
*/
NGTCP2_CONNECTION_ID_STATUS_TYPE_ACTIVATE,
/**
* :enum:`NGTCP2_CONNECTION_ID_STATUS_TYPE_DEACTIVATE` indicates
- * that a local endpoint stops using a given destination Connection
+ * that a local endpoint stops using a given Destination Connection
* ID.
*/
NGTCP2_CONNECTION_ID_STATUS_TYPE_DEACTIVATE
* @functypedef
*
* :type:`ngtcp2_connection_id_status` is a callback function which is
- * called when the status of Connection ID changes.
+ * called when the status of Destination Connection ID changes.
*
- * |token| is the associated stateless reset token and it is ``NULL``
+ * |token| is the associated stateless reset token, and it is ``NULL``
* if no token is present.
*
* |type| is the one of the value defined in
* @functypedef
*
* :type:`ngtcp2_recv_new_token` is a callback function which is
- * called when new token is received from server.
+ * called when new token is received from server. This callback is
+ * client use only.
*
* |token| is the received token of length |tokenlen| bytes long.
*
/**
* @macrosection
*
- * Datagram flags
+ * DATAGRAM frame flags
*/
/**
/**
* @macro
*
- * :macro:`NGTCP2_DATAGRAM_FLAG_EARLY` indicates that DATAGRAM frame
- * is received in 0RTT packet and the handshake has not completed yet,
+ * :macro:`NGTCP2_DATAGRAM_FLAG_0RTT` indicates that DATAGRAM frame is
+ * received in 0-RTT packet, and the handshake has not completed yet,
* which means that the data might be replayed.
*/
-#define NGTCP2_DATAGRAM_FLAG_EARLY 0x01u
+#define NGTCP2_DATAGRAM_FLAG_0RTT 0x01u
/**
* @functypedef
* received. |flags| is bitwise-OR of zero or more of
* :macro:`NGTCP2_DATAGRAM_FLAG_* <NGTCP2_DATAGRAM_FLAG_NONE>`.
*
- * If :macro:`NGTCP2_DATAGRAM_FLAG_EARLY` is set in |flags|, it
- * indicates that DATAGRAM frame was received in 0RTT packet and a
+ * If :macro:`NGTCP2_DATAGRAM_FLAG_0RTT` is set in |flags|, it
+ * indicates that DATAGRAM frame was received in 0-RTT packet, and a
* handshake has not completed yet.
*
* The callback function must return 0 if it succeeds, or
*
* :type:`ngtcp2_get_path_challenge_data` is a callback function to
* ask an application for new data that is sent in PATH_CHALLENGE
- * frame. Application must generate new unpredictable exactly
- * :macro:`NGTCP2_PATH_CHALLENGE_DATALEN` bytes of random data and
+ * frame. Application must generate new unpredictable, exactly
+ * :macro:`NGTCP2_PATH_CHALLENGE_DATALEN` bytes of random data, and
* store them into the buffer pointed by |data|.
*
* The callback function must return 0 if it succeeds. Returning
* server, it is called once when the version is negotiated.
*
* The implementation of this callback must install new Initial keys
- * for |version|. Use `ngtcp2_conn_install_vneg_initial_key` to
- * install keys.
+ * for |version| and Destination Connection ID |client_dcid| from
+ * client. Use `ngtcp2_conn_install_vneg_initial_key` to install
+ * keys.
*
* The callback function must return 0 if it succeeds. Returning
* :macro:`NGTCP2_ERR_CALLBACK_FAILURE` makes the library call return
* :macro:`NGTCP2_ERR_CALLBACK_FAILURE` makes the library call return
* immediately.
*/
-typedef int (*ngtcp2_recv_key)(ngtcp2_conn *conn, ngtcp2_crypto_level level,
+typedef int (*ngtcp2_recv_key)(ngtcp2_conn *conn, ngtcp2_encryption_level level,
void *user_data);
/**
* @functypedef
*
- * :type:`ngtcp2_early_data_rejected` is invoked when early data was
- * rejected by server, or client decided not to attempt early data.
+ * :type:`ngtcp2_tls_early_data_rejected` is invoked when early data
+ * was rejected by server during TLS handshake, or client decided not
+ * to attempt early data.
*
* The callback function must return 0 if it succeeds. Returning
* :macro:`NGTCP2_ERR_CALLBACK_FAILURE` makes the library call return
* immediately.
*/
-typedef int (*ngtcp2_early_data_rejected)(ngtcp2_conn *conn, void *user_data);
+typedef int (*ngtcp2_tls_early_data_rejected)(ngtcp2_conn *conn,
+ void *user_data);
#define NGTCP2_CALLBACKS_V1 1
#define NGTCP2_CALLBACKS_VERSION NGTCP2_CALLBACKS_V1
ngtcp2_client_initial client_initial;
/**
* :member:`recv_client_initial` is a callback function which is
- * invoked when a server receives the first packet from client.
- * This callback function must be specified for a server application.
+ * invoked when a server receives the first Initial packet from
+ * client. This callback function must be specified for a server
+ * application.
*/
ngtcp2_recv_client_initial recv_client_initial;
/**
ngtcp2_decrypt decrypt;
/**
* :member:`hp_mask` is a callback function which is invoked to get
- * a mask to encrypt or decrypt packet header. This callback
+ * a mask to encrypt or decrypt QUIC packet header. This callback
* function must be specified.
*/
ngtcp2_hp_mask hp_mask;
/**
* :member:`recv_stream_data` is a callback function which is
- * invoked when STREAM data, which includes application data, is
+ * invoked when stream data, which includes application data, is
* received. This callback function is optional.
*/
ngtcp2_recv_stream_data recv_stream_data;
/**
* :member:`acked_stream_data_offset` is a callback function which
- * is invoked when STREAM data, which includes application data, is
+ * is invoked when stream data, which includes application data, is
* acknowledged by a remote endpoint. It tells an application the
- * largest offset of acknowledged STREAM data without a gap so that
- * application can free memory for the data. This callback function
- * is optional.
+ * largest offset of acknowledged stream data without a gap so that
+ * application can free memory for the data up to that offset. This
+ * callback function is optional.
*/
ngtcp2_acked_stream_data_offset acked_stream_data_offset;
/**
ngtcp2_extend_max_streams extend_max_local_streams_uni;
/**
* :member:`rand` is a callback function which is invoked when the
- * library needs sequence of random data. This callback function
- * must be specified.
+ * library needs random data. This callback function must be
+ * specified.
*/
ngtcp2_rand rand;
/**
/**
* :member:`update_key` is a callback function which is invoked when
* the library tells an application that it must update keying
- * materials and install new keys. This callback function must be
+ * materials, and install new keys. This callback function must be
* specified.
*/
ngtcp2_update_key update_key;
/**
* :member:`select_preferred_addr` is a callback function which is
* invoked when the library asks a client to select preferred
- * address presented by a server. This callback function is
- * optional.
+ * address presented by a server. If not set, client ignores
+ * preferred addresses. This callback function is optional.
*/
ngtcp2_select_preferred_addr select_preferred_addr;
/**
ngtcp2_extend_max_streams extend_max_remote_streams_uni;
/**
* :member:`extend_max_stream_data` is callback function which is
- * invoked when the maximum offset of STREAM data that a local
+ * invoked when the maximum offset of stream data that a local
* endpoint can send is increased. This callback function is
* optional.
*/
ngtcp2_extend_max_stream_data extend_max_stream_data;
/**
* :member:`dcid_status` is a callback function which is invoked
- * when the new destination Connection ID is activated or the
- * activated destination Connection ID is now deactivated. This
+ * when the new Destination Connection ID is activated, or the
+ * activated Destination Connection ID is now deactivated. This
* callback function is optional.
*/
ngtcp2_connection_id_status dcid_status;
/**
* :member:`handshake_confirmed` is a callback function which is
* invoked when both endpoints agree that handshake has finished.
- * This field is ignored by server because handshake_completed
- * indicates the handshake confirmation for server. This callback
- * function is optional.
+ * This field is ignored by server because
+ * :member:`handshake_completed` also indicates the handshake
+ * confirmation for server. This callback function is optional.
*/
ngtcp2_handshake_confirmed handshake_confirmed;
/**
ngtcp2_recv_datagram recv_datagram;
/**
* :member:`ack_datagram` is a callback function which is invoked
- * when a packet containing DATAGRAM frame is acknowledged. This
- * callback function is optional.
+ * when a QUIC packet containing DATAGRAM frame is acknowledged by a
+ * remote endpoint. This callback function is optional.
*/
ngtcp2_ack_datagram ack_datagram;
/**
* :member:`lost_datagram` is a callback function which is invoked
- * when a packet containing DATAGRAM frame is declared lost. This
- * callback function is optional.
+ * when a QUIC packet containing DATAGRAM frame is declared lost.
+ * This callback function is optional.
*/
ngtcp2_lost_datagram lost_datagram;
/**
* :member:`get_path_challenge_data` is a callback function which is
- * invoked when the library needs new PATH_CHALLENGE data. This
- * callback must be specified.
+ * invoked when the library needs new data sent along with
+ * PATH_CHALLENGE frame. This callback must be specified.
*/
ngtcp2_get_path_challenge_data get_path_challenge_data;
/**
* :member:`recv_rx_key` is a callback function which is invoked
* when a new key for decrypting packets is installed during QUIC
* cryptographic handshake. It is not called for
- * :enum:`ngtcp2_crypto_level.NGTCP2_CRYPTO_LEVEL_INITIAL`.
+ * :enum:`ngtcp2_encryption_level.NGTCP2_ENCRYPTION_LEVEL_INITIAL`.
*/
ngtcp2_recv_key recv_rx_key;
/**
* :member:`recv_tx_key` is a callback function which is invoked
* when a new key for encrypting packets is installed during QUIC
* cryptographic handshake. It is not called for
- * :enum:`ngtcp2_crypto_level.NGTCP2_CRYPTO_LEVEL_INITIAL`.
+ * :enum:`ngtcp2_encryption_level.NGTCP2_ENCRYPTION_LEVEL_INITIAL`.
*/
ngtcp2_recv_key recv_tx_key;
/**
- * :member:`ngtcp2_early_data_rejected` is a callback function which
- * is invoked when an attempt to send early data by client was
- * rejected by server, or client decided not to attempt early data.
- * This callback function is only used by client.
+ * :member:`tls_early_data_rejected` is a callback function which is
+ * invoked when server rejected early data during TLS handshake, or
+ * client decided not to attempt early data. This callback function
+ * is only used by client.
*/
- ngtcp2_early_data_rejected early_data_rejected;
+ ngtcp2_tls_early_data_rejected tls_early_data_rejected;
} ngtcp2_callbacks;
/**
*
* The primary use case of this function is for server to send
* CONNECTION_CLOSE frame in Initial packet to close connection
- * without committing the state when validating Retry token fails.
+ * without committing any state when validating Retry token fails.
*
* This function returns the number of bytes written if it succeeds,
* or one of the following negative error codes:
* @function
*
* `ngtcp2_pkt_write_retry` writes Retry packet in the buffer pointed
- * by |dest| whose length is |destlen|. |dcid| is the destination
- * connection ID which appeared in a packet as a source connection ID
- * sent by client. |scid| is a server chosen source connection ID.
- * |odcid| specifies Original Destination Connection ID which appeared
- * in a packet as a destination connection ID sent by client. |token|
+ * by |dest| whose length is |destlen|. |dcid| is the Connection ID
+ * which appeared in a packet as a Source Connection ID sent by
+ * client. |scid| is a server chosen Source Connection ID. |odcid|
+ * specifies Original Destination Connection ID which appeared in a
+ * packet as a Destination Connection ID sent by client. |token|
* specifies Retry Token, and |tokenlen| specifies its length. |aead|
* must be AEAD_AES_128_GCM. |aead_ctx| must be initialized with
* :macro:`NGTCP2_RETRY_KEY` as an encryption key.
*
* `ngtcp2_accept` is used by server implementation, and decides
* whether packet |pkt| of length |pktlen| from client is acceptable
- * for the very initial packet to a connection.
+ * for the very first packet to a connection.
*
* If |dest| is not ``NULL`` and the function returns 0, the decoded
- * packet header is stored to the object pointed by |dest|.
+ * packet header is stored in the object pointed by |dest|.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
* @function
*
* `ngtcp2_conn_client_new` creates new :type:`ngtcp2_conn`, and
- * initializes it as client. |dcid| is randomized destination
- * connection ID. |scid| is source connection ID.
- * |client_chosen_version| is a QUIC version that a client chooses.
- * |path| is the network path where this QUIC connection is being
- * established and must not be ``NULL``. |callbacks|, |settings|, and
- * |params| must not be ``NULL``, and the function make a copy of each
- * of them. |params| is local QUIC transport parameters and sent to a
- * remote endpoint during handshake. |user_data| is the arbitrary
- * pointer which is passed to the user-defined callback functions. If
- * |mem| is ``NULL``, the memory allocator returned by
- * `ngtcp2_mem_default()` is used.
+ * initializes it as client. On success, it stores the pointer to the
+ * newly allocated object in |*pconn|. |dcid| is a randomized
+ * Destination Connection ID which must be longer than or equal to
+ * :macro:`NGTCP2_MIN_INITIAL_DCIDLEN`. |scid| is a Source Connection
+ * ID chosen by client. |client_chosen_version| is a QUIC version
+ * that a client chooses. |path| is the network path where this QUIC
+ * connection is being established, and must not be ``NULL``.
+ * |callbacks|, |settings|, and |params| must not be ``NULL``, and the
+ * function makes a copy of each of them. |params| is a local QUIC
+ * transport parameters, and sent to a remote endpoint during
+ * handshake. |user_data| is the arbitrary pointer which is passed to
+ * the user-defined callback functions. If |mem| is ``NULL``, the
+ * memory allocator returned by `ngtcp2_mem_default()` is used.
+ *
+ * Call `ngtcp2_conn_del` to free memory allocated for |*pconn|.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
* @function
*
* `ngtcp2_conn_server_new` creates new :type:`ngtcp2_conn`, and
- * initializes it as server. |dcid| is a destination connection ID.
- * |scid| is a source connection ID. |path| is the network path where
- * this QUIC connection is being established and must not be ``NULL``.
- * |client_chosen_version| is a QUIC version that a client chooses.
- * |callbacks|, |settings|, and |params| must not be ``NULL``, and the
- * function make a copy of each of them. |params| is local QUIC
- * transport parameters and sent to a remote endpoint during
- * handshake. |user_data| is the arbitrary pointer which is passed to
- * the user-defined callback functions. If |mem| is ``NULL``, the
- * memory allocator returned by `ngtcp2_mem_default()` is used.
+ * initializes it as server. On success, it stores the pointer to the
+ * newly allocated object in |*pconn|. |dcid| is a Destination
+ * Connection ID, and is usually the Connection ID that appears in
+ * client Initial packet as Source Connection ID. |scid| is a Source
+ * Connection ID chosen by server. |path| is the network path where
+ * this QUIC connection is being established, and must not be
+ * ``NULL``. |client_chosen_version| is a QUIC version that a client
+ * chooses. |callbacks|, |settings|, and |params| must not be
+ * ``NULL``, and the function makes a copy of each of them. |params|
+ * is a local QUIC transport parameters, and sent to a remote endpoint
+ * during handshake. |user_data| is the arbitrary pointer which is
+ * passed to the user-defined callback functions. If |mem| is
+ * ``NULL``, the memory allocator returned by `ngtcp2_mem_default()`
+ * is used.
+ *
+ * Call `ngtcp2_conn_del` to free memory allocated for |*pconn|.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* This function returns 0 if it succeeds, or negative error codes.
* If :macro:`NGTCP2_ERR_RETRY` is returned, application must be a
- * server and it must perform address validation by sending Retry
- * packet and discard the connection state. If
+ * server, and it must perform address validation by sending Retry
+ * packet (see `ngtcp2_crypto_write_retry` and
+ * `ngtcp2_pkt_write_retry`), and discard the connection state. If
* :macro:`NGTCP2_ERR_DROP_CONN` is returned, server application must
* drop the connection silently (without sending any CONNECTION_CLOSE
- * frame) and discard connection state. If
+ * frame), and discard connection state. If
* :macro:`NGTCP2_ERR_DRAINING` is returned, a connection has entered
* the draining state, and no further packet transmission is allowed.
* If :macro:`NGTCP2_ERR_CRYPTO` is returned, the error happened in
- * TLS stack and `ngtcp2_conn_get_tls_alert` returns TLS alert if set.
+ * TLS stack, and `ngtcp2_conn_get_tls_alert` returns TLS alert if
+ * set.
*
* If any other negative errors are returned, call
* `ngtcp2_conn_write_connection_close` to get terminal packet, and
* @function
*
* `ngtcp2_conn_write_pkt` is equivalent to calling
- * `ngtcp2_conn_writev_stream` with -1 as stream_id, no stream data, and
- * :macro:`NGTCP2_WRITE_STREAM_FLAG_NONE` as flags.
+ * `ngtcp2_conn_writev_stream` with -1 as |stream_id|, no stream data,
+ * and :macro:`NGTCP2_WRITE_STREAM_FLAG_NONE` as flags.
*/
NGTCP2_EXTERN ngtcp2_ssize ngtcp2_conn_write_pkt_versioned(
ngtcp2_conn *conn, ngtcp2_path *path, int pkt_info_version,
/**
* @function
*
- * `ngtcp2_conn_get_handshake_completed` returns nonzero if QUIC handshake
- * has completed.
+ * `ngtcp2_conn_get_handshake_completed` returns nonzero if QUIC
+ * handshake has completed.
*/
NGTCP2_EXTERN int ngtcp2_conn_get_handshake_completed(ngtcp2_conn *conn);
*
* `ngtcp2_conn_install_initial_key` installs packet protection keying
* materials for Initial packets. |rx_aead_ctx| is AEAD cipher
- * context object and must be initialized with a decryption key.
+ * context object, and must be initialized with a decryption key.
* |rx_iv| is IV of length |rx_ivlen| for decryption. |rx_hp_ctx| is
* a packet header protection cipher context object for decryption.
* Similarly, |tx_aead_ctx|, |tx_iv| and |tx_hp_ctx| are for
- * encrypting outgoing packets and are the same length with the
+ * encrypting outgoing packets, and are the same length with the
* decryption counterpart . If they have already been set, they are
* overwritten.
*
*
* If this function succeeds, |conn| takes ownership of |rx_aead_ctx|,
* |rx_hp_ctx|, |tx_aead_ctx|, and |tx_hp_ctx|.
- * :type:`ngtcp2_delete_crypto_aead_ctx` and
- * :type:`ngtcp2_delete_crypto_cipher_ctx` will be called to delete
- * these objects when they are no longer used. If this function
- * fails, the caller is responsible to delete them.
- *
- * After receiving Retry packet, the DCID most likely changes. In
- * that case, client application must generate these keying materials
- * again based on new DCID and install them again.
+ * :member:`ngtcp2_callbacks.delete_crypto_aead_ctx` and
+ * :member:`ngtcp2_callbacks.delete_crypto_cipher_ctx` will be called
+ * to delete these objects when they are no longer used. If this
+ * function fails, the caller is responsible to delete them.
+ *
+ * After receiving Retry packet, a Destination Connection ID that
+ * client sends in Initial packet most likely changes. In that case,
+ * client application must generate these keying materials again based
+ * on new Destination Connection ID, and install them again with this
+ * function.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
* `ngtcp2_conn_install_vneg_initial_key` installs packet protection
* keying materials for Initial packets on compatible version
* negotiation for |version|. |rx_aead_ctx| is AEAD cipher context
- * object and must be initialized with a decryption key. |rx_iv| is
+ * object, and must be initialized with a decryption key. |rx_iv| is
* IV of length |rx_ivlen| for decryption. |rx_hp_ctx| is a packet
* header protection cipher context object for decryption. Similarly,
* |tx_aead_ctx|, |tx_iv| and |tx_hp_ctx| are for encrypting outgoing
- * packets and are the same length with the decryption counterpart .
+ * packets, and are the same length with the decryption counterpart.
* If they have already been set, they are overwritten.
*
* |ivlen| must be the minimum length of AEAD nonce, or 8 bytes if
*
* If this function succeeds, |conn| takes ownership of |rx_aead_ctx|,
* |rx_hp_ctx|, |tx_aead_ctx|, and |tx_hp_ctx|.
- * :type:`ngtcp2_delete_crypto_aead_ctx` and
- * :type:`ngtcp2_delete_crypto_cipher_ctx` will be called to delete
- * these objects when they are no longer used. If this function
- * fails, the caller is responsible to delete them.
+ * :member:`ngtcp2_callbacks.delete_crypto_aead_ctx` and
+ * :member:`ngtcp2_callbacks.delete_crypto_cipher_ctx` will be called
+ * to delete these objects when they are no longer used. If this
+ * function fails, the caller is responsible to delete them.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
* that is larger.
*
* If this function succeeds, |conn| takes ownership of |aead_ctx|,
- * and |hp_ctx|. :type:`ngtcp2_delete_crypto_aead_ctx` and
- * :type:`ngtcp2_delete_crypto_cipher_ctx` will be called to delete
- * these objects when they are no longer used. If this function
- * fails, the caller is responsible to delete them.
+ * and |hp_ctx|. :member:`ngtcp2_callbacks.delete_crypto_aead_ctx`
+ * and :member:`ngtcp2_callbacks.delete_crypto_cipher_ctx` will be
+ * called to delete these objects when they are no longer used. If
+ * this function fails, the caller is responsible to delete them.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
* that is larger.
*
* If this function succeeds, |conn| takes ownership of |aead_ctx| and
- * |hp_ctx|. :type:`ngtcp2_delete_crypto_aead_ctx` and
- * :type:`ngtcp2_delete_crypto_cipher_ctx` will be called to delete
- * these objects when they are no longer used. If this function
- * fails, the caller is responsible to delete them.
+ * |hp_ctx|. :member:`ngtcp2_callbacks.delete_crypto_aead_ctx` and
+ * :member:`ngtcp2_callbacks.delete_crypto_cipher_ctx` will be called
+ * to delete these objects when they are no longer used. If this
+ * function fails, the caller is responsible to delete them.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
/**
* @function
*
- * `ngtcp2_conn_install_early_key` installs packet protection AEAD
+ * `ngtcp2_conn_install_0rtt_key` installs packet protection AEAD
* cipher context object |aead_ctx|, IV |iv| of length |ivlen|, and
* packet header protection cipher context object |hp_ctx| to encrypt
- * (for client) or decrypt (for server) 0RTT packets.
+ * (for client) or decrypt (for server) 0-RTT packets.
*
* |ivlen| must be the minimum length of AEAD nonce, or 8 bytes if
* that is larger.
*
* If this function succeeds, |conn| takes ownership of |aead_ctx| and
- * |hp_ctx|. :type:`ngtcp2_delete_crypto_aead_ctx` and
- * :type:`ngtcp2_delete_crypto_cipher_ctx` will be called to delete
- * these objects when they are no longer used. If this function
- * fails, the caller is responsible to delete them.
+ * |hp_ctx|. :member:`ngtcp2_callbacks.delete_crypto_aead_ctx` and
+ * :member:`ngtcp2_callbacks.delete_crypto_cipher_ctx` will be called
+ * to delete these objects when they are no longer used. If this
+ * function fails, the caller is responsible to delete them.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
* :macro:`NGTCP2_ERR_NOMEM`
* Out of memory.
*/
-NGTCP2_EXTERN int ngtcp2_conn_install_early_key(
+NGTCP2_EXTERN int ngtcp2_conn_install_0rtt_key(
ngtcp2_conn *conn, const ngtcp2_crypto_aead_ctx *aead_ctx,
const uint8_t *iv, size_t ivlen, const ngtcp2_crypto_cipher_ctx *hp_ctx);
* @function
*
* `ngtcp2_conn_install_rx_key` installs packet protection keying
- * materials for decrypting Short header packets. |secret| of length
+ * materials for decrypting 1-RTT packets. |secret| of length
* |secretlen| is the decryption secret which is used to derive keying
* materials passed to this function. |aead_ctx| is AEAD cipher
* context object which must be initialized with a decryption key.
* that is larger.
*
* If this function succeeds, |conn| takes ownership of |aead_ctx| and
- * |hp_ctx|. :type:`ngtcp2_delete_crypto_aead_ctx` and
- * :type:`ngtcp2_delete_crypto_cipher_ctx` will be called to delete
- * these objects when they are no longer used. If this function
- * fails, the caller is responsible to delete them.
+ * |hp_ctx|. :member:`ngtcp2_callbacks.delete_crypto_aead_ctx` and
+ * :member:`ngtcp2_callbacks.delete_crypto_cipher_ctx` will be called
+ * to delete these objects when they are no longer used. If this
+ * function fails, the caller is responsible to delete them.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
* @function
*
* `ngtcp2_conn_install_tx_key` installs packet protection keying
- * materials for encrypting Short header packets. |secret| of length
+ * materials for encrypting 1-RTT packets. |secret| of length
* |secretlen| is the encryption secret which is used to derive keying
* materials passed to this function. |aead_ctx| is AEAD cipher
* context object which must be initialized with an encryption key.
* that is larger.
*
* If this function succeeds, |conn| takes ownership of |aead_ctx| and
- * |hp_ctx|. :type:`ngtcp2_delete_crypto_aead_ctx` and
- * :type:`ngtcp2_delete_crypto_cipher_ctx` will be called to delete
- * these objects when they are no longer used. If this function
- * fails, the caller is responsible to delete them.
+ * |hp_ctx|. :member:`ngtcp2_callbacks.delete_crypto_aead_ctx` and
+ * :member:`ngtcp2_callbacks.delete_crypto_cipher_ctx` will be called
+ * to delete these objects when they are no longer used. If this
+ * function fails, the caller is responsible to delete them.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
* is defined as NGTCP2_ERR_* macro, such as
* :macro:`NGTCP2_ERR_DECRYPT`). In general, error code should be
* propagated via return value, but sometimes ngtcp2 API is called
- * inside callback function of TLS stack and it does not allow to
+ * inside callback function of TLS stack, and it does not allow to
* return ngtcp2 error code directly. In this case, implementation
* can set the error code (e.g.,
* :macro:`NGTCP2_ERR_MALFORMED_TRANSPORT_PARAM`) using this function.
+ *
+ * See also `ngtcp2_conn_get_tls_error`.
*/
NGTCP2_EXTERN void ngtcp2_conn_set_tls_error(ngtcp2_conn *conn, int liberr);
* @function
*
* `ngtcp2_conn_set_tls_alert` sets a TLS alert |alert| generated by a
- * local endpoint to |conn|.
+ * TLS stack of a local endpoint to |conn|.
+ *
+ * See also `ngtcp2_conn_get_tls_alert`.
*/
NGTCP2_EXTERN void ngtcp2_conn_set_tls_alert(ngtcp2_conn *conn, uint8_t alert);
* `ngtcp2_conn_set_keep_alive_timeout` sets keep-alive timeout. If
* nonzero value is given, after a connection is idle at least in a
* given amount of time, a keep-alive packet is sent. If 0 is set,
- * keep-alive functionality is disabled and this is the default.
+ * keep-alive functionality is disabled, and this is the default.
*/
NGTCP2_EXTERN void ngtcp2_conn_set_keep_alive_timeout(ngtcp2_conn *conn,
ngtcp2_duration timeout);
* `ngtcp2_conn_get_expiry` returns the next expiry time. It returns
* ``UINT64_MAX`` if there is no next expiry.
*
- * Call `ngtcp2_conn_handle_expiry()` and `ngtcp2_conn_write_pkt` (or
- * `ngtcp2_conn_writev_stream`) if expiry time is passed.
+ * Call `ngtcp2_conn_handle_expiry` and then
+ * `ngtcp2_conn_writev_stream` (or `ngtcp2_conn_writev_datagram`) when
+ * the expiry time has passed.
*/
NGTCP2_EXTERN ngtcp2_tstamp ngtcp2_conn_get_expiry(ngtcp2_conn *conn);
/**
* @function
*
- * `ngtcp2_conn_handle_expiry` handles expired timer. It does nothing
- * if timer is not expired.
+ * `ngtcp2_conn_handle_expiry` handles expired timer.
*/
NGTCP2_EXTERN int ngtcp2_conn_handle_expiry(ngtcp2_conn *conn,
ngtcp2_tstamp ts);
/**
* @function
*
- * `ngtcp2_conn_decode_remote_transport_params` decodes QUIC transport
- * parameters from the buffer pointed by |data| of length |datalen|,
- * and sets the result to |conn|.
+ * `ngtcp2_conn_decode_and_set_remote_transport_params` decodes QUIC
+ * transport parameters from the buffer pointed by |data| of length
+ * |datalen|, and sets the result to |conn|.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
* :macro:`NGTCP2_ERR_CALLBACK_FAILURE`
* User callback failed
*/
-NGTCP2_EXTERN int
-ngtcp2_conn_decode_remote_transport_params(ngtcp2_conn *conn,
- const uint8_t *data, size_t datalen);
+NGTCP2_EXTERN int ngtcp2_conn_decode_and_set_remote_transport_params(
+ ngtcp2_conn *conn, const uint8_t *data, size_t datalen);
/**
* @function
/**
* @function
*
- * `ngtcp2_conn_encode_early_transport_params` encodes the QUIC
- * transport parameters that are used for early data in the buffer
- * pointed by |dest| of length |destlen|. The subset includes at
- * least the following fields:
+ * `ngtcp2_conn_encode_0rtt_transport_params` encodes the QUIC
+ * transport parameters that are used for 0-RTT data in the buffer
+ * pointed by |dest| of length |destlen|. It includes at least the
+ * following fields:
*
- * - initial_max_stream_id_bidi
- * - initial_max_stream_id_uni
- * - initial_max_stream_data_bidi_local
- * - initial_max_stream_data_bidi_remote
- * - initial_max_stream_data_uni
- * - initial_max_data
- * - active_connection_id_limit
- * - max_datagram_frame_size
+ * - :member:`ngtcp2_transport_params.initial_max_streams_bidi`
+ * - :member:`ngtcp2_transport_params.initial_max_streams_uni`
+ * - :member:`ngtcp2_transport_params.initial_max_stream_data_bidi_local`
+ * - :member:`ngtcp2_transport_params.initial_max_stream_data_bidi_remote`
+ * - :member:`ngtcp2_transport_params.initial_max_stream_data_uni`
+ * - :member:`ngtcp2_transport_params.initial_max_data`
+ * - :member:`ngtcp2_transport_params.active_connection_id_limit`
+ * - :member:`ngtcp2_transport_params.max_datagram_frame_size`
*
* If |conn| is initialized as server, the following additional fields
* are also included:
*
- * - max_idle_timeout
- * - max_udp_payload_size
- * - disable_active_migration
+ * - :member:`ngtcp2_transport_params.max_idle_timeout`
+ * - :member:`ngtcp2_transport_params.max_udp_payload_size`
+ * - :member:`ngtcp2_transport_params.disable_active_migration`
*
* If |conn| is initialized as client, these parameters are
* synthesized from the remote transport parameters received from
* Buffer is too small.
*/
NGTCP2_EXTERN
-ngtcp2_ssize ngtcp2_conn_encode_early_transport_params(ngtcp2_conn *conn,
- uint8_t *dest,
- size_t destlen);
+ngtcp2_ssize ngtcp2_conn_encode_0rtt_transport_params(ngtcp2_conn *conn,
+ uint8_t *dest,
+ size_t destlen);
/**
* @function
*
- * `ngtcp2_conn_decode_early_transport_params` decodes QUIC transport
- * parameters from |data| of length |datalen|, which is assumed to be
- * the parameters received from the server in the previous connection,
- * and sets it to |conn|. These parameters are used to send early
- * data. QUIC requires that client application should remember
- * transport parameters along with a session ticket.
- *
- * At least following fields should be set:
- *
- * - initial_max_stream_id_bidi
- * - initial_max_stream_id_uni
- * - initial_max_stream_data_bidi_local
- * - initial_max_stream_data_bidi_remote
- * - initial_max_stream_data_uni
- * - initial_max_data
- * - active_connection_id_limit
- * - max_datagram_frame_size (if DATAGRAM extension was negotiated)
+ * `ngtcp2_conn_decode_and_set_0rtt_transport_params` decodes QUIC
+ * transport parameters from |data| of length |datalen|, which is
+ * assumed to be the parameters received from the server in the
+ * previous connection, and sets it to |conn|. These parameters are
+ * used to send 0-RTT data. QUIC requires that client application
+ * should remember transport parameters along with a session ticket.
+ *
+ * At least following fields should be included:
+ *
+ * - :member:`ngtcp2_transport_params.initial_max_streams_bidi`
+ * - :member:`ngtcp2_transport_params.initial_max_streams_uni`
+ * - :member:`ngtcp2_transport_params.initial_max_stream_data_bidi_local`
+ * - :member:`ngtcp2_transport_params.initial_max_stream_data_bidi_remote`
+ * - :member:`ngtcp2_transport_params.initial_max_stream_data_uni`
+ * - :member:`ngtcp2_transport_params.initial_max_data`
+ * - :member:`ngtcp2_transport_params.active_connection_id_limit`
+ * - :member:`ngtcp2_transport_params.max_datagram_frame_size` (if
+ * DATAGRAM extension was negotiated)
*
* This function must only be used by client.
*
* :macro:`NGTCP2_ERR_MALFORMED_TRANSPORT_PARAM`
* The input is malformed.
*/
-NGTCP2_EXTERN int ngtcp2_conn_decode_early_transport_params(ngtcp2_conn *conn,
- const uint8_t *data,
- size_t datalen);
+NGTCP2_EXTERN int ngtcp2_conn_decode_and_set_0rtt_transport_params(
+ ngtcp2_conn *conn, const uint8_t *data, size_t datalen);
/**
* @function
* Although the local transport parameters are passed to
* `ngtcp2_conn_server_new`, server might want to update them after
* ALPN is chosen. In that case, server can update the transport
- * parameter with this function. Server must call this function
+ * parameters with this function. Server must call this function
* before calling `ngtcp2_conn_install_tx_handshake_key`.
*
* This function returns 0 if it succeeds, or one of the following
* `ngtcp2_conn_encode_local_transport_params` encodes the local QUIC
* transport parameters in |dest| of length |destlen|.
*
- * This function returns the number of written, or one of the
+ * This function returns the number of bytes written, or one of the
* following negative error codes:
*
* :macro:`NGTCP2_ERR_NOBUF`
*
* `ngtcp2_conn_open_bidi_stream` opens new bidirectional stream. The
* |stream_user_data| is the user data specific to the stream. The
- * open stream ID is stored in |*pstream_id|.
+ * stream ID of the opened stream is stored in |*pstream_id|.
*
* Application can call this function before handshake completes. For
- * 0RTT packet, application can call this function after calling
- * `ngtcp2_conn_decode_early_transport_params`. For 1RTT packet,
- * application can call this function after calling
- * `ngtcp2_conn_decode_remote_transport_params` and
+ * 0-RTT packet, application can call this function after calling
+ * `ngtcp2_conn_decode_and_set_0rtt_transport_params`. For 1-RTT
+ * packet, application can call this function after calling
+ * `ngtcp2_conn_decode_and_set_remote_transport_params` and
* `ngtcp2_conn_install_tx_key`. If ngtcp2 crypto support library is
* used, application can call this function after calling
- * `ngtcp2_crypto_derive_and_install_tx_key` for 1RTT packet.
+ * `ngtcp2_crypto_derive_and_install_tx_key` for 1-RTT packet.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
* :macro:`NGTCP2_ERR_NOMEM`
* Out of memory
* :macro:`NGTCP2_ERR_STREAM_ID_BLOCKED`
- * The remote peer does not allow |stream_id| yet.
+ * The remote endpoint does not allow |stream_id| yet.
*/
NGTCP2_EXTERN int ngtcp2_conn_open_bidi_stream(ngtcp2_conn *conn,
int64_t *pstream_id,
*
* `ngtcp2_conn_open_uni_stream` opens new unidirectional stream. The
* |stream_user_data| is the user data specific to the stream. The
- * open stream ID is stored in |*pstream_id|.
+ * stream ID of the opened stream is stored in |*pstream_id|.
*
* Application can call this function before handshake completes. For
- * 0RTT packet, application can call this function after calling
- * `ngtcp2_conn_decode_early_transport_params`. For 1RTT packet,
- * application can call this function after calling
- * `ngtcp2_conn_decode_remote_transport_params` and
+ * 0-RTT packet, application can call this function after calling
+ * `ngtcp2_conn_decode_and_set_0rtt_transport_params`. For 1-RTT
+ * packet, application can call this function after calling
+ * `ngtcp2_conn_decode_and_set_remote_transport_params` and
* `ngtcp2_conn_install_tx_key`. If ngtcp2 crypto support library is
* used, application can call this function after calling
- * `ngtcp2_crypto_derive_and_install_tx_key` for 1RTT packet.
+ * `ngtcp2_crypto_derive_and_install_tx_key` for 1-RTT packet.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
* :macro:`NGTCP2_ERR_NOMEM`
* Out of memory
* :macro:`NGTCP2_ERR_STREAM_ID_BLOCKED`
- * The remote peer does not allow |stream_id| yet.
+ * The remote endpoint does not allow |stream_id| yet.
*/
NGTCP2_EXTERN int ngtcp2_conn_open_uni_stream(ngtcp2_conn *conn,
int64_t *pstream_id,
/**
* @function
*
- * `ngtcp2_conn_shutdown_stream` closes stream denoted by |stream_id|
- * abruptly. |app_error_code| is one of application error codes, and
- * indicates the reason of shutdown. Successful call of this function
- * does not immediately erase the state of the stream. The actual
- * deletion is done when the remote endpoint sends acknowledgement.
- * Calling this function is equivalent to call
+ * `ngtcp2_conn_shutdown_stream` closes a stream denoted by
+ * |stream_id| abruptly. |app_error_code| is one of application error
+ * codes, and indicates the reason of shutdown. Successful call of
+ * this function does not immediately erase the state of the stream.
+ * The actual deletion is done when the remote endpoint sends
+ * acknowledgement. Calling this function is equivalent to call
* `ngtcp2_conn_shutdown_stream_read`, and
* `ngtcp2_conn_shutdown_stream_write` sequentially with the following
* differences. If |stream_id| refers to a local unidirectional
* |stream_id| refers to a remote unidirectional stream, this function
* only shutdowns read side of the stream.
*
+ * |flags| is currently unused, and should be set to 0.
+ *
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :macro:`NGTCP2_ERR_NOMEM`
* Out of memory
*/
-NGTCP2_EXTERN int ngtcp2_conn_shutdown_stream(ngtcp2_conn *conn,
+NGTCP2_EXTERN int ngtcp2_conn_shutdown_stream(ngtcp2_conn *conn, uint32_t flags,
int64_t stream_id,
uint64_t app_error_code);
/**
* @function
*
- * `ngtcp2_conn_shutdown_stream_write` closes write-side of stream
+ * `ngtcp2_conn_shutdown_stream_write` closes write-side of a stream
* denoted by |stream_id| abruptly. |app_error_code| is one of
* application error codes, and indicates the reason of shutdown. If
- * this function succeeds, no application data is sent to the remote
- * endpoint. It discards all data which has not been acknowledged
- * yet.
+ * this function succeeds, no further application data is sent to the
+ * remote endpoint. It discards all data which has not been
+ * acknowledged yet.
+ *
+ * |flags| is currently unused, and should be set to 0.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
* |stream_id| refers to a remote unidirectional stream.
*/
NGTCP2_EXTERN int ngtcp2_conn_shutdown_stream_write(ngtcp2_conn *conn,
+ uint32_t flags,
int64_t stream_id,
uint64_t app_error_code);
/**
* @function
*
- * `ngtcp2_conn_shutdown_stream_read` closes read-side of stream
+ * `ngtcp2_conn_shutdown_stream_read` closes read-side of a stream
* denoted by |stream_id| abruptly. |app_error_code| is one of
* application error codes, and indicates the reason of shutdown. If
- * this function succeeds, no application data is forwarded to an
- * application layer.
+ * this function succeeds, no further application data is forwarded to
+ * an application layer.
+ *
+ * |flags| is currently unused, and should be set to 0.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
* |stream_id| refers to a local unidirectional stream.
*/
NGTCP2_EXTERN int ngtcp2_conn_shutdown_stream_read(ngtcp2_conn *conn,
+ uint32_t flags,
int64_t stream_id,
uint64_t app_error_code);
* @macro
*
* :macro:`NGTCP2_WRITE_STREAM_FLAG_MORE` indicates that more data may
- * come and should be coalesced into the same packet if possible.
+ * come, and should be coalesced into the same packet if possible.
*/
#define NGTCP2_WRITE_STREAM_FLAG_MORE 0x01u
/**
* @macro
*
- * :macro:`NGTCP2_WRITE_STREAM_FLAG_FIN` indicates that the passed
- * data is the final part of a stream.
+ * :macro:`NGTCP2_WRITE_STREAM_FLAG_FIN` indicates that a passed data
+ * is the final part of a stream.
*/
#define NGTCP2_WRITE_STREAM_FLAG_FIN 0x02u
* @function
*
* `ngtcp2_conn_writev_stream` writes a packet containing stream data
- * of stream denoted by |stream_id|. The buffer of the packet is
+ * of a stream denoted by |stream_id|. The buffer of the packet is
* pointed by |dest| of length |destlen|. This function performs QUIC
* handshake as well.
*
* Specifying -1 to |stream_id| means no new stream data to send.
*
* If |path| is not ``NULL``, this function stores the network path
- * with which the packet should be sent. Each addr field must point
- * to the buffer which should be at least ``sizeof(struct
- * sockaddr_storage)`` bytes long. The assignment might not be done
- * if nothing is written to |dest|.
+ * with which the packet should be sent. Each addr field
+ * (:member:`ngtcp2_path.local` and :member:`ngtcp2_path.remote`) must
+ * point to the buffer which should be at least
+ * sizeof(:type:`sockaddr_union`) bytes long. The assignment might
+ * not be done if nothing is written to |dest|.
*
* If |pi| is not ``NULL``, this function stores packet metadata in it
* if it succeeds. The metadata includes ECN markings. When calling
* :macro:`NGTCP2_ERR_WRITE_MORE`, caller must pass the same |pi| to
* this function.
*
- * If the all given data is encoded as STREAM frame in |dest|, and if
+ * Stream data is specified as vector of data |datav|. |datavcnt|
+ * specifies the number of :type:`ngtcp2_vec` that |datav| includes.
+ *
+ * If all given data is encoded as STREAM frame in |dest|, and if
* |flags| & :macro:`NGTCP2_WRITE_STREAM_FLAG_FIN` is nonzero, fin
* flag is set to outgoing STREAM frame. Otherwise, fin flag in
* STREAM frame is not set.
* The number of data encoded in STREAM frame is stored in |*pdatalen|
* if it is not ``NULL``. The caller must keep the portion of data
* covered by |*pdatalen| bytes in tact until
- * :type:`ngtcp2_acked_stream_data_offset` indicates that they are
- * acknowledged by a remote endpoint or the stream is closed.
- *
- * If |flags| equals to :macro:`NGTCP2_WRITE_STREAM_FLAG_NONE`, this
- * function produces a single payload of UDP packet. If the given
- * stream data is small (e.g., few bytes), the packet might be
- * severely under filled. Too many small packet might increase
- * overall packet processing costs. Unless there are retransmissions,
- * by default, application can only send 1 STREAM frame in one QUIC
- * packet. In order to include more than 1 STREAM frame in one QUIC
- * packet, specify :macro:`NGTCP2_WRITE_STREAM_FLAG_MORE` in |flags|.
- * This is analogous to ``MSG_MORE`` flag in :manpage:`send(2)`. If
- * the :macro:`NGTCP2_WRITE_STREAM_FLAG_MORE` is used, there are 4
+ * :member:`ngtcp2_callbacks.acked_stream_data_offset` indicates that
+ * they are acknowledged by a remote endpoint or the stream is closed.
+ *
+ * If the given stream data is small (e.g., few bytes), the packet
+ * might be severely under filled. Too many small packet might
+ * increase overall packet processing costs. Unless there are
+ * retransmissions, by default, application can only send 1 STREAM
+ * frame in one QUIC packet. In order to include more than 1 STREAM
+ * frame in one QUIC packet, specify
+ * :macro:`NGTCP2_WRITE_STREAM_FLAG_MORE` in |flags|. This is
+ * analogous to ``MSG_MORE`` flag in :manpage:`send(2)`. If the
+ * :macro:`NGTCP2_WRITE_STREAM_FLAG_MORE` is used, there are 4
* outcomes:
*
* - The function returns the written length of packet just like
* without :macro:`NGTCP2_WRITE_STREAM_FLAG_MORE`. This is because
- * packet is nearly full and the library decided to make a complete
+ * packet is nearly full, and the library decided to make a complete
* packet. |*pdatalen| might be -1 or >= 0. It may return 0 which
* indicates that no packet transmission is possible at the moment
* for some reason.
*
* - The function returns one of the following negative error codes:
* :macro:`NGTCP2_ERR_STREAM_DATA_BLOCKED`,
- * :macro:`NGTCP2_ERR_STREAM_NOT_FOUND`,
+ * :macro:`NGTCP2_ERR_STREAM_NOT_FOUND`, or
* :macro:`NGTCP2_ERR_STREAM_SHUT_WR`. In this case, |*pdatalen| ==
* -1 is asserted. Application can still write the stream data of
* the other streams by calling this function (or
* least once, it must not call other ngtcp2 API functions
* (application can still call `ngtcp2_conn_write_connection_close` to
* handle error from this function), just keep calling this function
- * (or `ngtcp2_conn_write_pkt`, or `ngtcp2_conn_writev_datagram`)
- * until it returns 0, a positive number (which indicates a complete
- * packet is ready), or the error codes other than
- * :macro:`NGTCP2_ERR_WRITE_MORE`,
+ * (or `ngtcp2_conn_writev_datagram`) until it returns 0, a positive
+ * number (which indicates a complete packet is ready), or the error
+ * codes other than :macro:`NGTCP2_ERR_WRITE_MORE`,
* :macro:`NGTCP2_ERR_STREAM_DATA_BLOCKED`,
* :macro:`NGTCP2_ERR_STREAM_NOT_FOUND`, and
* :macro:`NGTCP2_ERR_STREAM_SHUT_WR`. If there is no stream data to
* In general, if the error code which satisfies
* `ngtcp2_err_is_fatal(err) <ngtcp2_err_is_fatal>` != 0 is returned,
* the application should just close the connection by calling
- * `ngtcp2_conn_write_connection_close` or just delete the QUIC
+ * `ngtcp2_conn_write_connection_close`, or just delete the QUIC
* connection using `ngtcp2_conn_del`. It is undefined to call the
* other library functions.
*/
* @macro
*
* :macro:`NGTCP2_WRITE_DATAGRAM_FLAG_MORE` indicates that more data
- * may come and should be coalesced into the same packet if possible.
+ * may come, and should be coalesced into the same packet if possible.
*/
#define NGTCP2_WRITE_DATAGRAM_FLAG_MORE 0x01u
* For |path| and |pi| parameters, refer to
* `ngtcp2_conn_writev_stream`.
*
+ * Stream data is specified as vector of data |datav|. |datavcnt|
+ * specifies the number of :type:`ngtcp2_vec` that |datav| includes.
+ *
* If the given data is written to the buffer, nonzero value is
* assigned to |*paccepted| if it is not NULL. The data in DATAGRAM
* frame cannot be fragmented; writing partial data is not possible.
*
* |dgram_id| is an opaque identifier which should uniquely identify
- * the given DATAGRAM. It is passed to :type:`ngtcp2_ack_datagram`
- * callback when a packet that contains DATAGRAM frame is
- * acknowledged. It is passed to :type:`ngtcp2_lost_datagram`
- * callback when a packet that contains DATAGRAM frame is declared
- * lost. If an application uses neither of those callbacks, it can
- * sets 0 to this parameter.
+ * the given DATAGRAM data. It is passed to
+ * :member:`ngtcp2_callbacks.ack_datagram` callback when a packet that
+ * contains DATAGRAM frame is acknowledged. It is also passed to
+ * :member:`ngtcp2_callbacks.lost_datagram` callback when a packet
+ * that contains DATAGRAM frame is declared lost. If an application
+ * uses neither of those callbacks, it can sets 0 to this parameter.
*
- * This function might write other frames other than DATAGRAM, just
- * like `ngtcp2_conn_writev_stream`.
+ * This function might write other frames other than DATAGRAM frame,
+ * just like `ngtcp2_conn_writev_stream`.
*
* If the function returns 0, it means that no more data cannot be
* sent because of congestion control limit; or, data does not fit
* When application sees :macro:`NGTCP2_ERR_WRITE_MORE`, it must not
* call other ngtcp2 API functions (application can still call
* `ngtcp2_conn_write_connection_close` to handle error from this
- * function). Just keep calling `ngtcp2_conn_writev_datagram`,
- * `ngtcp2_conn_writev_stream` or `ngtcp2_conn_write_pkt` until it
- * returns a positive number (which indicates a complete packet is
- * ready).
+ * function). Just keep calling this function (or
+ * `ngtcp2_conn_writev_stream`) until it returns a positive number
+ * (which indicates a complete packet is ready).
*
* This function returns the number of bytes written in |dest| if it
* succeeds, or one of the following negative error codes:
* In general, if the error code which satisfies
* `ngtcp2_err_is_fatal(err) <ngtcp2_err_is_fatal>` != 0 is returned,
* the application should just close the connection by calling
- * `ngtcp2_conn_write_connection_close` or just delete the QUIC
+ * `ngtcp2_conn_write_connection_close`, or just delete the QUIC
* connection using `ngtcp2_conn_del`. It is undefined to call the
* other library functions.
*/
/**
* @function
*
- * `ngtcp2_conn_is_in_closing_period` returns nonzero if |conn| is in
- * the closing period.
+ * `ngtcp2_conn_in_closing_period` returns nonzero if |conn| is in the
+ * closing period.
*/
-NGTCP2_EXTERN int ngtcp2_conn_is_in_closing_period(ngtcp2_conn *conn);
+NGTCP2_EXTERN int ngtcp2_conn_in_closing_period(ngtcp2_conn *conn);
/**
* @function
*
- * `ngtcp2_conn_is_in_draining_period` returns nonzero if |conn| is in
+ * `ngtcp2_conn_in_draining_period` returns nonzero if |conn| is in
* the draining period.
*/
-NGTCP2_EXTERN int ngtcp2_conn_is_in_draining_period(ngtcp2_conn *conn);
+NGTCP2_EXTERN int ngtcp2_conn_in_draining_period(ngtcp2_conn *conn);
/**
* @function
*
- * `ngtcp2_conn_extend_max_stream_offset` extends stream's max stream
- * data value by |datalen|.
+ * `ngtcp2_conn_extend_max_stream_offset` extends the maximum stream
+ * data that a remote endpoint can send by |datalen|. |stream_id|
+ * specifies the stream ID. This function only extends stream-level
+ * flow control window.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :macro:`NGTCP2_ERR_NOMEM`
* Out of memory.
+ * :macro:`NGTCP2_ERR_INVALID_ARGUMENT`
+ * |stream_id| refers to a local unidirectional stream.
*/
NGTCP2_EXTERN int ngtcp2_conn_extend_max_stream_offset(ngtcp2_conn *conn,
int64_t stream_id,
* @function
*
* `ngtcp2_conn_extend_max_offset` extends max data offset by
- * |datalen|.
+ * |datalen|. This function only extends connection-level flow
+ * control window.
*/
NGTCP2_EXTERN void ngtcp2_conn_extend_max_offset(ngtcp2_conn *conn,
uint64_t datalen);
* @function
*
* `ngtcp2_conn_extend_max_streams_bidi` extends the number of maximum
- * local bidirectional streams that a remote endpoint can open by |n|.
+ * remote bidirectional streams that a remote endpoint can open by
+ * |n|.
*
* The library does not increase maximum stream limit automatically.
* The exception is when a stream is closed without
- * :type:`ngtcp2_stream_open` callback being called. In this case,
- * stream limit is increased automatically.
+ * :member:`ngtcp2_callbacks.stream_open` callback being called. In
+ * this case, stream limit is increased automatically.
*/
NGTCP2_EXTERN void ngtcp2_conn_extend_max_streams_bidi(ngtcp2_conn *conn,
size_t n);
* @function
*
* `ngtcp2_conn_extend_max_streams_uni` extends the number of maximum
- * local unidirectional streams that a remote endpoint can open by
+ * remote unidirectional streams that a remote endpoint can open by
* |n|.
*
* The library does not increase maximum stream limit automatically.
* The exception is when a stream is closed without
- * :type:`ngtcp2_stream_open` callback being called. In this case,
- * stream limit is increased automatically.
+ * :member:`ngtcp2_callbacks.stream_open` callback being called. In
+ * this case, stream limit is increased automatically.
*/
NGTCP2_EXTERN void ngtcp2_conn_extend_max_streams_uni(ngtcp2_conn *conn,
size_t n);
/**
* @function
*
- * `ngtcp2_conn_get_dcid` returns the non-NULL pointer to destination
- * connection ID. If no destination connection ID is present, the
- * return value is not ``NULL``, and its datalen field is 0.
+ * `ngtcp2_conn_get_dcid` returns the non-NULL pointer to the current
+ * Destination Connection ID. If no Destination Connection ID is
+ * present, the return value is not ``NULL``, and its :member:`datalen
+ * <ngtcp2_cid.datalen>` field is 0.
*/
NGTCP2_EXTERN const ngtcp2_cid *ngtcp2_conn_get_dcid(ngtcp2_conn *conn);
*
* `ngtcp2_conn_get_client_initial_dcid` returns the non-NULL pointer
* to the Destination Connection ID that client sent in its Initial
- * packet.
+ * packet. If the Destination Connection ID is not present, the
+ * return value is not ``NULL``, and its :member:`datalen
+ * <ngtcp2_cid.datalen>` field is 0.
*/
NGTCP2_EXTERN const ngtcp2_cid *
ngtcp2_conn_get_client_initial_dcid(ngtcp2_conn *conn);
/**
* @function
*
- * `ngtcp2_conn_get_num_scid` returns the number of source connection
- * IDs which the local endpoint has provided to the peer and have not
- * retired.
+ * `ngtcp2_conn_get_num_scid` returns the number of Source Connection
+ * IDs which a local endpoint has provided to a remote endpoint, and
+ * are not retired.
*/
NGTCP2_EXTERN size_t ngtcp2_conn_get_num_scid(ngtcp2_conn *conn);
/**
* @function
*
- * `ngtcp2_conn_get_scid` writes the all source connection IDs which
- * the local endpoint has provided to the peer and have not retired in
- * |dest|. The buffer pointed by |dest| must have
- * ``sizeof(ngtcp2_cid) * n`` bytes available, where n is the return
- * value of `ngtcp2_conn_get_num_scid()`.
+ * `ngtcp2_conn_get_scid` writes the all Source Connection IDs which a
+ * local endpoint has provided to a remote endpoint, and are not
+ * retired in |dest|. The buffer pointed by |dest| must have
+ * sizeof(:type:`ngtcp2_cid`) * n bytes available, where n is the
+ * return value of `ngtcp2_conn_get_num_scid`.
*/
NGTCP2_EXTERN size_t ngtcp2_conn_get_scid(ngtcp2_conn *conn, ngtcp2_cid *dest);
* @function
*
* `ngtcp2_conn_get_num_active_dcid` returns the number of the active
- * destination connection ID.
+ * Destination Connection ID.
*/
NGTCP2_EXTERN size_t ngtcp2_conn_get_num_active_dcid(ngtcp2_conn *conn);
*/
ngtcp2_cid cid;
/**
- * :member:`ps` is the path which is associated to this Connection
- * ID.
+ * :member:`ps` is the path which this Connection ID is associated
+ * with.
*/
ngtcp2_path_storage ps;
/**
/**
* @function
*
- * `ngtcp2_conn_get_active_dcid` writes the all active destination
- * connection IDs and tokens to |dest|. The buffer pointed by |dest|
- * must have ``sizeof(ngtcp2_cid_token) * n`` bytes available, where n
- * is the return value of `ngtcp2_conn_get_num_active_dcid()`.
+ * `ngtcp2_conn_get_active_dcid` writes the all active Destination
+ * Connection IDs and their tokens to |dest|. The buffer pointed by
+ * |dest| must have sizeof(:type:`ngtcp2_cid_token`) * n bytes
+ * available, where n is the return value of
+ * `ngtcp2_conn_get_num_active_dcid`.
*/
NGTCP2_EXTERN size_t ngtcp2_conn_get_active_dcid(ngtcp2_conn *conn,
ngtcp2_cid_token *dest);
/**
* @function
*
- * `ngtcp2_conn_get_negotiated_version` returns the negotiated version.
+ * `ngtcp2_conn_get_negotiated_version` returns the negotiated
+ * version.
*
* Until the version is negotiated, this function returns 0.
*/
/**
* @function
*
- * `ngtcp2_conn_early_data_rejected` tells |conn| that early data was
- * rejected by a server, or client decided not to attempt early data
- * for some reason. |conn| discards the following connection states:
+ * `ngtcp2_conn_tls_early_data_rejected` tells |conn| that early data
+ * was rejected by a server during TLS handshake, or client decided
+ * not to attempt early data for some reason. |conn| discards the
+ * following connection states:
*
- * - Any opended streams.
+ * - Any opened streams.
* - Stream identifier allocations.
* - Max data extended by `ngtcp2_conn_extend_max_offset`.
* - Max bidi streams extended by `ngtcp2_conn_extend_max_streams_bidi`.
* - Max uni streams extended by `ngtcp2_conn_extend_max_streams_uni`.
*
* Application which wishes to retransmit early data, it has to open
- * streams and send stream data again.
+ * streams, and send stream data again.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
* :macro:`NGTCP2_ERR_CALLBACK_FAILURE`
* User callback failed
*/
-NGTCP2_EXTERN int ngtcp2_conn_early_data_rejected(ngtcp2_conn *conn);
+NGTCP2_EXTERN int ngtcp2_conn_tls_early_data_rejected(ngtcp2_conn *conn);
/**
* @function
*
- * `ngtcp2_conn_get_early_data_rejected` returns nonzero if
- * `ngtcp2_conn_early_data_rejected` has been called.
+ * `ngtcp2_conn_get_tls_early_data_rejected` returns nonzero if
+ * `ngtcp2_conn_tls_early_data_rejected` has been called.
*/
-NGTCP2_EXTERN int ngtcp2_conn_get_early_data_rejected(ngtcp2_conn *conn);
+NGTCP2_EXTERN int ngtcp2_conn_get_tls_early_data_rejected(ngtcp2_conn *conn);
/**
* @function
/**
* @function
*
- * `ngtcp2_conn_submit_crypto_data` submits crypto stream data |data|
- * of length |datalen| to the library for transmission. The
- * encryption level is given in |crypto_level|.
+ * `ngtcp2_conn_submit_crypto_data` submits crypto data |data| of
+ * length |datalen| to the library for transmission.
+ * |encryption_level| specifies the encryption level of data.
*
* The library makes a copy of the buffer pointed by |data| of length
* |datalen|. Application can discard |data|.
*/
NGTCP2_EXTERN int
ngtcp2_conn_submit_crypto_data(ngtcp2_conn *conn,
- ngtcp2_crypto_level crypto_level,
+ ngtcp2_encryption_level encryption_level,
const uint8_t *data, const size_t datalen);
/**
* :macro:`NGTCP2_ERR_CONN_ID_BLOCKED`
* No unused connection ID is available.
* :macro:`NGTCP2_ERR_INVALID_ARGUMENT`
- * |local_addr| equals the current local address.
+ * :member:`local <ngtcp2_path.local>` field of |path| equals the
+ * current local address.
* :macro:`NGTCP2_ERR_NOMEM`
* Out of memory
*/
* `ngtcp2_conn_initiate_migration` starts connection migration to the
* given |path|. Only client can initiate migration. Unlike
* `ngtcp2_conn_initiate_immediate_migration`, this function starts a
- * path validation with a new path and migrate to the new path after
+ * path validation with a new path, and migrate to the new path after
* successful path validation.
*
* This function returns 0 if it succeeds, or one of the following
* :macro:`NGTCP2_ERR_CONN_ID_BLOCKED`
* No unused connection ID is available.
* :macro:`NGTCP2_ERR_INVALID_ARGUMENT`
- * |local_addr| equals the current local address.
+ * :member:`local <ngtcp2_path.local>` field of |path| equals the
+ * current local address.
* :macro:`NGTCP2_ERR_NOMEM`
* Out of memory
*/
* @function
*
* `ngtcp2_conn_get_max_data_left` returns the number of bytes that
- * this local endpoint can send in this connection.
+ * this local endpoint can send in this connection without violating
+ * connection-level flow control.
*/
NGTCP2_EXTERN uint64_t ngtcp2_conn_get_max_data_left(ngtcp2_conn *conn);
*
* `ngtcp2_conn_get_max_stream_data_left` returns the number of bytes
* that this local endpoint can send to a stream identified by
- * |stream_id|. If no such stream is found, this function returns 0.
+ * |stream_id| without violating stream-level flow control. If no
+ * such stream is found, this function returns 0.
*/
NGTCP2_EXTERN uint64_t ngtcp2_conn_get_max_stream_data_left(ngtcp2_conn *conn,
int64_t stream_id);
/**
* @function
*
- * `ngtcp2_conn_set_crypto_ctx` sets |ctx| for Handshake/1RTT packet
+ * `ngtcp2_conn_set_crypto_ctx` sets |ctx| for Handshake/1-RTT packet
* encryption. The passed data will be passed to
* :type:`ngtcp2_encrypt`, :type:`ngtcp2_decrypt` and
* :type:`ngtcp2_hp_mask` callbacks.
/**
* @function
*
- * `ngtcp2_conn_get_tls_native_handle` returns TLS native handle set by
- * `ngtcp2_conn_set_tls_native_handle()`.
+ * `ngtcp2_conn_get_crypto_ctx` returns :type:`ngtcp2_crypto_ctx`
+ * object for Handshake/1-RTT packet encryption.
*/
-NGTCP2_EXTERN void *ngtcp2_conn_get_tls_native_handle(ngtcp2_conn *conn);
+NGTCP2_EXTERN const ngtcp2_crypto_ctx *
+ngtcp2_conn_get_crypto_ctx(ngtcp2_conn *conn);
/**
* @function
*
- * `ngtcp2_conn_set_tls_native_handle` sets TLS native handle
- * |tls_native_handle| to |conn|. Internally, it is used as an opaque
- * pointer.
+ * `ngtcp2_conn_set_0rtt_crypto_ctx` sets |ctx| for 0-RTT packet
+ * encryption. The passed data will be passed to
+ * :type:`ngtcp2_encrypt`, :type:`ngtcp2_decrypt` and
+ * :type:`ngtcp2_hp_mask` callbacks.
*/
-NGTCP2_EXTERN void ngtcp2_conn_set_tls_native_handle(ngtcp2_conn *conn,
- void *tls_native_handle);
+NGTCP2_EXTERN void
+ngtcp2_conn_set_0rtt_crypto_ctx(ngtcp2_conn *conn,
+ const ngtcp2_crypto_ctx *ctx);
/**
* @function
*
- * `ngtcp2_conn_set_retry_aead` sets |aead| and |aead_ctx| for Retry
- * integrity tag verification. |aead| must be AEAD_AES_128_GCM.
- * |aead_ctx| must be initialized with :macro:`NGTCP2_RETRY_KEY` as
- * encryption key. This function must be called if |conn| is
- * initialized as client. Server does not verify the tag and has no
- * need to call this function.
- *
- * If this function succeeds, |conn| takes ownership of |aead_ctx|.
- * :type:`ngtcp2_delete_crypto_aead_ctx` will be called to delete this
- * object when it is no longer used. If this function fails, the
- * caller is responsible to delete it.
+ * `ngtcp2_conn_get_0rtt_crypto_ctx` returns :type:`ngtcp2_crypto_ctx`
+ * object for 0-RTT packet encryption.
*/
-NGTCP2_EXTERN void
-ngtcp2_conn_set_retry_aead(ngtcp2_conn *conn, const ngtcp2_crypto_aead *aead,
- const ngtcp2_crypto_aead_ctx *aead_ctx);
+NGTCP2_EXTERN const ngtcp2_crypto_ctx *
+ngtcp2_conn_get_0rtt_crypto_ctx(ngtcp2_conn *conn);
/**
* @function
*
- * `ngtcp2_conn_get_crypto_ctx` returns :type:`ngtcp2_crypto_ctx`
- * object for Handshake/1RTT packet encryption.
+ * `ngtcp2_conn_get_tls_native_handle` returns TLS native handle set
+ * by `ngtcp2_conn_set_tls_native_handle`.
*/
-NGTCP2_EXTERN const ngtcp2_crypto_ctx *
-ngtcp2_conn_get_crypto_ctx(ngtcp2_conn *conn);
+NGTCP2_EXTERN void *ngtcp2_conn_get_tls_native_handle(ngtcp2_conn *conn);
/**
* @function
*
- * `ngtcp2_conn_set_early_crypto_ctx` sets |ctx| for 0RTT packet
- * encryption. The passed data will be passed to
- * :type:`ngtcp2_encrypt`, :type:`ngtcp2_decrypt` and
- * :type:`ngtcp2_hp_mask` callbacks.
+ * `ngtcp2_conn_set_tls_native_handle` sets TLS native handle
+ * |tls_native_handle| to |conn|. Internally, it is used as an opaque
+ * pointer.
*/
-NGTCP2_EXTERN void
-ngtcp2_conn_set_early_crypto_ctx(ngtcp2_conn *conn,
- const ngtcp2_crypto_ctx *ctx);
+NGTCP2_EXTERN void ngtcp2_conn_set_tls_native_handle(ngtcp2_conn *conn,
+ void *tls_native_handle);
/**
* @function
*
- * `ngtcp2_conn_get_early_crypto_ctx` returns
- * :type:`ngtcp2_crypto_ctx` object for 0RTT packet encryption.
+ * `ngtcp2_conn_set_retry_aead` sets |aead| and |aead_ctx| for Retry
+ * integrity tag verification. |aead| must be AEAD_AES_128_GCM.
+ * |aead_ctx| must be initialized with :macro:`NGTCP2_RETRY_KEY` as
+ * encryption key. This function must be called if |conn| is
+ * initialized as client. Server does not verify the tag, and has no
+ * need to call this function.
+ *
+ * |conn| takes ownership of |aead_ctx|.
+ * :member:`ngtcp2_callbacks.delete_crypto_aead_ctx` will be called to
+ * delete this object when it is no longer used.
*/
-NGTCP2_EXTERN const ngtcp2_crypto_ctx *
-ngtcp2_conn_get_early_crypto_ctx(ngtcp2_conn *conn);
+NGTCP2_EXTERN void
+ngtcp2_conn_set_retry_aead(ngtcp2_conn *conn, const ngtcp2_crypto_aead *aead,
+ const ngtcp2_crypto_aead_ctx *aead_ctx);
/**
* @enum
/**
* @struct
*
- * :type:`ngtcp2_ccerr` contains connection error code, its type, and
- * the optional reason phrase.
+ * :type:`ngtcp2_ccerr` contains connection error code, its type, a
+ * frame type that caused this error, and the optional reason phrase.
*/
typedef struct ngtcp2_ccerr {
/**
* `ngtcp2_ccerr_set_liberr` sets type and error_code based on
* |liberr|.
*
+ * |reason| is the reason phrase of length |reasonlen|. This function
+ * does not make a copy of the reason phrase.
+ *
* If |liberr| is :macro:`NGTCP2_ERR_RECV_VERSION_NEGOTIATION`,
* :member:`ccerr->type <ngtcp2_ccerr.type>` is set to
* :enum:`ngtcp2_ccerr_type.NGTCP2_CCERR_TYPE_VERSION_NEGOTIATION`,
* and :member:`ccerr->error_code <ngtcp2_ccerr.error_code>` to
- * :macro:`NGTCP2_NO_ERROR`. If |liberr| is
- * :macro:`NGTCP2_ERR_IDLE_CLOSE`, :member:`ccerr->type
+ * :macro:`NGTCP2_NO_ERROR`.
+ *
+ * If |liberr| is :macro:`NGTCP2_ERR_IDLE_CLOSE`, :member:`ccerr->type
* <ngtcp2_ccerr.type>` is set to
* :enum:`ngtcp2_ccerr_type.NGTCP2_CCERR_TYPE_IDLE_CLOSE`, and
* :member:`ccerr->error_code <ngtcp2_ccerr.error_code>` to
- * :macro:`NGTCP2_NO_ERROR`. Otherwise, :member:`ccerr->type
- * <ngtcp2_ccerr.type>` is set to
+ * :macro:`NGTCP2_NO_ERROR`.
+ *
+ * Otherwise, :member:`ccerr->type <ngtcp2_ccerr.type>` is set to
* :enum:`ngtcp2_ccerr_type.NGTCP2_CCERR_TYPE_TRANSPORT`, and
* :member:`ccerr->error_code <ngtcp2_ccerr.error_code>` is set to an
* error code inferred by |liberr| (see
- * `ngtcp2_err_infer_quic_transport_error_code`). |reason| is the
- * reason phrase of length |reasonlen|. This function does not make a
- * copy of the reason phrase.
+ * `ngtcp2_err_infer_quic_transport_error_code`).
*/
NGTCP2_EXTERN void ngtcp2_ccerr_set_liberr(ngtcp2_ccerr *ccerr, int liberr,
const uint8_t *reason,
*
* If |path| is not ``NULL``, this function stores the network path
* with which the packet should be sent. Each addr field must point
- * to the buffer which should be at least ``sizeof(struct
- * sockaddr_storage)`` bytes long. The assignment might not be done
- * if nothing is written to |dest|.
+ * to the buffer which should be at least
+ * sizeof(:type:`ngtcp2_sockaddr_union`) bytes long. The assignment
+ * might not be done if nothing is written to |dest|.
*
* If |pi| is not ``NULL``, this function stores packet metadata in it
* if it succeeds. The metadata includes ECN markings.
* :macro:`NGTCP2_ERR_NOBUF`
* Buffer is too small
* :macro:`NGTCP2_ERR_INVALID_STATE`
- * The current state does not allow sending CONNECTION_CLOSE.
+ * The current state does not allow sending CONNECTION_CLOSE
+ * frame.
* :macro:`NGTCP2_ERR_PKT_NUM_EXHAUSTED`
* Packet number is exhausted, and cannot send any more packet.
* :macro:`NGTCP2_ERR_CALLBACK_FAILURE`
* @function
*
* `ngtcp2_conn_get_ccerr` returns the received connection close
- * error.
+ * error. If no connection error is received, it returns
+ * :type:`ngtcp2_ccerr` that is initialized by `ngtcp2_ccerr_default`.
*/
NGTCP2_EXTERN const ngtcp2_ccerr *ngtcp2_conn_get_ccerr(ngtcp2_conn *conn);
/**
* @function
*
- * `ngtcp2_conn_is_local_stream` returns nonzero if |stream_id| denotes the
- * stream which a local endpoint issues.
+ * `ngtcp2_conn_is_local_stream` returns nonzero if |stream_id|
+ * denotes a locally initiated stream.
*/
NGTCP2_EXTERN int ngtcp2_conn_is_local_stream(ngtcp2_conn *conn,
int64_t stream_id);
* @function
*
* `ngtcp2_conn_after_retry` returns nonzero if |conn| as a client has
- * received Retry packet from server and successfully validated it.
+ * received Retry packet from server, and successfully validated it.
*/
NGTCP2_EXTERN int ngtcp2_conn_after_retry(ngtcp2_conn *conn);
* @function
*
* `ngtcp2_conn_update_pkt_tx_time` sets the time instant of the next
- * packet transmission. This function must be called after (multiple
- * invocation of) `ngtcp2_conn_writev_stream`. If packet aggregation
- * (e.g., packet batching, GSO) is used, call this function after all
- * aggregated datagrams are sent, which indicates multiple invocation
- * of `ngtcp2_conn_writev_stream`.
+ * packet transmission to pace packets. This function must be called
+ * after (multiple invocation of) `ngtcp2_conn_writev_stream`. If
+ * packet aggregation (e.g., packet batching, GSO) is used, call this
+ * function after all aggregated datagrams are sent, which indicates
+ * multiple invocation of `ngtcp2_conn_writev_stream`.
*/
NGTCP2_EXTERN void ngtcp2_conn_update_pkt_tx_time(ngtcp2_conn *conn,
ngtcp2_tstamp ts);
*
* `ngtcp2_strerror` returns the text representation of |liberr|.
* |liberr| must be one of ngtcp2 library error codes (which is
- * defined as NGTCP2_ERR_* macro, such as
- * :macro:`NGTCP2_ERR_DECRYPT`).
+ * defined as :macro:`NGTCP2_ERR_* <NGTCP2_ERR_INVALID_ARGUMENT>`
+ * macros).
*/
NGTCP2_EXTERN const char *ngtcp2_strerror(int liberr);
*
* `ngtcp2_err_is_fatal` returns nonzero if |liberr| is a fatal error.
* |liberr| must be one of ngtcp2 library error codes (which is
- * defined as NGTCP2_ERR_* macro, such as
- * :macro:`NGTCP2_ERR_DECRYPT`).
+ * defined as :macro:`NGTCP2_ERR_* <NGTCP2_ERR_INVALID_ARGUMENT>`
+ * macros).
*/
NGTCP2_EXTERN int ngtcp2_err_is_fatal(int liberr);
* `ngtcp2_err_infer_quic_transport_error_code` returns a QUIC
* transport error code which corresponds to |liberr|. |liberr| must
* be one of ngtcp2 library error codes (which is defined as
- * NGTCP2_ERR_* macro, such as :macro:`NGTCP2_ERR_DECRYPT`).
+ * :macro:`NGTCP2_ERR_* <NGTCP2_ERR_INVALID_ARGUMENT>` macros).
*/
NGTCP2_EXTERN uint64_t ngtcp2_err_infer_quic_transport_error_code(int liberr);
* @function
*
* `ngtcp2_settings_default` initializes |settings| with the default
- * values. First this function fills |settings| with 0 and set the
+ * values. First this function fills |settings| with 0, and set the
* default value to the following fields:
*
* * :type:`cc_algo <ngtcp2_settings.cc_algo>` =
* @function
*
* `ngtcp2_transport_params_default` initializes |params| with the
- * default values. First this function fills |params| with 0 and set
+ * default values. First this function fills |params| with 0, and set
* the default value to the following fields:
*
* * :type:`max_udp_payload_size
/**
* @struct
*
- * :type:`ngtcp2_info` is what `ngtcp2_version()` returns. It holds
+ * :type:`ngtcp2_info` is what `ngtcp2_version` returns. It holds
* information about the particular ngtcp2 version.
*/
typedef struct ngtcp2_info {
int age;
/**
* :member:`version_num` is the :macro:`NGTCP2_VERSION_NUM` number
- * (since age ==1)
+ * (since :member:`age` ==1)
*/
int version_num;
/**
* :member:`version_str` points to the :macro:`NGTCP2_VERSION`
- * string (since age ==1)
+ * string (since :member:`age` ==1)
*/
const char *version_str;
/* -------- the above fields all exist when age == 1 */
/**
* @function
*
- * `ngtcp2_version` returns a pointer to a ngtcp2_info struct with
- * version information about the run-time library in use. The
+ * `ngtcp2_version` returns a pointer to a :type:`ngtcp2_info` struct
+ * with version information about the run-time library in use. The
* |least_version| argument can be set to a 24 bit numerical value for
- * the least accepted version number and if the condition is not met,
+ * the least accepted version number, and if the condition is not met,
* this function will return a ``NULL``. Pass in 0 to skip the
* version checking.
*/
/**
* @function
*
- * `ngtcp2_is_supported_version` returns nonzero if the library supports
- * QUIC version |version|.
+ * `ngtcp2_is_supported_version` returns nonzero if the library
+ * supports QUIC version |version|.
*/
NGTCP2_EXTERN int ngtcp2_is_supported_version(uint32_t version);
-/*
+/**
* @function
*
* `ngtcp2_is_reserved_version` returns nonzero if |version| is a
* |preferred_versions| of |preferred_versionslen| elements specifies
* the preference of versions, which is sorted in the order of
* preference. All versions included in |preferred_versions| must be
- * supported by the library, that is, passing a version to
- * `ngtcp2_is_supported_version` must return nonzero. This function
- * is intended to be used by client when it receives Version
+ * supported by the library, that is, passing any version in the array
+ * to `ngtcp2_is_supported_version` must return nonzero. This
+ * function is intended to be used by client when it receives Version
* Negotiation packet. If no version is selected, this function
* returns 0.
*/
projects / thirdparty / knot-dns.git / commitdiff
