http.h@ 75008

Last change on this file since 75008 was 74377, checked in by vboxsync, 6 years ago
IPRT/http: Added RTHttpSetProxyByUrl, deprecating RTHttpSetProxy in favor of it. bugref:9248
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 25.1 KB

Line
1	/* $Id: http.h 74377 2018-09-20 00:37:23Z vboxsync $ */
2	/** @file
3	* IPRT - Simple HTTP/HTTPS Client API.
4	*/
5
6	/*
7	* Copyright (C) 2012-2017 Oracle Corporation
8	*
9	* This file is part of VirtualBox Open Source Edition (OSE), as
10	* available from http://www.virtualbox.org. This file is free software;
11	* you can redistribute it and/or modify it under the terms of the GNU
12	* General Public License (GPL) as published by the Free Software
13	* Foundation, in version 2 as it comes in the "COPYING" file of the
14	* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
15	* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
16	*
17	* The contents of this file may alternatively be used under the terms
18	* of the Common Development and Distribution License Version 1.0
19	* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
20	* VirtualBox OSE distribution, in which case the provisions of the
21	* CDDL are applicable instead of those of the GPL.
22	*
23	* You may elect to license modified versions of this file under the
24	* terms and conditions of either the GPL or the CDDL or both.
25	*/
26
27	#ifndef ___iprt_http_h
28	#define ___iprt_http_h
29
30	#include <iprt/types.h>
31
32	RT_C_DECLS_BEGIN
33
34	/** @defgroup grp_rt_http RTHttp - Simple HTTP/HTTPS Client API
35	* @ingroup grp_rt
36	* @{
37	*/
38
39	/** @todo the following three definitions may move the iprt/types.h later. */
40	/** HTTP/HTTPS client handle. */
41	typedef R3PTRTYPE(struct RTHTTPINTERNAL *) RTHTTP;
42	/** Pointer to a HTTP/HTTPS client handle. */
43	typedef RTHTTP *PRTHTTP;
44	/** Nil HTTP/HTTPS client handle. */
45	#define NIL_RTHTTP ((RTHTTP)0)
46
47
48	/**
49	* Creates a HTTP client instance.
50	*
51	* @returns IPRT status code.
52	* @param phHttp Where to store the HTTP handle.
53	*/
54	RTR3DECL(int) RTHttpCreate(PRTHTTP phHttp);
55
56	/**
57	* Resets a HTTP client instance.
58	*
59	* @returns IPRT status code.
60	* @param hHttp Handle to the HTTP interface.
61	*/
62	RTR3DECL(int) RTHttpReset(RTHTTP hHttp);
63
64	/**
65	* Destroys a HTTP client instance.
66	*
67	* @returns IPRT status code.
68	* @param hHttp Handle to the HTTP interface.
69	*/
70	RTR3DECL(int) RTHttpDestroy(RTHTTP hHttp);
71
72
73	/**
74	* Retrieve the redir location for 301 responses.
75	*
76	* @param hHttp Handle to the HTTP interface.
77	* @param ppszRedirLocation Where to store the string. To be freed with
78	* RTStrFree().
79	*/
80	RTR3DECL(int) RTHttpGetRedirLocation(RTHTTP hHttp, char **ppszRedirLocation);
81
82	/**
83	* Perform a simple blocking HTTP GET request.
84	*
85	* This is a just a convenient wrapper around RTHttpGetBinary that returns a
86	* different type and sheds a parameter.
87	*
88	* @returns iprt status code.
89	*
90	* @param hHttp The HTTP client handle.
91	* @param pszUrl URL.
92	* @param ppszNotUtf8 Where to return the pointer to the HTTP response.
93	* The string is of course zero terminated. Use
94	* RTHttpFreeReponseText to free.
95	*
96	* @remarks BIG FAT WARNING!
97	*
98	* This function does not guarantee the that returned string is valid UTF-8 or
99	* any other kind of text encoding!
100	*
101	* The caller must determine and validate the string encoding _before_
102	* passing it along to functions that expect UTF-8!
103	*
104	* Also, this function does not guarantee that the returned string
105	* doesn't have embedded zeros and provides the caller no way of
106	* finding out! If you are worried about the response from the HTTPD
107	* containing embedded zero's, use RTHttpGetBinary instead.
108	*/
109	RTR3DECL(int) RTHttpGetText(RTHTTP hHttp, const char pszUrl, char *ppszNotUtf8);
110
111	/**
112	* Perform a simple blocking HTTP HEAD request.
113	*
114	* This is a just a convenient wrapper around RTHttpGetBinary that returns a
115	* different type and sheds a parameter.
116	*
117	* @returns iprt status code.
118	*
119	* @param hHttp The HTTP client handle.
120	* @param pszUrl URL.
121	* @param ppszNotUtf8 Where to return the pointer to the HTTP response.
122	* The string is of course zero terminated. Use
123	* RTHttpFreeReponseText to free.
124	*
125	* @remarks BIG FAT WARNING!
126	*
127	* This function does not guarantee the that returned string is valid UTF-8 or
128	* any other kind of text encoding!
129	*
130	* The caller must determine and validate the string encoding _before_
131	* passing it along to functions that expect UTF-8!
132	*
133	* Also, this function does not guarantee that the returned string
134	* doesn't have embedded zeros and provides the caller no way of
135	* finding out! If you are worried about the response from the HTTPD
136	* containing embedded zero's, use RTHttpGetHeaderBinary instead.
137	*/
138	RTR3DECL(int) RTHttpGetHeaderText(RTHTTP hHttp, const char pszUrl, char *ppszNotUtf8);
139
140	/**
141	* Frees memory returned by RTHttpGetText.
142	*
143	* @param pszNotUtf8 What RTHttpGetText returned.
144	*/
145	RTR3DECL(void) RTHttpFreeResponseText(char *pszNotUtf8);
146
147	/**
148	* Perform a simple blocking HTTP GET request.
149	*
150	* @returns iprt status code.
151	*
152	* @param hHttp The HTTP client handle.
153	* @param pszUrl The URL.
154	* @param ppvResponse Where to store the HTTP response data. Use
155	* RTHttpFreeResponse to free.
156	* @param pcb Size of the returned buffer.
157	*/
158	RTR3DECL(int) RTHttpGetBinary(RTHTTP hHttp, const char pszUrl, void ppvResponse, size_t pcb);
159
160	/**
161	* Perform a simple blocking HTTP HEAD request.
162	*
163	* @returns iprt status code.
164	*
165	* @param hHttp The HTTP client handle.
166	* @param pszUrl The URL.
167	* @param ppvResponse Where to store the HTTP response data. Use
168	* RTHttpFreeResponse to free.
169	* @param pcb Size of the returned buffer.
170	*/
171	RTR3DECL(int) RTHttpGetHeaderBinary(RTHTTP hHttp, const char pszUrl, void ppvResponse, size_t pcb);
172
173	/**
174	* Frees memory returned by RTHttpGetBinary.
175	*
176	* @param pvResponse What RTHttpGetBinary returned.
177	*/
178	RTR3DECL(void) RTHttpFreeResponse(void *pvResponse);
179
180	/**
181	* Perform a simple blocking HTTP request, writing the output to a file.
182	*
183	* @returns iprt status code.
184	*
185	* @param hHttp The HTTP client handle.
186	* @param pszUrl The URL.
187	* @param pszDstFile The destination file name.
188	*/
189	RTR3DECL(int) RTHttpGetFile(RTHTTP hHttp, const char pszUrl, const char pszDstFile);
190
191	/** HTTP methods. */
192	typedef enum RTHTTPMETHOD
193	{
194	RTHTTPMETHOD_INVALID = 0,
195	RTHTTPMETHOD_GET,
196	RTHTTPMETHOD_PUT,
197	RTHTTPMETHOD_POST,
198	RTHTTPMETHOD_PATCH,
199	RTHTTPMETHOD_DELETE,
200	RTHTTPMETHOD_HEAD,
201	RTHTTPMETHOD_OPTIONS,
202	RTHTTPMETHOD_TRACE,
203	RTHTTPMETHOD_END,
204	RTHTTPMETHOD_32BIT_HACK = 0x7fffffff
205	} RTHTTPMETHOD;
206
207	/**
208	* Returns the name of the HTTP method.
209	* @returns Read only string.
210	* @param enmMethod The HTTP method to name.
211	*/
212	RTR3DECL(const char *) RTHttpMethodName(RTHTTPMETHOD enmMethod);
213
214	/**
215	* Performs generic blocking HTTP request, optionally returning the body and headers.
216	*
217	* @returns IPRT status code.
218	* @param hHttp The HTTP client handle.
219	* @param pszUrl The URL.
220	* @param enmMethod The HTTP method for the request.
221	* @param pvReqBody Pointer to the request body. NULL if none.
222	* @param cbReqBody Size of the request body. Zero if none.
223	* @param puHttpStatus Where to return the HTTP status code. Optional.
224	* @param ppvHeaders Where to return the headers. Optional.
225	* @param pcbHeaders Where to return the header size.
226	* @param ppvBody Where to return the body. Optional.
227	* @param pcbBody Where to return the body size.
228	*/
229	RTR3DECL(int) RTHttpPerform(RTHTTP hHttp, const char pszUrl, RTHTTPMETHOD enmMethod, void const pvReqBody, size_t cbReqBody,
230	uint32_t puHttpStatus, void ppvHeaders, size_t pcbHeaders, void *ppvBody, size_t pcbBody);
231
232
233	/**
234	* Abort a pending HTTP request. A blocking RTHttpGet() call will return with
235	* VERR_HTTP_ABORTED. It may take some time (current cURL implementation needs
236	* up to 1 second) before the request is aborted.
237	*
238	* @returns iprt status code.
239	*
240	* @param hHttp The HTTP client handle.
241	*/
242	RTR3DECL(int) RTHttpAbort(RTHTTP hHttp);
243
244	/**
245	* Tells the HTTP interface to use the system proxy configuration.
246	*
247	* @returns iprt status code.
248	* @param hHttp The HTTP client handle.
249	*/
250	RTR3DECL(int) RTHttpUseSystemProxySettings(RTHTTP hHttp);
251
252	/**
253	* Sets up the proxy according to the specified URL.
254	*
255	* @returns IPRT status code.
256	* @retval VWRN_WRONG_TYPE if the type isn't known/supported and we defaulted to 'http'.
257	*
258	* @param hHttp The HTTP client handle.
259	* @param pszUrl The proxy URL (libproxy style):
260	*
261	* [{type}"://"][{userid}[@{password}]:]{server}[":"{port}]
262	*
263	* Valid proxy types are: http (default), https, socks4, socks4a,
264	* socks5, socks5h and direct. Support for the socks and https
265	* ones depends on the HTTP library we use.
266	*
267	* The port number defaults to 80 for http, 443 for https and 1080
268	* for the socks ones.
269	*
270	* If this starts with "direct://", then no proxy will be used.
271	* An empty or NULL string is equivalent to calling
272	* RTHttpUseSystemProxySettings().
273	*/
274	RTR3DECL(int) RTHttpSetProxyByUrl(RTHTTP hHttp, const char *pszUrl);
275
276	/**
277	* Specify proxy settings.
278	*
279	* @returns iprt status code.
280	*
281	* @param hHttp The HTTP client handle.
282	* @param pszProxyUrl URL of the proxy server.
283	* @param uPort port number of the proxy, use 0 for not specifying a port.
284	* @param pszProxyUser Username, pass NULL for no authentication.
285	* @param pszProxyPwd Password, pass NULL for no authentication.
286	*
287	* @todo This API does not allow specifying the type of proxy server... We're
288	* currently assuming it's a HTTP proxy.
289	*
290	* @deprecated Use RTHttpSetProxyByUrl.
291	*/
292	RTR3DECL(int) RTHttpSetProxy(RTHTTP hHttp, const char *pszProxyUrl, uint32_t uPort,
293	const char pszProxyUser, const char pszProxyPwd);
294
295	/**
296	* Set follow redirects (3xx)
297	*
298	* @returns iprt status code.
299	*
300	* @param hHttp The HTTP client handle.
301	* @param cMaxRedirects Max number of redirects to follow. Zero if no
302	* redirects should be followed but instead returned
303	* to caller.
304	*/
305	RTR3DECL(int) RTHttpSetFollowRedirects(RTHTTP hHttp, uint32_t cMaxRedirects);
306
307	/**
308	* Set custom raw headers.
309	*
310	* @returns iprt status code.
311	*
312	* @param hHttp The HTTP client handle.
313	* @param cHeaders Number of custom headers.
314	* @param papszHeaders Array of headers in form "foo: bar".
315	*/
316	RTR3DECL(int) RTHttpSetHeaders(RTHTTP hHttp, size_t cHeaders, const char * const *papszHeaders);
317
318	/** @name RTHTTPADDHDR_F_XXX - Flags for RTHttpAddRawHeader and RTHttpAddHeader
319	* @{ */
320	#define RTHTTPADDHDR_F_BACK UINT32_C(0) /*< Append the header. /
321	#define RTHTTPADDHDR_F_FRONT UINT32_C(1) /*< Prepend the header. /
322	/** @} */
323
324	/**
325	* Adds a raw header.
326	*
327	* @returns IPRT status code.
328	* @param hHttp The HTTP client handle.
329	* @param pszHeader Header string on the form "foo: bar".
330	* @param fFlags RTHTTPADDHDR_F_FRONT or RTHTTPADDHDR_F_BACK.
331	*/
332	RTR3DECL(int) RTHttpAddRawHeader(RTHTTP hHttp, const char *pszHeader, uint32_t fFlags);
333
334	/**
335	* Adds a header field and value.
336	*
337	* @returns IPRT status code.
338	* @param hHttp The HTTP client handle.
339	* @param pszField The header field name.
340	* @param pszValue The header field value.
341	* @param cchValue The value length or RTSTR_MAX.
342	* @param fFlags Only RTHTTPADDHDR_F_FRONT or RTHTTPADDHDR_F_BACK,
343	* may be extended with encoding controlling flags if
344	* needed later.
345	*/
346	RTR3DECL(int) RTHttpAddHeader(RTHTTP hHttp, const char pszField, const char pszValue, size_t cchValue, uint32_t fFlags);
347
348	/**
349	* Gets a header previously added using RTHttpSetHeaders, RTHttpAppendRawHeader
350	* or RTHttpAppendHeader.
351	*
352	* @returns Pointer to the header value on if found, otherwise NULL.
353	* @param hHttp The HTTP client handle.
354	* @param pszField The field name (no colon).
355	* @param cchField The length of the field name or RTSTR_MAX.
356	*/
357	RTR3DECL(const char ) RTHttpGetHeader(RTHTTP hHttp, const char pszField, size_t cchField);
358
359	/**
360	* Gets the number of headers specified by RTHttpAddHeader, RTHttpAddRawHeader or RTHttpSetHeaders.
361	*
362	* @returns Number of headers.
363	* @param hHttp The HTTP client handle.
364	* @note This can be slow and is only really intended for test cases and debugging!
365	*/
366	RTR3DECL(size_t) RTHttpGetHeaderCount(RTHTTP hHttp);
367
368	/**
369	* Gets a header by ordinal.
370	*
371	* Can be used together with RTHttpGetHeaderCount by test case and debug code to
372	* iterate headers specified by RTHttpAddHeader, RTHttpAddRawHeader or RTHttpSetHeaders.
373	*
374	* @returns The header string ("field: value").
375	* @param hHttp The HTTP client handle.
376	* @param iOrdinal The number of the header to get.
377	* @note This can be slow and is only really intended for test cases and debugging!
378	*/
379	RTR3DECL(const char *) RTHttpGetByOrdinal(RTHTTP hHttp, size_t iOrdinal);
380
381	/**
382	* Sign all headers present according to pending "Signing HTTP Messages" RFC.
383	*
384	* Currently hardcoded RSA-SHA-256 algorithm choice.
385	*
386	* @returns IPRT status code.
387	* @param hHttp The HTTP client handle.
388	* @param enmMethod The HTTP method that will be used for the request.
389	* @param pszUrl The target URL for the request.
390	* @param hKey The RSA key to use when signing.
391	* @param pszKeyId The key ID string corresponding to @a hKey.
392	* @param fFlags Reserved for future, MBZ.
393	*
394	* @note Caller is responsible for making all desired fields are present before
395	* making the call.
396	*
397	* @remarks Latest RFC draft at the time of writing:
398	* https://tools.ietf.org/html/draft-cavage-http-signatures-10
399	*/
400	RTR3DECL(int) RTHttpSignHeaders(RTHTTP hHttp, RTHTTPMETHOD enmMethod, const char *pszUrl,
401	RTCRKEY hKey, const char *pszKeyId, uint32_t fFlags);
402
403	/**
404	* Tells the HTTP client instance to gather system CA certificates into a
405	* temporary file and use it for HTTPS connections.
406	*
407	* This will be called automatically if a 'https' URL is presented and
408	* RTHttpSetCaFile hasn't been called yet.
409	*
410	* @returns IPRT status code.
411	* @param hHttp The HTTP client handle.
412	* @param pErrInfo Where to store additional error/warning information.
413	* Optional.
414	*/
415	RTR3DECL(int) RTHttpUseTemporaryCaFile(RTHTTP hHttp, PRTERRINFO pErrInfo);
416
417	/**
418	* Set a custom certification authority file, containing root certificates.
419	*
420	* @returns iprt status code.
421	*
422	* @param hHttp The HTTP client handle.
423	* @param pszCAFile File name containing root certificates.
424	*
425	* @remarks For portable HTTPS support, use RTHttpGatherCaCertsInFile and pass
426	*/
427	RTR3DECL(int) RTHttpSetCAFile(RTHTTP hHttp, const char *pszCAFile);
428
429	/**
430	* Gathers certificates into a cryptographic (certificate) store
431	*
432	* This is a just a combination of RTHttpGatherCaCertsInStore and
433	* RTCrStoreCertExportAsPem.
434	*
435	* @returns IPRT status code.
436	* @param hStore The certificate store to gather the certificates
437	* in.
438	* @param fFlags RTHTTPGATHERCACERT_F_XXX.
439	* @param pErrInfo Where to store additional error/warning information.
440	* Optional.
441	*/
442	RTR3DECL(int) RTHttpGatherCaCertsInStore(RTCRSTORE hStore, uint32_t fFlags, PRTERRINFO pErrInfo);
443
444	/**
445	* Gathers certificates into a file that can be used with RTHttpSetCAFile.
446	*
447	* This is a just a combination of RTHttpGatherCaCertsInStore and
448	* RTCrStoreCertExportAsPem.
449	*
450	* @returns IPRT status code.
451	* @param pszCaFile The output file.
452	* @param fFlags RTHTTPGATHERCACERT_F_XXX.
453	* @param pErrInfo Where to store additional error/warning information.
454	* Optional.
455	*/
456	RTR3DECL(int) RTHttpGatherCaCertsInFile(const char *pszCaFile, uint32_t fFlags, PRTERRINFO pErrInfo);
457
458	/**
459	* Callback function to be called during RTHttpGet*().
460	*
461	* Register it using RTHttpSetDownloadProgressCallback().
462	*
463	* @param hHttp The HTTP client handle.
464	* @param pvUser The user parameter specified when registering the callback.
465	* @param cbDowloadTotal The content-length value, if available.
466	* Warning! Not entirely clear what it will be if
467	* unavailable, probably 0.
468	* @param cbDowloaded How much was downloaded thus far.
469	*/
470	typedef DECLCALLBACK(void) FNRTHTTPDOWNLDPROGRCALLBACK(RTHTTP hHttp, void *pvUser, uint64_t cbDownloadTotal, uint64_t cbDownloaded);
471	/** Pointer to a download progress callback. */
472	typedef FNRTHTTPDOWNLDPROGRCALLBACK *PFNRTHTTPDOWNLDPROGRCALLBACK;
473
474	/**
475	* Set the callback function which is called during (GET)
476	*
477	* @returns IPRT status code.
478	* @param hHttp The HTTP client handle.
479	* @param pfnCallback Progress function to be called. Set it to
480	* NULL to disable the callback.
481	* @param pvUser Convenience pointer for the callback function.
482	*/
483	RTR3DECL(int) RTHttpSetDownloadProgressCallback(RTHTTP hHttp, PFNRTHTTPDOWNLDPROGRCALLBACK pfnCallback, void *pvUser);
484
485	/**
486	* Callback function for receiving body data.
487	*
488	* @returns IPRT status code.
489	* @param hHttp The HTTP client handle.
490	* @param pvBuf Pointer to buffer with body bytes.
491	* @param cbBuf Number of bytes in the buffer.
492	* @param uHttpStatus The HTTP status code.
493	* @param offContent The byte offset corresponding to the start of @a pvBuf.
494	* @param cbContent The content length field value, UINT64_MAX if not available.
495	* @param pvUser The user parameter.
496	*
497	* @note The @a offContent parameter does not imply random access or anthing
498	* like that, it is just a convenience provided by the caller. The
499	* value is the sum of the previous @a cbBuf values.
500	*/
501	typedef DECLCALLBACK(int) FNRTHTTPDOWNLOADCALLBACK(RTHTTP hHttp, void const *pvBuf, size_t cbBuf, uint32_t uHttpStatus,
502	uint64_t offContent, uint64_t cbContent, void *pvUser);
503	/** Pointer to a download data receiver callback. */
504	typedef FNRTHTTPDOWNLOADCALLBACK *PFNRTHTTPDOWNLOADCALLBACK;
505
506	/**
507	* Set the callback function for downloading data (HTTP GET).
508	*
509	* @returns IPRT status code.
510	* @param hHttp The HTTP client handle.
511	* @param fFlags RTHTTPDOWNLOAD_F_XXX.
512	* @param pfnCallback The callback function. Pass NULL to reset the callback.
513	* @param pvUser Convenience pointer for the callback function.
514	*
515	* @remarks There can only be one download callback, so it is not possible to
516	* call this method for different status codes. Only the last one
517	* with be honored.
518	*
519	* @note This only works reliably with RTHttpPerform at the moment.
520	*/
521	RTR3DECL(int) RTHttpSetDownloadCallback(RTHTTP hHttp, uint32_t fFlags, PFNRTHTTPDOWNLOADCALLBACK pfnCallback, void *pvUser);
522
523	/** @name RTHTTPDOWNLOAD_F_XXX */
524	/** The lower 10 bits gives the HTTP status required by the callback.
525	* For all other status codes, any body data will be returned via the
526	* RTHttpPerform ppvBody/pcbBody return parameters. */
527	#define RTHTTPDOWNLOAD_F_ONLY_STATUS_MASK UINT32_C(0x000003ff)
528	/** Callback requires no special HTTP status. */
529	#define RTHTTPDOWNLOAD_F_ANY_STATUS UINT32_C(0x000003ff)
530	/** @} */
531
532
533	/**
534	* Callback function for producing body data for uploading.
535	*
536	* @returns IPRT status code.
537	* @param hHttp The HTTP client handle.
538	* @param pvBuf Where to put the data to upload
539	* @param cbBuf Max number of bytes to provide.
540	* @param offContent The byte offset corresponding to the start of @a pvBuf.
541	* @param pcbActual Actual number of bytes provided.
542	* @param pvUser The user parameter.
543	*
544	* @note The @a offContent parameter does not imply random access or anthing
545	* like that, it is just a convenience provided by the caller. The
546	* value is the sum of the previously returned @a *pcbActual values.
547	*/
548	typedef DECLCALLBACK(int) FNRTHTTPUPLOADCALLBACK(RTHTTP hHttp, void *pvBuf, size_t cbBuf, uint64_t offContent,
549	size_t pcbActual, void pvUser);
550	/** Pointer to an upload data producer callback. */
551	typedef FNRTHTTPUPLOADCALLBACK *PFNRTHTTPUPLOADCALLBACK;
552
553	/**
554	* Set the callback function for providing upload data (HTTP PUT / POST).
555	*
556	* @returns IPRT status code.
557	* @param hHttp The HTTP client handle.
558	* @param cbContent The content length, UINT64_MAX if not know or specified separately.
559	* @param pfnCallback The callback function. Pass NULL to reset the callback.
560	* @param pvUser Convenience pointer for the callback function.
561	*
562	* @note This only works reliably with RTHttpPerform at the moment.
563	*/
564	RTR3DECL(int) RTHttpSetUploadCallback(RTHTTP hHttp, uint64_t cbContent, PFNRTHTTPUPLOADCALLBACK pfnCallback, void *pvUser);
565
566
567	/**
568	* Callback for consuming header fields.
569	*
570	* @returns IPRT status code.
571	* @param hHttp The HTTP client handle.
572	* @param uMatchWord Match word constructed by RTHTTP_MAKE_HDR_MATCH_WORD
573	* @param pchField The field name (not zero terminated).
574	* Not necessarily valid UTF-8!
575	* @param cchField The length of the field.
576	* @param pchValue The field value (not zero terminated).
577	* Not necessarily valid UTF-8!
578	* @param cchValue The length of the value.
579	* @param pvUser The user parameter.
580	*
581	* @remarks This is called with two fictitious header fields too:
582	* - ':http-status-line' -- the HTTP/{version} {status-code} stuff.
583	* - ':end-of-headers' -- marks the end of header callbacks.
584	*/
585	typedef DECLCALLBACK(int) FNRTHTTPHEADERCALLBACK(RTHTTP hHttp, uint32_t uMatchWord, const char *pchField, size_t cchField,
586	const char pchValue, size_t cchValue, void pvUser);
587	/** Pointer to a header field consumer callback. */
588	typedef FNRTHTTPHEADERCALLBACK *PFNRTHTTPHEADERCALLBACK;
589
590	/**
591	* Forms a fast header match word.
592	*
593	* @returns Fast header match word.
594	* @param a_cchField The length of the header field name.
595	* @param a_chLower1 The first character in the name, lowercased.
596	* @param a_chLower2 The second character in the name, lowercased.
597	* @param a_chLower3 The third character in the name, lowercased.
598	*/
599	#define RTHTTP_MAKE_HDR_MATCH_WORD(a_cchField, a_chLower1, a_chLower2, a_chLower3) \
600	RT_MAKE_U32_FROM_U8(a_cchField, a_chLower1, a_chLower2, a_chLower3)
601
602	/**
603	* Set the callback function for processing header fields in the response.
604	*
605	* @returns IPRT status code.
606	* @param hHttp The HTTP client handle.
607	* @param pfnCallback The callback function. Pass NULL to reset the callback.
608	* @param pvUser Convenience pointer for the callback function.
609	*
610	* @note This only works reliably with RTHttpPerform at the moment.
611	*/
612	RTR3DECL(int) RTHttpSetHeaderCallback(RTHTTP hHttp, PFNRTHTTPHEADERCALLBACK pfnCallback, void *pvUser);
613
614
615	/** @name thin wrappers for setting one or a few related curl options
616	* @remarks Temporary. Will not be included in the 6.0 release!
617	* @{ */
618	typedef size_t FNRTHTTPREADCALLBACKRAW(void pbDst, size_t cbItem, size_t cItems, void pvUser);
619	typedef FNRTHTTPREADCALLBACKRAW *PFNRTHTTPREADCALLBACKRAW;
620	#define RT_HTTP_READCALLBACK_ABORT 0x10000000 /* CURL_READFUNC_ABORT */
621	RTR3DECL(int) RTHttpRawSetReadCallback(RTHTTP hHttp, PFNRTHTTPREADCALLBACKRAW pfnRead, void *pvUser);
622
623	typedef size_t FNRTHTTPWRITECALLBACKRAW(char pbSrc, size_t cbItem, size_t cItems, void pvUser);
624	typedef FNRTHTTPWRITECALLBACKRAW *PFNRTHTTPWRITECALLBACKRAW;
625	RTR3DECL(int) RTHttpRawSetWriteCallback(RTHTTP hHttp, PFNRTHTTPWRITECALLBACKRAW pfnWrite, void *pvUser);
626	RTR3DECL(int) RTHttpRawSetWriteHeaderCallback(RTHTTP hHttp, PFNRTHTTPWRITECALLBACKRAW pfnWrite, void *pvUser);
627
628	RTR3DECL(int) RTHttpRawSetUrl(RTHTTP hHttp, const char *pszUrl);
629
630	RTR3DECL(int) RTHttpRawSetGet(RTHTTP hHttp);
631	RTR3DECL(int) RTHttpRawSetHead(RTHTTP hHttp);
632	RTR3DECL(int) RTHttpRawSetPost(RTHTTP hHttp);
633	RTR3DECL(int) RTHttpRawSetPut(RTHTTP hHttp);
634	RTR3DECL(int) RTHttpRawSetDelete(RTHTTP hHttp);
635	RTR3DECL(int) RTHttpRawSetCustomRequest(RTHTTP hHttp, const char *pszVerb);
636
637	RTR3DECL(int) RTHttpRawSetPostFields(RTHTTP hHttp, const void *pv, size_t cb);
638	RTR3DECL(int) RTHttpRawSetInfileSize(RTHTTP hHttp, RTFOFF cb);
639
640	RTR3DECL(int) RTHttpRawSetVerbose(RTHTTP hHttp, bool fValue);
641	RTR3DECL(int) RTHttpRawSetTimeout(RTHTTP hHttp, long sec);
642
643	RTR3DECL(int) RTHttpRawPerform(RTHTTP hHttp);
644
645	RTR3DECL(int) RTHttpRawGetResponseCode(RTHTTP hHttp, long *plCode);
646	/** @} */
647
648	/** @} */
649
650	RT_C_DECLS_END
651
652	#endif
653

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/include/iprt/http.h@ 75008

Download in other formats: