summaryrefslogtreecommitdiffstats
path: root/include/iprt/http-common.h
diff options
context:
space:
mode:
Diffstat (limited to 'include/iprt/http-common.h')
-rw-r--r--include/iprt/http-common.h286
1 files changed, 286 insertions, 0 deletions
diff --git a/include/iprt/http-common.h b/include/iprt/http-common.h
new file mode 100644
index 00000000..d9cc746f
--- /dev/null
+++ b/include/iprt/http-common.h
@@ -0,0 +1,286 @@
+/* $Id: http-common.h $ */
+/** @file
+ * IPRT - Common (client / server) HTTP API.
+ */
+
+/*
+ * Copyright (C) 2012-2022 Oracle and/or its affiliates.
+ *
+ * This file is part of VirtualBox base platform packages, as
+ * available from https://www.virtualbox.org.
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation, in version 3 of the
+ * License.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, see <https://www.gnu.org/licenses>.
+ *
+ * The contents of this file may alternatively be used under the terms
+ * of the Common Development and Distribution License Version 1.0
+ * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
+ * in the VirtualBox 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.
+ *
+ * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
+ */
+
+#ifndef IPRT_INCLUDED_http_common_h
+#define IPRT_INCLUDED_http_common_h
+#ifndef RT_WITHOUT_PRAGMA_ONCE
+# pragma once
+#endif
+
+#include <iprt/list.h>
+#include <iprt/types.h>
+
+RT_C_DECLS_BEGIN
+
+/** HTTP methods. */
+typedef enum RTHTTPMETHOD
+{
+ RTHTTPMETHOD_INVALID = 0,
+ RTHTTPMETHOD_GET,
+ RTHTTPMETHOD_PUT,
+ RTHTTPMETHOD_POST,
+ RTHTTPMETHOD_PATCH,
+ RTHTTPMETHOD_DELETE,
+ RTHTTPMETHOD_HEAD,
+ RTHTTPMETHOD_OPTIONS,
+ RTHTTPMETHOD_TRACE,
+#ifdef IPRT_HTTP_WITH_WEBDAV
+ RTHTTPMETHOD_PROPFIND,
+#endif
+ RTHTTPMETHOD_END,
+ RTHTTPMETHOD_32BIT_HACK = 0x7fffffff
+} RTHTTPMETHOD;
+
+/** HTTP status codes. */
+typedef enum RTHTTPSTATUS
+{
+ RTHTTPSTATUS_INTERNAL_NOT_SET = 0,
+ /**
+ * 2xx - Success / information codes.
+ */
+ RTHTTPSTATUS_OK = 200,
+ RTHTTPSTATUS_CREATED = 201,
+ RTHTTPSTATUS_ACCEPTED = 202,
+ RTHTTPSTATUS_NONAUTHORITATIVEINFORMATION = 203,
+ RTHTTPSTATUS_NOCONTENT = 204,
+ RTHTTPSTATUS_RESETCONTENT = 205,
+ RTHTTPSTATUS_PARTIALCONTENT = 206,
+ RTHTTPSTATUS_MULTISTATUS = 207,
+ RTHTTPSTATUS_ALREADYREPORTED = 208,
+ RTHTTPSTATUS_IMUSED = 226,
+ /**
+ * 4xx - Client error codes.
+ */
+ RTHTTPSTATUS_BADREQUEST = 400,
+ RTHTTPSTATUS_UNAUTHORIZED = 401,
+ RTHTTPSTATUS_PAYMENTREQUIRED = 402,
+ RTHTTPSTATUS_FORBIDDEN = 403,
+ RTHTTPSTATUS_NOTFOUND = 404,
+ RTHTTPSTATUS_METHODNOTALLOWED = 405,
+ RTHTTPSTATUS_NOTACCEPTABLE = 406,
+ RTHTTPSTATUS_PROXYAUTHENTICATIONREQUIRED = 407,
+ RTHTTPSTATUS_REQUESTTIMEOUT = 408,
+ RTHTTPSTATUS_CONFLICT = 409,
+ RTHTTPSTATUS_GONE = 410,
+ RTHTTPSTATUS_LENGTHREQUIRED = 411,
+ RTHTTPSTATUS_PRECONDITIONFAILED = 412,
+ RTHTTPSTATUS_PAYLOADTOOLARGE = 413,
+ RTHTTPSTATUS_URITOOLONG = 414,
+ RTHTTPSTATUS_UNSUPPORTEDMEDIATYPE = 415,
+ RTHTTPSTATUS_RANGENOTSATISFIABLE = 416,
+ RTHTTPSTATUS_EXPECTATIONFAILED = 417,
+ RTHTTPSTATUS_IMATEAPOT = 418,
+ RTHTTPSTATUS_UNPROCESSABLEENTITY = 422,
+ RTHTTPSTATUS_LOCKED = 423,
+ RTHTTPSTATUS_FAILEDDEPENDENCY = 424,
+ RTHTTPSTATUS_UPGRADEREQUIRED = 426,
+ RTHTTPSTATUS_PRECONDITIONREQUIRED = 428,
+ RTHTTPSTATUS_TOOMANYREQUESTS = 429,
+ RTHTTPSTATUS_REQUESTHEADERFIELDSTOOLARGE = 431,
+ RTHTTPSTATUS_UNAVAILABLEFORLEGALREASONS = 451,
+ /**
+ * 5xx - Server error codes.
+ */
+ RTHTTPSTATUS_INTERNALSERVERERROR = 500,
+ RTHTTPSTATUS_NOTIMPLEMENTED = 501,
+ RTHTTPSTATUS_BADGATEWAY = 502,
+ RTHTTPSTATUS_SERVICEUNAVAILABLE = 503,
+ RTHTTPSTATUS_GATEWAYTIMEOUT = 504,
+ RTHTTPSTATUS_HTTPVERSIONNOTSUPPORTED = 505,
+ RTHTTPSTATUS_VARIANTALSONEGOTIATES = 506,
+ RTHTTPSTATUS_INSUFFICIENTSTORAGE = 507,
+ RTHTTPSTATUS_LOOPDETECTED = 508,
+ RTHTTPSTATUS_NOTEXTENDED = 510,
+ RTHTTPSTATUS_NETWORKAUTHENTICATIONREQUIRED = 511,
+
+ RTHTTPSTATUS_32BIT_HACK = 0x7fffffff
+} RTHTTPSTATUS;
+
+/** Checks whether a HTTP status is of type "informational" or not. */
+#define RTHTTPSTATUS_IS_INFO(a_Code) (a_Code >= 100 && a_Code < 200)
+/** Checks whether a HTTP status indicates success or not. */
+#define RTHTTPSTATUS_IS_OK(a_Code) (a_Code >= 200 && a_Code < 300)
+/** Checks whether a HTTP status indicates a redirection or not. */
+#define RTHTTPSTATUS_IS_REDIRECT(a_Code) (a_Code >= 300 && a_Code < 400)
+/** Checks whether a HTTP status indicates a client error or not. */
+#define RTHTTPSTATUS_IS_CLIENTERROR(a_Code) (a_Code >= 400 && a_Code < 500)
+/** Checks whether a HTTP status indicates a server error or not. */
+#define RTHTTPSTATUS_IS_SERVERERROR(a_Code) (a_Code >= 500 && a_Code < 600)
+/** Checks whether a HTTP status indicates an error or not. */
+#define RTHTTPSTATUS_IS_ERROR(a_Code) (a_Code >= 400)
+
+/** Specifies a HTTP MIME type. */
+typedef uint32_t RTHTTPMIMETYPE;
+
+#define RTHTTPMIMETYPE_TEXT_PLAIN "text/plain"
+#define RTHTTPMIMETYPE_APPLICATION_OCTET_STREAM "application/octet-stream"
+
+/** Specifies HTTP version 1.1 as a string. */
+#define RTHTTPVER_1_1_STR "HTTP/1.1"
+
+/** @todo the following three definitions may move the iprt/types.h later. */
+/** HTTP header list handle. */
+typedef R3PTRTYPE(struct RTHTTPHEADERLISTINTERNAL *) RTHTTPHEADERLIST;
+/** Pointer to a HTTP header list handle. */
+typedef RTHTTPHEADERLIST *PRTHTTPHEADERLIST;
+/** Nil HTTP HTTP header list handle. */
+#define NIL_RTHTTPHEADERLIST ((RTHTTPHEADERLIST)0)
+
+/**
+ * HTTP header list entry.
+ */
+typedef struct RTHTTPHEADERENTRY
+{
+ /** The list node. */
+ RTLISTNODE Node;
+ /** The field name length. */
+ uint32_t cchName;
+ /** The value offset. */
+ uint32_t offValue;
+ /** The full header field. */
+ RT_FLEXIBLE_ARRAY_EXTENSION
+ RT_GCC_EXTENSION char szData[RT_FLEXIBLE_ARRAY];
+} RTHTTPHEADERENTRY;
+/** Pointer to a HTTP header. */
+typedef RTHTTPHEADERENTRY *PRTHTTPHEADERENTRY;
+
+/**
+ * Structure for maintaining a HTTP body.
+ */
+typedef struct RTHTTPBODY
+{
+ /** Body to send, if any. Can be NULL. */
+ void *pvBody;
+ /** Body allocation size (in bytes). */
+ size_t cbBodyAlloc;
+ /** How much body data is being used (in bytes). */
+ size_t cbBodyUsed;
+ /** Current body data read/write offset (in bytes). */
+ size_t offBody;
+} RTHTTPBODY;
+/** Pointer to a HTTP body. */
+typedef RTHTTPBODY *PRTHTTPBODY;
+
+/**
+ * Returns the name of the HTTP method.
+ * @returns Read only string.
+ * @param enmMethod The HTTP method to name.
+ */
+RTR3DECL(const char *) RTHttpMethodToStr(RTHTTPMETHOD enmMethod);
+
+RTR3DECL(const char *) RTHttpStatusToStr(RTHTTPSTATUS enmSts);
+
+RTR3DECL(int) RTHttpHeaderListInit(PRTHTTPHEADERLIST hHdrList);
+
+RTR3DECL(void) RTHttpHeaderListDestroy(RTHTTPHEADERLIST hHdrList);
+
+/**
+ * Set custom raw headers.
+ *
+ * @returns IPRT status code.
+ * @param hHdrLst The HTTP header list handle.
+ * @param cHeaders Number of custom headers.
+ * @param papszHeaders Array of headers in form "foo: bar".
+ */
+RTR3DECL(int) RTHttpHeaderListSet(RTHTTPHEADERLIST hHdrLst, size_t cHeaders, const char * const *papszHeaders);
+
+/** @name RTHTTPHEADERLISTADD_F_XXX - Flags for RTHttpHeaderListAddRaw and RTHttpHeaderListAdd
+ * @{ */
+#define RTHTTPHEADERLISTADD_F_BACK UINT32_C(0) /**< Append the header. */
+#define RTHTTPHEADERLISTADD_F_FRONT UINT32_C(1) /**< Prepend the header. */
+/** @} */
+
+/**
+ * Adds a raw header.
+ *
+ * @returns IPRT status code.
+ * @param hHdrLst The HTTP header list handle.
+ * @param pszHeader Header string on the form "foo: bar".
+ * @param fFlags RTHTTPADDHDR_F_FRONT or RTHTTPADDHDR_F_BACK.
+ */
+RTR3DECL(int) RTHttpHeaderListAddRaw(RTHTTPHEADERLIST hHdrLst, const char *pszHeader, uint32_t fFlags);
+
+/**
+ * Adds a header field and value.
+ *
+ * @returns IPRT status code.
+ * @param hHdrLst The HTTP header list handle.
+ * @param pszField The header field name.
+ * @param pszValue The header field value.
+ * @param cchValue The value length or RTSTR_MAX.
+ * @param fFlags Only RTHTTPADDHDR_F_FRONT or RTHTTPADDHDR_F_BACK,
+ * may be extended with encoding controlling flags if
+ * needed later.
+ */
+RTR3DECL(int) RTHttpHeaderListAdd(RTHTTPHEADERLIST hHdrLst, const char *pszField, const char *pszValue, size_t cchValue, uint32_t fFlags);
+
+/**
+ * Gets a header previously added using RTHttpSetHeaders, RTHttpAppendRawHeader
+ * or RTHttpAppendHeader.
+ *
+ * @returns Pointer to the header value on if found, otherwise NULL.
+ * @param hHdrLst The HTTP header list handle.
+ * @param pszField The field name (no colon).
+ * @param cchField The length of the field name or RTSTR_MAX.
+ */
+RTR3DECL(const char *) RTHttpHeaderListGet(RTHTTPHEADERLIST hHdrLst, const char *pszField, size_t cchField);
+
+/**
+ * Gets the number of headers specified by RTHttpAddHeader, RTHttpAddRawHeader or RTHttpSetHeaders.
+ *
+ * @returns Number of headers.
+ * @param hHdrLst The HTTP header list handle.
+ * @note This can be slow and is only really intended for test cases and debugging!
+ */
+RTR3DECL(size_t) RTHttpHeaderListGetCount(RTHTTPHEADERLIST hHdrLst);
+
+/**
+ * Gets a header by ordinal.
+ *
+ * Can be used together with RTHttpGetHeaderCount by test case and debug code to
+ * iterate headers specified by RTHttpAddHeader, RTHttpAddRawHeader or RTHttpSetHeaders.
+ *
+ * @returns The header string ("field: value").
+ * @param hHdrLst The HTTP header list handle.
+ * @param iOrdinal The number of the header to get.
+ * @note This can be slow and is only really intended for test cases and debugging!
+ */
+RTR3DECL(const char *) RTHttpHeaderListGetByOrdinal(RTHTTPHEADERLIST hHdrLst, size_t iOrdinal);
+
+RT_C_DECLS_END
+
+#endif /* !IPRT_INCLUDED_http_common_h */
+