VirtualBox

source: vbox/trunk/include/iprt/http-common.h

Last change on this file was 102562, checked in by vboxsync, 5 months ago

IPRT/http: Fixed a memory leak, updated docs. bugref:9437
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 11.2 KB
Line 
1/* $Id: http-common.h 102562 2023-12-11 08:32:42Z vboxsync $ */
2/** @file
3 * IPRT - Common (client / server) HTTP 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_common_h
38#define IPRT_INCLUDED_http_common_h
39#ifndef RT_WITHOUT_PRAGMA_ONCE
40# pragma once
41#endif
42
43#include <iprt/list.h>
44#include <iprt/types.h>
45
46RT_C_DECLS_BEGIN
47
48/** HTTP methods. */
49typedef enum RTHTTPMETHOD
50{
51 RTHTTPMETHOD_INVALID = 0,
52 RTHTTPMETHOD_GET,
53 RTHTTPMETHOD_PUT,
54 RTHTTPMETHOD_POST,
55 RTHTTPMETHOD_PATCH,
56 RTHTTPMETHOD_DELETE,
57 RTHTTPMETHOD_HEAD,
58 RTHTTPMETHOD_OPTIONS,
59 RTHTTPMETHOD_TRACE,
60#ifdef IPRT_HTTP_WITH_WEBDAV
61 RTHTTPMETHOD_PROPFIND,
62#endif
63 RTHTTPMETHOD_END,
64 RTHTTPMETHOD_32BIT_HACK = 0x7fffffff
65} RTHTTPMETHOD;
66
67/** HTTP status codes. */
68typedef enum RTHTTPSTATUS
69{
70 RTHTTPSTATUS_INTERNAL_NOT_SET = 0,
71 /**
72 * 2xx - Success / information codes.
73 */
74 RTHTTPSTATUS_OK = 200,
75 RTHTTPSTATUS_CREATED = 201,
76 RTHTTPSTATUS_ACCEPTED = 202,
77 RTHTTPSTATUS_NONAUTHORITATIVEINFORMATION = 203,
78 RTHTTPSTATUS_NOCONTENT = 204,
79 RTHTTPSTATUS_RESETCONTENT = 205,
80 RTHTTPSTATUS_PARTIALCONTENT = 206,
81 RTHTTPSTATUS_MULTISTATUS = 207,
82 RTHTTPSTATUS_ALREADYREPORTED = 208,
83 RTHTTPSTATUS_IMUSED = 226,
84 /**
85 * 4xx - Client error codes.
86 */
87 RTHTTPSTATUS_BADREQUEST = 400,
88 RTHTTPSTATUS_UNAUTHORIZED = 401,
89 RTHTTPSTATUS_PAYMENTREQUIRED = 402,
90 RTHTTPSTATUS_FORBIDDEN = 403,
91 RTHTTPSTATUS_NOTFOUND = 404,
92 RTHTTPSTATUS_METHODNOTALLOWED = 405,
93 RTHTTPSTATUS_NOTACCEPTABLE = 406,
94 RTHTTPSTATUS_PROXYAUTHENTICATIONREQUIRED = 407,
95 RTHTTPSTATUS_REQUESTTIMEOUT = 408,
96 RTHTTPSTATUS_CONFLICT = 409,
97 RTHTTPSTATUS_GONE = 410,
98 RTHTTPSTATUS_LENGTHREQUIRED = 411,
99 RTHTTPSTATUS_PRECONDITIONFAILED = 412,
100 RTHTTPSTATUS_PAYLOADTOOLARGE = 413,
101 RTHTTPSTATUS_URITOOLONG = 414,
102 RTHTTPSTATUS_UNSUPPORTEDMEDIATYPE = 415,
103 RTHTTPSTATUS_RANGENOTSATISFIABLE = 416,
104 RTHTTPSTATUS_EXPECTATIONFAILED = 417,
105 RTHTTPSTATUS_IMATEAPOT = 418,
106 RTHTTPSTATUS_UNPROCESSABLEENTITY = 422,
107 RTHTTPSTATUS_LOCKED = 423,
108 RTHTTPSTATUS_FAILEDDEPENDENCY = 424,
109 RTHTTPSTATUS_UPGRADEREQUIRED = 426,
110 RTHTTPSTATUS_PRECONDITIONREQUIRED = 428,
111 RTHTTPSTATUS_TOOMANYREQUESTS = 429,
112 RTHTTPSTATUS_REQUESTHEADERFIELDSTOOLARGE = 431,
113 RTHTTPSTATUS_UNAVAILABLEFORLEGALREASONS = 451,
114 /**
115 * 5xx - Server error codes.
116 */
117 RTHTTPSTATUS_INTERNALSERVERERROR = 500,
118 RTHTTPSTATUS_NOTIMPLEMENTED = 501,
119 RTHTTPSTATUS_BADGATEWAY = 502,
120 RTHTTPSTATUS_SERVICEUNAVAILABLE = 503,
121 RTHTTPSTATUS_GATEWAYTIMEOUT = 504,
122 RTHTTPSTATUS_HTTPVERSIONNOTSUPPORTED = 505,
123 RTHTTPSTATUS_VARIANTALSONEGOTIATES = 506,
124 RTHTTPSTATUS_INSUFFICIENTSTORAGE = 507,
125 RTHTTPSTATUS_LOOPDETECTED = 508,
126 RTHTTPSTATUS_NOTEXTENDED = 510,
127 RTHTTPSTATUS_NETWORKAUTHENTICATIONREQUIRED = 511,
128
129 RTHTTPSTATUS_32BIT_HACK = 0x7fffffff
130} RTHTTPSTATUS;
131
132/** Checks whether a HTTP status is of type "informational" or not. */
133#define RTHTTPSTATUS_IS_INFO(a_Code) (a_Code >= 100 && a_Code < 200)
134/** Checks whether a HTTP status indicates success or not. */
135#define RTHTTPSTATUS_IS_OK(a_Code) (a_Code >= 200 && a_Code < 300)
136/** Checks whether a HTTP status indicates a redirection or not. */
137#define RTHTTPSTATUS_IS_REDIRECT(a_Code) (a_Code >= 300 && a_Code < 400)
138/** Checks whether a HTTP status indicates a client error or not. */
139#define RTHTTPSTATUS_IS_CLIENTERROR(a_Code) (a_Code >= 400 && a_Code < 500)
140/** Checks whether a HTTP status indicates a server error or not. */
141#define RTHTTPSTATUS_IS_SERVERERROR(a_Code) (a_Code >= 500 && a_Code < 600)
142/** Checks whether a HTTP status indicates an error or not. */
143#define RTHTTPSTATUS_IS_ERROR(a_Code) (a_Code >= 400)
144
145/** Specifies a HTTP MIME type. */
146typedef uint32_t RTHTTPMIMETYPE;
147
148#define RTHTTPMIMETYPE_TEXT_PLAIN "text/plain"
149#define RTHTTPMIMETYPE_APPLICATION_OCTET_STREAM "application/octet-stream"
150
151/** Specifies HTTP version 1.1 as a string. */
152#define RTHTTPVER_1_1_STR "HTTP/1.1"
153
154/** @todo the following three definitions may move the iprt/types.h later. */
155/** HTTP header list handle. */
156typedef R3PTRTYPE(struct RTHTTPHEADERLISTINTERNAL *) RTHTTPHEADERLIST;
157/** Pointer to a HTTP header list handle. */
158typedef RTHTTPHEADERLIST *PRTHTTPHEADERLIST;
159/** Nil HTTP HTTP header list handle. */
160#define NIL_RTHTTPHEADERLIST ((RTHTTPHEADERLIST)0)
161
162/**
163 * HTTP header list entry.
164 */
165typedef struct RTHTTPHEADERENTRY
166{
167 /** The list node. */
168 RTLISTNODE Node;
169 /** The field name length. */
170 uint32_t cchName;
171 /** The value offset. */
172 uint32_t offValue;
173 /** The full header field. */
174 RT_FLEXIBLE_ARRAY_EXTENSION
175 RT_GCC_EXTENSION char szData[RT_FLEXIBLE_ARRAY];
176} RTHTTPHEADERENTRY;
177/** Pointer to a HTTP header. */
178typedef RTHTTPHEADERENTRY *PRTHTTPHEADERENTRY;
179
180/**
181 * Structure for maintaining a HTTP body.
182 */
183typedef struct RTHTTPBODY
184{
185 /** Body to send, if any. Can be NULL. */
186 void *pvBody;
187 /** Body allocation size (in bytes). */
188 size_t cbBodyAlloc;
189 /** How much body data is being used (in bytes). */
190 size_t cbBodyUsed;
191 /** Current body data read/write offset (in bytes). */
192 size_t offBody;
193} RTHTTPBODY;
194/** Pointer to a HTTP body. */
195typedef RTHTTPBODY *PRTHTTPBODY;
196
197/**
198 * Returns the name of the HTTP method as a string.
199 *
200 * @returns Read only string.
201 * @param enmMethod The HTTP method to return string for.
202 */
203RTR3DECL(const char *) RTHttpMethodToStr(RTHTTPMETHOD enmMethod);
204
205/**
206 * Returns the name of the HTTP status as a string.
207 *
208 * @returns Read only string.
209 * @param enmSts The HTTP status to return string for.
210 */
211RTR3DECL(const char *) RTHttpStatusToStr(RTHTTPSTATUS enmSts);
212
213/**
214 * Initializes an HTTP header list.
215 *
216 * @returns VBox status code.
217 * @param hHdrList Header list to initialize.
218 */
219RTR3DECL(int) RTHttpHeaderListInit(PRTHTTPHEADERLIST hHdrList);
220
221/**
222 * Destroys an HTTP header list.
223 *
224 * @param hHdrList Header list to destroy.
225 * The object will be invalid on return.
226 */
227RTR3DECL(void) RTHttpHeaderListDestroy(RTHTTPHEADERLIST hHdrList);
228
229/**
230 * Set custom raw headers.
231 *
232 * @returns IPRT status code.
233 * @param hHdrLst The HTTP header list handle.
234 * @param cHeaders Number of custom headers.
235 * @param papszHeaders Array of headers in form "foo: bar".
236 */
237RTR3DECL(int) RTHttpHeaderListSet(RTHTTPHEADERLIST hHdrLst, size_t cHeaders, const char * const *papszHeaders);
238
239/** @name RTHTTPHEADERLISTADD_F_XXX - Flags for RTHttpHeaderListAddRaw and RTHttpHeaderListAdd
240 * @{ */
241#define RTHTTPHEADERLISTADD_F_BACK UINT32_C(0) /**< Append the header. */
242#define RTHTTPHEADERLISTADD_F_FRONT UINT32_C(1) /**< Prepend the header. */
243/** @} */
244
245/**
246 * Adds a raw header.
247 *
248 * @returns IPRT status code.
249 * @param hHdrLst The HTTP header list handle.
250 * @param pszHeader Header string on the form "foo: bar".
251 * @param fFlags RTHTTPADDHDR_F_FRONT or RTHTTPADDHDR_F_BACK.
252 */
253RTR3DECL(int) RTHttpHeaderListAddRaw(RTHTTPHEADERLIST hHdrLst, const char *pszHeader, uint32_t fFlags);
254
255/**
256 * Adds a header field and value.
257 *
258 * @returns IPRT status code.
259 * @param hHdrLst The HTTP header list handle.
260 * @param pszField The header field name.
261 * @param pszValue The header field value.
262 * @param cchValue The value length or RTSTR_MAX.
263 * @param fFlags Only RTHTTPADDHDR_F_FRONT or RTHTTPADDHDR_F_BACK,
264 * may be extended with encoding controlling flags if
265 * needed later.
266 */
267RTR3DECL(int) RTHttpHeaderListAdd(RTHTTPHEADERLIST hHdrLst, const char *pszField, const char *pszValue, size_t cchValue, uint32_t fFlags);
268
269/**
270 * Gets a header previously added using RTHttpSetHeaders, RTHttpAppendRawHeader
271 * or RTHttpAppendHeader.
272 *
273 * @returns Pointer to the header value on if found, otherwise NULL.
274 * @param hHdrLst The HTTP header list handle.
275 * @param pszField The field name (no colon).
276 * @param cchField The length of the field name or RTSTR_MAX.
277 */
278RTR3DECL(const char *) RTHttpHeaderListGet(RTHTTPHEADERLIST hHdrLst, const char *pszField, size_t cchField);
279
280/**
281 * Gets the number of headers specified by RTHttpAddHeader, RTHttpAddRawHeader or RTHttpSetHeaders.
282 *
283 * @returns Number of headers.
284 * @param hHdrLst The HTTP header list handle.
285 * @note This can be slow and is only really intended for test cases and debugging!
286 */
287RTR3DECL(size_t) RTHttpHeaderListGetCount(RTHTTPHEADERLIST hHdrLst);
288
289/**
290 * Gets a header by ordinal.
291 *
292 * Can be used together with RTHttpGetHeaderCount by test case and debug code to
293 * iterate headers specified by RTHttpAddHeader, RTHttpAddRawHeader or RTHttpSetHeaders.
294 *
295 * @returns The header string ("field: value").
296 * @param hHdrLst The HTTP header list handle.
297 * @param iOrdinal The number of the header to get.
298 * @note This can be slow and is only really intended for test cases and debugging!
299 */
300RTR3DECL(const char *) RTHttpHeaderListGetByOrdinal(RTHTTPHEADERLIST hHdrLst, size_t iOrdinal);
301
302RT_C_DECLS_END
303
304#endif /* !IPRT_INCLUDED_http_common_h */
305
Note: See TracBrowser for help on using the repository browser.

© 2023 Oracle
Contact – Privacy policy – Terms of Use