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