http.h@ 92258

Last change on this file since 92258 was 90839, checked in by vboxsync, 3 years ago
IPRT: Doxygen fixes.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 28.1 KB

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

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

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

Download in other formats: