Changeset 87063 in vbox for trunk/src/VBox/GuestHost/SharedClipboard/clipboard-transfers-http.cpp

Timestamp:

Dec 9, 2020 1:53:36 PM (4 years ago)

Author:

vboxsync

Message:

Shared Clipboard/Transfers: Documentation. bugref:9874

File:

• trunk/src/VBox/GuestHost/SharedClipboard/clipboard-transfers-http.cpp (modified) (13 diffs)

trunk/src/VBox/GuestHost/SharedClipboard/clipboard-transfers-http.cpp

@@ -76 +76 @@
 *   Internal functions                                                                                                           *
 *********************************************************************************************************************************/
+
+/**
+ * Return the HTTP server transfer for a specific transfer ID.
+ *
+ * @returns Pointer to HTTP server transfer if found, NULL if not found.
+ * @param   pSrv                HTTP server instance.
+ * @param   idTransfer          Transfer ID to return HTTP server transfer for.
+ */
 static PSHCLHTTPSERVERTRANSFER shClTransferHttpServerGetTransferById(PSHCLHTTPSERVER pSrv, SHCLTRANSFERID idTransfer)
 {
@@ -206 +214 @@
 *   Public functions                                                                                                             *
 *********************************************************************************************************************************/
+
+/**
+ * Creates a new Shared Clipboard HTTP server instance, extended version.
+ *
+ * @returns VBox status code.
+ * @param   pSrv                HTTP server instance to create.
+ * @param   uPort               TCP port number to use.
+ */
 int ShClTransferHttpServerCreateEx(PSHCLHTTPSERVER pSrv, uint16_t uPort)
 {
@@ -249 +265 @@
 }
 
+/**
+ * Creates a new Shared Clipboard HTTP server instance.
+ *
+ * This does automatic probing of TCP ports if one already is being used.
+ *
+ * @returns VBox status code.
+ * @param   pSrv                HTTP server instance to create.
+ * @param   puPort              Where to return the TCP port number being used on success.
+ */
 int ShClTransferHttpServerCreate(PSHCLHTTPSERVER pSrv, uint16_t *puPort)
 {
@@ -281 +306 @@
 }
 
+/**
+ * Destroys a Shared Clipboard HTTP server instance.
+ *
+ * @returns VBox status code.
+ * @param   pSrv                HTTP server instance to destroy.
+ */
 int ShClTransferHttpServerDestroy(PSHCLHTTPSERVER pSrv)
 {
@@ -302 +333 @@
 }
 
+/**
+ * Registers a Shared Clipboard transfer to a HTTP server instance.
+ *
+ * @returns VBox status code.
+ * @param   pSrv                HTTP server instance to register transfer for.
+ * @param   pTransfer           Transfer to register.
+ */
 int ShClTransferHttpServerRegisterTransfer(PSHCLHTTPSERVER pSrv, PSHCLTRANSFER pTransfer)
 {
@@ -341 +379 @@
 }
 
+/**
+ * Unregisters a formerly registered Shared Clipboard transfer.
+ *
+ * @returns VBox status code.
+ * @param   pSrv                HTTP server instance to unregister transfer from.
+ * @param   pTransfer           Transfer to unregister.
+ */
 int ShClTransferHttpServerUnregisterTransfer(PSHCLHTTPSERVER pSrv, PSHCLTRANSFER pTransfer)
 {
@@ -361 +406 @@
             pSrvTx = NULL;
 
+            Assert(pSrv->cTransfers);
             pSrv->cTransfers--;
 
@@ -372 +418 @@
 }
 
+/**
+ * Returns whether a specific transfer ID is registered with a HTTP server instance or not.
+ *
+ * @returns \c true if the transfer ID is registered, \c false if not.
+ * @param   pSrv                HTTP server instance.
+ * @param   idTransfer          Transfer ID to check for.
+ */
 bool ShClTransferHttpServerHasTransfer(PSHCLHTTPSERVER pSrv, SHCLTRANSFERID idTransfer)
 {
@@ -385 +438 @@
 }
 
+/**
+ * Returns the used TCP port number of a HTTP server instance.
+ *
+ * @returns TCP port number. 0 if not specified yet.
+ * @param   pSrv                HTTP server instance to return port for.
+ */
 uint16_t ShClTransferHttpServerGetPort(PSHCLHTTPSERVER pSrv)
 {
@@ -398 +457 @@
 }
 
+/**
+ * Returns the number of registered HTTP server transfers of a HTTP server instance.
+ *
+ * @returns Number of registered transfers.
+ * @param   pSrv                HTTP server instance to return registered transfers for.
+ */
 uint32_t ShClTransferHttpServerGetTransferCount(PSHCLHTTPSERVER pSrv)
 {
@@ -411 +476 @@
 }
 
+/**
+ * Returns the host name (scheme) of a HTTP server instance.
+ *
+ * @param   pSrv                HTTP server instance to return host name (scheme) for.
+ *
+ * @returns Host name (scheme).
+ */
 static const char *shClTransferHttpServerGetHost(PSHCLHTTPSERVER pSrv)
 {
@@ -417 +489 @@
 }
 
+/**
+ * Returns an allocated string with a HTTP server instance's address.
+ *
+ * @returns Allocated string with a HTTP server instance's address, or NULL on OOM.
+ *          Needs to be free'd by the caller using RTStrFree().
+ * @param   pSrv                HTTP server instance to return address for.
+ */
 char *ShClTransferHttpServerGetAddressA(PSHCLHTTPSERVER pSrv)
 {
@@ -430 +509 @@
 }
 
+/**
+ * Returns an allocated string with the URL of a given Shared Clipboard transfer ID.
+ *
+ * @returns Allocated string with the URL of a given Shared Clipboard transfer ID, or NULL if not found.
+ *          Needs to be free'd by the caller using RTStrFree().
+ * @param   pSrv                HTTP server instance to return URL for.
+ */
 char *ShClTransferHttpServerGetUrlA(PSHCLHTTPSERVER pSrv, SHCLTRANSFERID idTransfer)
 {