VirtualBox

source: vbox/trunk/include/iprt/http-server.h@ 96550

Last change on this file since 96550 was 96407, checked in by vboxsync, 2 years ago

scm copyright and license note update

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

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette