From 9aee43f7d8378895db32f34951a86586baac1793 Mon Sep 17 00:00:00 2001 From: Tatsuhiro Tsujikawa Date: Wed, 24 Feb 2016 23:51:00 +0900 Subject: [PATCH] Update doc for extension frames --- lib/includes/nghttp2/nghttp2.h | 45 +++++++++++++++++++++++++--------- 1 file changed, 33 insertions(+), 12 deletions(-) diff --git a/lib/includes/nghttp2/nghttp2.h b/lib/includes/nghttp2/nghttp2.h index 6a2a5c13..9b753a71 100644 --- a/lib/includes/nghttp2/nghttp2.h +++ b/lib/includes/nghttp2/nghttp2.h @@ -1736,11 +1736,19 @@ typedef int (*nghttp2_on_extension_chunk_recv_callback)( * :type:`nghttp2_on_extension_chunk_recv_callback`. The frame header * is already unpacked by the library and provided as |hd|. * + * To receive extension frames, the application must tell desired + * extension frame type to the library using + * `nghttp2_option_set_user_recv_extension_type()`. + * * The implementation of this function may store the pointer to the * created object as a result of unpacking in |*payload|, and returns * 0. The pointer stored in |*payload| is opaque to the library, and - * the library does not own its pointer. |*payload| is initialled as - * `NULL`. + * the library does not own its pointer. |*payload| is initialized as + * `NULL`. The |*payload| is available as ``frame->ext.payload`` in + * :type:`nghttp2_on_frame_recv_callback`. Therefore if application + * can free that memory inside :type:`nghttp2_on_frame_recv_callback` + * callback. Of course, application has a liberty not ot use + * |*payload|, and do its own mechanism to process extension frames. * * To abort processing this extension frame, return * :enum:`NGHTTP2_ERR_CANCEL`. @@ -1760,16 +1768,16 @@ typedef int (*nghttp2_unpack_extension_callback)(nghttp2_session *session, /** * @functypedef * - * Callbck function invoked when library asks the application to pack + * Callback function invoked when library asks the application to pack * extension payload in its wire format. The frame header will be * packed by library. Application must pack payload only. - * frame->ext.payload is the object passed to + * ``frame->ext.payload`` is the object passed to * `nghttp2_submit_extension()` as payload parameter. Application * must pack extension payload to the |buf| of its capacity |len| - * bytes. + * bytes. The |len| is at least 16KiB. * - * The implementation of this function returns the number of bytes - * written into |buf| when it succeeds. + * The implementation of this function should return the number of + * bytes written into |buf| when it succeeds. * * To abort processing this extension frame, return * :enum:`NGHTTP2_ERR_CANCEL`, and @@ -2229,13 +2237,15 @@ nghttp2_option_set_max_reserved_remote_streams(nghttp2_option *option, /** * @function * - * Set extension frame type the application is willing to handle with + * Sets extension frame type the application is willing to handle with * user defined callbacks (see * :type:`nghttp2_on_extension_chunk_recv_callback` and * :type:`nghttp2_unpack_extension_callback`). The |type| is * extension frame type, and must be strictly greater than 0x9. - * Otherwise, this function does nothing. The application does not - * have to call this function if it just sends extension frames. + * Otherwise, this function does nothing. The application can call + * this function multiple times to set more than one frame type to + * receive. The application does not have to call this function if it + * just sends extension frames. */ NGHTTP2_EXTERN void nghttp2_option_set_user_recv_extension_type(nghttp2_option *option, @@ -3916,12 +3926,23 @@ NGHTTP2_EXTERN int nghttp2_submit_window_update(nghttp2_session *session, * * Submits extension frame. * - * Application can pass arbitrary frame flags and stream ID to |flags| + * Application can pass arbitrary frame flags and stream ID in |flags| * and |stream_id| respectively. The |payload| is opaque pointer, and - * it can be accessible though frame->ext.payload in + * it can be accessible though ``frame->ext.payload`` in * :type:`nghttp2_pack_extension_callback`. The library will not own * passed |payload| pointer. * + * The application must set :type:`nghttp2_pack_extension_callback` + * using `nghttp2_session_callbacks_set_pack_extension_callback()`. + * + * The application should retain the memory pointed by |payload| until + * the transmission of extension frame is done (which is indicated by + * :type:`nghttp2_on_frame_send_callback`), or transmission fails + * (which is indicated by :type:`nghttp2_on_frame_not_send_callback`). + * If application does not touch this memory region after packing it + * into a wire format, application can free it inside + * :type:`nghttp2_pack_extension_callback`. + * * The standard HTTP/2 frame cannot be sent with this function, so * |type| must be strictly grater than 0x9. Otherwise, this function * will fail with error code :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`.