Changeset 87011 in vbox

Timestamp:

Nov 27, 2020 5:33:42 PM (4 years ago)

Author:

vboxsync

Message:

Shared Clipboard/Transfers: Docs. bugref:9874

File:

• trunk/src/VBox/Runtime/r3/http-server.cpp (modified) (13 diffs)

trunk/src/VBox/Runtime/r3/http-server.cpp

@@ -249 +249 @@
 };
 
+
 /*********************************************************************************************************************************
 *   Internal Functions                                                                                                           *
@@ -296 +297 @@
 *********************************************************************************************************************************/
 
+/**
+ * Guesses the HTTP MIME type based on a given file extension.
+ *
+ * Note: Has to include the beginning dot, e.g. ".mp3" (see IPRT).
+ *
+ * @returns Guessed MIME type, or "application/octet-stream" if not found.
+ * @param   pszFileExt          File extension to guess MIME type for.
+ */
 static const char *rtHttpServerGuessMIMEType(const char *pszFileExt)
 {
@@ -311 +320 @@
 }
 
+/**
+ * Allocates and initializes a new client request.
+ *
+ * @returns Pointer to the new client request, or NULL on OOM.
+ *          Needs to be free'd with rtHttpServerReqFree().
+ */
 static PRTHTTPSERVERREQ rtHttpServerReqAlloc(void)
 {
@@ -322 +337 @@
 }
 
+/**
+ * Frees a formerly allocated client request.
+ *
+ * @param   pReq                Pointer to client request to free.
+ */
 static void rtHttpServerReqFree(PRTHTTPSERVERREQ pReq)
 {
@@ -340 +360 @@
 *********************************************************************************************************************************/
 
+/**
+ * Main function for sending a response back to the client.
+ *
+ * @returns VBox status code.
+ * @param   pClient             Client to reply to.
+ * @param   enmSts              Status code to send.
+ * @param   pHdrLst             Header list to send. Optional and can be NULL.
+ */
 static int rtHttpServerSendResponseHdrEx(PRTHTTPSERVERCLIENT pClient,
                                          RTHTTPSTATUS enmSts, PRTHTTPHEADERLIST pHdrLst)
@@ -405 +433 @@
 
 /**
- * Replies with (three digit) response status back to the client.
+ * Replies with (three digit) response status back to the client, extended version.
  *
  * @returns VBox status code.
@@ -419 +447 @@
 }
 
+/**
+ * Replies with (three digit) response status back to the client.
+ *
+ * @returns VBox status code.
+ * @param   pClient             Client to reply to.
+ * @param   enmSts              Status code to send.
+ */
 static int rtHttpServerSendResponseSimple(PRTHTTPSERVERCLIENT pClient, RTHTTPSTATUS enmSts)
 {
@@ -424 +459 @@
 }
 
+/**
+ * Sends a chunk of the response body to the client.
+ *
+ * @returns VBox status code.
+ * @param   pClient             Client to send body to.
+ * @param   pvBuf               Data buffer to send.
+ * @param   cbBuf               Size (in bytes) of data buffer to send.
+ * @param   pcbSent             Where to store the sent bytes. Optional and can be NULL.
+ */
 static int rtHttpServerSendResponseBody(PRTHTTPSERVERCLIENT pClient, void *pvBuf, size_t cbBuf, size_t *pcbSent)
 {
@@ -434 +478 @@
 }
 
+/**
+ * Resolves a VBox status code to a HTTP status code.
+ *
+ * @returns Resolved HTTP status code, or RTHTTPSTATUS_INTERNALSERVERERROR if not able to resolve.
+ * @param   rc                  VBox status code to resolve.
+ */
 static RTHTTPSTATUS rtHttpServerRcToStatus(int rc)
 {
@@ -459 +509 @@
 *********************************************************************************************************************************/
 
+/**
+ * Handler for the GET method.
+ *
+ * @returns VBox status code.
+ * @param   pClient             Client to handle GET method for.
+ * @param   pReq                Client request to handle.
+ */
 static DECLCALLBACK(int) rtHttpServerHandleGET(PRTHTTPSERVERCLIENT pClient, PRTHTTPSERVERREQ pReq)
 {
@@ -543 +600 @@
 }
 
+/**
+ * Handler for the HEAD method.
+ *
+ * @returns VBox status code.
+ * @param   pClient             Client to handle HEAD method for.
+ * @param   pReq                Client request to handle.
+ */
 static DECLCALLBACK(int) rtHttpServerHandleHEAD(PRTHTTPSERVERCLIENT pClient, PRTHTTPSERVERREQ pReq)
 {
@@ -625 +689 @@
 }
 
+/**
+ * Parses headers and fills them into a given header list.
+ *
+ * @returns VBox status code.
+ * @param   hList               Header list to fill parsed headers in.
+ * @param   pszReq              Request string with headers to parse.
+ * @param   cbReq               Size (in bytes) of request string to parse.
+ */
 static int rtHttpServerParseHeaders(RTHTTPHEADERLIST hList, char *pszReq, size_t cbReq)
 {
@@ -638 +710 @@
 }
 
+/**
+ * Main function for parsing and allocating a client request.
+ *
+ * @returns VBox status code.
+ * @param   pClient             Client to parse request from.
+ * @param   pszReq              Request string with headers to parse.
+ * @param   cbReq               Size (in bytes) of request string to parse.
+ * @param   ppReq               Where to store the allocated client request on success.
+ *                              Needs to be free'd via rtHttpServerReqFree().
+ */
 static int rtHttpServerParseRequest(PRTHTTPSERVERCLIENT pClient, char *pszReq, size_t cbReq,
                                     PRTHTTPSERVERREQ *ppReq)