include/iprt/http-server.h

   1 /* $Id$ */
   2 /** @file
   3  * Header file for HTTP server implementation.
   4  */
   5
   6 /*
   7  * Copyright (C) 2020-2024 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_server_h
  38 #define IPRT_INCLUDED_http_server_h
  39 #ifndef RT_WITHOUT_PRAGMA_ONCE
  40 # pragma once
  41 #endif
  42
  43 #include <iprt/http-common.h>
  44 #include <iprt/types.h>
  45 #include <iprt/fs.h>
  46
  47 RT_C_DECLS_BEGIN
  48
  49 /** @defgroup grp_rt_httpserver  RTHttpServer - HTTP server implementation.
  50  * @ingroup grp_rt
  51  * @{
  52  */
  53
  54 /** @todo the following three definitions may move the iprt/types.h later. */
  55 /** HTTP server handle. */
  56 typedef R3PTRTYPE(struct RTHTTPSERVERINTERNAL *) RTHTTPSERVER;
  57 /** Pointer to a HTTP server handle. */
  58 typedef RTHTTPSERVER                            *PRTHTTPSERVER;
  59 /** Nil HTTP client handle. */
  60 #define NIL_RTHTTPSERVER                         ((RTHTTPSERVER)0)
  61
  62 /**
  63  * Structure for maintaining a HTTP client request.
  64  */
  65 typedef struct RTHTTPSERVERREQ
  66 {
  67     /** Request URL. Unmodified (i.e. escaped by HTTP client). */
  68     char            *pszUrl;
  69     /** Request method. */
  70     RTHTTPMETHOD     enmMethod;
  71     /** Request header list. */
  72     RTHTTPHEADERLIST hHdrLst;
  73     /** Request body data. */
  74     RTHTTPBODY       Body;
  75     /** User-supplied (opaque) pointer.
  76      *  Can be used for faster lookups between callbacks. */
  77     void            *pvUser;
  78 } RTHTTPSERVERREQ;
  79 /** Pointer to a HTTP client request. */
  80 typedef RTHTTPSERVERREQ *PRTHTTPSERVERREQ;
  81
  82 /**
  83  * Structure for maintaining a HTTP server response.
  84  */
  85 typedef struct RTHTTPSERVERRESP
  86 {
  87     /** HTTP status to send. */
  88     RTHTTPSTATUS     enmSts;
  89     /** List of headers to send. */
  90     RTHTTPHEADERLIST hHdrLst;
  91     /** Body data to send. */
  92     RTHTTPBODY       Body;
  93 } RTHTTPSERVERRESP;
  94 /** Pointer to a HTTP server response. */
  95 typedef RTHTTPSERVERRESP *PRTHTTPSERVERRESP;
  96
  97 RTR3DECL(int)  RTHttpServerResponseInitEx(PRTHTTPSERVERRESP pResp, size_t cbBody);
  98 RTR3DECL(int)  RTHttpServerResponseInit(PRTHTTPSERVERRESP pResp);
  99 RTR3DECL(void) RTHttpServerResponseDestroy(PRTHTTPSERVERRESP pResp);
 100
 101 /**
 102  * Structure for maintaining a HTTP server client state.
 103  *
 104  * Note: The HTTP protocol itself is stateless, but we want to have to possibility to store
 105  *       some state stuff here nevertheless.
 106  */
 107 typedef struct RTHTTPSERVERCLIENTSTATE
 108 {
 109     /** If non-zero, the time (in ms) to keep a client connection alive.
 110      *  Requested via client header, but set and controlled by the server in the end. */
 111     RTMSINTERVAL msKeepAlive;
 112 } RTHTTPSERVERCLIENTSTATE;
 113 /** Pointer to a FTP server client state. */
 114 typedef RTHTTPSERVERCLIENTSTATE *PRTHTTPSERVERCLIENTSTATE;
 115
 116 /**
 117  * Structure for storing HTTP server callback data.
 118  */
 119 typedef struct RTHTTPCALLBACKDATA
 120 {
 121     /** Pointer to the client state. */
 122     PRTHTTPSERVERCLIENTSTATE pClient;
 123     /** Saved user pointer. */
 124     void                    *pvUser;
 125     /** Size (in bytes) of data at user pointer. */
 126     size_t                   cbUser;
 127 } RTHTTPCALLBACKDATA;
 128 /** Pointer to HTTP server callback data. */
 129 typedef RTHTTPCALLBACKDATA *PRTHTTPCALLBACKDATA;
 130
 131 /**
 132  * Function callback table for the HTTP server implementation.
 133  *
 134  * All callbacks are optional and therefore can be NULL.
 135  */
 136 typedef struct RTHTTPSERVERCALLBACKS
 137 {
 138     /**
 139      * Called before beginning to process a request. Guaranteed.
 140      *
 141      * @returns VBox status code.
 142      * @param   pData           Pointer to HTTP callback data.
 143      * @param   pReq            Pointer to request to handle.
 144      */
 145     DECLCALLBACKMEMBER(int, pfnRequestBegin,(PRTHTTPCALLBACKDATA pData, PRTHTTPSERVERREQ pReq));
 146     /**
 147      * Called after processing a request. Guaranteed.
 148      *
 149      * @returns VBox status code.
 150      * @param   pData           Pointer to HTTP callback data.
 151      * @param   pReq            Pointer to request to handle.
 152      */
 153     DECLCALLBACKMEMBER(int, pfnRequestEnd,(PRTHTTPCALLBACKDATA pData, PRTHTTPSERVERREQ pReq));
 154     /**
 155      * Opens a resource for a GET request.
 156      *
 157      * Will be called as as a second function for a GET request.
 158      *
 159      * Note: High level function, not being called when pfnOnGetRequest is implemented.
 160      *
 161      * @returns VBox status code.
 162      * @param   pData           Pointer to HTTP callback data.
 163      * @param   pReq            Pointer to request to handle.
 164      * @param   ppvHandle       Where to return the pointer to the opaque handle used for object identification.
 165      */
 166     DECLCALLBACKMEMBER(int, pfnOpen,(PRTHTTPCALLBACKDATA pData, PRTHTTPSERVERREQ pReq, void **ppvHandle));
 167     /**
 168      * Reads a resource for a GET request.
 169      *
 170      * Note:  High level function, not being called when pfnOnGetRequest is implemented.
 171      * Note2: Can be called multiple times, based on the body size to send.
 172      *
 173      * @returns VBox status code.
 174      * @param   pData           Pointer to HTTP callback data.
 175      * @param   pReq            Pointer to request to handle.
 176      * @param   pvHandle        Opaque handle for object identification.
 177      * @param   pvBuf           Pointer to buffer where to store the read data.
 178      * @param   cbBuf           Size (in bytes) of the buffer where to store the read data.
 179      * @param   pcbRead         Where to return the amount (in bytes) of read data. Optional and can be NULL.
 180      */
 181     DECLCALLBACKMEMBER(int, pfnRead,(PRTHTTPCALLBACKDATA pData, PRTHTTPSERVERREQ pReq, void *pvHandle, void *pvBuf, size_t cbBuf, size_t *pcbRead));
 182     /**
 183      * Closes a resouce for a GET a request.
 184      *
 185      * Note: High level function, not being called when pfnOnGetRequest is implemented.
 186      *
 187      * @returns VBox status code.
 188      * @param   pData           Pointer to HTTP callback data.
 189      * @param   pReq            Pointer to request to handle.
 190      * @param   pvHandle        Opaque handle for object identification.
 191      */
 192     DECLCALLBACKMEMBER(int, pfnClose,(PRTHTTPCALLBACKDATA pData, PRTHTTPSERVERREQ pReq, void *pvHandle));
 193     /**
 194      * Queries information about a given URL.
 195      *
 196      * Will be called as first function for a GET or HEAD request.
 197      *
 198      * Note: High level function, not being called when pfnOnGetRequest is implemented.*
 199      *
 200      * @returns VBox status code.
 201      * @param   pData           Pointer to HTTP callback data.
 202      * @param   pReq            Pointer to request to handle.
 203      * @param   pObjInfo        Where to store the queried file information on success.
 204      * @param   ppszMIMEHint    Where to return an allocated MIME type hint on success.
 205      *                          Must be free'd by the caller using RTStrFree().
 206      */
 207     DECLCALLBACKMEMBER(int, pfnQueryInfo,(PRTHTTPCALLBACKDATA pData, PRTHTTPSERVERREQ pReq, PRTFSOBJINFO pObjInfo, char **ppszMIMEHint));
 208     /**
 209      * Low-level handler for a GET method request.
 210      *
 211      * @returns VBox status code.
 212      * @param   pData           Pointer to HTTP callback data.
 213      * @param   pReq            Pointer to request to handle.
 214      */
 215     DECLCALLBACKMEMBER(int, pfnOnGetRequest,(PRTHTTPCALLBACKDATA pData, PRTHTTPSERVERREQ pReq));
 216     /**
 217      * Low-level handler for a HEAD method request.
 218      *
 219      * @returns VBox status code.
 220      * @param   pData           Pointer to HTTP callback data.
 221      * @param   pReq            Pointer to request to handle.
 222      */
 223     DECLCALLBACKMEMBER(int, pfnOnHeadRequest,(PRTHTTPCALLBACKDATA pData, PRTHTTPSERVERREQ pReq));
 224     /**
 225      * Called before the HTTP server will be destroyed.
 226      *
 227      * @returns VBox status code.
 228      * @param   pData           Pointer to HTTP callback data.
 229      */
 230     DECLCALLBACKMEMBER(int, pfnDestroy,(PRTHTTPCALLBACKDATA pData));
 231 } RTHTTPSERVERCALLBACKS;
 232 /** Pointer to a HTTP server callback data table. */
 233 typedef RTHTTPSERVERCALLBACKS *PRTHTTPSERVERCALLBACKS;
 234
 235 /** Maximum length (in bytes) a single client request can have. */
 236 #define RTHTTPSERVER_MAX_REQ_LEN        _8K
 237 /** EOL string according to the HTTP 1.1 specs.
 238  *  See https://tools.ietf.org/html/rfc2616#section-2.2 */
 239 #define RTHTTPSERVER_HTTP11_EOL_STR     "\r\n"
 240
 241 /**
 242  * Creates a HTTP server instance.
 243  *
 244  * @returns IPRT status code.
 245  * @param   phHttpServer        Where to store the HTTP server handle.
 246  * @param   pcszAddress         The address for creating a listening socket.
 247  *                              If NULL or empty string the server is bound to all interfaces.
 248  * @param   uPort               The port for creating a listening socket.
 249  * @param   pCallbacks          Callback table to use.
 250  * @param   pvUser              Pointer to user-specific data. Optional.
 251  * @param   cbUser              Size of user-specific data. Optional.
 252  */
 253 RTR3DECL(int) RTHttpServerCreate(PRTHTTPSERVER phHttpServer, const char *pcszAddress, uint16_t uPort,
 254                                  PRTHTTPSERVERCALLBACKS pCallbacks, void *pvUser, size_t cbUser);
 255
 256 /**
 257  * Destroys a HTTP server instance.
 258  *
 259  * @returns IPRT status code.
 260  * @param   hHttpServer          Handle to the HTTP server handle.
 261  */
 262 RTR3DECL(int) RTHttpServerDestroy(RTHTTPSERVER hHttpServer);
 263
 264 /** @} */
 265 RT_C_DECLS_END
 266
 267 #endif /* !IPRT_INCLUDED_http_server_h */
 268