From 56175a5544f7faf1d5a27ef0f88396d0a664a08f Mon Sep 17 00:00:00 2001 From: Tatsuhiro Tsujikawa Date: Sun, 27 Apr 2014 16:33:36 +0900 Subject: [PATCH] Update doc --- apiref.html | 34 +++++++++++++++++++++++++++++ genindex.html | 8 +++++++ nghttp2.h.html | 57 +++++++++++++++++++++++++++++++++++++++++-------- objects.inv | Bin 2437 -> 2455 bytes searchindex.js | 2 +- 5 files changed, 91 insertions(+), 10 deletions(-) diff --git a/apiref.html b/apiref.html index c749623d..98cc3e31 100644 --- a/apiref.html +++ b/apiref.html @@ -1816,6 +1816,30 @@ inclusive. Choosing number not in this range will be treated as NGHTTP2_ERR_CALLBACK_FAILURE.

+
+
+typedef int (*nghttp2_adjust_priority_callback)(nghttp2_session *session, const nghttp2_frame *frame, nghttp2_priority_spec *pri_spec, void *user_data)
+

Callback function invoked to adjust priority value for request +HEADERS. This callback is called only for request HEADERS (which +means, frame->hd.type == NGHTTP2_HEADERS && frame->headers.cat == +NGHTTP2_HCAT_REQUEST() hold) and before +nghttp2_before_frame_send_callback(). The application can +adjust priority value pri_spec. Initially, pri_spec is filled +with the current priority value, which is equal to +frame->headers.pri_spec(). If the application doesn’t alter +priority value, just return 0 without updating pri_spec.

+

Since the application doesn’t know stream ID when it submits +requests, it may not be able to add correct priority value to +HEADERS frame and forced to use follwing PRIORITY frame. The +purpose of this callback is give the chance to the application to +adjust priority value with the latest information it has just +before transmission so that correct priority is included in HEADERS +frame and it doesn’t have to send additional PRIORITY frame.

+

Returning NGHTTP2_ERR_CALLBACK_FAILURE will make +nghttp2_session_send() function immediately return +NGHTTP2_ERR_CALLBACK_FAILURE.

+
+
nghttp2_session_callbacks
@@ -1913,6 +1937,13 @@ many padding bytes are required for the transmission of the given frame.

+
+
+nghttp2_adjust_priority_callback adjust_priority_callback
+

Callback function invoked to adjust priority value just before +request HEADERS is serialized to the wire format.

+
+
@@ -2093,6 +2124,9 @@ which tells when each callback is invoked:

