VirtualBox

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

Last change on this file since 103224 was 98103, checked in by vboxsync, 21 months ago

Copyright year updates by scm.

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

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette