diff options
Diffstat (limited to 'include/iprt/http-server.h')
| -rw-r--r-- | include/iprt/http-server.h | 244 |
1 files changed, 244 insertions, 0 deletions
diff --git a/include/iprt/http-server.h b/include/iprt/http-server.h new file mode 100644 index 00000000..eab06a37 --- /dev/null +++ b/include/iprt/http-server.h @@ -0,0 +1,244 @@ +/* $Id: http-server.h $ */ +/** @file + * Header file for HTTP server implementation. + */ + +/* + * Copyright (C) 2020-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_server_h +#define IPRT_INCLUDED_http_server_h +#ifndef RT_WITHOUT_PRAGMA_ONCE +# pragma once +#endif + +#include <iprt/http-common.h> +#include <iprt/types.h> +#include <iprt/fs.h> + +RT_C_DECLS_BEGIN + +/** @defgroup grp_rt_httpserver RTHttpServer - HTTP server implementation. + * @ingroup grp_rt + * @{ + */ + +/** @todo the following three definitions may move the iprt/types.h later. */ +/** HTTP server handle. */ +typedef R3PTRTYPE(struct RTHTTPSERVERINTERNAL *) RTHTTPSERVER; +/** Pointer to a HTTP server handle. */ +typedef RTHTTPSERVER *PRTHTTPSERVER; +/** Nil HTTP client handle. */ +#define NIL_RTHTTPSERVER ((RTHTTPSERVER)0) + +/** + * Structure for maintaining a HTTP client request. + */ +typedef struct RTHTTPSERVERREQ +{ + /** Request URL. */ + char *pszUrl; + /** Request method. */ + RTHTTPMETHOD enmMethod; + /** Request header list. */ + RTHTTPHEADERLIST hHdrLst; + /** Request body data. */ + RTHTTPBODY Body; +} RTHTTPSERVERREQ; +/** Pointer to a HTTP client request. */ +typedef RTHTTPSERVERREQ *PRTHTTPSERVERREQ; + +/** + * Structure for maintaining a HTTP server response. + */ +typedef struct RTHTTPSERVERRESP +{ + /** HTTP status to send. */ + RTHTTPSTATUS enmSts; + /** List of headers to send. */ + RTHTTPHEADERLIST hHdrLst; + /** Body data to send. */ + RTHTTPBODY Body; +} RTHTTPSERVERRESP; +/** Pointer to a HTTP server response. */ +typedef RTHTTPSERVERRESP *PRTHTTPSERVERRESP; + +RTR3DECL(int) RTHttpServerResponseInitEx(PRTHTTPSERVERRESP pResp, size_t cbBody); +RTR3DECL(int) RTHttpServerResponseInit(PRTHTTPSERVERRESP pResp); +RTR3DECL(void) RTHttpServerResponseDestroy(PRTHTTPSERVERRESP pResp); + +/** + * Structure for maintaining a HTTP server client state. + * + * Note: The HTTP protocol itself is stateless, but we want to have to possibility to store + * some state stuff here nevertheless. + */ +typedef struct RTHTTPSERVERCLIENTSTATE +{ + /** If non-zero, the time (in ms) to keep a client connection alive. + * Requested via client header, but set and controlled by the server in the end. */ + RTMSINTERVAL msKeepAlive; +} RTHTTPSERVERCLIENTSTATE; +/** Pointer to a FTP server client state. */ +typedef RTHTTPSERVERCLIENTSTATE *PRTHTTPSERVERCLIENTSTATE; + +/** + * Structure for storing HTTP server callback data. + */ +typedef struct RTHTTPCALLBACKDATA +{ + /** Pointer to the client state. */ + PRTHTTPSERVERCLIENTSTATE pClient; + /** Saved user pointer. */ + void *pvUser; + /** Size (in bytes) of data at user pointer. */ + size_t cbUser; +} RTHTTPCALLBACKDATA; +/** Pointer to HTTP server callback data. */ +typedef RTHTTPCALLBACKDATA *PRTHTTPCALLBACKDATA; + +/** + * Function callback table for the HTTP server implementation. + * + * All callbacks are optional and therefore can be NULL. + */ +typedef struct RTHTTPSERVERCALLBACKS +{ + /** + * Called before a given URL will be retrieved by the GET method. + * + * Note: High level function, not being called when pfnOnGetRequest is implemented. + * + * @returns VBox status code. + * @param pData Pointer to HTTP callback data. + * @param pReq Pointer to request to handle. + * @param ppvHandle Where to return the pointer to the opaque handle used for object identification. + */ + DECLCALLBACKMEMBER(int, pfnOpen,(PRTHTTPCALLBACKDATA pData, PRTHTTPSERVERREQ pReq, void **ppvHandle)); + /** + * Called when a given URL will be retrieved by the GET method. + * + * Note: High level function, not being called when pfnOnGetRequest is implemented. + * Note2: Can be called multiple times, based on the body size to send. + * + * @returns VBox status code. + * @param pData Pointer to HTTP callback data. + * @param pvHandle Opaque handle for object identification. + * @param pvBuf Pointer to buffer where to store the read data. + * @param cbBuf Size (in bytes) of the buffer where to store the read data. + * @param pcbRead Where to return the amount (in bytes) of read data. Optional and can be NULL. + */ + DECLCALLBACKMEMBER(int, pfnRead,(PRTHTTPCALLBACKDATA pData, void *pvHandle, void *pvBuf, size_t cbBuf, size_t *pcbRead)); + /** + * Called when a given URL is done retrieving by the GET method. + * + * Note: High level function, not being called when pfnOnGetRequest is implemented. + * + * @returns VBox status code. + * @param pData Pointer to HTTP callback data. + * @param pszUrl URL to handle. + * @param pvHandle Opaque handle for object identification. + */ + DECLCALLBACKMEMBER(int, pfnClose,(PRTHTTPCALLBACKDATA pData, void *pvHandle)); + /** + * Queries information about a given URL. + * + * Will be called with GET or HEAD request. + * + * @returns VBox status code. + * @param pData Pointer to HTTP callback data. + * @param pReq Pointer to request to handle. + * @param pObjInfo Where to store the queried file information on success. + * @param ppszMIMEHint Where to return an allocated MIME type hint on success. + * Must be free'd by the caller using RTStrFree(). + */ + DECLCALLBACKMEMBER(int, pfnQueryInfo,(PRTHTTPCALLBACKDATA pData, PRTHTTPSERVERREQ pReq, PRTFSOBJINFO pObjInfo, char **ppszMIMEHint)); + /** + * Low-level handler for a GET method request. + * + * @returns VBox status code. + * @param pData Pointer to HTTP callback data. + * @param pReq Pointer to request to handle. + */ + DECLCALLBACKMEMBER(int, pfnOnGetRequest,(PRTHTTPCALLBACKDATA pData, PRTHTTPSERVERREQ pReq)); + /** + * Low-level handler for a HEAD method request. + * + * @returns VBox status code. + * @param pData Pointer to HTTP callback data. + * @param pReq Pointer to request to handle. + */ + DECLCALLBACKMEMBER(int, pfnOnHeadRequest,(PRTHTTPCALLBACKDATA pData, PRTHTTPSERVERREQ pReq)); + /** + * Called before the HTTP server will be destroyed. + * + * @returns VBox status code. + * @param pData Pointer to HTTP callback data. + */ + DECLCALLBACKMEMBER(int, pfnDestroy,(PRTHTTPCALLBACKDATA pData)); +} RTHTTPSERVERCALLBACKS; +/** Pointer to a HTTP server callback data table. */ +typedef RTHTTPSERVERCALLBACKS *PRTHTTPSERVERCALLBACKS; + +/** Maximum length (in bytes) a single client request can have. */ +#define RTHTTPSERVER_MAX_REQ_LEN _8K +/** EOL string according to the HTTP 1.1 specs. + * See https://tools.ietf.org/html/rfc2616#section-2.2 */ +#define RTHTTPSERVER_HTTP11_EOL_STR "\r\n" + +/** + * Creates a HTTP server instance. + * + * @returns IPRT status code. + * @param phHttpServer Where to store the HTTP server handle. + * @param pcszAddress The address for creating a listening socket. + * If NULL or empty string the server is bound to all interfaces. + * @param uPort The port for creating a listening socket. + * @param pCallbacks Callback table to use. + * @param pvUser Pointer to user-specific data. Optional. + * @param cbUser Size of user-specific data. Optional. + */ +RTR3DECL(int) RTHttpServerCreate(PRTHTTPSERVER phHttpServer, const char *pcszAddress, uint16_t uPort, + PRTHTTPSERVERCALLBACKS pCallbacks, void *pvUser, size_t cbUser); + +/** + * Destroys a HTTP server instance. + * + * @returns IPRT status code. + * @param hHttpServer Handle to the HTTP server handle. + */ +RTR3DECL(int) RTHttpServerDestroy(RTHTTPSERVER hHttpServer); + +/** @} */ +RT_C_DECLS_END + +#endif /* !IPRT_INCLUDED_http_server_h */ + |