VirtualBox

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

Last change on this file since 103224 was 102141, checked in by vboxsync, 11 months ago

Shared Clipboard/Transfers: Implemented support for percent-encoded URLs for HTTP downloads. Extended testcase. bugref:9437

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 10.1 KB
Line 
1/* $Id: http-server.h 102141 2023-11-17 15:27:32Z vboxsync $ */
2/** @file
3 * Header file for HTTP server implementation.
4 */
5
6/*
7 * Copyright (C) 2020-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_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. 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. */
80typedef RTHTTPSERVERREQ *PRTHTTPSERVERREQ;
81
82/**
83 * Structure for maintaining a HTTP server response.
84 */
85typedef 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. */
95typedef RTHTTPSERVERRESP *PRTHTTPSERVERRESP;
96
97RTR3DECL(int) RTHttpServerResponseInitEx(PRTHTTPSERVERRESP pResp, size_t cbBody);
98RTR3DECL(int) RTHttpServerResponseInit(PRTHTTPSERVERRESP pResp);
99RTR3DECL(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 */
107typedef 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. */
114typedef RTHTTPSERVERCLIENTSTATE *PRTHTTPSERVERCLIENTSTATE;
115
116/**
117 * Structure for storing HTTP server callback data.
118 */
119typedef 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. */
129typedef 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 */
136typedef 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. */
233typedef 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 */
253RTR3DECL(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 */
262RTR3DECL(int) RTHttpServerDestroy(RTHTTPSERVER hHttpServer);
263
264/** @} */
265RT_C_DECLS_END
266
267#endif /* !IPRT_INCLUDED_http_server_h */
268
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