nghttp3.h 91 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972197319741975197619771978197919801981198219831984198519861987198819891990199119921993199419951996199719981999200020012002200320042005200620072008200920102011201220132014201520162017201820192020202120222023202420252026202720282029203020312032203320342035203620372038203920402041204220432044204520462047204820492050205120522053205420552056205720582059206020612062206320642065206620672068206920702071207220732074207520762077207820792080208120822083208420852086208720882089209020912092209320942095209620972098209921002101210221032104210521062107210821092110211121122113211421152116211721182119212021212122212321242125212621272128212921302131213221332134213521362137213821392140214121422143214421452146214721482149215021512152215321542155215621572158215921602161216221632164216521662167216821692170217121722173217421752176217721782179218021812182218321842185218621872188218921902191219221932194219521962197219821992200220122022203220422052206220722082209221022112212221322142215221622172218221922202221222222232224222522262227222822292230223122322233223422352236223722382239224022412242224322442245224622472248224922502251225222532254225522562257225822592260226122622263226422652266226722682269227022712272227322742275227622772278227922802281228222832284228522862287228822892290229122922293229422952296229722982299230023012302230323042305230623072308230923102311231223132314231523162317231823192320232123222323232423252326232723282329233023312332233323342335233623372338233923402341234223432344234523462347234823492350235123522353235423552356235723582359236023612362236323642365236623672368236923702371237223732374237523762377237823792380238123822383238423852386238723882389239023912392239323942395239623972398239924002401240224032404240524062407240824092410241124122413241424152416241724182419242024212422242324242425242624272428242924302431243224332434243524362437243824392440244124422443244424452446244724482449245024512452245324542455245624572458245924602461246224632464246524662467246824692470247124722473247424752476247724782479248024812482248324842485248624872488248924902491249224932494249524962497249824992500250125022503250425052506250725082509251025112512251325142515251625172518251925202521252225232524252525262527252825292530253125322533253425352536253725382539254025412542254325442545254625472548254925502551255225532554255525562557255825592560256125622563256425652566256725682569257025712572257325742575257625772578257925802581258225832584258525862587258825892590259125922593259425952596259725982599260026012602260326042605260626072608260926102611261226132614261526162617261826192620262126222623262426252626262726282629263026312632263326342635263626372638263926402641264226432644264526462647264826492650265126522653265426552656265726582659266026612662266326642665266626672668266926702671267226732674267526762677267826792680268126822683268426852686268726882689269026912692269326942695269626972698269927002701270227032704270527062707270827092710271127122713271427152716271727182719272027212722272327242725272627272728272927302731273227332734273527362737273827392740274127422743274427452746274727482749275027512752275327542755275627572758275927602761276227632764276527662767276827692770277127722773277427752776277727782779278027812782278327842785278627872788278927902791279227932794279527962797279827992800280128022803280428052806280728082809281028112812281328142815281628172818281928202821282228232824282528262827282828292830283128322833283428352836283728382839284028412842284328442845284628472848284928502851285228532854285528562857285828592860286128622863286428652866286728682869287028712872287328742875287628772878287928802881288228832884288528862887288828892890289128922893289428952896289728982899290029012902290329042905290629072908290929102911291229132914291529162917291829192920292129222923292429252926292729282929293029312932293329342935293629372938293929402941
  1. /*
  2. * nghttp3
  3. *
  4. * Copyright (c) 2018 nghttp3 contributors
  5. * Copyright (c) 2017 ngtcp2 contributors
  6. * Copyright (c) 2017 nghttp2 contributors
  7. *
  8. * Permission is hereby granted, free of charge, to any person obtaining
  9. * a copy of this software and associated documentation files (the
  10. * "Software"), to deal in the Software without restriction, including
  11. * without limitation the rights to use, copy, modify, merge, publish,
  12. * distribute, sublicense, and/or sell copies of the Software, and to
  13. * permit persons to whom the Software is furnished to do so, subject to
  14. * the following conditions:
  15. *
  16. * The above copyright notice and this permission notice shall be
  17. * included in all copies or substantial portions of the Software.
  18. *
  19. * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  20. * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  21. * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  22. * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
  23. * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
  24. * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  25. * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  26. */
  27. #ifndef NGHTTP3_H
  28. #define NGHTTP3_H
  29. /* Define WIN32 when build target is Win32 API (borrowed from
  30. libcurl) */
  31. #if (defined(_WIN32) || defined(__WIN32__)) && !defined(WIN32)
  32. # define WIN32
  33. #endif
  34. #ifdef __cplusplus
  35. extern "C" {
  36. #endif
  37. #include <stdlib.h>
  38. #if defined(_MSC_VER) && (_MSC_VER < 1800)
  39. /* MSVC < 2013 does not have inttypes.h because it is not C99
  40. compliant. See compiler macros and version number in
  41. https://sourceforge.net/p/predef/wiki/Compilers/ */
  42. # include <stdint.h>
  43. #else /* !defined(_MSC_VER) || (_MSC_VER >= 1800) */
  44. # include <inttypes.h>
  45. #endif /* !defined(_MSC_VER) || (_MSC_VER >= 1800) */
  46. #include <sys/types.h>
  47. #include <stdarg.h>
  48. #include <stddef.h>
  49. #include <nghttp3/version.h>
  50. #ifdef NGHTTP3_STATICLIB
  51. # define NGHTTP3_EXTERN
  52. #elif defined(WIN32)
  53. # ifdef BUILDING_NGHTTP3
  54. # define NGHTTP3_EXTERN __declspec(dllexport)
  55. # else /* !BUILDING_NGHTTP3 */
  56. # define NGHTTP3_EXTERN __declspec(dllimport)
  57. # endif /* !BUILDING_NGHTTP3 */
  58. #else /* !defined(WIN32) */
  59. # ifdef BUILDING_NGHTTP3
  60. # define NGHTTP3_EXTERN __attribute__((visibility("default")))
  61. # else /* !BUILDING_NGHTTP3 */
  62. # define NGHTTP3_EXTERN
  63. # endif /* !BUILDING_NGHTTP3 */
  64. #endif /* !defined(WIN32) */
  65. #ifdef _MSC_VER
  66. # define NGHTTP3_ALIGN(N) __declspec(align(N))
  67. #else /* !_MSC_VER */
  68. # define NGHTTP3_ALIGN(N) __attribute__((aligned(N)))
  69. #endif /* !_MSC_VER */
  70. /**
  71. * @typedef
  72. *
  73. * :type:`nghttp3_ssize` is signed counterpart of size_t.
  74. */
  75. typedef ptrdiff_t nghttp3_ssize;
  76. /**
  77. * @macro
  78. *
  79. * :macro:`NGHTTP3_ALPN_H3` is a serialized form of HTTP/3 ALPN
  80. * protocol identifier this library supports. Notice that the first
  81. * byte is the length of the following protocol identifier.
  82. */
  83. #define NGHTTP3_ALPN_H3 "\x2h3"
  84. /**
  85. * @macrosection
  86. *
  87. * nghttp3 library error codes
  88. */
  89. /**
  90. * @macro
  91. *
  92. * :macro:`NGHTTP3_ERR_INVALID_ARGUMENT` indicates that a passed
  93. * argument is invalid.
  94. */
  95. #define NGHTTP3_ERR_INVALID_ARGUMENT -101
  96. /**
  97. * @macro
  98. *
  99. * :macro:`NGHTTP3_ERR_INVALID_STATE` indicates that a requested
  100. * operation is not allowed at the current connection state.
  101. */
  102. #define NGHTTP3_ERR_INVALID_STATE -102
  103. /**
  104. * @macro
  105. *
  106. * :macro:`NGHTTP3_ERR_WOULDBLOCK` indicates that an operation might
  107. * block.
  108. */
  109. #define NGHTTP3_ERR_WOULDBLOCK -103
  110. /**
  111. * @macro
  112. *
  113. * :macro:`NGHTTP3_ERR_STREAM_IN_USE` indicates that a stream ID is
  114. * already in use.
  115. */
  116. #define NGHTTP3_ERR_STREAM_IN_USE -104
  117. /**
  118. * @macro
  119. *
  120. * :macro:`NGHTTP3_ERR_MALFORMED_HTTP_HEADER` indicates that an HTTP
  121. * header field is malformed.
  122. */
  123. #define NGHTTP3_ERR_MALFORMED_HTTP_HEADER -105
  124. /**
  125. * @macro
  126. *
  127. * :macro:`NGHTTP3_ERR_REMOVE_HTTP_HEADER` indicates that an HTTP
  128. * header field is discarded.
  129. */
  130. #define NGHTTP3_ERR_REMOVE_HTTP_HEADER -106
  131. /**
  132. * @macro
  133. *
  134. * :macro:`NGHTTP3_ERR_MALFORMED_HTTP_MESSAGING` indicates that HTTP
  135. * messaging is malformed.
  136. */
  137. #define NGHTTP3_ERR_MALFORMED_HTTP_MESSAGING -107
  138. /**
  139. * @macro
  140. *
  141. * :macro:`NGHTTP3_ERR_QPACK_FATAL` indicates that a fatal error is
  142. * occurred during QPACK processing, and it cannot be recoverable.
  143. */
  144. #define NGHTTP3_ERR_QPACK_FATAL -108
  145. /**
  146. * @macro
  147. *
  148. * :macro:`NGHTTP3_ERR_QPACK_HEADER_TOO_LARGE` indicates that a header
  149. * field is too large to process.
  150. */
  151. #define NGHTTP3_ERR_QPACK_HEADER_TOO_LARGE -109
  152. /**
  153. * @macro
  154. *
  155. * :macro:`NGHTTP3_ERR_STREAM_NOT_FOUND` indicates that a stream is
  156. * not found.
  157. */
  158. #define NGHTTP3_ERR_STREAM_NOT_FOUND -110
  159. /**
  160. * @macro
  161. *
  162. * :macro:`NGHTTP3_ERR_CONN_CLOSING` indicates that a connection is
  163. * closing state.
  164. */
  165. #define NGHTTP3_ERR_CONN_CLOSING -111
  166. /**
  167. * @macro
  168. *
  169. * :macro:`NGHTTP3_ERR_STREAM_DATA_OVERFLOW` indicates that the length
  170. * of stream data is too long, and causes overflow.
  171. */
  172. #define NGHTTP3_ERR_STREAM_DATA_OVERFLOW -112
  173. /**
  174. * @macro
  175. *
  176. * :macro:`NGHTTP3_ERR_QPACK_DECOMPRESSION_FAILED` indicates that a
  177. * QPACK decompression failed.
  178. */
  179. #define NGHTTP3_ERR_QPACK_DECOMPRESSION_FAILED -401
  180. /**
  181. * @macro
  182. *
  183. * :macro:`NGHTTP3_ERR_QPACK_ENCODER_STREAM_ERROR` indicates that an
  184. * error occurred while reading QPACK encoder stream.
  185. */
  186. #define NGHTTP3_ERR_QPACK_ENCODER_STREAM_ERROR -402
  187. /**
  188. * @macro
  189. *
  190. * :macro:`NGHTTP3_ERR_QPACK_DECODER_STREAM_ERROR` indicates that an
  191. * error occurred while reading QPACK decoder stream.
  192. */
  193. #define NGHTTP3_ERR_QPACK_DECODER_STREAM_ERROR -403
  194. /**
  195. * @macro
  196. *
  197. * :macro:`NGHTTP3_ERR_H3_FRAME_UNEXPECTED` indicates that an
  198. * unexpected HTTP/3 frame is received.
  199. */
  200. #define NGHTTP3_ERR_H3_FRAME_UNEXPECTED -601
  201. /**
  202. * @macro
  203. *
  204. * :macro:`NGHTTP3_ERR_H3_FRAME_ERROR` indicates that an HTTP/3 frame
  205. * is malformed.
  206. */
  207. #define NGHTTP3_ERR_H3_FRAME_ERROR -602
  208. /**
  209. * @macro
  210. *
  211. * :macro:`NGHTTP3_ERR_H3_MISSING_SETTINGS` indicates that an HTTP/3
  212. * SETTINGS frame is missing.
  213. */
  214. #define NGHTTP3_ERR_H3_MISSING_SETTINGS -603
  215. /**
  216. * @macro
  217. *
  218. * :macro:`NGHTTP3_ERR_H3_INTERNAL_ERROR` indicates an internal error.
  219. */
  220. #define NGHTTP3_ERR_H3_INTERNAL_ERROR -604
  221. /**
  222. * @macro
  223. *
  224. * :macro:`NGHTTP3_ERR_H3_CLOSED_CRITICAL_STREAM` indicates that a
  225. * critical stream is closed.
  226. */
  227. #define NGHTTP3_ERR_H3_CLOSED_CRITICAL_STREAM -605
  228. /**
  229. * @macro
  230. *
  231. * :macro:`NGHTTP3_ERR_H3_GENERAL_PROTOCOL_ERROR` indicates a general
  232. * protocol error. This is typically a catch-all error.
  233. */
  234. #define NGHTTP3_ERR_H3_GENERAL_PROTOCOL_ERROR -606
  235. /**
  236. * @macro
  237. *
  238. * :macro:`NGHTTP3_ERR_H3_ID_ERROR` indicates that an ID related error
  239. * occurred.
  240. */
  241. #define NGHTTP3_ERR_H3_ID_ERROR -607
  242. /**
  243. * @macro
  244. *
  245. * :macro:`NGHTTP3_ERR_H3_SETTINGS_ERROR` indicates that an HTTP/3
  246. * SETTINGS frame is malformed.
  247. */
  248. #define NGHTTP3_ERR_H3_SETTINGS_ERROR -608
  249. /**
  250. * @macro
  251. *
  252. * :macro:`NGHTTP3_ERR_H3_STREAM_CREATION_ERROR` indicates that a
  253. * remote endpoint attempts to create a new stream which is not
  254. * allowed.
  255. */
  256. #define NGHTTP3_ERR_H3_STREAM_CREATION_ERROR -609
  257. /**
  258. * @macro
  259. *
  260. * :macro:`NGHTTP3_ERR_FATAL` indicates that error codes less than
  261. * this value is fatal error. When this error is returned, an
  262. * endpoint should drop connection immediately.
  263. */
  264. #define NGHTTP3_ERR_FATAL -900
  265. /**
  266. * @macro
  267. *
  268. * :macro:`NGHTTP3_ERR_NOMEM` indicates out of memory.
  269. */
  270. #define NGHTTP3_ERR_NOMEM -901
  271. /**
  272. * @macro
  273. *
  274. * :macro:`NGHTTP3_ERR_CALLBACK_FAILURE` indicates that user defined
  275. * callback function failed.
  276. */
  277. #define NGHTTP3_ERR_CALLBACK_FAILURE -902
  278. /**
  279. * @macrosection
  280. *
  281. * HTTP/3 application error code
  282. */
  283. /**
  284. * @macro
  285. *
  286. * :macro:`NGHTTP3_H3_NO_ERROR` is HTTP/3 application error code
  287. * ``H3_NO_ERROR``.
  288. */
  289. #define NGHTTP3_H3_NO_ERROR 0x0100
  290. /**
  291. * @macro
  292. *
  293. * :macro:`NGHTTP3_H3_GENERAL_PROTOCOL_ERROR` is HTTP/3 application
  294. * error code ``H3_GENERAL_PROTOCOL_ERROR``.
  295. */
  296. #define NGHTTP3_H3_GENERAL_PROTOCOL_ERROR 0x0101
  297. /**
  298. * @macro
  299. *
  300. * :macro:`NGHTTP3_H3_INTERNAL_ERROR` is HTTP/3 application error code
  301. * ``H3_INTERNAL_ERROR``.
  302. */
  303. #define NGHTTP3_H3_INTERNAL_ERROR 0x0102
  304. /**
  305. * @macro
  306. *
  307. * :macro:`NGHTTP3_H3_STREAM_CREATION_ERROR` is HTTP/3 application
  308. * error code ``H3_STREAM_CREATION_ERROR``.
  309. */
  310. #define NGHTTP3_H3_STREAM_CREATION_ERROR 0x0103
  311. /**
  312. * @macro
  313. *
  314. * :macro:`NGHTTP3_H3_CLOSED_CRITICAL_STREAM` is HTTP/3 application
  315. * error code ``H3_CLOSED_CRITICAL_STREAM``.
  316. */
  317. #define NGHTTP3_H3_CLOSED_CRITICAL_STREAM 0x0104
  318. /**
  319. * @macro
  320. *
  321. * :macro:`NGHTTP3_H3_FRAME_UNEXPECTED` is HTTP/3 application error
  322. * code ``H3_FRAME_UNEXPECTED``.
  323. */
  324. #define NGHTTP3_H3_FRAME_UNEXPECTED 0x0105
  325. /**
  326. * @macro
  327. *
  328. * :macro:`NGHTTP3_H3_FRAME_ERROR` is HTTP/3 application error code
  329. * ``H3_FRAME_ERROR``.
  330. */
  331. #define NGHTTP3_H3_FRAME_ERROR 0x0106
  332. /**
  333. * @macro
  334. *
  335. * :macro:`NGHTTP3_H3_EXCESSIVE_LOAD` is HTTP/3 application error code
  336. * ``H3_EXCESSIVE_LOAD``.
  337. */
  338. #define NGHTTP3_H3_EXCESSIVE_LOAD 0x0107
  339. /**
  340. * @macro
  341. *
  342. * :macro:`NGHTTP3_H3_ID_ERROR` is HTTP/3 application error code
  343. * ``H3_ID_ERROR``.
  344. */
  345. #define NGHTTP3_H3_ID_ERROR 0x0108
  346. /**
  347. * @macro
  348. *
  349. * :macro:`NGHTTP3_H3_SETTINGS_ERROR` is HTTP/3 application error code
  350. * ``H3_SETTINGS_ERROR``.
  351. */
  352. #define NGHTTP3_H3_SETTINGS_ERROR 0x0109
  353. /**
  354. * @macro
  355. *
  356. * :macro:`NGHTTP3_H3_MISSING_SETTINGS` is HTTP/3 application error
  357. * code ``H3_MISSING_SETTINGS``.
  358. */
  359. #define NGHTTP3_H3_MISSING_SETTINGS 0x010a
  360. /**
  361. * @macro
  362. *
  363. * :macro:`NGHTTP3_H3_REQUEST_REJECTED` is HTTP/3 application error
  364. * code ``H3_REQUEST_REJECTED``.
  365. */
  366. #define NGHTTP3_H3_REQUEST_REJECTED 0x010b
  367. /**
  368. * @macro
  369. *
  370. * :macro:`NGHTTP3_H3_REQUEST_CANCELLED` is HTTP/3 application error
  371. * code ``H3_REQUEST_CANCELLED``.
  372. */
  373. #define NGHTTP3_H3_REQUEST_CANCELLED 0x010c
  374. /**
  375. * @macro
  376. *
  377. * :macro:`NGHTTP3_H3_REQUEST_INCOMPLETE` is HTTP/3 application error
  378. * code ``H3_REQUEST_INCOMPLETE``.
  379. */
  380. #define NGHTTP3_H3_REQUEST_INCOMPLETE 0x010d
  381. /**
  382. * @macro
  383. *
  384. * :macro:`NGHTTP3_H3_MESSAGE_ERROR` is HTTP/3 application error code
  385. * ``H3_MESSAGE_ERROR``.
  386. */
  387. #define NGHTTP3_H3_MESSAGE_ERROR 0x010e
  388. /**
  389. * @macro
  390. *
  391. * :macro:`NGHTTP3_H3_CONNECT_ERROR` is HTTP/3 application error code
  392. * ``H3_CONNECT_ERROR``.
  393. */
  394. #define NGHTTP3_H3_CONNECT_ERROR 0x010f
  395. /**
  396. * @macro
  397. *
  398. * :macro:`NGHTTP3_H3_VERSION_FALLBACK` is HTTP/3 application error
  399. * code ``H3_VERSION_FALLBACK``.
  400. */
  401. #define NGHTTP3_H3_VERSION_FALLBACK 0x0110
  402. /**
  403. * @macro
  404. *
  405. * :macro:`NGHTTP3_QPACK_DECOMPRESSION_FAILED` is HTTP/3 application
  406. * error code ``QPACK_DECOMPRESSION_FAILED``.
  407. */
  408. #define NGHTTP3_QPACK_DECOMPRESSION_FAILED 0x0200
  409. /**
  410. * @macro
  411. *
  412. * :macro:`NGHTTP3_QPACK_ENCODER_STREAM_ERROR` is HTTP/3 application
  413. * error code ``QPACK_ENCODER_STREAM_ERROR``.
  414. */
  415. #define NGHTTP3_QPACK_ENCODER_STREAM_ERROR 0x0201
  416. /**
  417. * @macro
  418. *
  419. * :macro:`NGHTTP3_QPACK_DECODER_STREAM_ERROR` is HTTP/3 application
  420. * error code ``QPACK_DECODER_STREAM_ERROR``.
  421. */
  422. #define NGHTTP3_QPACK_DECODER_STREAM_ERROR 0x0202
  423. /**
  424. * @functypedef
  425. *
  426. * :type:`nghttp3_malloc` is a custom memory allocator to replace
  427. * :manpage:`malloc(3)`. The |user_data| is the
  428. * :member:`nghttp3_mem.user_data`.
  429. */
  430. typedef void *(*nghttp3_malloc)(size_t size, void *user_data);
  431. /**
  432. * @functypedef
  433. *
  434. * :type:`nghttp3_free` is a custom memory allocator to replace
  435. * :manpage:`free(3)`. The |user_data| is the
  436. * :member:`nghttp3_mem.user_data`.
  437. */
  438. typedef void (*nghttp3_free)(void *ptr, void *user_data);
  439. /**
  440. * @functypedef
  441. *
  442. * :type:`nghttp3_calloc` is a custom memory allocator to replace
  443. * :manpage:`calloc(3)`. The |user_data| is the
  444. * :member:`nghttp3_mem.user_data`.
  445. */
  446. typedef void *(*nghttp3_calloc)(size_t nmemb, size_t size, void *user_data);
  447. /**
  448. * @functypedef
  449. *
  450. * :type:`nghttp3_realloc` is a custom memory allocator to replace
  451. * :manpage:`realloc(3)`. The |user_data| is the
  452. * :member:`nghttp3_mem.user_data`.
  453. */
  454. typedef void *(*nghttp3_realloc)(void *ptr, size_t size, void *user_data);
  455. /**
  456. * @struct
  457. *
  458. * :type:`nghttp3_mem` is a custom memory allocator functions and user
  459. * defined pointer. The :member:`user_data` field is passed to each
  460. * allocator function. This can be used, for example, to achieve
  461. * per-session memory pool.
  462. *
  463. * In the following example code, ``my_malloc``, ``my_free``,
  464. * ``my_calloc``, and ``my_realloc`` are the replacement of the
  465. * standard allocators :manpage:`malloc(3)`, :manpage:`free(3)`,
  466. * :manpage:`calloc(3)` and :manpage:`realloc(3)` respectively::
  467. *
  468. * void *my_malloc_cb(size_t size, void *user_data) {
  469. * (void)user_data;
  470. * return my_malloc(size);
  471. * }
  472. *
  473. * void my_free_cb(void *ptr, void *user_data) {
  474. * (void)user_data;
  475. * my_free(ptr);
  476. * }
  477. *
  478. * void *my_calloc_cb(size_t nmemb, size_t size, void *user_data) {
  479. * (void)user_data;
  480. * return my_calloc(nmemb, size);
  481. * }
  482. *
  483. * void *my_realloc_cb(void *ptr, size_t size, void *user_data) {
  484. * (void)user_data;
  485. * return my_realloc(ptr, size);
  486. * }
  487. *
  488. * void conn_new() {
  489. * nghttp3_mem mem = {NULL, my_malloc_cb, my_free_cb, my_calloc_cb,
  490. * my_realloc_cb};
  491. *
  492. * ...
  493. * }
  494. */
  495. typedef struct nghttp3_mem {
  496. /**
  497. * :member:`user_data` is an arbitrary user supplied data. This is
  498. * passed to each allocator function.
  499. */
  500. void *user_data;
  501. /**
  502. * :member:`malloc` is a custom allocator function to replace
  503. * :manpage:`malloc(3)`.
  504. */
  505. nghttp3_malloc malloc;
  506. /**
  507. * :member:`free` is a custom allocator function to replace
  508. * :manpage:`free(3)`.
  509. */
  510. nghttp3_free free;
  511. /**
  512. * :member:`calloc` is a custom allocator function to replace
  513. * :manpage:`calloc(3)`.
  514. */
  515. nghttp3_calloc calloc;
  516. /**
  517. * :member:`realloc` is a custom allocator function to replace
  518. * :manpage:`realloc(3)`.
  519. */
  520. nghttp3_realloc realloc;
  521. } nghttp3_mem;
  522. /**
  523. * @function
  524. *
  525. * `nghttp3_mem_default` returns the default memory allocator which
  526. * uses malloc/calloc/realloc/free.
  527. */
  528. NGHTTP3_EXTERN const nghttp3_mem *nghttp3_mem_default(void);
  529. /**
  530. * @struct
  531. *
  532. * :type:`nghttp3_vec` is ``struct iovec`` compatible structure to
  533. * reference arbitrary array of bytes.
  534. */
  535. typedef struct nghttp3_vec {
  536. /**
  537. * :member:`base` points to the data.
  538. */
  539. uint8_t *base;
  540. /**
  541. * :member:`len` is the number of bytes which the buffer pointed by
  542. * :member:`base` contains.
  543. */
  544. size_t len;
  545. } nghttp3_vec;
  546. /**
  547. * @struct
  548. *
  549. * :type:`nghttp3_rcbuf` is the object representing reference counted
  550. * buffer. The details of this structure are intentionally hidden
  551. * from the public API.
  552. */
  553. typedef struct nghttp3_rcbuf nghttp3_rcbuf;
  554. /**
  555. * @function
  556. *
  557. * `nghttp3_rcbuf_incref` increments the reference count of |rcbuf| by
  558. * 1.
  559. */
  560. NGHTTP3_EXTERN void nghttp3_rcbuf_incref(nghttp3_rcbuf *rcbuf);
  561. /**
  562. * @function
  563. *
  564. * `nghttp3_rcbuf_decref` decrements the reference count of |rcbuf| by
  565. * 1. If the reference count becomes zero, the object pointed by
  566. * |rcbuf| will be freed. In this case, application must not use
  567. * |rcbuf| again.
  568. */
  569. NGHTTP3_EXTERN void nghttp3_rcbuf_decref(nghttp3_rcbuf *rcbuf);
  570. /**
  571. * @function
  572. *
  573. * `nghttp3_rcbuf_get_buf` returns the underlying buffer managed by
  574. * |rcbuf|.
  575. */
  576. NGHTTP3_EXTERN nghttp3_vec nghttp3_rcbuf_get_buf(const nghttp3_rcbuf *rcbuf);
  577. /**
  578. * @function
  579. *
  580. * `nghttp3_rcbuf_is_static` returns nonzero if the underlying buffer
  581. * is statically allocated, and 0 otherwise. This can be useful for
  582. * language bindings that wish to avoid creating duplicate strings for
  583. * these buffers.
  584. */
  585. NGHTTP3_EXTERN int nghttp3_rcbuf_is_static(const nghttp3_rcbuf *rcbuf);
  586. /**
  587. * @struct
  588. *
  589. * :type:`nghttp3_buf` is the variable size buffer.
  590. */
  591. typedef struct nghttp3_buf {
  592. /**
  593. * :member:`begin` points to the beginning of the buffer.
  594. */
  595. uint8_t *begin;
  596. /**
  597. * :member:`end` points to the one beyond of the last byte of the
  598. * buffer
  599. */
  600. uint8_t *end;
  601. /**
  602. * :member:`pos` points to the start of data. Typically, this
  603. * points to the address that next data should be read. Initially,
  604. * it points to :member:`begin`.
  605. */
  606. uint8_t *pos;
  607. /**
  608. * :member:`last` points to the one beyond of the last data of the
  609. * buffer. Typically, new data is written at this point.
  610. * Initially, it points to :member:`begin`.
  611. */
  612. uint8_t *last;
  613. } nghttp3_buf;
  614. /**
  615. * @function
  616. *
  617. * `nghttp3_buf_init` initializes empty |buf|.
  618. */
  619. NGHTTP3_EXTERN void nghttp3_buf_init(nghttp3_buf *buf);
  620. /**
  621. * @function
  622. *
  623. * `nghttp3_buf_free` frees resources allocated for |buf| using |mem|
  624. * as memory allocator. :member:`buf->begin <nghttp3_buf.begin>` must
  625. * be a heap buffer allocated by |mem|.
  626. */
  627. NGHTTP3_EXTERN void nghttp3_buf_free(nghttp3_buf *buf, const nghttp3_mem *mem);
  628. /**
  629. * @function
  630. *
  631. * `nghttp3_buf_left` returns the number of additional bytes which can
  632. * be written to the underlying buffer. In other words, it returns
  633. * :member:`buf->end <nghttp3_buf.end>` - :member:`buf->last
  634. * <nghttp3_buf.last>`.
  635. */
  636. NGHTTP3_EXTERN size_t nghttp3_buf_left(const nghttp3_buf *buf);
  637. /**
  638. * @function
  639. *
  640. * `nghttp3_buf_len` returns the number of bytes left to read. In
  641. * other words, it returns :member:`buf->last <nghttp3_buf.last>` -
  642. * :member:`buf->pos <nghttp3_buf.pos>`.
  643. */
  644. NGHTTP3_EXTERN size_t nghttp3_buf_len(const nghttp3_buf *buf);
  645. /**
  646. * @function
  647. *
  648. * `nghttp3_buf_reset` sets :member:`buf->pos <nghttp3_buf.pos>` and
  649. * :member:`buf->last <nghttp3_buf.last>` to :member:`buf->begin
  650. * <nghttp3_buf.begin>`.
  651. */
  652. NGHTTP3_EXTERN void nghttp3_buf_reset(nghttp3_buf *buf);
  653. /**
  654. * @macrosection
  655. *
  656. * Flags for HTTP field name/value pair
  657. */
  658. /**
  659. * @macro
  660. *
  661. * :macro:`NGHTTP3_NV_FLAG_NONE` indicates no flag set.
  662. */
  663. #define NGHTTP3_NV_FLAG_NONE 0x00u
  664. /**
  665. * @macro
  666. *
  667. * :macro:`NGHTTP3_NV_FLAG_NEVER_INDEX` indicates that this name/value
  668. * pair must not be indexed. Other implementation calls this bit as
  669. * "sensitive".
  670. */
  671. #define NGHTTP3_NV_FLAG_NEVER_INDEX 0x01u
  672. /**
  673. * @macro
  674. *
  675. * :macro:`NGHTTP3_NV_FLAG_NO_COPY_NAME` is set solely by application.
  676. * If this flag is set, the library does not make a copy of field
  677. * name. This could improve performance.
  678. */
  679. #define NGHTTP3_NV_FLAG_NO_COPY_NAME 0x02u
  680. /**
  681. * @macro
  682. *
  683. * :macro:`NGHTTP3_NV_FLAG_NO_COPY_VALUE` is set solely by
  684. * application. If this flag is set, the library does not make a copy
  685. * of field value. This could improve performance.
  686. */
  687. #define NGHTTP3_NV_FLAG_NO_COPY_VALUE 0x04u
  688. /**
  689. * @macro
  690. *
  691. * :macro:`NGHTTP3_NV_FLAG_TRY_INDEX` gives a hint to QPACK encoder to
  692. * index an HTTP field which is not indexed by default. This is just
  693. * a hint, and QPACK encoder might not encode the field in various
  694. * reasons.
  695. */
  696. #define NGHTTP3_NV_FLAG_TRY_INDEX 0x08u
  697. /**
  698. * @struct
  699. *
  700. * :type:`nghttp3_nv` is the name/value pair, which mainly used to
  701. * represent HTTP fields.
  702. */
  703. typedef struct nghttp3_nv {
  704. /**
  705. * :member:`name` is the HTTP field name.
  706. */
  707. const uint8_t *name;
  708. /**
  709. * :member:`value` is the HTTP field value.
  710. */
  711. const uint8_t *value;
  712. /**
  713. * :member:`namelen` is the length of the |name|, excluding
  714. * terminating NULL.
  715. */
  716. size_t namelen;
  717. /**
  718. * :member:`valuelen` is the length of the |value|, excluding
  719. * terminating NULL.
  720. */
  721. size_t valuelen;
  722. /**
  723. * :member:`flags` is bitwise OR of one or more of
  724. * :macro:`NGHTTP3_NV_FLAG_* <NGHTTP3_NV_FLAG_NONE>`.
  725. */
  726. uint8_t flags;
  727. } nghttp3_nv;
  728. /* Generated by mkstatichdtbl.py */
  729. /**
  730. * @enum
  731. *
  732. * :type:`nghttp3_qpack_token` defines HTTP field name tokens to
  733. * identify field name quickly. It appears in
  734. * :member:`nghttp3_qpack_nv.token`.
  735. */
  736. typedef enum nghttp3_qpack_token {
  737. /**
  738. * :enum:`NGHTTP3_QPACK_TOKEN__AUTHORITY` is a token for
  739. * ``:authority``.
  740. */
  741. NGHTTP3_QPACK_TOKEN__AUTHORITY = 0,
  742. /**
  743. * :enum:`NGHTTP3_QPACK_TOKEN__PATH` is a token for ``:path``.
  744. */
  745. NGHTTP3_QPACK_TOKEN__PATH = 8,
  746. /**
  747. * :enum:`NGHTTP3_QPACK_TOKEN_AGE` is a token for ``age``.
  748. */
  749. NGHTTP3_QPACK_TOKEN_AGE = 43,
  750. /**
  751. * :enum:`NGHTTP3_QPACK_TOKEN_CONTENT_DISPOSITION` is a token for
  752. * ``content-disposition``.
  753. */
  754. NGHTTP3_QPACK_TOKEN_CONTENT_DISPOSITION = 52,
  755. /**
  756. * :enum:`NGHTTP3_QPACK_TOKEN_CONTENT_LENGTH` is a token for
  757. * ``content-length``.
  758. */
  759. NGHTTP3_QPACK_TOKEN_CONTENT_LENGTH = 55,
  760. /**
  761. * :enum:`NGHTTP3_QPACK_TOKEN_COOKIE` is a token for ``cookie``.
  762. */
  763. NGHTTP3_QPACK_TOKEN_COOKIE = 68,
  764. /**
  765. * :enum:`NGHTTP3_QPACK_TOKEN_DATE` is a token for ``date``.
  766. */
  767. NGHTTP3_QPACK_TOKEN_DATE = 69,
  768. /**
  769. * :enum:`NGHTTP3_QPACK_TOKEN_ETAG` is a token for ``etag``.
  770. */
  771. NGHTTP3_QPACK_TOKEN_ETAG = 71,
  772. /**
  773. * :enum:`NGHTTP3_QPACK_TOKEN_IF_MODIFIED_SINCE` is a token for
  774. * ``if-modified-since``.
  775. */
  776. NGHTTP3_QPACK_TOKEN_IF_MODIFIED_SINCE = 74,
  777. /**
  778. * :enum:`NGHTTP3_QPACK_TOKEN_IF_NONE_MATCH` is a token for
  779. * ``if-none-match``.
  780. */
  781. NGHTTP3_QPACK_TOKEN_IF_NONE_MATCH = 75,
  782. /**
  783. * :enum:`NGHTTP3_QPACK_TOKEN_LAST_MODIFIED` is a token for
  784. * ``last-modified``.
  785. */
  786. NGHTTP3_QPACK_TOKEN_LAST_MODIFIED = 77,
  787. /**
  788. * :enum:`NGHTTP3_QPACK_TOKEN_LINK` is a token for ``link``.
  789. */
  790. NGHTTP3_QPACK_TOKEN_LINK = 78,
  791. /**
  792. * :enum:`NGHTTP3_QPACK_TOKEN_LOCATION` is a token for ``location``.
  793. */
  794. NGHTTP3_QPACK_TOKEN_LOCATION = 79,
  795. /**
  796. * :enum:`NGHTTP3_QPACK_TOKEN_REFERER` is a token for ``referer``.
  797. */
  798. NGHTTP3_QPACK_TOKEN_REFERER = 83,
  799. /**
  800. * :enum:`NGHTTP3_QPACK_TOKEN_SET_COOKIE` is a token for
  801. * ``set-cookie``.
  802. */
  803. NGHTTP3_QPACK_TOKEN_SET_COOKIE = 85,
  804. /**
  805. * :enum:`NGHTTP3_QPACK_TOKEN__METHOD` is a token for ``:method``.
  806. */
  807. NGHTTP3_QPACK_TOKEN__METHOD = 1,
  808. /**
  809. * :enum:`NGHTTP3_QPACK_TOKEN__SCHEME` is a token for ``:scheme``.
  810. */
  811. NGHTTP3_QPACK_TOKEN__SCHEME = 9,
  812. /**
  813. * :enum:`NGHTTP3_QPACK_TOKEN__STATUS` is a token for ``:status``.
  814. */
  815. NGHTTP3_QPACK_TOKEN__STATUS = 11,
  816. /**
  817. * :enum:`NGHTTP3_QPACK_TOKEN_ACCEPT` is a token for ``accept``.
  818. */
  819. NGHTTP3_QPACK_TOKEN_ACCEPT = 25,
  820. /**
  821. * :enum:`NGHTTP3_QPACK_TOKEN_ACCEPT_ENCODING` is a token for
  822. * ``accept-encoding``.
  823. */
  824. NGHTTP3_QPACK_TOKEN_ACCEPT_ENCODING = 27,
  825. /**
  826. * :enum:`NGHTTP3_QPACK_TOKEN_ACCEPT_RANGES` is a token for
  827. * ``accept-ranges``.
  828. */
  829. NGHTTP3_QPACK_TOKEN_ACCEPT_RANGES = 29,
  830. /**
  831. * :enum:`NGHTTP3_QPACK_TOKEN_ACCESS_CONTROL_ALLOW_HEADERS` is a
  832. * token for ``access-control-allow-headers``.
  833. */
  834. NGHTTP3_QPACK_TOKEN_ACCESS_CONTROL_ALLOW_HEADERS = 32,
  835. /**
  836. * :enum:`NGHTTP3_QPACK_TOKEN_ACCESS_CONTROL_ALLOW_ORIGIN` is a
  837. * token for ``access-control-allow-origin``.
  838. */
  839. NGHTTP3_QPACK_TOKEN_ACCESS_CONTROL_ALLOW_ORIGIN = 38,
  840. /**
  841. * :enum:`NGHTTP3_QPACK_TOKEN_CACHE_CONTROL` is a token for
  842. * ``cache-control``.
  843. */
  844. NGHTTP3_QPACK_TOKEN_CACHE_CONTROL = 46,
  845. /**
  846. * :enum:`NGHTTP3_QPACK_TOKEN_CONTENT_ENCODING` is a token for
  847. * ``content-encoding``.
  848. */
  849. NGHTTP3_QPACK_TOKEN_CONTENT_ENCODING = 53,
  850. /**
  851. * :enum:`NGHTTP3_QPACK_TOKEN_CONTENT_TYPE` is a token for
  852. * ``content-type``.
  853. */
  854. NGHTTP3_QPACK_TOKEN_CONTENT_TYPE = 57,
  855. /**
  856. * :enum:`NGHTTP3_QPACK_TOKEN_RANGE` is a token for ``range``.
  857. */
  858. NGHTTP3_QPACK_TOKEN_RANGE = 82,
  859. /**
  860. * :enum:`NGHTTP3_QPACK_TOKEN_STRICT_TRANSPORT_SECURITY` is a token
  861. * for ``strict-transport-security``.
  862. */
  863. NGHTTP3_QPACK_TOKEN_STRICT_TRANSPORT_SECURITY = 86,
  864. /**
  865. * :enum:`NGHTTP3_QPACK_TOKEN_VARY` is a token for ``vary``.
  866. */
  867. NGHTTP3_QPACK_TOKEN_VARY = 92,
  868. /**
  869. * :enum:`NGHTTP3_QPACK_TOKEN_X_CONTENT_TYPE_OPTIONS` is a token for
  870. * ``x-content-type-options``.
  871. */
  872. NGHTTP3_QPACK_TOKEN_X_CONTENT_TYPE_OPTIONS = 94,
  873. /**
  874. * :enum:`NGHTTP3_QPACK_TOKEN_X_XSS_PROTECTION` is a token for
  875. * ``x-xss-protection``.
  876. */
  877. NGHTTP3_QPACK_TOKEN_X_XSS_PROTECTION = 98,
  878. /**
  879. * :enum:`NGHTTP3_QPACK_TOKEN_ACCEPT_LANGUAGE` is a token for
  880. * ``accept-language``.
  881. */
  882. NGHTTP3_QPACK_TOKEN_ACCEPT_LANGUAGE = 28,
  883. /**
  884. * :enum:`NGHTTP3_QPACK_TOKEN_ACCESS_CONTROL_ALLOW_CREDENTIALS` is a
  885. * token for ``access-control-allow-credentials``.
  886. */
  887. NGHTTP3_QPACK_TOKEN_ACCESS_CONTROL_ALLOW_CREDENTIALS = 30,
  888. /**
  889. * :enum:`NGHTTP3_QPACK_TOKEN_ACCESS_CONTROL_ALLOW_METHODS` is a
  890. * token for ``access-control-allow-methods``.
  891. */
  892. NGHTTP3_QPACK_TOKEN_ACCESS_CONTROL_ALLOW_METHODS = 35,
  893. /**
  894. * :enum:`NGHTTP3_QPACK_TOKEN_ACCESS_CONTROL_EXPOSE_HEADERS` is a
  895. * token for ``access-control-expose-headers``.
  896. */
  897. NGHTTP3_QPACK_TOKEN_ACCESS_CONTROL_EXPOSE_HEADERS = 39,
  898. /**
  899. * :enum:`NGHTTP3_QPACK_TOKEN_ACCESS_CONTROL_REQUEST_HEADERS` is a
  900. * token for ``access-control-request-headers``.
  901. */
  902. NGHTTP3_QPACK_TOKEN_ACCESS_CONTROL_REQUEST_HEADERS = 40,
  903. /**
  904. * :enum:`NGHTTP3_QPACK_TOKEN_ACCESS_CONTROL_REQUEST_METHOD` is a
  905. * token for ``access-control-request-method``.
  906. */
  907. NGHTTP3_QPACK_TOKEN_ACCESS_CONTROL_REQUEST_METHOD = 41,
  908. /**
  909. * :enum:`NGHTTP3_QPACK_TOKEN_ALT_SVC` is a token for ``alt-svc``.
  910. */
  911. NGHTTP3_QPACK_TOKEN_ALT_SVC = 44,
  912. /**
  913. * :enum:`NGHTTP3_QPACK_TOKEN_AUTHORIZATION` is a token for
  914. * ``authorization``.
  915. */
  916. NGHTTP3_QPACK_TOKEN_AUTHORIZATION = 45,
  917. /**
  918. * :enum:`NGHTTP3_QPACK_TOKEN_CONTENT_SECURITY_POLICY` is a token
  919. * for ``content-security-policy``.
  920. */
  921. NGHTTP3_QPACK_TOKEN_CONTENT_SECURITY_POLICY = 56,
  922. /**
  923. * :enum:`NGHTTP3_QPACK_TOKEN_EARLY_DATA` is a token for
  924. * ``early-data``.
  925. */
  926. NGHTTP3_QPACK_TOKEN_EARLY_DATA = 70,
  927. /**
  928. * :enum:`NGHTTP3_QPACK_TOKEN_EXPECT_CT` is a token for
  929. * ``expect-ct``.
  930. */
  931. NGHTTP3_QPACK_TOKEN_EXPECT_CT = 72,
  932. /**
  933. * :enum:`NGHTTP3_QPACK_TOKEN_FORWARDED` is a token for
  934. * ``forwarded``.
  935. */
  936. NGHTTP3_QPACK_TOKEN_FORWARDED = 73,
  937. /**
  938. * :enum:`NGHTTP3_QPACK_TOKEN_IF_RANGE` is a token for ``if-range``.
  939. */
  940. NGHTTP3_QPACK_TOKEN_IF_RANGE = 76,
  941. /**
  942. * :enum:`NGHTTP3_QPACK_TOKEN_ORIGIN` is a token for ``origin``.
  943. */
  944. NGHTTP3_QPACK_TOKEN_ORIGIN = 80,
  945. /**
  946. * :enum:`NGHTTP3_QPACK_TOKEN_PURPOSE` is a token for ``purpose``.
  947. */
  948. NGHTTP3_QPACK_TOKEN_PURPOSE = 81,
  949. /**
  950. * :enum:`NGHTTP3_QPACK_TOKEN_SERVER` is a token for ``server``.
  951. */
  952. NGHTTP3_QPACK_TOKEN_SERVER = 84,
  953. /**
  954. * :enum:`NGHTTP3_QPACK_TOKEN_TIMING_ALLOW_ORIGIN` is a token for
  955. * ``timing-allow-origin``.
  956. */
  957. NGHTTP3_QPACK_TOKEN_TIMING_ALLOW_ORIGIN = 89,
  958. /**
  959. * :enum:`NGHTTP3_QPACK_TOKEN_UPGRADE_INSECURE_REQUESTS` is a token
  960. * for ``upgrade-insecure-requests``.
  961. */
  962. NGHTTP3_QPACK_TOKEN_UPGRADE_INSECURE_REQUESTS = 90,
  963. /**
  964. * :enum:`NGHTTP3_QPACK_TOKEN_USER_AGENT` is a token for
  965. * ``user-agent``.
  966. */
  967. NGHTTP3_QPACK_TOKEN_USER_AGENT = 91,
  968. /**
  969. * :enum:`NGHTTP3_QPACK_TOKEN_X_FORWARDED_FOR` is a token for
  970. * ``x-forwarded-for``.
  971. */
  972. NGHTTP3_QPACK_TOKEN_X_FORWARDED_FOR = 95,
  973. /**
  974. * :enum:`NGHTTP3_QPACK_TOKEN_X_FRAME_OPTIONS` is a token for
  975. * ``x-frame-options``.
  976. */
  977. NGHTTP3_QPACK_TOKEN_X_FRAME_OPTIONS = 96,
  978. /* Additional HTTP fields for HTTP messaging validation */
  979. /**
  980. * :enum:`NGHTTP3_QPACK_TOKEN_HOST` is a token for ``host``.
  981. */
  982. NGHTTP3_QPACK_TOKEN_HOST = 1000,
  983. /**
  984. * :enum:`NGHTTP3_QPACK_TOKEN_CONNECTION` is a token for
  985. * ``connection``.
  986. */
  987. NGHTTP3_QPACK_TOKEN_CONNECTION,
  988. /**
  989. * :enum:`NGHTTP3_QPACK_TOKEN_KEEP_ALIVE` is a token for
  990. * ``keep-alive``.
  991. */
  992. NGHTTP3_QPACK_TOKEN_KEEP_ALIVE,
  993. /**
  994. * :enum:`NGHTTP3_QPACK_TOKEN_PROXY_CONNECTION` is a token for
  995. * ``proxy-connection``.
  996. */
  997. NGHTTP3_QPACK_TOKEN_PROXY_CONNECTION,
  998. /**
  999. * :enum:`NGHTTP3_QPACK_TOKEN_TRANSFER_ENCODING` is a token for
  1000. * ``transfer-encoding``.
  1001. */
  1002. NGHTTP3_QPACK_TOKEN_TRANSFER_ENCODING,
  1003. /**
  1004. * :enum:`NGHTTP3_QPACK_TOKEN_UPGRADE` is a token for ``upgrade``.
  1005. */
  1006. NGHTTP3_QPACK_TOKEN_UPGRADE,
  1007. /**
  1008. * :enum:`NGHTTP3_QPACK_TOKEN_TE` is a token for ``te``.
  1009. */
  1010. NGHTTP3_QPACK_TOKEN_TE,
  1011. /**
  1012. * :enum:`NGHTTP3_QPACK_TOKEN__PROTOCOL` is a token for
  1013. * ``:protocol``.
  1014. */
  1015. NGHTTP3_QPACK_TOKEN__PROTOCOL,
  1016. /**
  1017. * :enum:`NGHTTP3_QPACK_TOKEN_PRIORITY` is a token for ``priority``.
  1018. */
  1019. NGHTTP3_QPACK_TOKEN_PRIORITY
  1020. } nghttp3_qpack_token;
  1021. /**
  1022. * @struct
  1023. *
  1024. * :type:`nghttp3_qpack_nv` represents HTTP field name/value pair just
  1025. * like :type:`nghttp3_nv`. It is an extended version of
  1026. * :type:`nghttp3_nv`, and has reference counted buffers and tokens.
  1027. */
  1028. typedef struct nghttp3_qpack_nv {
  1029. /**
  1030. * :member:`name` is the buffer containing HTTP field name.
  1031. * NULL-termination is guaranteed.
  1032. */
  1033. nghttp3_rcbuf *name;
  1034. /**
  1035. * :member:`value` is the buffer containing HTTP field value.
  1036. * NULL-termination is guaranteed.
  1037. */
  1038. nghttp3_rcbuf *value;
  1039. /**
  1040. * :member:`token` is :type:`nghttp3_qpack_token` value of
  1041. * :member:`name`. It could be -1 if we have no token for that HTTP
  1042. * field name.
  1043. */
  1044. int32_t token;
  1045. /**
  1046. * :member:`flags` is a bitwise OR of one or more of
  1047. * :macro:`NGHTTP3_NV_FLAG_* <NGHTTP3_NV_FLAG_NONE>`.
  1048. */
  1049. uint8_t flags;
  1050. } nghttp3_qpack_nv;
  1051. /**
  1052. * @struct
  1053. *
  1054. * :type:`nghttp3_qpack_encoder` is QPACK encoder. The details of
  1055. * this structure are intentionally hidden from the public API.
  1056. */
  1057. typedef struct nghttp3_qpack_encoder nghttp3_qpack_encoder;
  1058. /**
  1059. * @function
  1060. *
  1061. * `nghttp3_qpack_encoder_new` initializes QPACK encoder. |pencoder|
  1062. * must be non-NULL pointer. |hard_max_dtable_capacity| is the upper
  1063. * bound of the dynamic table capacity. |mem| is a memory allocator.
  1064. * This function allocates memory for :type:`nghttp3_qpack_encoder`
  1065. * itself, and assigns its pointer to |*pencoder| if it succeeds.
  1066. *
  1067. * The maximum dynamic table capacity is still 0. In order to change
  1068. * the maximum dynamic table capacity, call
  1069. * `nghttp3_qpack_encoder_set_max_dtable_capacity`.
  1070. *
  1071. * This function returns 0 if it succeeds, or one of the following
  1072. * negative error codes:
  1073. *
  1074. * :macro:`NGHTTP3_ERR_NOMEM`
  1075. * Out of memory.
  1076. */
  1077. NGHTTP3_EXTERN int nghttp3_qpack_encoder_new(nghttp3_qpack_encoder **pencoder,
  1078. size_t hard_max_dtable_capacity,
  1079. const nghttp3_mem *mem);
  1080. /**
  1081. * @function
  1082. *
  1083. * `nghttp3_qpack_encoder_del` frees memory allocated for |encoder|.
  1084. * This function also frees memory pointed by |encoder| itself. This
  1085. * function does nothing if |encoder| is NULL.
  1086. */
  1087. NGHTTP3_EXTERN void nghttp3_qpack_encoder_del(nghttp3_qpack_encoder *encoder);
  1088. /**
  1089. * @function
  1090. *
  1091. * `nghttp3_qpack_encoder_encode` encodes the list of HTTP fields
  1092. * |nva|. |nvlen| is the length of |nva|. |stream_id| is the
  1093. * identifier of the stream which these HTTP fields belong to. This
  1094. * function writes field section prefix, encoded HTTP field section,
  1095. * and encoder stream to |pbuf|, |rbuf|, and |ebuf| respectively.
  1096. * Each :member:`nghttp3_buf.last` will be adjusted when data is
  1097. * written. An application should write |pbuf| and |rbuf| to the
  1098. * request stream in this order.
  1099. *
  1100. * The buffer pointed by |pbuf|, |rbuf|, and |ebuf| can be empty
  1101. * buffer. It is fine to pass a buffer initialized by
  1102. * `nghttp3_buf_init(buf) <nghttp3_buf_init>`. This function
  1103. * allocates memory for these buffers as necessary. In particular, it
  1104. * frees and expands buffer if the current capacity of buffer is not
  1105. * enough. If :member:`nghttp3_buf.begin` of any buffer is not NULL,
  1106. * it must be allocated by the same memory allocator passed to
  1107. * `nghttp3_qpack_encoder_new`.
  1108. *
  1109. * This function returns 0 if it succeeds, or one of the following
  1110. * negative error codes:
  1111. *
  1112. * :macro:`NGHTTP3_ERR_NOMEM`
  1113. * Out of memory
  1114. * :macro:`NGHTTP3_ERR_QPACK_FATAL`
  1115. * |encoder| is in unrecoverable error state, and cannot be used
  1116. * anymore.
  1117. */
  1118. NGHTTP3_EXTERN int nghttp3_qpack_encoder_encode(
  1119. nghttp3_qpack_encoder *encoder, nghttp3_buf *pbuf, nghttp3_buf *rbuf,
  1120. nghttp3_buf *ebuf, int64_t stream_id, const nghttp3_nv *nva, size_t nvlen);
  1121. /**
  1122. * @function
  1123. *
  1124. * `nghttp3_qpack_encoder_read_decoder` reads decoder stream. The
  1125. * buffer pointed by |src| of length |srclen| contains decoder stream.
  1126. *
  1127. * This function returns the number of bytes read, or one of the
  1128. * following negative error codes:
  1129. *
  1130. * :macro:`NGHTTP3_ERR_NOMEM`
  1131. * Out of memory
  1132. * :macro:`NGHTTP3_ERR_QPACK_FATAL`
  1133. * |encoder| is in unrecoverable error state, and cannot be used
  1134. * anymore.
  1135. * :macro:`NGHTTP3_ERR_QPACK_DECODER_STREAM`
  1136. * |encoder| is unable to process input because it is malformed.
  1137. */
  1138. NGHTTP3_EXTERN nghttp3_ssize nghttp3_qpack_encoder_read_decoder(
  1139. nghttp3_qpack_encoder *encoder, const uint8_t *src, size_t srclen);
  1140. /**
  1141. * @function
  1142. *
  1143. * `nghttp3_qpack_encoder_set_max_dtable_capacity` sets max dynamic
  1144. * table capacity to |max_dtable_capacity|. If |max_dtable_capacity|
  1145. * is larger than ``hard_max_dtable_capacity`` parameter of
  1146. * `nghttp3_qpack_encoder_new`, it is truncated to the latter.
  1147. */
  1148. NGHTTP3_EXTERN void
  1149. nghttp3_qpack_encoder_set_max_dtable_capacity(nghttp3_qpack_encoder *encoder,
  1150. size_t max_dtable_capacity);
  1151. /**
  1152. * @function
  1153. *
  1154. * `nghttp3_qpack_encoder_set_max_blocked_streams` sets the number of
  1155. * streams which can be blocked to |max_blocked_streams|.
  1156. */
  1157. NGHTTP3_EXTERN void
  1158. nghttp3_qpack_encoder_set_max_blocked_streams(nghttp3_qpack_encoder *encoder,
  1159. size_t max_blocked_streams);
  1160. /**
  1161. * @function
  1162. *
  1163. * `nghttp3_qpack_encoder_ack_everything` tells |encoder| that all
  1164. * encoded HTTP field sections are acknowledged. This function is
  1165. * provided for debugging purpose only. In HTTP/3, |encoder| knows
  1166. * this by reading decoder stream with
  1167. * `nghttp3_qpack_encoder_read_decoder`.
  1168. */
  1169. NGHTTP3_EXTERN void
  1170. nghttp3_qpack_encoder_ack_everything(nghttp3_qpack_encoder *encoder);
  1171. /**
  1172. * @function
  1173. *
  1174. * `nghttp3_qpack_encoder_get_num_blocked_streams` returns the number
  1175. * of streams which are potentially blocked at decoder side.
  1176. */
  1177. NGHTTP3_EXTERN size_t
  1178. nghttp3_qpack_encoder_get_num_blocked_streams(nghttp3_qpack_encoder *encoder);
  1179. /**
  1180. * @struct
  1181. *
  1182. * :type:`nghttp3_qpack_stream_context` is a decoder context for an
  1183. * individual stream. Its state is per HTTP field section. In order
  1184. * to reuse this object for another HTTP field section, call
  1185. * `nghttp3_qpack_stream_context_reset`. The details of this
  1186. * structure are intentionally hidden from the public API.
  1187. */
  1188. typedef struct nghttp3_qpack_stream_context nghttp3_qpack_stream_context;
  1189. /**
  1190. * @function
  1191. *
  1192. * `nghttp3_qpack_stream_context_new` initializes stream context.
  1193. * |psctx| must be non-NULL pointer. |stream_id| is stream ID. |mem|
  1194. * is a memory allocator. This function allocates memory for
  1195. * :type:`nghttp3_qpack_stream_context` itself, and assigns its
  1196. * pointer to |*psctx| if it succeeds.
  1197. *
  1198. * This function returns 0 if it succeeds, or one of the following
  1199. * negative error codes:
  1200. *
  1201. * :macro:`NGHTTP3_ERR_NOMEM`
  1202. * Out of memory.
  1203. */
  1204. NGHTTP3_EXTERN int
  1205. nghttp3_qpack_stream_context_new(nghttp3_qpack_stream_context **psctx,
  1206. int64_t stream_id, const nghttp3_mem *mem);
  1207. /**
  1208. * @function
  1209. *
  1210. * `nghttp3_qpack_stream_context_del` frees memory allocated for
  1211. * |sctx|. This function frees memory pointed by |sctx| itself. This
  1212. * function does nothing if |sctx| is NULL.
  1213. */
  1214. NGHTTP3_EXTERN void
  1215. nghttp3_qpack_stream_context_del(nghttp3_qpack_stream_context *sctx);
  1216. /**
  1217. * @function
  1218. *
  1219. * `nghttp3_qpack_stream_context_get_ricnt` returns required insert
  1220. * count.
  1221. */
  1222. NGHTTP3_EXTERN uint64_t
  1223. nghttp3_qpack_stream_context_get_ricnt(nghttp3_qpack_stream_context *sctx);
  1224. /**
  1225. * @function
  1226. *
  1227. * `nghttp3_qpack_stream_context_reset` resets the state of |sctx|.
  1228. * Then it can be reused for decoding an another HTTP field section in
  1229. * the same stream.
  1230. */
  1231. NGHTTP3_EXTERN
  1232. void nghttp3_qpack_stream_context_reset(nghttp3_qpack_stream_context *sctx);
  1233. /**
  1234. * @struct
  1235. *
  1236. * :type:`nghttp3_qpack_decoder` is QPACK decoder. The details of
  1237. * this structure are intentionally hidden from the public API.
  1238. */
  1239. typedef struct nghttp3_qpack_decoder nghttp3_qpack_decoder;
  1240. /**
  1241. * @function
  1242. *
  1243. * `nghttp3_qpack_decoder_new` initializes QPACK decoder. |pdecoder|
  1244. * must be non-NULL pointer. |hard_max_dtable_capacity| is the upper
  1245. * bound of the dynamic table capacity. |max_blocked_streams| is the
  1246. * maximum number of streams which can be blocked. |mem| is a memory
  1247. * allocator. This function allocates memory for
  1248. * :type:`nghttp3_qpack_decoder` itself, and assigns its pointer to
  1249. * |*pdecoder| if it succeeds.
  1250. *
  1251. * This function returns 0 if it succeeds, or one of the following
  1252. * negative error codes:
  1253. *
  1254. * :macro:`NGHTTP3_ERR_NOMEM`
  1255. * Out of memory.
  1256. */
  1257. NGHTTP3_EXTERN int nghttp3_qpack_decoder_new(nghttp3_qpack_decoder **pdecoder,
  1258. size_t hard_max_dtable_capacity,
  1259. size_t max_blocked_streams,
  1260. const nghttp3_mem *mem);
  1261. /**
  1262. * @function
  1263. *
  1264. * `nghttp3_qpack_decoder_del` frees memory allocated for |decoder|.
  1265. * This function frees memory pointed by |decoder| itself. This
  1266. * function does nothing if |decoder| is NULL.
  1267. */
  1268. NGHTTP3_EXTERN void nghttp3_qpack_decoder_del(nghttp3_qpack_decoder *decoder);
  1269. /**
  1270. * @function
  1271. *
  1272. * `nghttp3_qpack_decoder_read_encoder` reads encoder stream. The
  1273. * buffer pointed by |src| of length |srclen| contains encoder stream.
  1274. *
  1275. * This function returns the number of bytes read, or one of the
  1276. * following negative error codes:
  1277. *
  1278. * :macro:`NGHTTP3_ERR_NOMEM`
  1279. * Out of memory.
  1280. * :macro:`NGHTTP3_ERR_QPACK_FATAL`
  1281. * |decoder| is in unrecoverable error state, and cannot be used
  1282. * anymore.
  1283. * :macro:`NGHTTP3_ERR_QPACK_ENCODER_STREAM`
  1284. * Could not interpret encoder stream instruction.
  1285. */
  1286. NGHTTP3_EXTERN nghttp3_ssize nghttp3_qpack_decoder_read_encoder(
  1287. nghttp3_qpack_decoder *decoder, const uint8_t *src, size_t srclen);
  1288. /**
  1289. * @function
  1290. *
  1291. * `nghttp3_qpack_decoder_get_icnt` returns insert count.
  1292. */
  1293. NGHTTP3_EXTERN uint64_t
  1294. nghttp3_qpack_decoder_get_icnt(const nghttp3_qpack_decoder *decoder);
  1295. /**
  1296. * @macrosection
  1297. *
  1298. * Flags for QPACK decoder
  1299. */
  1300. /**
  1301. * @macro
  1302. *
  1303. * :macro:`NGHTTP3_QPACK_DECODE_FLAG_NONE` indicates that no flag set.
  1304. */
  1305. #define NGHTTP3_QPACK_DECODE_FLAG_NONE 0x00u
  1306. /**
  1307. * @macro
  1308. *
  1309. * :macro:`NGHTTP3_QPACK_DECODE_FLAG_EMIT` indicates that an HTTP
  1310. * field is successfully decoded.
  1311. */
  1312. #define NGHTTP3_QPACK_DECODE_FLAG_EMIT 0x01u
  1313. /**
  1314. * @macro
  1315. *
  1316. * :macro:`NGHTTP3_QPACK_DECODE_FLAG_FINAL` indicates that an entire
  1317. * HTTP field section has been decoded.
  1318. */
  1319. #define NGHTTP3_QPACK_DECODE_FLAG_FINAL 0x02u
  1320. /**
  1321. * @macro
  1322. *
  1323. * :macro:`NGHTTP3_QPACK_DECODE_FLAG_BLOCKED` indicates that decoding
  1324. * has been blocked.
  1325. */
  1326. #define NGHTTP3_QPACK_DECODE_FLAG_BLOCKED 0x04u
  1327. /**
  1328. * @function
  1329. *
  1330. * `nghttp3_qpack_decoder_read_request` reads request stream. The
  1331. * request stream is given as the buffer pointed by |src| of length
  1332. * |srclen|. |sctx| is the stream context, and it must be created by
  1333. * `nghttp3_qpack_stream_context_new`. |*pflags| must be non-NULL
  1334. * pointer. |nv| must be non-NULL pointer.
  1335. *
  1336. * If this function succeeds, it assigns flags to |*pflags|. If
  1337. * |*pflags| has :macro:`NGHTTP3_QPACK_DECODE_FLAG_EMIT` set, a
  1338. * decoded HTTP field is assigned to |nv|. If |*pflags| has
  1339. * :macro:`NGHTTP3_QPACK_DECODE_FLAG_FINAL` set, an entire HTTP field
  1340. * section has been successfully decoded. If |*pflags| has
  1341. * :macro:`NGHTTP3_QPACK_DECODE_FLAG_BLOCKED` set, decoding is blocked
  1342. * due to required insert count.
  1343. *
  1344. * When an HTTP field is decoded, an application receives it in |nv|.
  1345. * :member:`nv->name <nghttp3_qpack_nv.name>` and :member:`nv->value
  1346. * <nghttp3_qpack_nv.value>` are reference counted buffer, and their
  1347. * reference counts are already incremented for application use.
  1348. * Therefore, when application finishes processing |nv|, it must call
  1349. * `nghttp3_rcbuf_decref(nv->name) <nghttp3_rcbuf_decref>` and
  1350. * `nghttp3_rcbuf_decref(nv->value) <nghttp3_rcbuf_decref>`, or memory
  1351. * leak might occur. These :type:`nghttp3_rcbuf` objects hold the
  1352. * pointer to :type:`nghttp3_mem` that is passed to
  1353. * `nghttp3_qpack_decoder_new` (or either `nghttp3_conn_client_new` or
  1354. * `nghttp3_conn_server_new` if it is used indirectly). As long as
  1355. * these objects are alive, the pointed :type:`nghttp3_mem` object
  1356. * must be available. Otherwise, `nghttp3_rcbuf_decref` will cause
  1357. * undefined behavior.
  1358. *
  1359. * This function returns the number of bytes read, or one of the
  1360. * following negative error codes:
  1361. *
  1362. * :macro:`NGHTTP3_ERR_NOMEM`
  1363. * Out of memory.
  1364. * :macro:`NGHTTP3_ERR_QPACK_FATAL`
  1365. * |decoder| is in unrecoverable error state, and cannot be used
  1366. * anymore.
  1367. * :macro:`NGHTTP3_ERR_QPACK_DECOMPRESSION_FAILED`
  1368. * Could not interpret field line representations.
  1369. * :macro:`NGHTTP3_ERR_QPACK_HEADER_TOO_LARGE`
  1370. * HTTP field is too large.
  1371. */
  1372. NGHTTP3_EXTERN nghttp3_ssize nghttp3_qpack_decoder_read_request(
  1373. nghttp3_qpack_decoder *decoder, nghttp3_qpack_stream_context *sctx,
  1374. nghttp3_qpack_nv *nv, uint8_t *pflags, const uint8_t *src, size_t srclen,
  1375. int fin);
  1376. /**
  1377. * @function
  1378. *
  1379. * `nghttp3_qpack_decoder_write_decoder` writes decoder stream into
  1380. * |dbuf|.
  1381. *
  1382. * The caller must ensure that `nghttp3_buf_left(dbuf)
  1383. * <nghttp3_buf_left>` >=
  1384. * `nghttp3_qpack_decoder_get_decoder_streamlen(decoder)
  1385. * <nghttp3_qpack_decoder_get_decoder_streamlen>`.
  1386. */
  1387. NGHTTP3_EXTERN void
  1388. nghttp3_qpack_decoder_write_decoder(nghttp3_qpack_decoder *decoder,
  1389. nghttp3_buf *dbuf);
  1390. /**
  1391. * @function
  1392. *
  1393. * `nghttp3_qpack_decoder_get_decoder_streamlen` returns the length of
  1394. * decoder stream that is currently pending.
  1395. */
  1396. NGHTTP3_EXTERN size_t
  1397. nghttp3_qpack_decoder_get_decoder_streamlen(nghttp3_qpack_decoder *decoder);
  1398. /**
  1399. * @function
  1400. *
  1401. * `nghttp3_qpack_decoder_cancel_stream` cancels HTTP field section
  1402. * decoding for stream denoted by |stream_id|.
  1403. *
  1404. * This function returns 0 if it succeeds, or one of the following
  1405. * negative error codes:
  1406. *
  1407. * :macro:`NGHTTP3_ERR_NOMEM`
  1408. * Out of memory.
  1409. * :macro:`NGHTTP3_ERR_QPACK_FATAL`
  1410. * Decoder stream overflow.
  1411. */
  1412. NGHTTP3_EXTERN int
  1413. nghttp3_qpack_decoder_cancel_stream(nghttp3_qpack_decoder *decoder,
  1414. int64_t stream_id);
  1415. /**
  1416. * @function
  1417. *
  1418. * `nghttp3_qpack_decoder_set_max_dtable_capacity` sets
  1419. * |max_dtable_capacity| as maximum dynamic table size.
  1420. * |max_dtable_capacity| must be equal to, or smaller than
  1421. * ``hard_max_dtable_capacity`` parameter of
  1422. * `nghttp3_qpack_decoder_new`. Normally, the maximum capacity is
  1423. * communicated in encoder stream. This function is provided for
  1424. * debugging and testing purpose.
  1425. *
  1426. * This function returns 0 if it succeeds, or one of the following
  1427. * negative error codes:
  1428. *
  1429. * :macro:`NGHTTP3_ERR_INVALID_ARGUMENT`
  1430. * |max_dtable_capacity| exceeds the upper bound of the dynamic
  1431. * table capacity.
  1432. */
  1433. NGHTTP3_EXTERN int
  1434. nghttp3_qpack_decoder_set_max_dtable_capacity(nghttp3_qpack_decoder *decoder,
  1435. size_t max_dtable_capacity);
  1436. /**
  1437. * @function
  1438. *
  1439. * `nghttp3_qpack_decoder_set_max_concurrent_streams` tells |decoder|
  1440. * the maximum number of concurrent streams that a remote endpoint can
  1441. * open, including both bidirectional and unidirectional streams which
  1442. * potentially receive QPACK encoded HEADERS frame. This value is
  1443. * used as a hint to limit the length of decoder stream.
  1444. */
  1445. NGHTTP3_EXTERN void
  1446. nghttp3_qpack_decoder_set_max_concurrent_streams(nghttp3_qpack_decoder *decoder,
  1447. size_t max_concurrent_streams);
  1448. /**
  1449. * @function
  1450. *
  1451. * `nghttp3_strerror` returns textual representation of |liberr|.
  1452. */
  1453. NGHTTP3_EXTERN const char *nghttp3_strerror(int liberr);
  1454. /**
  1455. * @function
  1456. *
  1457. * `nghttp3_err_infer_quic_app_error_code` returns a QUIC application
  1458. * error code which corresponds to |liberr|.
  1459. */
  1460. NGHTTP3_EXTERN uint64_t nghttp3_err_infer_quic_app_error_code(int liberr);
  1461. /**
  1462. * @functypedef
  1463. *
  1464. * :type:`nghttp3_debug_vprintf_callback` is a callback function
  1465. * invoked when the library outputs debug logging. The function is
  1466. * called with arguments suitable for :manpage:`vfprintf(3)`.
  1467. *
  1468. * The debug output is only enabled if the library is built with
  1469. * :macro:`DEBUGBUILD` macro defined.
  1470. */
  1471. typedef void (*nghttp3_debug_vprintf_callback)(const char *format,
  1472. va_list args);
  1473. /**
  1474. * @function
  1475. *
  1476. * `nghttp3_set_debug_vprintf_callback` sets a debug output callback
  1477. * called by the library when built with :macro:`DEBUGBUILD` macro
  1478. * defined. If a callback function is not set by this function, debug
  1479. * log is written into standard error output.
  1480. *
  1481. * For builds without :macro:`DEBUGBUILD` macro defined, this function
  1482. * is noop.
  1483. *
  1484. * Note that building with :macro:`DEBUGBUILD` may cause significant
  1485. * performance penalty to libnghttp3 because of extra processing. It
  1486. * should be used for debugging purpose only.
  1487. *
  1488. * .. Warning::
  1489. *
  1490. * Building with :macro:`DEBUGBUILD` may cause significant
  1491. * performance penalty to libnghttp3 because of extra processing.
  1492. * It should be used for debugging purpose only. We write this two
  1493. * times because this is important.
  1494. */
  1495. NGHTTP3_EXTERN void nghttp3_set_debug_vprintf_callback(
  1496. nghttp3_debug_vprintf_callback debug_vprintf_callback);
  1497. /**
  1498. * @macrosection
  1499. *
  1500. * Shutdown related constants
  1501. */
  1502. /**
  1503. * @macro
  1504. *
  1505. * :macro:`NGHTTP3_SHUTDOWN_NOTICE_STREAM_ID` specifies stream ID sent
  1506. * by a server when it initiates graceful shutdown of the connection
  1507. * via `nghttp3_conn_submit_shutdown_notice`.
  1508. */
  1509. #define NGHTTP3_SHUTDOWN_NOTICE_STREAM_ID ((1ull << 62) - 4)
  1510. /**
  1511. * @macro
  1512. *
  1513. * :macro:`NGHTTP3_SHUTDOWN_NOTICE_PUSH_ID` specifies push ID sent by
  1514. * a client when it initiates graceful shutdown of the connection via
  1515. * `nghttp3_conn_submit_shutdown_notice`. Note that libnghttp3 does
  1516. * not implement HTTP/3 Server Push.
  1517. */
  1518. #define NGHTTP3_SHUTDOWN_NOTICE_PUSH_ID ((1ull << 62) - 1)
  1519. /**
  1520. * @struct
  1521. *
  1522. * :type:`nghttp3_conn` represents a single HTTP/3 connection. The
  1523. * details of this structure are intentionally hidden from the public
  1524. * API.
  1525. */
  1526. typedef struct nghttp3_conn nghttp3_conn;
  1527. #define NGHTTP3_SETTINGS_V1 1
  1528. #define NGHTTP3_SETTINGS_VERSION NGHTTP3_SETTINGS_V1
  1529. /**
  1530. * @struct
  1531. *
  1532. * :type:`nghttp3_settings` defines HTTP/3 settings.
  1533. */
  1534. typedef struct nghttp3_settings {
  1535. /**
  1536. * :member:`max_field_section_size` specifies the maximum header
  1537. * section (block) size.
  1538. */
  1539. uint64_t max_field_section_size;
  1540. /**
  1541. * :member:`qpack_max_dtable_capacity` is the maximum size of QPACK
  1542. * dynamic table.
  1543. */
  1544. size_t qpack_max_dtable_capacity;
  1545. /**
  1546. * :member:`qpack_encoder_max_dtable_capacity` is the upper bound of
  1547. * QPACK dynamic table capacity that the QPACK encoder is willing to
  1548. * use. The effective maximum dynamic table capacity is the minimum
  1549. * of this field and the value of the received
  1550. * SETTINGS_QPACK_MAX_TABLE_CAPACITY. If this field is set to 0,
  1551. * the encoder does not use the dynamic table.
  1552. *
  1553. * When :type:`nghttp3_settings` is passed to
  1554. * :member:`nghttp3_callbacks.recv_settings` callback, this field
  1555. * should be ignored.
  1556. */
  1557. size_t qpack_encoder_max_dtable_capacity;
  1558. /**
  1559. * :member:`qpack_blocked_streams` is the maximum number of streams
  1560. * which can be blocked while they are being decoded.
  1561. */
  1562. size_t qpack_blocked_streams;
  1563. /**
  1564. * :member:`enable_connect_protocol`, if set to nonzero, enables
  1565. * Extended CONNECT Method (see :rfc:`9220`). Client ignores this
  1566. * field.
  1567. */
  1568. uint8_t enable_connect_protocol;
  1569. /**
  1570. * :member:`h3_datagram`, if set to nonzero, enables HTTP/3
  1571. * Datagrams (see :rfc:`9297`).
  1572. */
  1573. uint8_t h3_datagram;
  1574. } nghttp3_settings;
  1575. /**
  1576. * @functypedef
  1577. *
  1578. * :type:`nghttp3_acked_stream_data` is a callback function which is
  1579. * invoked when data sent on stream denoted by |stream_id| supplied
  1580. * from application is acknowledged by remote endpoint. The number of
  1581. * bytes acknowledged is given in |datalen|.
  1582. *
  1583. * The implementation of this callback must return 0 if it succeeds.
  1584. * Returning :macro:`NGHTTP3_ERR_CALLBACK_FAILURE` will return to the
  1585. * caller immediately. Any values other than 0 is treated as
  1586. * :macro:`NGHTTP3_ERR_CALLBACK_FAILURE`.
  1587. */
  1588. typedef int (*nghttp3_acked_stream_data)(nghttp3_conn *conn, int64_t stream_id,
  1589. uint64_t datalen, void *conn_user_data,
  1590. void *stream_user_data);
  1591. /**
  1592. * @functypedef
  1593. *
  1594. * :type:`nghttp3_conn_stream_close` is a callback function which is
  1595. * invoked when a stream identified by |stream_id| is closed. QUIC
  1596. * application error code |app_error_code| indicates the reason of
  1597. * this closure.
  1598. *
  1599. * The implementation of this callback must return 0 if it succeeds.
  1600. * Returning :macro:`NGHTTP3_ERR_CALLBACK_FAILURE` will return to the
  1601. * caller immediately. Any values other than 0 is treated as
  1602. * :macro:`NGHTTP3_ERR_CALLBACK_FAILURE`.
  1603. */
  1604. typedef int (*nghttp3_stream_close)(nghttp3_conn *conn, int64_t stream_id,
  1605. uint64_t app_error_code,
  1606. void *conn_user_data,
  1607. void *stream_user_data);
  1608. /**
  1609. * @functypedef
  1610. *
  1611. * :type:`nghttp3_recv_data` is a callback function which is invoked
  1612. * when a part of request or response body on stream identified by
  1613. * |stream_id| is received. |data| points to the received data, and
  1614. * its length is |datalen|.
  1615. *
  1616. * The application is responsible for increasing flow control credit
  1617. * (say, increasing by |datalen| bytes).
  1618. *
  1619. * The implementation of this callback must return 0 if it succeeds.
  1620. * Returning :macro:`NGHTTP3_ERR_CALLBACK_FAILURE` will return to the
  1621. * caller immediately. Any values other than 0 is treated as
  1622. * :macro:`NGHTTP3_ERR_CALLBACK_FAILURE`.
  1623. */
  1624. typedef int (*nghttp3_recv_data)(nghttp3_conn *conn, int64_t stream_id,
  1625. const uint8_t *data, size_t datalen,
  1626. void *conn_user_data, void *stream_user_data);
  1627. /**
  1628. * @functypedef
  1629. *
  1630. * :type:`nghttp3_deferred_consume` is a callback function which is
  1631. * invoked when the library consumed |consumed| bytes for a stream
  1632. * identified by |stream_id|. This callback is used to notify the
  1633. * consumed bytes for stream blocked due to synchronization between
  1634. * streams. The application is responsible for increasing flow
  1635. * control credit by |consumed| bytes.
  1636. *
  1637. * The implementation of this callback must return 0 if it succeeds.
  1638. * Returning :macro:`NGHTTP3_ERR_CALLBACK_FAILURE` will return to the
  1639. * caller immediately. Any values other than 0 is treated as
  1640. * :macro:`NGHTTP3_ERR_CALLBACK_FAILURE`.
  1641. */
  1642. typedef int (*nghttp3_deferred_consume)(nghttp3_conn *conn, int64_t stream_id,
  1643. size_t consumed, void *conn_user_data,
  1644. void *stream_user_data);
  1645. /**
  1646. * @functypedef
  1647. *
  1648. * :type:`nghttp3_begin_headers` is a callback function which is
  1649. * invoked when an incoming HTTP field section is started on a stream
  1650. * denoted by |stream_id|. Each HTTP field is passed to application
  1651. * by :type:`nghttp3_recv_header` callback. And then
  1652. * :type:`nghttp3_end_headers` is called when a whole HTTP field
  1653. * section is processed.
  1654. *
  1655. * The implementation of this callback must return 0 if it succeeds.
  1656. * Returning :macro:`NGHTTP3_ERR_CALLBACK_FAILURE` will return to the
  1657. * caller immediately. Any values other than 0 is treated as
  1658. * :macro:`NGHTTP3_ERR_CALLBACK_FAILURE`.
  1659. */
  1660. typedef int (*nghttp3_begin_headers)(nghttp3_conn *conn, int64_t stream_id,
  1661. void *conn_user_data,
  1662. void *stream_user_data);
  1663. /**
  1664. * @functypedef
  1665. *
  1666. * :type:`nghttp3_recv_header` is a callback function which is invoked
  1667. * when an HTTP field is received on a stream denoted by |stream_id|.
  1668. * |name| contains a field name, and |value| contains a field value.
  1669. * |token| is one of token defined in :type:`nghttp3_qpack_token` or
  1670. * -1 if no token is defined for |name|. |flags| is bitwise OR of
  1671. * zero or more of :macro:`NGHTTP3_NV_FLAG_* <NGHTTP3_NV_FLAG_NONE>`.
  1672. *
  1673. * The buffers for |name| and |value| are reference counted. If
  1674. * application needs to keep them, increment the reference count with
  1675. * `nghttp3_rcbuf_incref`. When they are no longer used, call
  1676. * `nghttp3_rcbuf_decref`.
  1677. *
  1678. * The implementation of this callback must return 0 if it succeeds.
  1679. * Returning :macro:`NGHTTP3_ERR_CALLBACK_FAILURE` will return to the
  1680. * caller immediately. Any values other than 0 is treated as
  1681. * :macro:`NGHTTP3_ERR_CALLBACK_FAILURE`.
  1682. */
  1683. typedef int (*nghttp3_recv_header)(nghttp3_conn *conn, int64_t stream_id,
  1684. int32_t token, nghttp3_rcbuf *name,
  1685. nghttp3_rcbuf *value, uint8_t flags,
  1686. void *conn_user_data,
  1687. void *stream_user_data);
  1688. /**
  1689. * @functypedef
  1690. *
  1691. * :type:`nghttp3_end_headers` is a callback function which is invoked
  1692. * when an incoming HTTP field section has ended.
  1693. *
  1694. * If the stream ends with this HTTP field section, |fin| is set to
  1695. * nonzero.
  1696. *
  1697. * The implementation of this callback must return 0 if it succeeds.
  1698. * Returning :macro:`NGHTTP3_ERR_CALLBACK_FAILURE` will return to the
  1699. * caller immediately. Any values other than 0 is treated as
  1700. * :macro:`NGHTTP3_ERR_CALLBACK_FAILURE`.
  1701. */
  1702. typedef int (*nghttp3_end_headers)(nghttp3_conn *conn, int64_t stream_id,
  1703. int fin, void *conn_user_data,
  1704. void *stream_user_data);
  1705. /**
  1706. * @functypedef
  1707. *
  1708. * :type:`nghttp3_end_stream` is a callback function which is invoked
  1709. * when the receiving side of stream is closed. For server, this
  1710. * callback function is invoked when HTTP request is received
  1711. * completely. For client, this callback function is invoked when
  1712. * HTTP response is received completely.
  1713. *
  1714. * The implementation of this callback must return 0 if it succeeds.
  1715. * Returning :macro:`NGHTTP3_ERR_CALLBACK_FAILURE` will return to the
  1716. * caller immediately. Any values other than 0 is treated as
  1717. * :macro:`NGHTTP3_ERR_CALLBACK_FAILURE`.
  1718. */
  1719. typedef int (*nghttp3_end_stream)(nghttp3_conn *conn, int64_t stream_id,
  1720. void *conn_user_data, void *stream_user_data);
  1721. /**
  1722. * @functypedef
  1723. *
  1724. * :type:`nghttp3_stop_sending` is a callback function which is
  1725. * invoked when the library asks application to send STOP_SENDING to
  1726. * the stream identified by |stream_id|. QUIC application error code
  1727. * |app_error_code| indicates the reason for this action.
  1728. *
  1729. * The implementation of this callback must return 0 if it succeeds.
  1730. * Returning :macro:`NGHTTP3_ERR_CALLBACK_FAILURE` will return to the
  1731. * caller immediately. Any values other than 0 is treated as
  1732. * :macro:`NGHTTP3_ERR_CALLBACK_FAILURE`.
  1733. */
  1734. typedef int (*nghttp3_stop_sending)(nghttp3_conn *conn, int64_t stream_id,
  1735. uint64_t app_error_code,
  1736. void *conn_user_data,
  1737. void *stream_user_data);
  1738. /**
  1739. * @functypedef
  1740. *
  1741. * :type:`nghttp3_reset_stream` is a callback function which is
  1742. * invoked when the library asks application to reset stream
  1743. * identified by |stream_id|. QUIC application error code
  1744. * |app_error_code| indicates the reason for this action.
  1745. *
  1746. * The implementation of this callback must return 0 if it succeeds.
  1747. * Returning :macro:`NGHTTP3_ERR_CALLBACK_FAILURE` will return to the
  1748. * caller immediately. Any values other than 0 is treated as
  1749. * :macro:`NGHTTP3_ERR_CALLBACK_FAILURE`.
  1750. */
  1751. typedef int (*nghttp3_reset_stream)(nghttp3_conn *conn, int64_t stream_id,
  1752. uint64_t app_error_code,
  1753. void *conn_user_data,
  1754. void *stream_user_data);
  1755. /**
  1756. * @functypedef
  1757. *
  1758. * :type:`nghttp3_shutdown` is a callback function which is invoked
  1759. * when a shutdown is initiated by the remote endpoint. For client,
  1760. * |id| contains a stream ID of a client initiated stream, for server,
  1761. * it contains a push ID. All client streams with stream ID, or pushes
  1762. * with push ID equal to, or larger than |ID| are guaranteed to not be
  1763. * processed by the remote endpoint. Note that libnghttp3 does not
  1764. * implement Server Push.
  1765. *
  1766. * Parameter |id| for client can contain a special value
  1767. * :macro:`NGHTTP3_SHUTDOWN_NOTICE_STREAM_ID`, and for server it can
  1768. * contain special value
  1769. * :macro:`NGHTTP3_SHUTDOWN_NOTICE_PUSH_ID`. These values signal
  1770. * request for graceful shutdown of the connection, triggered by
  1771. * remote endpoint's invocation of
  1772. * `nghttp3_conn_submit_shutdown_notice`.
  1773. *
  1774. * It is possible that this callback is invoked multiple times on a
  1775. * single connection, however the |id| can only stay the same or
  1776. * decrease, never increase.
  1777. *
  1778. * The implementation of this callback must return 0 if it succeeds.
  1779. * Returning :macro:`NGHTTP3_ERR_CALLBACK_FAILURE` will return to the
  1780. * caller immediately. Any values other than 0 is treated as
  1781. * :macro:`NGHTTP3_ERR_CALLBACK_FAILURE`.
  1782. */
  1783. typedef int (*nghttp3_shutdown)(nghttp3_conn *conn, int64_t id,
  1784. void *conn_user_data);
  1785. /**
  1786. * @functypedef
  1787. *
  1788. * :type:`nghttp3_recv_settings` is a callback function which is
  1789. * invoked when SETTINGS frame is received. |settings| is a received
  1790. * remote HTTP/3 settings.
  1791. *
  1792. * The implementation of this callback must return 0 if it succeeds.
  1793. * Returning :macro:`NGHTTP3_ERR_CALLBACK_FAILURE` will return to the
  1794. * caller immediately. Any values other than 0 is treated as
  1795. * :macro:`NGHTTP3_ERR_CALLBACK_FAILURE`.
  1796. */
  1797. typedef int (*nghttp3_recv_settings)(nghttp3_conn *conn,
  1798. const nghttp3_settings *settings,
  1799. void *conn_user_data);
  1800. #define NGHTTP3_CALLBACKS_V1 1
  1801. #define NGHTTP3_CALLBACKS_VERSION NGHTTP3_CALLBACKS_V1
  1802. /**
  1803. * @struct
  1804. *
  1805. * :type:`nghttp3_callbacks` holds a set of callback functions.
  1806. */
  1807. typedef struct nghttp3_callbacks {
  1808. /**
  1809. * :member:`acked_stream_data` is a callback function which is
  1810. * invoked when data sent on a particular stream have been
  1811. * acknowledged by a remote endpoint.
  1812. */
  1813. nghttp3_acked_stream_data acked_stream_data;
  1814. /**
  1815. * :member:`stream_close` is a callback function which is invoked
  1816. * when a particular stream has closed.
  1817. */
  1818. nghttp3_stream_close stream_close;
  1819. /**
  1820. * :member:`recv_data` is a callback function which is invoked when
  1821. * stream data is received.
  1822. */
  1823. nghttp3_recv_data recv_data;
  1824. /**
  1825. * :member:`deferred_consume` is a callback function which is
  1826. * invoked when the library consumed data for a particular stream
  1827. * which had been blocked for synchronization between streams.
  1828. */
  1829. nghttp3_deferred_consume deferred_consume;
  1830. /**
  1831. * :member:`begin_headers` is a callback function which is invoked
  1832. * when an HTTP header field section has started on a particular
  1833. * stream.
  1834. */
  1835. nghttp3_begin_headers begin_headers;
  1836. /**
  1837. * :member:`recv_header` is a callback function which is invoked
  1838. * when a single HTTP header field is received on a particular
  1839. * stream.
  1840. */
  1841. nghttp3_recv_header recv_header;
  1842. /**
  1843. * :member:`end_headers` is a callback function which is invoked
  1844. * when an HTTP header field section has ended on a particular
  1845. * stream.
  1846. */
  1847. nghttp3_end_headers end_headers;
  1848. /**
  1849. * :member:`begin_trailers` is a callback function which is invoked
  1850. * when an HTTP trailer field section has started on a particular
  1851. * stream.
  1852. */
  1853. nghttp3_begin_headers begin_trailers;
  1854. /**
  1855. * :member:`recv_trailer` is a callback function which is invoked
  1856. * when a single HTTP trailer field is received on a particular
  1857. * stream.
  1858. */
  1859. nghttp3_recv_header recv_trailer;
  1860. /**
  1861. * :member:`end_trailers` is a callback function which is invoked
  1862. * when an HTTP trailer field section has ended on a particular
  1863. * stream.
  1864. */
  1865. nghttp3_end_headers end_trailers;
  1866. /**
  1867. * :member:`stop_sending` is a callback function which is invoked
  1868. * when the library asks application to send STOP_SENDING to a
  1869. * particular stream.
  1870. */
  1871. nghttp3_stop_sending stop_sending;
  1872. /**
  1873. * :member:`end_stream` is a callback function which is invoked when
  1874. * a receiving side of stream has been closed.
  1875. */
  1876. nghttp3_end_stream end_stream;
  1877. /**
  1878. * :member:`reset_stream` is a callback function which is invoked
  1879. * when the library asks application to reset stream (by sending
  1880. * RESET_STREAM).
  1881. */
  1882. nghttp3_reset_stream reset_stream;
  1883. /**
  1884. * :member:`shutdown` is a callback function which is invoked when
  1885. * the remote endpoint has signalled initiation of connection
  1886. * shutdown.
  1887. */
  1888. nghttp3_shutdown shutdown;
  1889. /**
  1890. * :member:`recv_settings` is a callback function which is invoked
  1891. * when SETTINGS frame is received.
  1892. */
  1893. nghttp3_recv_settings recv_settings;
  1894. } nghttp3_callbacks;
  1895. /**
  1896. * @function
  1897. *
  1898. * `nghttp3_settings_default` fills |settings| with the default
  1899. * values.
  1900. *
  1901. * - :member:`max_field_section_size
  1902. * <nghttp3_settings.max_field_section_size>` = :expr:`((1ull << 62) - 1)`
  1903. * - :member:`qpack_max_dtable_capacity
  1904. * <nghttp3_settings.qpack_max_dtable_capacity>` = 0
  1905. * - :member:`qpack_encoder_max_dtable_capacity
  1906. * <nghttp3_settings.qpack_encoder_max_dtable_capacity>` = 4096
  1907. * - :member:`qpack_blocked_streams
  1908. * <nghttp3_settings.qpack_blocked_streams>` = 0
  1909. * - :member:`enable_connect_protocol
  1910. * <nghttp3_settings.enable_connect_protocol>` = 0
  1911. */
  1912. NGHTTP3_EXTERN void
  1913. nghttp3_settings_default_versioned(int settings_version,
  1914. nghttp3_settings *settings);
  1915. /**
  1916. * @function
  1917. *
  1918. * `nghttp3_conn_client_new` creates :type:`nghttp3_conn`, and
  1919. * initializes it for client use. The pointer to the object is stored
  1920. * in |*pconn|. If |mem| is ``NULL``, the memory allocator returned
  1921. * by `nghttp3_mem_default` is used.
  1922. *
  1923. * This function returns 0 if it succeeds, or one of the following
  1924. * negative error codes:
  1925. *
  1926. * :macro:`NGHTTP3_ERR_NOMEM`
  1927. * Out of memory.
  1928. */
  1929. NGHTTP3_EXTERN int
  1930. nghttp3_conn_client_new_versioned(nghttp3_conn **pconn, int callbacks_version,
  1931. const nghttp3_callbacks *callbacks,
  1932. int settings_version,
  1933. const nghttp3_settings *settings,
  1934. const nghttp3_mem *mem, void *conn_user_data);
  1935. /**
  1936. * @function
  1937. *
  1938. * `nghttp3_conn_server_new` creates :type:`nghttp3_conn`, and
  1939. * initializes it for server use. The pointer to the object is stored
  1940. * in |*pconn|. If |mem| is ``NULL``, the memory allocator returned
  1941. * by `nghttp3_mem_default` is used.
  1942. *
  1943. * This function returns 0 if it succeeds, or one of the following
  1944. * negative error codes:
  1945. *
  1946. * :macro:`NGHTTP3_ERR_NOMEM`
  1947. * Out of memory.
  1948. */
  1949. NGHTTP3_EXTERN int
  1950. nghttp3_conn_server_new_versioned(nghttp3_conn **pconn, int callbacks_version,
  1951. const nghttp3_callbacks *callbacks,
  1952. int settings_version,
  1953. const nghttp3_settings *settings,
  1954. const nghttp3_mem *mem, void *conn_user_data);
  1955. /**
  1956. * @function
  1957. *
  1958. * `nghttp3_conn_del` frees resources allocated for |conn|. This
  1959. * function also frees memory pointed by |conn| itself. This function
  1960. * does nothing if |conn| is NULL.
  1961. */
  1962. NGHTTP3_EXTERN void nghttp3_conn_del(nghttp3_conn *conn);
  1963. /**
  1964. * @function
  1965. *
  1966. * `nghttp3_conn_bind_control_stream` binds stream denoted by
  1967. * |stream_id| to outgoing unidirectional control stream.
  1968. *
  1969. * This function returns 0 if it succeeds, or one of the following
  1970. * negative error codes:
  1971. *
  1972. * :macro:`NGHTTP3_ERR_INVALID_STATE`
  1973. * Control stream has already corresponding stream ID.
  1974. * :macro:`NGHTTP3_ERR_NOMEM`
  1975. * Out of memory.
  1976. */
  1977. NGHTTP3_EXTERN int nghttp3_conn_bind_control_stream(nghttp3_conn *conn,
  1978. int64_t stream_id);
  1979. /**
  1980. * @function
  1981. *
  1982. * `nghttp3_conn_bind_qpack_streams` binds stream denoted by
  1983. * |qenc_stream_id| to outgoing QPACK encoder stream, and stream
  1984. * denoted by |qdec_stream_id| to outgoing QPACK encoder stream.
  1985. *
  1986. * This function returns 0 if it succeeds, or one of the following
  1987. * negative error codes:
  1988. *
  1989. * :macro:`NGHTTP3_ERR_INVALID_STATE`
  1990. * QPACK encoder/decoder stream have already corresponding stream
  1991. * IDs.
  1992. * :macro:`NGHTTP3_ERR_NOMEM`
  1993. * Out of memory.
  1994. */
  1995. NGHTTP3_EXTERN int nghttp3_conn_bind_qpack_streams(nghttp3_conn *conn,
  1996. int64_t qenc_stream_id,
  1997. int64_t qdec_stream_id);
  1998. /**
  1999. * @function
  2000. *
  2001. * `nghttp3_conn_read_stream` reads data |src| of length |srclen| on
  2002. * stream identified by |stream_id|. It returns the number of bytes
  2003. * consumed. The "consumed" means that application can increase flow
  2004. * control credit (both stream and connection) of underlying QUIC
  2005. * connection by that amount. It does not include the amount of data
  2006. * carried by DATA frame which contains application data (excluding
  2007. * any control or QPACK unidirectional streams) . See
  2008. * :type:`nghttp3_recv_data` to handle those bytes. If |fin| is
  2009. * nonzero, this is the last data from remote endpoint in this stream.
  2010. *
  2011. * This function returns the number of bytes consumed, or one of the
  2012. * following negative error codes:
  2013. *
  2014. * :macro:`NGHTTP3_ERR_NOMEM`
  2015. * Out of memory.
  2016. * :macro:`NGHTTP3_ERR_CALLBACK_FAILURE`
  2017. * User callback failed.
  2018. *
  2019. * It may return the other error codes. The negative error code means
  2020. * that |conn| encountered a connection error, and the connection must
  2021. * be closed. Calling nghttp3 API other than `nghttp3_conn_del`
  2022. * causes undefined behavior.
  2023. */
  2024. NGHTTP3_EXTERN nghttp3_ssize nghttp3_conn_read_stream(nghttp3_conn *conn,
  2025. int64_t stream_id,
  2026. const uint8_t *src,
  2027. size_t srclen, int fin);
  2028. /**
  2029. * @function
  2030. *
  2031. * `nghttp3_conn_writev_stream` stores stream data to send to |vec| of
  2032. * length |veccnt|, and returns the number of nghttp3_vec object in
  2033. * which it stored data. It stores stream ID to |*pstream_id|. An
  2034. * application has to call `nghttp3_conn_add_write_offset` to inform
  2035. * |conn| of the actual number of bytes that underlying QUIC stack
  2036. * accepted. |*pfin| will be nonzero if this is the last data to
  2037. * send. If there is no stream to write data or send fin, this
  2038. * function returns 0, and -1 is assigned to |*pstream_id|. This
  2039. * function may return 0, and |*pstream_id| is not -1, and |*pfin| is
  2040. * nonzero. It means 0 length data to |*pstream_id|, and it is the
  2041. * last data to the stream. They must be passed to QUIC stack, and
  2042. * they are accepted, the application has to call
  2043. * `nghttp3_conn_add_write_offset` with 0 byte.
  2044. *
  2045. * This function returns the number of bytes consumed, or one of the
  2046. * following negative error codes:
  2047. *
  2048. * :macro:`NGHTTP3_ERR_NOMEM`
  2049. * Out of memory.
  2050. * :macro:`NGHTTP3_ERR_CALLBACK_FAILURE`
  2051. * User callback failed.
  2052. *
  2053. * It may return the other error codes. The negative error code means
  2054. * that |conn| encountered a connection error, and the connection must
  2055. * be closed. Calling nghttp3 API other than `nghttp3_conn_del`
  2056. * causes undefined behavior.
  2057. */
  2058. NGHTTP3_EXTERN nghttp3_ssize nghttp3_conn_writev_stream(nghttp3_conn *conn,
  2059. int64_t *pstream_id,
  2060. int *pfin,
  2061. nghttp3_vec *vec,
  2062. size_t veccnt);
  2063. /**
  2064. * @function
  2065. *
  2066. * `nghttp3_conn_add_write_offset` tells |conn| the number of bytes
  2067. * |n| for stream denoted by |stream_id| QUIC stack accepted.
  2068. *
  2069. * If stream has no data to send but just sends fin (closing the write
  2070. * side of a stream), the number of bytes sent is 0. It is important
  2071. * to call this function even if |n| is 0 in this case. It is safe to
  2072. * call this function if |n| is 0.
  2073. *
  2074. * `nghttp3_conn_writev_stream` must be called before calling this
  2075. * function to get data to send, and those data must be fed into QUIC
  2076. * stack.
  2077. *
  2078. * If a stream denoted by |stream_id| is not found, this function
  2079. * returns 0.
  2080. *
  2081. * This function returns 0 if it succeeds, or one of the following
  2082. * negative error codes:
  2083. *
  2084. * :macro:`NGHTTP3_ERR_NOMEM`
  2085. * Out of memory.
  2086. */
  2087. NGHTTP3_EXTERN int nghttp3_conn_add_write_offset(nghttp3_conn *conn,
  2088. int64_t stream_id, size_t n);
  2089. /**
  2090. * @function
  2091. *
  2092. * `nghttp3_conn_add_ack_offset` tells |conn| the number of bytes |n|
  2093. * for stream denoted by |stream_id| QUIC stack has acknowledged.
  2094. *
  2095. * If a stream denoted by |stream_id| is not found, this function
  2096. * returns 0.
  2097. *
  2098. * Alternatively, `nghttp3_conn_update_ack_offset` can be used to
  2099. * accomplish the same thing.
  2100. *
  2101. * This function returns 0 if it succeeds, or one of the following
  2102. * negative error codes:
  2103. *
  2104. * :macro:`NGHTTP3_ERR_CALLBACK_FAILURE`
  2105. * User callback failed.
  2106. */
  2107. NGHTTP3_EXTERN int nghttp3_conn_add_ack_offset(nghttp3_conn *conn,
  2108. int64_t stream_id, uint64_t n);
  2109. /**
  2110. * @function
  2111. *
  2112. * `nghttp3_conn_update_ack_offset` tells |conn| that QUIC stack has
  2113. * acknowledged the stream data up to |offset| for a stream denoted by
  2114. * |stream_id|.
  2115. *
  2116. * If a stream denoted by |stream_id| is not found, this function
  2117. * returns 0.
  2118. *
  2119. * Alternatively, `nghttp3_conn_add_ack_offset` can be used to
  2120. * accomplish the same thing.
  2121. *
  2122. * This function returns 0 if it succeeds, or one of the following
  2123. * negative error codes:
  2124. *
  2125. * :macro:`NGHTTP3_ERR_INVALID_ARGUMENT`
  2126. * |offset| is less than the number of bytes acknowledged so far.
  2127. * :macro:`NGHTTP3_ERR_CALLBACK_FAILURE`
  2128. * User callback failed.
  2129. */
  2130. NGHTTP3_EXTERN int nghttp3_conn_update_ack_offset(nghttp3_conn *conn,
  2131. int64_t stream_id,
  2132. uint64_t offset);
  2133. /**
  2134. * @function
  2135. *
  2136. * `nghttp3_conn_block_stream` tells the library that stream
  2137. * identified by |stream_id| is blocked due to QUIC flow control.
  2138. */
  2139. NGHTTP3_EXTERN void nghttp3_conn_block_stream(nghttp3_conn *conn,
  2140. int64_t stream_id);
  2141. /**
  2142. * @function
  2143. *
  2144. * `nghttp3_conn_unblock_stream` tells the library that stream
  2145. * identified by |stream_id| which was blocked by QUIC flow control
  2146. * (see `nghttp3_conn_block_stream`) is unblocked.
  2147. *
  2148. * If a stream denoted by |stream_id| is not found, this function
  2149. * returns 0.
  2150. *
  2151. * This function returns 0 if it succeeds, or one of the following
  2152. * negative error codes:
  2153. *
  2154. * :macro:`NGHTTP3_ERR_NOMEM`
  2155. * Out of memory.
  2156. */
  2157. NGHTTP3_EXTERN int nghttp3_conn_unblock_stream(nghttp3_conn *conn,
  2158. int64_t stream_id);
  2159. /**
  2160. * @function
  2161. *
  2162. * `nghttp3_conn_is_stream_writable` returns nonzero if a stream
  2163. * identified by |stream_id| is writable. It is not writable if:
  2164. *
  2165. * - the stream does not exist; or,
  2166. * - the stream is closed (e.g., `nghttp3_conn_close_stream` is
  2167. * called); or,
  2168. * - the stream is QUIC flow control blocked (e.g.,
  2169. * `nghttp3_conn_block_stream` is called); or,
  2170. * - the stream is input data blocked (e.g.,
  2171. * :macro:`NGHTTP3_ERR_WOULDBLOCK` is returned from
  2172. * :type:`nghttp3_read_data_callback`); or,
  2173. * - the stream is half-closed local (e.g.,
  2174. * `nghttp3_conn_shutdown_stream_write` is called).
  2175. */
  2176. NGHTTP3_EXTERN int nghttp3_conn_is_stream_writable(nghttp3_conn *conn,
  2177. int64_t stream_id);
  2178. /**
  2179. * @function
  2180. *
  2181. * `nghttp3_conn_shutdown_stream_write` tells the library that any
  2182. * further write operation to stream identified by |stream_id| is
  2183. * prohibited. This works like `nghttp3_conn_block_stream`, but it
  2184. * cannot be unblocked by `nghttp3_conn_unblock_stream`.
  2185. */
  2186. NGHTTP3_EXTERN void nghttp3_conn_shutdown_stream_write(nghttp3_conn *conn,
  2187. int64_t stream_id);
  2188. /**
  2189. * @function
  2190. *
  2191. * `nghttp3_conn_shutdown_stream_read` tells the library that
  2192. * read-side of stream denoted by |stream_id| is abruptly closed, and
  2193. * any further incoming data and pending stream data should be
  2194. * discarded.
  2195. *
  2196. * If a stream denoted by |stream_id| is not client bidirectional
  2197. * stream, this function returns 0. If the stream has already
  2198. * shutdown read-side stream, this function returns 0.
  2199. *
  2200. * This function does not fail if a stream denoted by |stream_id| is
  2201. * not found, although it may fail with the other reasons.
  2202. *
  2203. * This function returns 0 if it succeeds, or one of the following
  2204. * negative error codes:
  2205. *
  2206. * :macro:`NGHTTP3_ERR_NOMEM`
  2207. * Out of memory.
  2208. * :macro:`NGHTTP3_ERR_QPACK_FATAL`
  2209. * QPACK decoder stream overflow.
  2210. */
  2211. NGHTTP3_EXTERN int nghttp3_conn_shutdown_stream_read(nghttp3_conn *conn,
  2212. int64_t stream_id);
  2213. /**
  2214. * @function
  2215. *
  2216. * `nghttp3_conn_resume_stream` resumes stream identified by
  2217. * |stream_id| which was previously unable to provide data. See
  2218. * :type:`nghttp3_read_data_callback`.
  2219. *
  2220. * If a stream denoted by |stream_id| is not found, this function
  2221. * returns 0.
  2222. *
  2223. * This function returns 0 if it succeeds, or one of the following
  2224. * negative error codes:
  2225. *
  2226. * :macro:`NGHTTP3_ERR_NOMEM`
  2227. * Out of memory.
  2228. */
  2229. NGHTTP3_EXTERN int nghttp3_conn_resume_stream(nghttp3_conn *conn,
  2230. int64_t stream_id);
  2231. /**
  2232. * @function
  2233. *
  2234. * `nghttp3_conn_close_stream` tells the library that a stream
  2235. * identified by |stream_id| has been closed. QUIC application error
  2236. * code |app_error_code| is the reason of the closure.
  2237. *
  2238. * This function returns 0 if it succeeds, or one of the following
  2239. * negative error codes:
  2240. *
  2241. * :macro:`NGHTTP3_ERR_STREAM_NOT_FOUND`
  2242. * Stream not found.
  2243. * :macro:`NGHTTP3_ERR_H3_CLOSED_CRITICAL_STREAM`
  2244. * A critical stream is closed.
  2245. * :macro:`NGHTTP3_ERR_CALLBACK_FAILURE`
  2246. * User callback failed
  2247. */
  2248. NGHTTP3_EXTERN int nghttp3_conn_close_stream(nghttp3_conn *conn,
  2249. int64_t stream_id,
  2250. uint64_t app_error_code);
  2251. /**
  2252. * @macrosection
  2253. *
  2254. * Data flags
  2255. */
  2256. /**
  2257. * @macro
  2258. *
  2259. * :macro:`NGHTTP3_DATA_FLAG_NONE` indicates no flag set.
  2260. */
  2261. #define NGHTTP3_DATA_FLAG_NONE 0x00u
  2262. /**
  2263. * @macro
  2264. *
  2265. * :macro:`NGHTTP3_DATA_FLAG_EOF` indicates that all request or
  2266. * response body has been provided to the library. It also indicates
  2267. * that sending side of stream is closed unless
  2268. * :macro:`NGHTTP3_DATA_FLAG_NO_END_STREAM` is given at the same time.
  2269. */
  2270. #define NGHTTP3_DATA_FLAG_EOF 0x01u
  2271. /**
  2272. * @macro
  2273. *
  2274. * :macro:`NGHTTP3_DATA_FLAG_NO_END_STREAM` indicates that sending
  2275. * side of stream is not closed even if :macro:`NGHTTP3_DATA_FLAG_EOF`
  2276. * is set. Usually this flag is used to send trailer fields with
  2277. * `nghttp3_conn_submit_trailers`. If `nghttp3_conn_submit_trailers`
  2278. * has been called, regardless of this flag, the submitted trailer
  2279. * fields are sent.
  2280. */
  2281. #define NGHTTP3_DATA_FLAG_NO_END_STREAM 0x02u
  2282. /**
  2283. * @function
  2284. *
  2285. * `nghttp3_conn_set_max_client_streams_bidi` tells |conn| the
  2286. * cumulative number of bidirectional streams that client can open.
  2287. */
  2288. NGHTTP3_EXTERN void
  2289. nghttp3_conn_set_max_client_streams_bidi(nghttp3_conn *conn,
  2290. uint64_t max_streams);
  2291. /**
  2292. * @function
  2293. *
  2294. * `nghttp3_conn_set_max_concurrent_streams` tells |conn| the maximum
  2295. * number of concurrent streams that a remote endpoint can open,
  2296. * including both bidirectional and unidirectional streams which
  2297. * potentially receive QPACK encoded HEADERS frame. This value is
  2298. * used as a hint to limit the internal resource consumption.
  2299. */
  2300. NGHTTP3_EXTERN void
  2301. nghttp3_conn_set_max_concurrent_streams(nghttp3_conn *conn,
  2302. size_t max_concurrent_streams);
  2303. /**
  2304. * @functypedef
  2305. *
  2306. * :type:`nghttp3_read_data_callback` is a callback function invoked
  2307. * when the library asks an application to provide stream data for a
  2308. * stream denoted by |stream_id|.
  2309. *
  2310. * The library provides |vec| of length |veccnt| to the application.
  2311. * The application should fill data and its length to |vec|. It has
  2312. * to return the number of the filled objects. The application must
  2313. * retain data until they are safe to free. It is notified by
  2314. * :type:`nghttp3_acked_stream_data` callback.
  2315. *
  2316. * If this is the last data to send (or there is no data to send
  2317. * because all data have been sent already), set
  2318. * :macro:`NGHTTP3_DATA_FLAG_EOF` to |*pflags|.
  2319. *
  2320. * If the application is unable to provide data temporarily, return
  2321. * :macro:`NGHTTP3_ERR_WOULDBLOCK`. When it is ready to provide data,
  2322. * call `nghttp3_conn_resume_stream`.
  2323. *
  2324. * The callback should return the number of objects in |vec| that the
  2325. * application filled if it succeeds, or
  2326. * :macro:`NGHTTP3_ERR_CALLBACK_FAILURE`.
  2327. *
  2328. * TODO Add NGHTTP3_ERR_TEMPORAL_CALLBACK_FAILURE to reset just this
  2329. * stream.
  2330. */
  2331. typedef nghttp3_ssize (*nghttp3_read_data_callback)(
  2332. nghttp3_conn *conn, int64_t stream_id, nghttp3_vec *vec, size_t veccnt,
  2333. uint32_t *pflags, void *conn_user_data, void *stream_user_data);
  2334. /**
  2335. * @struct
  2336. *
  2337. * :type:`nghttp3_data_reader` specifies the way how to generate
  2338. * request or response body.
  2339. */
  2340. typedef struct nghttp3_data_reader {
  2341. /**
  2342. * :member:`read_data` is a callback function to generate body.
  2343. */
  2344. nghttp3_read_data_callback read_data;
  2345. } nghttp3_data_reader;
  2346. /**
  2347. * @function
  2348. *
  2349. * `nghttp3_conn_submit_request` submits HTTP request header fields
  2350. * and body on the stream identified by |stream_id|. |stream_id| must
  2351. * be a client initiated bidirectional stream. Only client can submit
  2352. * HTTP request. |nva| of length |nvlen| specifies HTTP request
  2353. * header fields. |dr| specifies a request body. If there is no
  2354. * request body, specify NULL. If |dr| is NULL, it implies the end of
  2355. * stream. |stream_user_data| is an opaque pointer attached to the
  2356. * stream.
  2357. *
  2358. * This function returns 0 if it succeeds, or one of the following
  2359. * negative error codes:
  2360. *
  2361. * :macro:`NGHTTP3_ERR_INVALID_ARGUMENT`
  2362. * |stream_id| identifies unidirectional stream.
  2363. * :macro:`NGHTTP3_ERR_CONN_CLOSING`
  2364. * Connection is shutting down, and no new stream is allowed.
  2365. * :macro:`NGHTTP3_ERR_STREAM_IN_USE`
  2366. * Stream has already been opened.
  2367. * :macro:`NGHTTP3_ERR_NOMEM`
  2368. * Out of memory.
  2369. */
  2370. NGHTTP3_EXTERN int nghttp3_conn_submit_request(
  2371. nghttp3_conn *conn, int64_t stream_id, const nghttp3_nv *nva, size_t nvlen,
  2372. const nghttp3_data_reader *dr, void *stream_user_data);
  2373. /**
  2374. * @function
  2375. *
  2376. * `nghttp3_conn_submit_info` submits HTTP non-final response header
  2377. * fields on the stream identified by |stream_id|. |nva| of length
  2378. * |nvlen| specifies HTTP response header fields.
  2379. *
  2380. * This function returns 0 if it succeeds, or one of the following
  2381. * negative error codes:
  2382. *
  2383. * :macro:`NGHTTP3_ERR_STREAM_NOT_FOUND`
  2384. * Stream not found
  2385. * :macro:`NGHTTP3_ERR_NOMEM`
  2386. * Out of memory.
  2387. */
  2388. NGHTTP3_EXTERN int nghttp3_conn_submit_info(nghttp3_conn *conn,
  2389. int64_t stream_id,
  2390. const nghttp3_nv *nva,
  2391. size_t nvlen);
  2392. /**
  2393. * @function
  2394. *
  2395. * `nghttp3_conn_submit_response` submits HTTP response header fields
  2396. * and body on the stream identified by |stream_id|. |nva| of length
  2397. * |nvlen| specifies HTTP response header fields. |dr| specifies a
  2398. * response body. If there is no response body, specify NULL. If
  2399. * |dr| is NULL, it implies the end of stream.
  2400. *
  2401. * This function returns 0 if it succeeds, or one of the following
  2402. * negative error codes:
  2403. *
  2404. * :macro:`NGHTTP3_ERR_STREAM_NOT_FOUND`
  2405. * Stream not found
  2406. * :macro:`NGHTTP3_ERR_NOMEM`
  2407. * Out of memory.
  2408. */
  2409. NGHTTP3_EXTERN int nghttp3_conn_submit_response(nghttp3_conn *conn,
  2410. int64_t stream_id,
  2411. const nghttp3_nv *nva,
  2412. size_t nvlen,
  2413. const nghttp3_data_reader *dr);
  2414. /**
  2415. * @function
  2416. *
  2417. * `nghttp3_conn_submit_trailers` submits HTTP trailer fields on the
  2418. * stream identified by |stream_id|. |nva| of length |nvlen|
  2419. * specifies HTTP trailer fields. Calling this function implies the
  2420. * end of stream.
  2421. *
  2422. * This function returns 0 if it succeeds, or one of the following
  2423. * negative error codes:
  2424. *
  2425. * :macro:`NGHTTP3_ERR_STREAM_NOT_FOUND`
  2426. * Stream not found
  2427. * :macro:`NGHTTP3_ERR_INVALID_STATE`
  2428. * Application has already submitted fin to stream.
  2429. * :macro:`NGHTTP3_ERR_NOMEM`
  2430. * Out of memory.
  2431. */
  2432. NGHTTP3_EXTERN int nghttp3_conn_submit_trailers(nghttp3_conn *conn,
  2433. int64_t stream_id,
  2434. const nghttp3_nv *nva,
  2435. size_t nvlen);
  2436. /**
  2437. * @function
  2438. *
  2439. * `nghttp3_conn_submit_shutdown_notice` notifies the other endpoint
  2440. * to stop creating new stream. After a couple of RTTs later, call
  2441. * `nghttp3_conn_shutdown` to start graceful shutdown.
  2442. *
  2443. * This function returns 0 if it succeeds, or one of the following
  2444. * negative error codes:
  2445. *
  2446. * :macro:`NGHTTP3_ERR_NOMEM`
  2447. * Out of memory.
  2448. */
  2449. NGHTTP3_EXTERN int nghttp3_conn_submit_shutdown_notice(nghttp3_conn *conn);
  2450. /**
  2451. * @function
  2452. *
  2453. * `nghttp3_conn_shutdown` starts graceful shutdown. It should be
  2454. * called after `nghttp3_conn_submit_shutdown_notice` and a couple of
  2455. * RTTs. After calling this function, the local endpoint starts
  2456. * rejecting new incoming streams. The existing streams are processed
  2457. * normally. See also `nghttp3_conn_is_drained`.
  2458. *
  2459. * This function returns 0 if it succeeds, or one of the following
  2460. * negative error codes:
  2461. *
  2462. * :macro:`NGHTTP3_ERR_NOMEM`
  2463. * Out of memory.
  2464. */
  2465. NGHTTP3_EXTERN int nghttp3_conn_shutdown(nghttp3_conn *conn);
  2466. /**
  2467. * @function
  2468. *
  2469. * `nghttp3_conn_set_stream_user_data` sets |stream_user_data| to the
  2470. * stream identified by |stream_id|.
  2471. *
  2472. * This function returns 0 if it succeeds, or one of the following
  2473. * negative error codes:
  2474. *
  2475. * :macro:`NGHTTP3_ERR_STREAM_NOT_FOUND`
  2476. * Stream not found.
  2477. */
  2478. NGHTTP3_EXTERN int nghttp3_conn_set_stream_user_data(nghttp3_conn *conn,
  2479. int64_t stream_id,
  2480. void *stream_user_data);
  2481. /**
  2482. * @function
  2483. *
  2484. * `nghttp3_conn_get_frame_payload_left` returns the number of bytes
  2485. * left to read current frame payload for a stream denoted by
  2486. * |stream_id|. If no such stream is found, or |stream_id| identifies
  2487. * neither client bidirectional stream nor remote control stream, it
  2488. * returns 0.
  2489. */
  2490. NGHTTP3_EXTERN uint64_t nghttp3_conn_get_frame_payload_left(nghttp3_conn *conn,
  2491. int64_t stream_id);
  2492. /**
  2493. * @macrosection
  2494. *
  2495. * HTTP stream priority flags
  2496. */
  2497. /**
  2498. * @macro
  2499. *
  2500. * :macro:`NGHTTP3_DEFAULT_URGENCY` is the default urgency level.
  2501. */
  2502. #define NGHTTP3_DEFAULT_URGENCY 3
  2503. /**
  2504. * @macro
  2505. *
  2506. * :macro:`NGHTTP3_URGENCY_HIGH` is the highest urgency level.
  2507. */
  2508. #define NGHTTP3_URGENCY_HIGH 0
  2509. /**
  2510. * @macro
  2511. *
  2512. * :macro:`NGHTTP3_URGENCY_LOW` is the lowest urgency level.
  2513. */
  2514. #define NGHTTP3_URGENCY_LOW 7
  2515. /**
  2516. * @macro
  2517. *
  2518. * :macro:`NGHTTP3_URGENCY_LEVELS` is the number of urgency levels.
  2519. */
  2520. #define NGHTTP3_URGENCY_LEVELS (NGHTTP3_URGENCY_LOW + 1)
  2521. #define NGHTTP3_PRI_V1 1
  2522. #define NGHTTP3_PRI_VERSION NGHTTP3_PRI_V1
  2523. /**
  2524. * @struct
  2525. *
  2526. * :type:`nghttp3_pri` represents HTTP priority.
  2527. */
  2528. typedef struct NGHTTP3_ALIGN(8) nghttp3_pri {
  2529. /**
  2530. * :member:`urgency` is the urgency of a stream, it must be in
  2531. * [:macro:`NGHTTP3_URGENCY_HIGH`, :macro:`NGHTTP3_URGENCY_LOW`],
  2532. * inclusive, and 0 is the highest urgency.
  2533. */
  2534. uint32_t urgency;
  2535. /**
  2536. * :member:`inc` indicates that a content can be processed
  2537. * incrementally or not. If it is 0, it cannot be processed
  2538. * incrementally. If it is 1, it can be processed incrementally.
  2539. * Other value is not permitted.
  2540. */
  2541. uint8_t inc;
  2542. } nghttp3_pri;
  2543. /**
  2544. * @function
  2545. *
  2546. * `nghttp3_conn_get_stream_priority` stores stream priority of a
  2547. * stream denoted by |stream_id| into |*dest|. |stream_id| must
  2548. * identify client initiated bidirectional stream. Only server can
  2549. * use this function.
  2550. *
  2551. * This function must not be called if |conn| is initialized as
  2552. * client.
  2553. *
  2554. * This function returns 0 if it succeeds, or one of the following
  2555. * negative error codes:
  2556. *
  2557. * :macro:`NGHTTP3_ERR_INVALID_ARGUMENT`
  2558. * |stream_id| is not a client initiated bidirectional stream ID.
  2559. * :macro:`NGHTTP3_ERR_STREAM_NOT_FOUND`
  2560. * Stream not found.
  2561. */
  2562. NGHTTP3_EXTERN int nghttp3_conn_get_stream_priority_versioned(
  2563. nghttp3_conn *conn, int pri_version, nghttp3_pri *dest, int64_t stream_id);
  2564. /**
  2565. * @function
  2566. *
  2567. * `nghttp3_conn_set_client_stream_priority` updates priority of a
  2568. * stream denoted by |stream_id| with the value pointed by |data| of
  2569. * length |datalen|, which should be a serialized :rfc:`9218` priority
  2570. * field value. |stream_id| must identify client initiated
  2571. * bidirectional stream.
  2572. *
  2573. * This function must not be called if |conn| is initialized as
  2574. * server.
  2575. *
  2576. * This function returns 0 if it succeeds, or one of the following
  2577. * negative error codes:
  2578. *
  2579. * :macro:`NGHTTP3_ERR_INVALID_ARGUMENT`
  2580. * |stream_id| is not a client initiated bidirectional stream ID.
  2581. * :macro:`NGHTTP3_ERR_STREAM_NOT_FOUND`
  2582. * Stream not found.
  2583. * :macro:`NGHTTP3_ERR_NOMEM`
  2584. * Out of memory.
  2585. */
  2586. NGHTTP3_EXTERN int nghttp3_conn_set_client_stream_priority(nghttp3_conn *conn,
  2587. int64_t stream_id,
  2588. const uint8_t *data,
  2589. size_t datalen);
  2590. /**
  2591. * @function
  2592. *
  2593. * `nghttp3_conn_set_server_stream_priority` updates priority of a
  2594. * stream denoted by |stream_id| with the value pointed by |pri|.
  2595. * |stream_id| must identify client initiated bidirectional stream.
  2596. *
  2597. * This function must not be called if |conn| is initialized as
  2598. * client.
  2599. *
  2600. * This function completely overrides stream priority set by client,
  2601. * and any attempts to update priority by client are ignored.
  2602. *
  2603. * This function returns 0 if it succeeds, or one of the following
  2604. * negative error codes:
  2605. *
  2606. * :macro:`NGHTTP3_ERR_INVALID_ARGUMENT`
  2607. * |stream_id| is not a client initiated bidirectional stream ID.
  2608. * :macro:`NGHTTP3_ERR_STREAM_NOT_FOUND`
  2609. * Stream not found.
  2610. * :macro:`NGHTTP3_ERR_NOMEM`
  2611. * Out of memory.
  2612. */
  2613. NGHTTP3_EXTERN int nghttp3_conn_set_server_stream_priority_versioned(
  2614. nghttp3_conn *conn, int64_t stream_id, int pri_version,
  2615. const nghttp3_pri *pri);
  2616. /**
  2617. * @function
  2618. *
  2619. * `nghttp3_vec_len` returns the sum of length in |vec| of |cnt|
  2620. * elements.
  2621. */
  2622. NGHTTP3_EXTERN uint64_t nghttp3_vec_len(const nghttp3_vec *vec, size_t cnt);
  2623. /**
  2624. * @function
  2625. *
  2626. * `nghttp3_check_header_name` returns nonzero if HTTP field name
  2627. * |name| of length |len| is valid according to
  2628. * :rfc:`7230#section-3.2`.
  2629. *
  2630. * Because this is an HTTP field name in HTTP/3, the upper cased
  2631. * alphabet is treated as error.
  2632. */
  2633. NGHTTP3_EXTERN int nghttp3_check_header_name(const uint8_t *name, size_t len);
  2634. /**
  2635. * @function
  2636. *
  2637. * `nghttp3_check_header_value` returns nonzero if HTTP field value
  2638. * |value| of length |len| is valid according to
  2639. * :rfc:`7230#section-3.2`.
  2640. */
  2641. NGHTTP3_EXTERN int nghttp3_check_header_value(const uint8_t *value, size_t len);
  2642. /**
  2643. * @function
  2644. *
  2645. * `nghttp3_conn_is_drained` returns nonzero if
  2646. * `nghttp3_conn_shutdown` has been called, and there is no active
  2647. * remote streams. This function is for server use only.
  2648. */
  2649. NGHTTP3_EXTERN int nghttp3_conn_is_drained(nghttp3_conn *conn);
  2650. /**
  2651. * @function
  2652. *
  2653. * `nghttp3_pri_parse_priority` parses Priority header field value
  2654. * pointed by |value| of length |len|, and stores the result in the
  2655. * object pointed by |dest|. Priority header field is defined in
  2656. * :rfc:`9218`.
  2657. *
  2658. * This function does not initialize the object pointed by |dest|
  2659. * before storing the result. It only assigns the values that the
  2660. * parser correctly extracted to fields.
  2661. *
  2662. * This function returns 0 if it succeeds, or one of the following
  2663. * negative error codes:
  2664. *
  2665. * :macro:`NGHTTP3_ERR_INVALID_ARGUMENT`
  2666. * Failed to parse the header field value.
  2667. */
  2668. NGHTTP3_EXTERN int nghttp3_pri_parse_priority_versioned(int pri_version,
  2669. nghttp3_pri *dest,
  2670. const uint8_t *value,
  2671. size_t len);
  2672. /**
  2673. * @macrosection
  2674. *
  2675. * nghttp3_info flags
  2676. */
  2677. /**
  2678. * @macro
  2679. *
  2680. * :macro:`NGHTTP3_VERSION_AGE` is the age of :type:`nghttp3_info`.
  2681. */
  2682. #define NGHTTP3_VERSION_AGE 1
  2683. /**
  2684. * @struct
  2685. *
  2686. * :type:`nghttp3_info` is what `nghttp3_version` returns. It holds
  2687. * information about the particular nghttp3 version.
  2688. */
  2689. typedef struct nghttp3_info {
  2690. /**
  2691. * :member:`age` is the age of this struct. This instance of
  2692. * nghttp3 sets it to :macro:`NGHTTP3_VERSION_AGE` but a future
  2693. * version may bump it and add more struct fields at the bottom
  2694. */
  2695. int age;
  2696. /**
  2697. * :member:`version_num` is the :macro:`NGHTTP3_VERSION_NUM` number
  2698. * (since age == 1)
  2699. */
  2700. int version_num;
  2701. /**
  2702. * :member:`version_str` points to the :macro:`NGHTTP3_VERSION`
  2703. * string (since age ==1)
  2704. */
  2705. const char *version_str;
  2706. /* -------- the above fields all exist when age == 1 */
  2707. } nghttp3_info;
  2708. /**
  2709. * @function
  2710. *
  2711. * `nghttp3_version` returns a pointer to a :type:`nghttp3_info`
  2712. * struct with version information about the run-time library in use.
  2713. * The |least_version| argument can be set to a 24 bit numerical value
  2714. * for the least accepted version number, and if the condition is not
  2715. * met, this function will return a ``NULL``. Pass in 0 to skip the
  2716. * version checking.
  2717. */
  2718. NGHTTP3_EXTERN const nghttp3_info *nghttp3_version(int least_version);
  2719. /**
  2720. * @function
  2721. *
  2722. * `nghttp3_err_is_fatal` returns nonzero if |liberr| is a fatal
  2723. * error. |liberr| must be one of nghttp3 library error codes (which
  2724. * is defined as NGHTTP3_ERR_* macro, such as
  2725. * :macro:`NGHTTP3_ERR_NOMEM`).
  2726. */
  2727. NGHTTP3_EXTERN int nghttp3_err_is_fatal(int liberr);
  2728. /*
  2729. * Versioned function wrappers
  2730. */
  2731. /*
  2732. * `nghttp3_settings_default` is a wrapper around
  2733. * `nghttp3_settings_default_versioned` to set the correct struct
  2734. * version.
  2735. */
  2736. #define nghttp3_settings_default(SETTINGS) \
  2737. nghttp3_settings_default_versioned(NGHTTP3_SETTINGS_VERSION, (SETTINGS))
  2738. /*
  2739. * `nghttp3_conn_client_new` is a wrapper around
  2740. * `nghttp3_conn_client_new_versioned` to set the correct struct
  2741. * version.
  2742. */
  2743. #define nghttp3_conn_client_new(PCONN, CALLBACKS, SETTINGS, MEM, USER_DATA) \
  2744. nghttp3_conn_client_new_versioned((PCONN), NGHTTP3_CALLBACKS_VERSION, \
  2745. (CALLBACKS), NGHTTP3_SETTINGS_VERSION, \
  2746. (SETTINGS), (MEM), (USER_DATA))
  2747. /*
  2748. * `nghttp3_conn_server_new` is a wrapper around
  2749. * `nghttp3_conn_server_new_versioned` to set the correct struct
  2750. * version.
  2751. */
  2752. #define nghttp3_conn_server_new(PCONN, CALLBACKS, SETTINGS, MEM, USER_DATA) \
  2753. nghttp3_conn_server_new_versioned((PCONN), NGHTTP3_CALLBACKS_VERSION, \
  2754. (CALLBACKS), NGHTTP3_SETTINGS_VERSION, \
  2755. (SETTINGS), (MEM), (USER_DATA))
  2756. /*
  2757. * `nghttp3_conn_set_server_stream_priority` is a wrapper around
  2758. * `nghttp3_conn_set_server_stream_priority_versioned` to set the
  2759. * correct struct version.
  2760. */
  2761. #define nghttp3_conn_set_server_stream_priority(CONN, STREAM_ID, PRI) \
  2762. nghttp3_conn_set_server_stream_priority_versioned( \
  2763. (CONN), (STREAM_ID), NGHTTP3_PRI_VERSION, (PRI))
  2764. /*
  2765. * `nghttp3_conn_get_stream_priority` is a wrapper around
  2766. * `nghttp3_conn_get_stream_priority_versioned` to set the correct
  2767. * struct version.
  2768. */
  2769. #define nghttp3_conn_get_stream_priority(CONN, DEST, STREAM_ID) \
  2770. nghttp3_conn_get_stream_priority_versioned((CONN), NGHTTP3_PRI_VERSION, \
  2771. (DEST), (STREAM_ID))
  2772. /*
  2773. * `nghttp3_pri_parse_priority` is a wrapper around
  2774. * `nghttp3_pri_parse_priority_versioned` to set the correct struct
  2775. * version.
  2776. */
  2777. #define nghttp3_pri_parse_priority(DEST, VALUE, LEN) \
  2778. nghttp3_pri_parse_priority_versioned(NGHTTP3_PRI_VERSION, (DEST), (VALUE), \
  2779. (LEN))
  2780. #ifdef __cplusplus
  2781. }
  2782. #endif
  2783. #endif /* NGHTTP3_H */