doc/nghttp2_submit_extension.rst

   1
   2 nghttp2_submit_extension
   3 ========================
   4
   5 Synopsis
   6 --------
   7
   8 *#include <nghttp2/nghttp2.h>*
   9
  10 .. function:: int nghttp2_submit_extension(nghttp2_session *session, uint8_t type, uint8_t flags, int32_t stream_id, void *payload)
  11
  12
  13     Submits extension frame.
  14
  15     Application can pass arbitrary frame flags and stream ID in *flags*
  16     and *stream_id* respectively.  The *payload* is opaque pointer, and
  17     it can be accessible though ``frame->ext.payload`` in
  18     :type:`nghttp2_pack_extension_callback`.  The library will not own
  19     passed *payload* pointer.
  20
  21     The application must set :type:`nghttp2_pack_extension_callback`
  22     using `nghttp2_session_callbacks_set_pack_extension_callback()`.
  23
  24     The application should retain the memory pointed by *payload* until
  25     the transmission of extension frame is done (which is indicated by
  26     :type:`nghttp2_on_frame_send_callback`), or transmission fails
  27     (which is indicated by :type:`nghttp2_on_frame_not_send_callback`).
  28     If application does not touch this memory region after packing it
  29     into a wire format, application can free it inside
  30     :type:`nghttp2_pack_extension_callback`.
  31
  32     The standard HTTP/2 frame cannot be sent with this function, so
  33     *type* must be strictly grater than 0x9.  Otherwise, this function
  34     will fail with error code :macro:`NGHTTP2_ERR_INVALID_ARGUMENT`.
  35
  36     This function returns 0 if it succeeds, or one of the following
  37     negative error codes:
  38
  39     :macro:`NGHTTP2_ERR_INVALID_STATE`
  40         If :type:`nghttp2_pack_extension_callback` is not set.
  41     :macro:`NGHTTP2_ERR_INVALID_ARGUMENT`
  42         If  *type* specifies  standard  HTTP/2 frame  type.  The  frame
  43         types  in the  rage [0x0,  0x9], both  inclusive, are  standard
  44         HTTP/2 frame type, and cannot be sent using this function.
  45     :macro:`NGHTTP2_ERR_NOMEM`
  46         Out of memory