are not met (e.g., request HEADERS cannot be sent after GOAWAY), nghttp2_session_callbacks.on_frame_not_send_callback is invoked. Abort the following steps. +
  • If the frame is request HEADERS, +nghttp2_session_callbacks.adjust_priority_callback is +invoked.
  • If the frame is HEADERS, PUSH_PROMISE or DATA, nghttp2_session_callbacks.select_padding_callback is invoked.
    • diff --git a/genindex.html b/genindex.html index 7f0f6f31..b8367bab 100644 --- a/genindex.html +++ b/genindex.html @@ -167,6 +167,10 @@
    +
    nghttp2_adjust_priority_callback (C type) +
    + +
    NGHTTP2_ALTSVC (C macro)
    @@ -1001,6 +1005,10 @@ +
    nghttp2_session_callbacks.adjust_priority_callback (C member) +
    + +
    nghttp2_session_callbacks.before_frame_send_callback (C member)
    diff --git a/nghttp2.h.html b/nghttp2.h.html index 47e6ba26..c903d665 100644 --- a/nghttp2.h.html +++ b/nghttp2.h.html @@ -1580,6 +1580,37 @@ size_t max_payloadlen, void *user_data); +/** + * @functypedef + * + * Callback function invoked to adjust priority value for request + * HEADERS. This callback is called only for request HEADERS (which + * means, `frame->hd.type == NGHTTP2_HEADERS && frame->headers.cat == + * NGHTTP2_HCAT_REQUEST` hold) and before + * :type:`nghttp2_before_frame_send_callback()`. The application can + * adjust priority value |pri_spec|. Initially, |pri_spec| is filled + * with the current priority value, which is equal to + * `frame->headers.pri_spec`. If the application doesn't alter + * priority value, just return 0 without updating |pri_spec|. + * + * Since the application doesn't know stream ID when it submits + * requests, it may not be able to add correct priority value to + * HEADERS frame and forced to use follwing PRIORITY frame. The + * purpose of this callback is give the chance to the application to + * adjust priority value with the latest information it has just + * before transmission so that correct priority is included in HEADERS + * frame and it doesn't have to send additional PRIORITY frame. + * + * Returning :enum:`NGHTTP2_ERR_CALLBACK_FAILURE` will make + * `nghttp2_session_send()` function immediately return + * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`. + */ +typedef int (*nghttp2_adjust_priority_callback) +(nghttp2_session *session, + const nghttp2_frame *frame, + nghttp2_priority_spec *pri_spec, + void *user_data); + /** * @struct * @@ -1653,6 +1684,11 @@ * frame. */ nghttp2_select_padding_callback select_padding_callback; + /** + * Callback function invoked to adjust priority value just before + * request HEADERS is serialized to the wire format. + */ + nghttp2_adjust_priority_callback adjust_priority_callback; } nghttp2_session_callbacks; struct nghttp2_option; @@ -1859,20 +1895,23 @@ * are not met (e.g., request HEADERS cannot be sent after GOAWAY), * :member:`nghttp2_session_callbacks.on_frame_not_send_callback` * is invoked. Abort the following steps. - * 4. If the frame is HEADERS, PUSH_PROMISE or DATA, + * 4. If the frame is request HEADERS, + * :member:`nghttp2_session_callbacks.adjust_priority_callback` is + * invoked. + * 5. If the frame is HEADERS, PUSH_PROMISE or DATA, * :member:`nghttp2_session_callbacks.select_padding_callback` is * invoked. - * 5. If the frame is request HEADERS, the stream is opened here. - * 6. :member:`nghttp2_session_callbacks.before_frame_send_callback` is + * 6. If the frame is request HEADERS, the stream is opened here. + * 7. :member:`nghttp2_session_callbacks.before_frame_send_callback` is * invoked. - * 7. :member:`nghttp2_session_callbacks.send_callback` is invoked one + * 8. :member:`nghttp2_session_callbacks.send_callback` is invoked one * or more times to send the frame. - * 8. :member:`nghttp2_session_callbacks.on_frame_send_callback` is - * invoked. - * 9. If the transmission of the frame triggers closure of the stream, - * the stream is closed and - * :member:`nghttp2_session_callbacks.on_stream_close_callback` is + * 9. :member:`nghttp2_session_callbacks.on_frame_send_callback` is * invoked. + * 10. If the transmission of the frame triggers closure of the stream, + * the stream is closed and + * :member:`nghttp2_session_callbacks.on_stream_close_callback` is + * invoked. * * This function returns 0 if it succeeds, or one of the following * negative error codes: diff --git a/objects.inv b/objects.inv index 96ddcade134594b89661a34071fd7c9505413b83..80da55818a314482b7d12145bc3aee0ac50ec0e8 100644 GIT binary patch delta 2352 zcmV-03D5S06PFW^fPcx7qc{+~_g6S#=GsI|ALmBfauqQcJS?@$ML~gVGlhX>vAg=~ zCj|(b@Mk20DV586Pw9OY#c3pd&dMtKGYQ^AGW+_+EdThr@4nD>)js)cw#uS9 z5i>)6^kpm3D}&Uh-H7(lQUpb~8$Q^6);;F753GZ&_>yjSRezO#<3UoDhfv!^v+&Qo z*uRNl_Qx#9<3eoOQK9zx?CTfn;nDNf-#Bv|ZdgycX)L(w=^m5Ag0RT0j#884b-Ckt zk?rGBXz3vl>6F?er&$GGr&0eMemRd!UoeNy z?bZ73D%2R4d4HZ^J-BM1r++sYca47-YWPC;biOq8hh|2Hxh`9vcE1xrB#KhYg9vSI z!}6G8>89MM?VzSm$hmY1~bnh867m{$LnH@SlC~ zlSA&K`A!6hbYwZ#($&(@SIFdeekPdRv_aH7cIW9kIn-E8PoQxMhZ{#XB6(^|mQ^8w zJr9$t6o15|tec+uG)Hcz37u5@thmZ0SXXPZ#wH22RGW7J|J}6bf68Av;+%RM!GEmA0&CxWL``u7pqL$bor4Dpi~*Dz z!PXm)gw1{us-RYs9!3M{dMvd6Mk-sx$RgapCw(OPdONo%a&FpKq}3vVzCI!r)So5z zHO@^^{wB6@s+ashFD#&7YclYi7K(paFH{NHLd>>i`GO@WCahi2vye{ z*MI8{i(X|lqz4U;SiOP-6k9t^EsbwtlNF*Xwi6i(FeXQt3Y@@$ifP)TkJ^4G(@6S)^Gc`I^k=S z0pgNx0Fa_#7iHC@cAVFM17s~Hl*9f9`Xpo7 z^IbL!oxK>YhcXOgVLZFO&Gkl;vBaxH^w=^=*tsmc8jV^gI($sHi=&3!mdOVvRazlJiai%{^- zE5N8-w^;2s>^%o7Jlu)!9m?D$sFMoo`KM%x4$n>{fte-LM5~59n)Qqovwe?hT5W?| z-+9%aV1@y_M5cjf+cy_@>JI6t3x5pM;s(@A>;5X^UjlX+7Ge)LnwAR+QPxn&q;W~Q zMt2bTSQWiEausA)FmXErPL^Un^IOEgHlSK)&Qo{^)>umI)`$#Lf@j0>bq}ix44@E6 zZql6xe+7vSkM5;V*_<2!m^9F<^LC!r`>AR;0Oh4VXQNd?y`dF>aM>Fx)_*~%*L~CD z&rHf#1ibo|WZ}D@CD%MFD!NEOEnvO5=DNon_P5WF=(Hg)%vz8PE%P$Q(EZB^w7nI` zBxK~dfM}Hxewd|UT@;WVyBI+u$?n8RNRZh}ysa^2Qv(zzviue4CK2zUv_oMJqj}>Z z4+2QoRy$gelDeYI_IUU|kbjj3cS~2v-c2Em$PB2&Z?0Q&W}+U2qzKHJ6esE$KP!ol zVGEI!)zw>80|WU{i&``Y1ba9=d;ZK|#*3EqC@sQYZQqeJWJUA5?)nQW%B*$BX^`J3 zk%>FjPVJGAJYGKs$wEr_aMteHwp^SBGdG#;cZb^4xW$H^Tqz19Z* zQH=ulXu>$%C`d;$3V-?)TBZszt%5iXO}{!t!0AGRKzd}i30~{$Ma${&Kj5hf_t14u z(oOc+;Q`o0nbWWU^!^R(7HA{`nnF%1Ni4B^Dvnf0ND*5pkWb{G1d)L&1xvOG<3Z(bpM6{kRplXn&Dg=i4HP1hrTXisb#Q zj||BNTYuJHxo$#aE?yzV2;Yzh1F=n5C&`%rwpN1Cb7WLwZuRaE*vs*Mv#L#3vxz zL`4&>y_zr;9e)>MpH*TCD8ALGOYbdF7d0qXA7FCJwit~BONo=nM=DY5<5c!doNn>x zajc1-VN#cHe7H1rDq^FXylh)STBYxJMVN(c41+Ij&x#?RcYaSW3hugm zLum9pefJ8KL+ln zc`L)hl-rAY1k-+|r0NbI<8a`V%XsB%VNj8E9{17r_%o^W6r#+tv_wZXO=@oE=+$3R z3=9hsYG`*4fbWu2HUNlGqM7U^GU4Q3^<2FKm?_GgVA}}paM6mOF1zr*_2^I-s$G@$ WDh&e80xa0)0VEYn|IU9!W~#X|?|YB{ delta 2334 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