VirtualBox

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

Last change on this file since 47908 was 46070, checked in by vboxsync, 12 years ago

RTDbgCfg,++: Compressed server files and other fixes.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 5.3 KB
Line 
1/* $Id: http.h 46070 2013-05-14 15:21:57Z vboxsync $ */
2/** @file
3 * IPRT - Simple HTTP Communication API.
4 */
5
6/*
7 * Copyright (C) 2012-2013 Oracle Corporation
8 *
9 * This file is part of VirtualBox Open Source Edition (OSE), as
10 * available from http://www.virtualbox.org. This file is free software;
11 * you can redistribute it and/or modify it under the terms of the GNU
12 * General Public License (GPL) as published by the Free Software
13 * Foundation, in version 2 as it comes in the "COPYING" file of the
14 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
15 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
16 *
17 * The contents of this file may alternatively be used under the terms
18 * of the Common Development and Distribution License Version 1.0
19 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
20 * VirtualBox OSE distribution, in which case the provisions of the
21 * CDDL are applicable instead of those of the GPL.
22 *
23 * You may elect to license modified versions of this file under the
24 * terms and conditions of either the GPL or the CDDL or both.
25 */
26
27#ifndef ___iprt_http_h
28#define ___iprt_http_h
29
30#include <iprt/types.h>
31
32RT_C_DECLS_BEGIN
33
34/** @defgroup grp_rt_http RTHttp - Simple HTTP API
35 * @ingroup grp_rt
36 * @{
37 */
38
39/** @todo the following three definitions may move the iprt/types.h later. */
40/** RTHTTP interface handle. */
41typedef R3PTRTYPE(struct RTHTTPINTERNAL *) RTHTTP;
42/** Pointer to a RTHTTP interface handle. */
43typedef RTHTTP *PRTHTTP;
44/** Nil RTHTTP interface handle. */
45#define NIL_RTHTTP ((RTHTTP)0)
46
47
48/**
49 * Creates a HTTP interface handle.
50 *
51 * @returns iprt status code.
52 *
53 * @param phHttp Where to store the HTTP handle.
54 */
55RTR3DECL(int) RTHttpCreate(PRTHTTP phHttp);
56
57/**
58 * Destroys a HTTP interface handle.
59 *
60 * @param hHttp Handle to the HTTP interface.
61 */
62RTR3DECL(void) RTHttpDestroy(RTHTTP hHttp);
63
64/**
65 * Perform a simple blocking HTTP request.
66 *
67 * @returns iprt status code.
68 *
69 * @param hHttp HTTP interface handle.
70 * @param pcszUrl URL.
71 * @param ppszResponse HTTP response. It is guaranteed that this string is
72 * '\0'-terminated.
73 */
74RTR3DECL(int) RTHttpGet(RTHTTP hHttp, const char *pcszUrl, char **ppszResponse);
75
76/**
77 * Perform a simple blocking HTTP request, writing the output to a file.
78 *
79 * @returns iprt status code.
80 *
81 * @param hHttp HTTP interface handle.
82 * @param pszUrl URL.
83 * @param pszDstFile The destination file name.
84 */
85RTR3DECL(int) RTHttpGetFile(RTHTTP hHttp, const char *pszUrl, const char *pszDstFile);
86
87/**
88 * Abort a pending HTTP request. A blocking RTHttpGet() call will return with
89 * VERR_HTTP_ABORTED. It may take some time (current cURL implementation needs
90 * up to 1 second) before the request is aborted.
91 *
92 * @returns iprt status code.
93 *
94 * @param hHttp HTTP interface handle.
95 */
96RTR3DECL(int) RTHttpAbort(RTHTTP hHttp);
97
98/**
99 * Tells the HTTP interface to use the system proxy configuration.
100 *
101 * @returns iprt status code.
102 * @param hHttp HTTP interface handle.
103 */
104RTR3DECL(int) RTHttpUseSystemProxySettings(RTHTTP hHttp);
105
106/**
107 * Specify proxy settings.
108 *
109 * @returns iprt status code.
110 *
111 * @param hHttp HTTP interface handle.
112 * @param pcszProxy URL of the proxy
113 * @param uPort port number of the proxy, use 0 for not specifying a port.
114 * @param pcszUser username, pass NULL for no authentication
115 * @param pcszPwd password, pass NULL for no authentication
116 */
117RTR3DECL(int) RTHttpSetProxy(RTHTTP hHttp, const char *pcszProxyUrl, uint32_t uPort,
118 const char *pcszProxyUser, const char *pcszProxyPwd);
119
120/**
121 * Set custom headers.
122 *
123 * @returns iprt status code.
124 *
125 * @param hHttp HTTP interface handle.
126 * @param cHeaders number of custom headers.
127 * @param pcszHeaders array of headers in form "foo: bar".
128 */
129RTR3DECL(int) RTHttpSetHeaders(RTHTTP hHttp, size_t cHeaders, const char * const *papszHeaders);
130
131/**
132 * Set a custom certification authority file, containing root certificates.
133 *
134 * @returns iprt status code.
135 *
136 * @param hHttp HTTP interface handle.
137 * @param pcszCAFile File name containing root certificates.
138 */
139RTR3DECL(int) RTHttpSetCAFile(RTHTTP hHttp, const char *pcszCAFile);
140
141
142/**
143 * Determine the digest (fingerprint) of a certificate. Allocate memory for
144 * storing the SHA1 fingerprint as well as the SHA512 fingerprint. This
145 * memory has to be freed by RTMemFree().
146 *
147 * @todo Move this function to somewhere else.
148 *
149 * @returns iprt status code.
150 *
151 * @param hHttp HTTP interface handle (ignored).
152 * @param pcszCert The certificate in PEM format.
153 * @param cbCert Size of the certificate.
154 * @param pabSha1 Where to store the pointer to the SHA1 fingerprint.
155 * @param pcbSha1 Where to store the size of the SHA1 fingerprint.
156 * @param pabSha512 Where to store the pointer to the SHA512 fingerprint.
157 * @param pcbSha512 Where to store the size of the SHA512 fingerprint.
158 */
159RTR3DECL(int) RTHttpCertDigest(RTHTTP hHttp, char *pcszCert, size_t cbCert,
160 uint8_t **pabSha1, size_t *pcbSha1,
161 uint8_t **pabSha512, size_t *pcbSha512);
162
163
164/** @} */
165
166RT_C_DECLS_END
167
168#endif
169
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