http.h@ 81372

Last change on this file since 81372 was 81369, checked in by vboxsync, 5 years ago
*: doxygen fixes
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 26.7 KB

Line
1	/* $Id: http.h 81369 2019-10-18 21:13:03Z vboxsync $ */
2	/** @file
3	* IPRT - Simple HTTP/HTTPS Client API.
4	*/
5
6	/*
7	* Copyright (C) 2012-2019 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 DECLCALLBACK(void) FNRTHTTPDOWNLDPROGRCALLBACK(RTHTTP hHttp, void *pvUser, uint64_t cbDownloadTotal, uint64_t cbDownloaded);
518	/** Pointer to a download progress callback. */
519	typedef FNRTHTTPDOWNLDPROGRCALLBACK *PFNRTHTTPDOWNLDPROGRCALLBACK;
520
521	/**
522	* Set the callback function which is called during (GET)
523	*
524	* @returns IPRT status code.
525	* @param hHttp The HTTP client handle.
526	* @param pfnCallback Progress function to be called. Set it to
527	* NULL to disable the callback.
528	* @param pvUser Convenience pointer for the callback function.
529	*/
530	RTR3DECL(int) RTHttpSetDownloadProgressCallback(RTHTTP hHttp, PFNRTHTTPDOWNLDPROGRCALLBACK pfnCallback, void *pvUser);
531
532	/**
533	* Callback function for receiving body data.
534	*
535	* @returns IPRT status code.
536	* @param hHttp The HTTP client handle.
537	* @param pvBuf Pointer to buffer with body bytes.
538	* @param cbBuf Number of bytes in the buffer.
539	* @param uHttpStatus The HTTP status code.
540	* @param offContent The byte offset corresponding to the start of @a pvBuf.
541	* @param cbContent The content length field value, UINT64_MAX if not available.
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 previous @a cbBuf values.
547	*/
548	typedef DECLCALLBACK(int) FNRTHTTPDOWNLOADCALLBACK(RTHTTP hHttp, void const *pvBuf, size_t cbBuf, uint32_t uHttpStatus,
549	uint64_t offContent, uint64_t cbContent, void *pvUser);
550	/** Pointer to a download data receiver callback. */
551	typedef FNRTHTTPDOWNLOADCALLBACK *PFNRTHTTPDOWNLOADCALLBACK;
552
553	/**
554	* Set the callback function for downloading data (HTTP GET).
555	*
556	* @returns IPRT status code.
557	* @param hHttp The HTTP client handle.
558	* @param fFlags RTHTTPDOWNLOAD_F_XXX.
559	* @param pfnCallback The callback function. Pass NULL to reset the callback.
560	* @param pvUser Convenience pointer for the callback function.
561	*
562	* @remarks There can only be one download callback, so it is not possible to
563	* call this method for different status codes. Only the last one
564	* with be honored.
565	*
566	* @note This only works reliably with RTHttpPerform at the moment.
567	*/
568	RTR3DECL(int) RTHttpSetDownloadCallback(RTHTTP hHttp, uint32_t fFlags, PFNRTHTTPDOWNLOADCALLBACK pfnCallback, void *pvUser);
569
570	/** @name RTHTTPDOWNLOAD_F_XXX
571	* @{ */
572	/** The lower 10 bits gives the HTTP status required by the callback.
573	* For all other status codes, any body data will be returned via the
574	* RTHttpPerform ppvBody/pcbBody return parameters. */
575	#define RTHTTPDOWNLOAD_F_ONLY_STATUS_MASK UINT32_C(0x000003ff)
576	/** Callback requires no special HTTP status. */
577	#define RTHTTPDOWNLOAD_F_ANY_STATUS UINT32_C(0x000003ff)
578	/** @} */
579
580
581	/**
582	* Callback function for producing body data for uploading.
583	*
584	* @returns IPRT status code.
585	* @param hHttp The HTTP client handle.
586	* @param pvBuf Where to put the data to upload
587	* @param cbBuf Max number of bytes to provide.
588	* @param offContent The byte offset corresponding to the start of @a pvBuf.
589	* @param pcbActual Actual number of bytes provided.
590	* @param pvUser The user parameter.
591	*
592	* @note The @a offContent parameter does not imply random access or anthing
593	* like that, it is just a convenience provided by the caller. The
594	* value is the sum of the previously returned @a *pcbActual values.
595	*/
596	typedef DECLCALLBACK(int) FNRTHTTPUPLOADCALLBACK(RTHTTP hHttp, void *pvBuf, size_t cbBuf, uint64_t offContent,
597	size_t pcbActual, void pvUser);
598	/** Pointer to an upload data producer callback. */
599	typedef FNRTHTTPUPLOADCALLBACK *PFNRTHTTPUPLOADCALLBACK;
600
601	/**
602	* Set the callback function for providing upload data (HTTP PUT / POST).
603	*
604	* @returns IPRT status code.
605	* @param hHttp The HTTP client handle.
606	* @param cbContent The content length, UINT64_MAX if not know or specified separately.
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) RTHttpSetUploadCallback(RTHTTP hHttp, uint64_t cbContent, PFNRTHTTPUPLOADCALLBACK pfnCallback, void *pvUser);
613
614
615	/**
616	* Callback for consuming header fields.
617	*
618	* @returns IPRT status code.
619	* @param hHttp The HTTP client handle.
620	* @param uMatchWord Match word constructed by RTHTTP_MAKE_HDR_MATCH_WORD
621	* @param pchField The field name (not zero terminated).
622	* Not necessarily valid UTF-8!
623	* @param cchField The length of the field.
624	* @param pchValue The field value (not zero terminated).
625	* Not necessarily valid UTF-8!
626	* @param cchValue The length of the value.
627	* @param pvUser The user parameter.
628	*
629	* @remarks This is called with two fictitious header fields too:
630	* - ':http-status-line' -- the HTTP/{version} {status-code} stuff.
631	* - ':end-of-headers' -- marks the end of header callbacks.
632	*/
633	typedef DECLCALLBACK(int) FNRTHTTPHEADERCALLBACK(RTHTTP hHttp, uint32_t uMatchWord, const char *pchField, size_t cchField,
634	const char pchValue, size_t cchValue, void pvUser);
635	/** Pointer to a header field consumer callback. */
636	typedef FNRTHTTPHEADERCALLBACK *PFNRTHTTPHEADERCALLBACK;
637
638	/**
639	* Forms a fast header match word.
640	*
641	* @returns Fast header match word.
642	* @param a_cchField The length of the header field name.
643	* @param a_chLower1 The first character in the name, lowercased.
644	* @param a_chLower2 The second character in the name, lowercased.
645	* @param a_chLower3 The third character in the name, lowercased.
646	*/
647	#define RTHTTP_MAKE_HDR_MATCH_WORD(a_cchField, a_chLower1, a_chLower2, a_chLower3) \
648	RT_MAKE_U32_FROM_U8(a_cchField, a_chLower1, a_chLower2, a_chLower3)
649
650	/**
651	* Set the callback function for processing header fields in the response.
652	*
653	* @returns IPRT status code.
654	* @param hHttp The HTTP client handle.
655	* @param pfnCallback The callback function. Pass NULL to reset the callback.
656	* @param pvUser Convenience pointer for the callback function.
657	*
658	* @note This only works reliably with RTHttpPerform at the moment.
659	*/
660	RTR3DECL(int) RTHttpSetHeaderCallback(RTHTTP hHttp, PFNRTHTTPHEADERCALLBACK pfnCallback, void *pvUser);
661
662
663	/** @name thin wrappers for setting one or a few related curl options
664	* @remarks Temporary. Will not be included in the 6.0 release!
665	* @{ */
666	typedef size_t FNRTHTTPREADCALLBACKRAW(void pbDst, size_t cbItem, size_t cItems, void pvUser);
667	typedef FNRTHTTPREADCALLBACKRAW *PFNRTHTTPREADCALLBACKRAW;
668	#define RT_HTTP_READCALLBACK_ABORT 0x10000000 /* CURL_READFUNC_ABORT */
669	RTR3DECL(int) RTHttpRawSetReadCallback(RTHTTP hHttp, PFNRTHTTPREADCALLBACKRAW pfnRead, void *pvUser);
670
671	typedef size_t FNRTHTTPWRITECALLBACKRAW(char pbSrc, size_t cbItem, size_t cItems, void pvUser);
672	typedef FNRTHTTPWRITECALLBACKRAW *PFNRTHTTPWRITECALLBACKRAW;
673	RTR3DECL(int) RTHttpRawSetWriteCallback(RTHTTP hHttp, PFNRTHTTPWRITECALLBACKRAW pfnWrite, void *pvUser);
674	RTR3DECL(int) RTHttpRawSetWriteHeaderCallback(RTHTTP hHttp, PFNRTHTTPWRITECALLBACKRAW pfnWrite, void *pvUser);
675
676	RTR3DECL(int) RTHttpRawSetUrl(RTHTTP hHttp, const char *pszUrl);
677
678	RTR3DECL(int) RTHttpRawSetGet(RTHTTP hHttp);
679	RTR3DECL(int) RTHttpRawSetHead(RTHTTP hHttp);
680	RTR3DECL(int) RTHttpRawSetPost(RTHTTP hHttp);
681	RTR3DECL(int) RTHttpRawSetPut(RTHTTP hHttp);
682	RTR3DECL(int) RTHttpRawSetDelete(RTHTTP hHttp);
683	RTR3DECL(int) RTHttpRawSetCustomRequest(RTHTTP hHttp, const char *pszVerb);
684
685	RTR3DECL(int) RTHttpRawSetPostFields(RTHTTP hHttp, const void *pv, size_t cb);
686	RTR3DECL(int) RTHttpRawSetInfileSize(RTHTTP hHttp, RTFOFF cb);
687
688	RTR3DECL(int) RTHttpRawSetVerbose(RTHTTP hHttp, bool fValue);
689	RTR3DECL(int) RTHttpRawSetTimeout(RTHTTP hHttp, long sec);
690
691	RTR3DECL(int) RTHttpRawPerform(RTHTTP hHttp);
692
693	RTR3DECL(int) RTHttpRawGetResponseCode(RTHTTP hHttp, long *plCode);
694	/** @} */
695
696	/** @} */
697
698	RT_C_DECLS_END
699
700	#endif /* !IPRT_INCLUDED_http_h */
701

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

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

Download in other formats: