1 // Copyright (c) 2022 Marshall A. Greenblatt. All rights reserved. 2 // 3 // Redistribution and use in source and binary forms, with or without 4 // modification, are permitted provided that the following conditions are 5 // met: 6 // 7 // * Redistributions of source code must retain the above copyright 8 // notice, this list of conditions and the following disclaimer. 9 // * Redistributions in binary form must reproduce the above 10 // copyright notice, this list of conditions and the following disclaimer 11 // in the documentation and/or other materials provided with the 12 // distribution. 13 // * Neither the name of Google Inc. nor the name Chromium Embedded 14 // Framework nor the names of its contributors may be used to endorse 15 // or promote products derived from this software without specific prior 16 // written permission. 17 // 18 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 19 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 20 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 21 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 22 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 23 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 24 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 25 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 26 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 27 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 28 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 29 // 30 // --------------------------------------------------------------------------- 31 // 32 // This file was generated by the CEF translator tool and should not edited 33 // by hand. See the translator.README.txt file in the tools directory for 34 // more information. 35 // 36 // $hash=72c2b4f976016cea50e54a386c09a786973c01a3$ 37 // 38 39 #ifndef CEF_INCLUDE_CAPI_CEF_SERVER_CAPI_H_ 40 #define CEF_INCLUDE_CAPI_CEF_SERVER_CAPI_H_ 41 #pragma once 42 43 #include "include/capi/cef_base_capi.h" 44 #include "include/capi/cef_callback_capi.h" 45 #include "include/capi/cef_request_capi.h" 46 #include "include/capi/cef_task_capi.h" 47 48 #ifdef __cplusplus 49 extern "C" { 50 #endif 51 52 struct _cef_server_handler_t; 53 54 /// 55 // Structure representing a server that supports HTTP and WebSocket requests. 56 // Server capacity is limited and is intended to handle only a small number of 57 // simultaneous connections (e.g. for communicating between applications on 58 // localhost). The functions of this structure are safe to call from any thread 59 // in the brower process unless otherwise indicated. 60 /// 61 typedef struct _cef_server_t { 62 /// 63 // Base structure. 64 /// 65 cef_base_ref_counted_t base; 66 67 /// 68 // Returns the task runner for the dedicated server thread. 69 /// 70 struct _cef_task_runner_t*(CEF_CALLBACK* get_task_runner)( 71 struct _cef_server_t* self); 72 73 /// 74 // Stop the server and shut down the dedicated server thread. See 75 // cef_server_handler_t::OnServerCreated documentation for a description of 76 // server lifespan. 77 /// 78 void(CEF_CALLBACK* shutdown)(struct _cef_server_t* self); 79 80 /// 81 // Returns true (1) if the server is currently running and accepting incoming 82 // connections. See cef_server_handler_t::OnServerCreated documentation for a 83 // description of server lifespan. This function must be called on the 84 // dedicated server thread. 85 /// 86 int(CEF_CALLBACK* is_running)(struct _cef_server_t* self); 87 88 /// 89 // Returns the server address including the port number. 90 /// 91 // The resulting string must be freed by calling cef_string_userfree_free(). 92 cef_string_userfree_t(CEF_CALLBACK* get_address)(struct _cef_server_t* self); 93 94 /// 95 // Returns true (1) if the server currently has a connection. This function 96 // must be called on the dedicated server thread. 97 /// 98 int(CEF_CALLBACK* has_connection)(struct _cef_server_t* self); 99 100 /// 101 // Returns true (1) if |connection_id| represents a valid connection. This 102 // function must be called on the dedicated server thread. 103 /// 104 int(CEF_CALLBACK* is_valid_connection)(struct _cef_server_t* self, 105 int connection_id); 106 107 /// 108 // Send an HTTP 200 "OK" response to the connection identified by 109 // |connection_id|. |content_type| is the response content type (e.g. 110 // "text/html"), |data| is the response content, and |data_size| is the size 111 // of |data| in bytes. The contents of |data| will be copied. The connection 112 // will be closed automatically after the response is sent. 113 /// 114 void(CEF_CALLBACK* send_http200response)(struct _cef_server_t* self, 115 int connection_id, 116 const cef_string_t* content_type, 117 const void* data, 118 size_t data_size); 119 120 /// 121 // Send an HTTP 404 "Not Found" response to the connection identified by 122 // |connection_id|. The connection will be closed automatically after the 123 // response is sent. 124 /// 125 void(CEF_CALLBACK* send_http404response)(struct _cef_server_t* self, 126 int connection_id); 127 128 /// 129 // Send an HTTP 500 "Internal Server Error" response to the connection 130 // identified by |connection_id|. |error_message| is the associated error 131 // message. The connection will be closed automatically after the response is 132 // sent. 133 /// 134 void(CEF_CALLBACK* send_http500response)(struct _cef_server_t* self, 135 int connection_id, 136 const cef_string_t* error_message); 137 138 /// 139 // Send a custom HTTP response to the connection identified by 140 // |connection_id|. |response_code| is the HTTP response code sent in the 141 // status line (e.g. 200), |content_type| is the response content type sent as 142 // the "Content-Type" header (e.g. "text/html"), |content_length| is the 143 // expected content length, and |extra_headers| is the map of extra response 144 // headers. If |content_length| is >= 0 then the "Content-Length" header will 145 // be sent. If |content_length| is 0 then no content is expected and the 146 // connection will be closed automatically after the response is sent. If 147 // |content_length| is < 0 then no "Content-Length" header will be sent and 148 // the client will continue reading until the connection is closed. Use the 149 // SendRawData function to send the content, if applicable, and call 150 // CloseConnection after all content has been sent. 151 /// 152 void(CEF_CALLBACK* send_http_response)(struct _cef_server_t* self, 153 int connection_id, 154 int response_code, 155 const cef_string_t* content_type, 156 int64 content_length, 157 cef_string_multimap_t extra_headers); 158 159 /// 160 // Send raw data directly to the connection identified by |connection_id|. 161 // |data| is the raw data and |data_size| is the size of |data| in bytes. The 162 // contents of |data| will be copied. No validation of |data| is performed 163 // internally so the client should be careful to send the amount indicated by 164 // the "Content-Length" header, if specified. See SendHttpResponse 165 // documentation for intended usage. 166 /// 167 void(CEF_CALLBACK* send_raw_data)(struct _cef_server_t* self, 168 int connection_id, 169 const void* data, 170 size_t data_size); 171 172 /// 173 // Close the connection identified by |connection_id|. See SendHttpResponse 174 // documentation for intended usage. 175 /// 176 void(CEF_CALLBACK* close_connection)(struct _cef_server_t* self, 177 int connection_id); 178 179 /// 180 // Send a WebSocket message to the connection identified by |connection_id|. 181 // |data| is the response content and |data_size| is the size of |data| in 182 // bytes. The contents of |data| will be copied. See 183 // cef_server_handler_t::OnWebSocketRequest documentation for intended usage. 184 /// 185 void(CEF_CALLBACK* send_web_socket_message)(struct _cef_server_t* self, 186 int connection_id, 187 const void* data, 188 size_t data_size); 189 } cef_server_t; 190 191 /// 192 // Create a new server that binds to |address| and |port|. |address| must be a 193 // valid IPv4 or IPv6 address (e.g. 127.0.0.1 or ::1) and |port| must be a port 194 // number outside of the reserved range (e.g. between 1025 and 65535 on most 195 // platforms). |backlog| is the maximum number of pending connections. A new 196 // thread will be created for each CreateServer call (the "dedicated server 197 // thread"). It is therefore recommended to use a different cef_server_handler_t 198 // instance for each CreateServer call to avoid thread safety issues in the 199 // cef_server_handler_t implementation. The 200 // cef_server_handler_t::OnServerCreated function will be called on the 201 // dedicated server thread to report success or failure. See 202 // cef_server_handler_t::OnServerCreated documentation for a description of 203 // server lifespan. 204 /// 205 CEF_EXPORT void cef_server_create(const cef_string_t* address, 206 uint16 port, 207 int backlog, 208 struct _cef_server_handler_t* handler); 209 210 /// 211 // Implement this structure to handle HTTP server requests. A new thread will be 212 // created for each cef_server_t::CreateServer call (the "dedicated server 213 // thread"), and the functions of this structure will be called on that thread. 214 // It is therefore recommended to use a different cef_server_handler_t instance 215 // for each cef_server_t::CreateServer call to avoid thread safety issues in the 216 // cef_server_handler_t implementation. 217 /// 218 typedef struct _cef_server_handler_t { 219 /// 220 // Base structure. 221 /// 222 cef_base_ref_counted_t base; 223 224 /// 225 // Called when |server| is created. If the server was started successfully 226 // then cef_server_t::IsRunning will return true (1). The server will continue 227 // running until cef_server_t::Shutdown is called, after which time 228 // OnServerDestroyed will be called. If the server failed to start then 229 // OnServerDestroyed will be called immediately after this function returns. 230 /// 231 void(CEF_CALLBACK* on_server_created)(struct _cef_server_handler_t* self, 232 struct _cef_server_t* server); 233 234 /// 235 // Called when |server| is destroyed. The server thread will be stopped after 236 // this function returns. The client should release any references to |server| 237 // when this function is called. See OnServerCreated documentation for a 238 // description of server lifespan. 239 /// 240 void(CEF_CALLBACK* on_server_destroyed)(struct _cef_server_handler_t* self, 241 struct _cef_server_t* server); 242 243 /// 244 // Called when a client connects to |server|. |connection_id| uniquely 245 // identifies the connection. Each call to this function will have a matching 246 // call to OnClientDisconnected. 247 /// 248 void(CEF_CALLBACK* on_client_connected)(struct _cef_server_handler_t* self, 249 struct _cef_server_t* server, 250 int connection_id); 251 252 /// 253 // Called when a client disconnects from |server|. |connection_id| uniquely 254 // identifies the connection. The client should release any data associated 255 // with |connection_id| when this function is called and |connection_id| 256 // should no longer be passed to cef_server_t functions. Disconnects can 257 // originate from either the client or the server. For example, the server 258 // will disconnect automatically after a cef_server_t::SendHttpXXXResponse 259 // function is called. 260 /// 261 void(CEF_CALLBACK* on_client_disconnected)(struct _cef_server_handler_t* self, 262 struct _cef_server_t* server, 263 int connection_id); 264 265 /// 266 // Called when |server| receives an HTTP request. |connection_id| uniquely 267 // identifies the connection, |client_address| is the requesting IPv4 or IPv6 268 // client address including port number, and |request| contains the request 269 // contents (URL, function, headers and optional POST data). Call cef_server_t 270 // functions either synchronously or asynchronusly to send a response. 271 /// 272 void(CEF_CALLBACK* on_http_request)(struct _cef_server_handler_t* self, 273 struct _cef_server_t* server, 274 int connection_id, 275 const cef_string_t* client_address, 276 struct _cef_request_t* request); 277 278 /// 279 // Called when |server| receives a WebSocket request. |connection_id| uniquely 280 // identifies the connection, |client_address| is the requesting IPv4 or IPv6 281 // client address including port number, and |request| contains the request 282 // contents (URL, function, headers and optional POST data). Execute 283 // |callback| either synchronously or asynchronously to accept or decline the 284 // WebSocket connection. If the request is accepted then OnWebSocketConnected 285 // will be called after the WebSocket has connected and incoming messages will 286 // be delivered to the OnWebSocketMessage callback. If the request is declined 287 // then the client will be disconnected and OnClientDisconnected will be 288 // called. Call the cef_server_t::SendWebSocketMessage function after 289 // receiving the OnWebSocketConnected callback to respond with WebSocket 290 // messages. 291 /// 292 void(CEF_CALLBACK* on_web_socket_request)(struct _cef_server_handler_t* self, 293 struct _cef_server_t* server, 294 int connection_id, 295 const cef_string_t* client_address, 296 struct _cef_request_t* request, 297 struct _cef_callback_t* callback); 298 299 /// 300 // Called after the client has accepted the WebSocket connection for |server| 301 // and |connection_id| via the OnWebSocketRequest callback. See 302 // OnWebSocketRequest documentation for intended usage. 303 /// 304 void(CEF_CALLBACK* on_web_socket_connected)( 305 struct _cef_server_handler_t* self, 306 struct _cef_server_t* server, 307 int connection_id); 308 309 /// 310 // Called when |server| receives an WebSocket message. |connection_id| 311 // uniquely identifies the connection, |data| is the message content and 312 // |data_size| is the size of |data| in bytes. Do not keep a reference to 313 // |data| outside of this function. See OnWebSocketRequest documentation for 314 // intended usage. 315 /// 316 void(CEF_CALLBACK* on_web_socket_message)(struct _cef_server_handler_t* self, 317 struct _cef_server_t* server, 318 int connection_id, 319 const void* data, 320 size_t data_size); 321 } cef_server_handler_t; 322 323 #ifdef __cplusplus 324 } 325 #endif 326 327 #endif // CEF_INCLUDE_CAPI_CEF_SERVER_CAPI_H_ 328