http.h@ 76327

Last change on this file since 76327 was 75108, checked in by vboxsync, 6 years ago
IPRT/http: Extended RTHttpReset with a flag parameter so headers can be kept. bugref:9167
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 25.5 KB

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

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

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

Download in other formats: