http.h@ 86716

Last change on this file since 86716 was 85650, checked in by vboxsync, 4 years ago
IPRT/http,VBoxManage,CloudGateway: Corrections to the proxy information retrival interface. Main problem was that it did not include the possibility of indicating that no proxying was needed. Corrected user code to not use uProxyPort when it's set to UINT32_MAX. Bunch of cleanups. Completely untested. bugref:9469
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 28.6 KB

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

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

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

Download in other formats: