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

Updated doc

This commit is contained in:
Tatsuhiro Tsujikawa 2012-02-22 23:39:30 +09:00
parent 33cd4b5946
commit 05627f7712
1 changed files with 148 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

187
lib/spdylay_session.h
View File

@ -157,40 +157,84 @@ struct spdylay_session {
/* TODO stream timeout etc */ /* TODO stream timeout etc */
/* /*
* Returns non-zero value if |stream_id| is initiated by local host. * Returns nonzero value if |stream_id| is initiated by local
* Otherwrise returns 0. * endpoint.
*/ */
int spdylay_session_is_my_stream_id(spdylay_session *session, int spdylay_session_is_my_stream_id(spdylay_session *session,
int32_t stream_id); int32_t stream_id);
/* /*
* Adds frame |frame| of type |frame_type| to tx queue in |session|. * Adds frame |frame| of type |frame_type| to the outbound queue in
* |aux_data| is a pointer to arbitrary data. Its interpretation is * |session|. |aux_data| is a pointer to the arbitrary data. Its
* defined per |frame_type|. When this function succeeds, it takes * interpretation is defined per |frame_type|. When this function
* ownership of |frame| and |aux_data|, so caller must not free them. * succeeds, it takes ownership of |frame| and |aux_data|, so caller
* This function returns 0 if it succeeds, or negative error code. * must not free them on success.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* SPDYLAY_ERR_NOMEM
* Out of memory.
*/ */
int spdylay_session_add_frame(spdylay_session *session, int spdylay_session_add_frame(spdylay_session *session,
spdylay_frame_type frame_type, spdylay_frame_type frame_type,
spdylay_frame *frame, spdylay_frame *frame,
void *aux_data); void *aux_data);
/*
* Adds RST_STREAM frame for the stream |stream_id| with status code
* |status_code|. This is a convenient function built on top of
* spdylay_session_add_frame() to add RST_STREAM easily.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* SPDYLAY_ERR_NOMEM
* Out of memory.
*/
int spdylay_session_add_rst_stream(spdylay_session *session, int spdylay_session_add_rst_stream(spdylay_session *session,
int32_t stream_id, uint32_t status_code); int32_t stream_id, uint32_t status_code);
/*
* Adds PING frame with unique ID |unique_id|. This is a convenient
* functin built on top of spdylay_session_add_frame() to add PING
* easily.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* SPDYLAY_ERR_NOMEM
* Out of memory.
*/
int spdylay_session_add_ping(spdylay_session *session, uint32_t unique_id); int spdylay_session_add_ping(spdylay_session *session, uint32_t unique_id);
/*
* Adds GOAWAY frame with last-good-stream-ID
* |last_good_stream_id|. This is a convenient function built on top
* of spdylay_session_add_frame() to add GOAWAY easily.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* SPDYLAY_ERR_NOMEM
* Out of memory.
*/
int spdylay_session_add_goaway(spdylay_session *session, int spdylay_session_add_goaway(spdylay_session *session,
int32_t last_good_stream_id); int32_t last_good_stream_id);
/* /*
* Creates new stream in |session| with stream ID |stream_id|, * Creates new stream in |session| with stream ID |stream_id|,
* priority |pri| and flags |flags|. Currently, |flags| & * priority |pri| and flags |flags|. SPDYLAY_FLAG_UNIDIRECTIONAL flag
* SPDYLAY_FLAG_UNIDIRECTIONAL is non-zero, this stream is * is set in |flags|, this stream is unidirectional. SPDYLAY_FLAG_FIN
* unidirectional. |flags| & SPDYLAY_FLAG_FIN is non-zero, the sender * flag is set in |flags|, the sender of SYN_STREAM will not send any
* of SYN_STREAM will not send any further data in this stream. The * further data in this stream. Since this function is called when
* state of stream is set to |initial_state|. This function returns a * SYN_STREAM is sent or received, these flags are taken from
* pointer to created new stream object, or NULL. * SYN_STREAM. The state of stream is set to |initial_state|.
* |stream_user_data| is a pointer to the arbitrary user supplied data
* to be associated to this stream.
*
* This function returns a pointer to created new stream object, or
* NULL.
*/ */
spdylay_stream* spdylay_session_open_stream(spdylay_session *session, spdylay_stream* spdylay_session_open_stream(spdylay_session *session,
int32_t stream_id, int32_t stream_id,
@ -200,10 +244,14 @@ spdylay_stream* spdylay_session_open_stream(spdylay_session *session,
/* /*
* Closes stream whose stream ID is |stream_id|. The reason of closure * Closes stream whose stream ID is |stream_id|. The reason of closure
* is indicated by |status_code|. This function returns 0 if it * is indicated by |status_code|. When closing the stream,
* succeeds, or negative error code. The possible error code is * on_stream_close_callback will be called.
* SPDYLAY_ERR_INVALID_ARGUMENT, which is used when stream |stream_id| *
* does not exist. So the caller may ignore this error. * This function returns 0 if it succeeds, or one the following
* negative error codes:
*
* SPDYLAY_ERR_INVALID_ARGUMENT
* The specified stream does not exist.
*/ */
int spdylay_session_close_stream(spdylay_session *session, int32_t stream_id, int spdylay_session_close_stream(spdylay_session *session, int32_t stream_id,
spdylay_status_code status_code); spdylay_status_code status_code);
@ -217,64 +265,108 @@ void spdylay_session_close_pushed_streams(spdylay_session *session,
spdylay_status_code status_code); spdylay_status_code status_code);
/* /*
* If further receptions and transmissions over this stream are * If further receptions and transmissions over the stream |stream_id|
* disallowed, close this stream. This function returns 0 if it * are disallowed, close the stream with status code |status_code|.
* succeeds, or negative error code. If either receptions or *
* transmissions is allowed, this function returns 0 and the stream * This function returns 0 if it
* will not be closed. * succeeds, or one of the following negative error codes:
*
* SPDYLAY_ERR_INVALID_ARGUMENT
* The specified stream does not exist.
*/ */
int spdylay_session_close_stream_if_shut_rdwr(spdylay_session *session, int spdylay_session_close_stream_if_shut_rdwr(spdylay_session *session,
spdylay_stream *stream); spdylay_stream *stream);
/* /*
* Called when SYN_STREAM is received. Received frame is |frame|. * Called when SYN_STREAM is received, assuming |frame.syn_stream| is
* This function does first validate received frame and then open * properly initialized. This function does first validate received
* stream and call callback functions. This function returns 0 if it * frame and then open stream and call callback functions. This
* succeeds, or negative error code. This function does not return * function does not return error if frame is not valid.
* error if frame is not valid. *
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* SPDYLAY_ERR_NOMEM
* Out of memory.
*/ */
int spdylay_session_on_syn_stream_received(spdylay_session *session, int spdylay_session_on_syn_stream_received(spdylay_session *session,
spdylay_frame *frame); spdylay_frame *frame);
/* /*
* Called when SYN_REPLY is received. Received frame is |frame|. * Called when SYN_REPLY is received, assuming |frame.syn_reply| is
* properly initialized.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* SPDYLAY_ERR_NOMEM
* Out of memory.
*/ */
int spdylay_session_on_syn_reply_received(spdylay_session *session, int spdylay_session_on_syn_reply_received(spdylay_session *session,
spdylay_frame *frame); spdylay_frame *frame);
/* /*
* Called when RST_STREAM is received. Received frame is |frame|. * Called when RST_STREAM is received, assuming |frame.rst_stream| is
* properly initialized.
*
* This function returns 0 and never fail.
*/ */
int spdylay_session_on_rst_stream_received(spdylay_session *session, int spdylay_session_on_rst_stream_received(spdylay_session *session,
spdylay_frame *frame); spdylay_frame *frame);
/* /*
* Called when SETTINGS is received. Received frame is |frame|. * Called when SETTINGS is received, assuming |frame.settings| is
* properly initialized.
*
* This function returns 0 and never fail.
*/ */
int spdylay_session_on_settings_received(spdylay_session *session, int spdylay_session_on_settings_received(spdylay_session *session,
spdylay_frame *frame); spdylay_frame *frame);
/* /*
* Called when PING is received. Received frame is |frame|. * Called when PING is received, assuming |frame.ping| is properly
* initialized.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* SPDYLAY_ERR_NOMEM
* Out of memory.
*/ */
int spdylay_session_on_ping_received(spdylay_session *session, int spdylay_session_on_ping_received(spdylay_session *session,
spdylay_frame *frame); spdylay_frame *frame);
/* /*
* Called when GOAWAY is received. Received frame is |frame|. * Called when GOAWAY is received, assuming |frame.goaway| is properly
* initialized.
*
* This function returns 0 and never fail.
*/ */
int spdylay_session_on_goaway_received(spdylay_session *session, int spdylay_session_on_goaway_received(spdylay_session *session,
spdylay_frame *frame); spdylay_frame *frame);
/* /*
* Called when HEADERS is recieved. Received frame is |frame|. * Called when HEADERS is recieved, assuming |frame.headers| is
* properly initialized.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* SPDYLAY_ERR_NOMEM
* Out of memory.
*/ */
int spdylay_session_on_headers_received(spdylay_session *session, int spdylay_session_on_headers_received(spdylay_session *session,
spdylay_frame *frame); spdylay_frame *frame);
/* /*
* Called when DATA is received. * Called when DATA is received.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* SPDYLAY_ERR_NOMEM
* Out of memory.
*/ */
int spdylay_session_on_data_received(spdylay_session *session, int spdylay_session_on_data_received(spdylay_session *session,
uint8_t flags, int32_t length, uint8_t flags, int32_t length,
@ -288,12 +380,21 @@ spdylay_stream* spdylay_session_get_stream(spdylay_session *session,
int32_t stream_id); int32_t stream_id);
/* /*
* Packs DATA frame |frame| in wire frame format and store it in * Packs DATA frame |frame| in wire frame format and stores it in
* |*buf_ptr|. The capacity of |*buf_ptr| is |*buflen_ptr| * |*buf_ptr|. The capacity of |*buf_ptr| is |*buflen_ptr|
* length. This function expands |*buf_ptr| as necessary to store * length. This function expands |*buf_ptr| as necessary to store
* given |frame|. It packs header in first 8 bytes. Remaining bytes * given |frame|. It packs header in first 8 bytes. Remaining bytes
* are filled using frame->data_prd. This function returns the size * are filled using frame->data_prd.
* of packed frame if it succeeds, or negative error code. *
* This function returns the size of packed frame if it succeeds, or
* one of the following negative error codes:
*
* SPDYLAY_ERR_NOMEM
* Out of memory.
* SPDYLAY_ERR_DEFERRED
* The DATA frame is postponed.
* SPDYLAY_ERR_CALLBACK_FAILURE
* The read_callback failed.
*/ */
ssize_t spdylay_session_pack_data(spdylay_session *session, ssize_t spdylay_session_pack_data(spdylay_session *session,
uint8_t **buf_ptr, size_t *buflen_ptr, uint8_t **buf_ptr, size_t *buflen_ptr,
@ -301,9 +402,17 @@ ssize_t spdylay_session_pack_data(spdylay_session *session,
/* /*
* Packs DATA frame |frame| in wire frame format and store it in * Packs DATA frame |frame| in wire frame format and store it in
* |buf|. |len| must be greater than or equal to 8. This function * |buf|. |len| must be greater than or equal to 8.
* returns the sizeof packed frame if it succeeds, or negative error *
* code. * This function returns the size of packed frame if it succeeds, or
* one of the following negative error codes:
*
* SPDYLAY_ERR_NOMEM
* Out of memory.
* SPDYLAY_ERR_DEFERRED
* The DATA frame is postponed.
* SPDYLAY_ERR_CALLBACK_FAILURE
* The read_callback failed.
*/ */
ssize_t spdylay_session_pack_data_overwrite(spdylay_session *session, ssize_t spdylay_session_pack_data_overwrite(spdylay_session *session,
uint8_t *buf, size_t len, uint8_t *buf, size_t len,