walkero
/
nghttp2
1
0
Fork 0
Code Issues Pull Requests Projects Releases 1 Wiki Activity

Update doc for extension frames

This commit is contained in:
Tatsuhiro Tsujikawa 2016-02-24 23:51:00 +09:00
parent 34bf153653
commit 9aee43f7d8
1 changed files with 33 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
lib/includes/nghttp2/nghttp2.h
View File

@ -1736,11 +1736,19 @@ typedef int (*nghttp2_on_extension_chunk_recv_callback)(
* :type:`nghttp2_on_extension_chunk_recv_callback`. The frame header * :type:`nghttp2_on_extension_chunk_recv_callback`. The frame header
* is already unpacked by the library and provided as |hd|. * 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 * The implementation of this function may store the pointer to the
* created object as a result of unpacking in |*payload|, and returns * created object as a result of unpacking in |*payload|, and returns
* 0. The pointer stored in |*payload| is opaque to the library, and * 0. The pointer stored in |*payload| is opaque to the library, and
* the library does not own its pointer. |*payload| is initialled as * the library does not own its pointer. |*payload| is initialized as
* `NULL`. * `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 * To abort processing this extension frame, return
* :enum:`NGHTTP2_ERR_CANCEL`. * :enum:`NGHTTP2_ERR_CANCEL`.
@ -1760,16 +1768,16 @@ typedef int (*nghttp2_unpack_extension_callback)(nghttp2_session *session,
/** /**
* @functypedef * @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 * extension payload in its wire format. The frame header will be
* packed by library. Application must pack payload only. * 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 * `nghttp2_submit_extension()` as payload parameter. Application
* must pack extension payload to the |buf| of its capacity |len| * 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 * The implementation of this function should return the number of
* written into |buf| when it succeeds. * bytes written into |buf| when it succeeds.
* *
* To abort processing this extension frame, return * To abort processing this extension frame, return
* :enum:`NGHTTP2_ERR_CANCEL`, and * :enum:`NGHTTP2_ERR_CANCEL`, and
@ -2229,13 +2237,15 @@ nghttp2_option_set_max_reserved_remote_streams(nghttp2_option *option,
/** /**
* @function * @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 * user defined callbacks (see
* :type:`nghttp2_on_extension_chunk_recv_callback` and * :type:`nghttp2_on_extension_chunk_recv_callback` and
* :type:`nghttp2_unpack_extension_callback`). The |type| is * :type:`nghttp2_unpack_extension_callback`). The |type| is
* extension frame type, and must be strictly greater than 0x9. * extension frame type, and must be strictly greater than 0x9.
* Otherwise, this function does nothing. The application does not * Otherwise, this function does nothing. The application can call
* have to call this function if it just sends extension frames. * 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_EXTERN void
nghttp2_option_set_user_recv_extension_type(nghttp2_option *option, 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. * 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 * 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 * :type:`nghttp2_pack_extension_callback`. The library will not own
* passed |payload| pointer. * 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 * The standard HTTP/2 frame cannot be sent with this function, so
* |type| must be strictly grater than 0x9. Otherwise, this function * |type| must be strictly grater than 0x9. Otherwise, this function
* will fail with error code :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`. * will fail with error code :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`.