VirtualBox

Changeset 99403 in vbox for trunk/src/VBox


Ignore:
Timestamp:
Apr 14, 2023 2:57:12 PM (23 months ago)
Author:
vboxsync
svn:sync-xref-src-repo-rev:
156853
Message:

Shared Clipboard/Transfers: Docs. bugref:9437

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r98103 r99403  
    11/* $Id$ */
    22/** @file
    3  * Shared Clipboard: Common Shared Clipboard transfer handling code.
     3 * Shared Clipboard: Common clipboard transfer handling code.
    44 */
    55
    … …  
    6767 * Frees a transfer root list.
    6868 *
    69  * @param   pRootList           transfer root list to free. The pointer will be
     69 * @param   pRootList           Transfer root list to free. The pointer will be
    7070 *                              invalid after returning from this function.
    7171 */
    … …  
    247247 *
    248248 * @param   pListEntry          Transfer list header structure to free.
     249 *                              The pointer will be invalid on return.
    249250 */
    250251void ShClTransferListHdrFree(PSHCLLISTHDR pListHdr)
    … …  
    273274    PSHCLLISTHDR pListHdrDup = (PSHCLLISTHDR)RTMemAlloc(sizeof(SHCLLISTHDR));
    274275    if (pListHdrDup)
    275     {
    276276        *pListHdrDup = *pListHdr;
    277     }
    278277
    279278    return pListHdrDup;
    … …  
    337336}
    338337
     338/**
     339 * (Deep-)Copies a transfer list open parameters structure from one into another.
     340 *
     341 * @returns VBox status code.
     342 * @param   pDst                Destination parameters to copy to.
     343 * @param   pSrc                Source parameters to copy from.
     344 */
    339345int ShClTransferListOpenParmsCopy(PSHCLLISTOPENPARMS pDst, PSHCLLISTOPENPARMS pSrc)
    340346{
    … …  
    443449 * Creates (allocates) and initializes a clipboard list entry structure.
    444450 *
     451 * @returns VBox status code.
    445452 * @param   ppDirData           Where to return the created clipboard list entry structure on success.
    446453 */
    … …  
    461468 * Frees a clipboard list entry structure.
    462469 *
    463  * @param   pListEntry         Clipboard list entry structure to free.
     470 * @param   pListEntry          Clipboard list entry structure to free.
     471 *                              The pointer will be invalid on return.
    464472 */
    465473void ShClTransferListEntryFree(PSHCLLISTENTRY pListEntry)
    … …  
    473481
    474482/**
    475  * (Deep) Copies a clipboard list entry structure.
    476  *
    477  * @returns VBox status code.
    478  * @param   pListEntry          Clipboard list entry to copy.
     483 * (Deep-)Copies a clipboard list entry structure.
     484 *
     485 * @returns VBox status code.
     486 * @param   pDst                Destination list entry to copy to.
     487 * @param   pSrc                Source list entry to copy from.
    479488 */
    480489int ShClTransferListEntryCopy(PSHCLLISTENTRY pDst, PSHCLLISTENTRY pSrc)
    … …  
    633642 *
    634643 * @returns VBox status code.
    635  * @param   pObjCtx             transfer object context to initialize.
     644 * @param   pObjCtx             Transfer object context to initialize.
    636645 */
    637646int ShClTransferObjCtxInit(PSHCLCLIENTTRANSFEROBJCTX pObjCtx)
    … …  
    649658 * Destroys a transfer object context.
    650659 *
    651  * @param   pObjCtx             transfer object context to destroy.
     660 * @param   pObjCtx             Transfer object context to destroy.
    652661 */
    653662void ShClTransferObjCtxDestroy(PSHCLCLIENTTRANSFEROBJCTX pObjCtx)
    … …  
    662671 *
    663672 * @returns \c true if valid, \c false if not.
    664  * @param   pObjCtx             transfer object context to check.
     673 * @param   pObjCtx             Transfer object context to check.
    665674 */
    666675bool ShClTransferObjCtxIsValid(PSHCLCLIENTTRANSFEROBJCTX pObjCtx)
    … …  
    711720 *
    712721 * @returns VBox status code.
    713  * @param   pParms              transfer object open parameters structure to initialize.
     722 * @param   pParms              Transfer object open parameters structure to initialize.
    714723 */
    715724int ShClTransferObjOpenParmsInit(PSHCLOBJOPENCREATEPARMS pParms)
    … …  
    768777 * Destroys a transfer object open parameters structure.
    769778 *
    770  * @param   pParms              transfer object open parameters structure to destroy.
     779 * @param   pParms              Transfer object open parameters structure to destroy.
    771780 */
    772781void ShClTransferObjOpenParmsDestroy(PSHCLOBJOPENCREATEPARMS pParms)
    … …  
    10921101 *
    10931102 * @returns Duplicated object data chunk on success, or NULL on failure.
    1094  * @param   pDataChunk          transfer object data chunk to duplicate.
     1103 * @param   pDataChunk          Transfer object data chunk to duplicate.
    10951104 */
    10961105PSHCLOBJDATACHUNK ShClTransferObjDataChunkDup(PSHCLOBJDATACHUNK pDataChunk)
    10971106{
    1098     if (!pDataChunk)
    1099         return NULL;
     1107    AssertPtrReturn(pDataChunk, NULL);
    11001108
    11011109    PSHCLOBJDATACHUNK pDataChunkDup = (PSHCLOBJDATACHUNK)RTMemAllocZ(sizeof(SHCLOBJDATACHUNK));
    … …  
    11091117        pDataChunkDup->uHandle = pDataChunk->uHandle;
    11101118        pDataChunkDup->pvData  = RTMemDup(pDataChunk->pvData, pDataChunk->cbData);
     1119        AssertPtrReturn(pDataChunkDup->pvData, NULL);
    11111120        pDataChunkDup->cbData  = pDataChunk->cbData;
    11121121    }
    … …  
    11181127 * Destroys a transfer object data chunk.
    11191128 *
    1120  * @param   pDataChunk          transfer object data chunk to destroy.
     1129 * @param   pDataChunk          Transfer object data chunk to destroy.
    11211130 */
    11221131void ShClTransferObjDataChunkDestroy(PSHCLOBJDATACHUNK pDataChunk)
    … …  
    11411150 * Frees a transfer object data chunk.
    11421151 *
    1143  * @param   pDataChunk          transfer object data chunk to free. The handed-in pointer will
    1144  *                              be invalid after calling this function.
     1152 * @param   pDataChunk          Transfer object data chunk to free.
     1153 *                              The pointer will be invalid on return.
    11451154 */
    11461155void ShClTransferObjDataChunkFree(PSHCLOBJDATACHUNK pDataChunk)
    … …  
    11591168 *
    11601169 * @returns VBox status code.
    1161  * @param   ppTransfer          Where to return the created Shared Clipboard transfer struct.
     1170 * @param   ppTransfer          Where to return the created clipboard transfer struct.
    11621171 *                              Must be destroyed by ShClTransferDestroy().
    11631172 */
    … …  
    12201229
    12211230/**
    1222  * Destroys a clipboard transfer context struct.
     1231 * Destroys a clipboard transfer.
    12231232 *
    12241233 * @returns VBox status code.
    … …  
    12451254
    12461255/**
    1247  * Initializes a Shared Clipboard transfer object.
     1256 * Initializes a clipboard transfer.
    12481257 *
    12491258 * @returns VBox status code.
    … …  
    12781287
    12791288/**
    1280  * Returns a specific list handle info of a transfer.
     1289 * Returns a specific list handle info of a clipboard transfer.
    12811290 *
    12821291 * @returns Pointer to list handle info if found, or NULL if not found.
    … …  
    14281437
    14291438/**
    1430  * Opens a list.
     1439 * Opens a transfer list.
    14311440 *
    14321441 * @returns VBox status code.
    … …  
    15521561
    15531562/**
    1554  * Closes a list.
     1563 * Closes a transfer list.
    15551564 *
    15561565 * @returns VBox status code.
    … …  
    16141623
    16151624/**
    1616  * Adds a file to a list heaer.
     1625 * Adds a file to a transfer list header.
    16171626 *
    16181627 * @returns VBox status code.
    … …  
    16221631static int shclTransferListHdrAddFile(PSHCLLISTHDR pHdr, const char *pszPath)
    16231632{
     1633    AssertPtrReturn(pHdr, VERR_INVALID_POINTER);
     1634    AssertPtrReturn(pszPath, VERR_INVALID_POINTER);
     1635
    16241636    uint64_t cbSize = 0;
    16251637    int rc = RTFileQuerySizeByPath(pszPath, &cbSize);
    … …  
    16351647
    16361648/**
    1637  * Builds a list header, internal version.
     1649 * Builds a transfer list header, internal version.
    16381650 *
    16391651 * @returns VBox status code.
    16401652 * @param   pHdr                Where to store the build list header.
    1641  * @param   pcszSrcPath         Source path of list.
    1642  * @param   pcszDstPath         Destination path of list.
    1643  * @param   pcszDstBase         Destination base path.
    1644  * @param   cchDstBase          Number of charaters of destination base path.
     1653 * @param   pcszPathAbs         Absolute path to use for building the transfer list.
    16451654 */
    16461655static int shclTransferListHdrFromDir(PSHCLLISTHDR pHdr, const char *pcszPathAbs)
    … …  
    17281737
    17291738/**
    1730  * Retrieves the header of a Shared Clipboard list.
     1739 * Retrieves the header of a transfer list.
    17311740 *
    17321741 * @returns VBox status code.
    … …  
    18061815
    18071816/**
    1808  * Returns the current transfer object for a Shared Clipboard transfer list.
     1817 * Returns the current transfer object of a transfer list.
    18091818 *
    18101819 * Currently not implemented and wil return NULL.
    … …  
    18121821 * @returns Pointer to transfer object, or NULL if not found / invalid.
    18131822 * @param   pTransfer           Clipboard transfer to return transfer object for.
    1814  * @param   hList               Handle of Shared Clipboard transfer list to get object for.
     1823 * @param   hList               Handle of clipboard transfer list to get object for.
    18151824 * @param   uIdx                Index of object to get.
    18161825 */
    … …  
    18281837
    18291838/**
    1830  * Reads a single Shared Clipboard list entry.
     1839 * Reads a single transfer list entry.
    18311840 *
    18321841 * @returns VBox status code or VERR_NO_MORE_FILES if the end of the list has been reached.
    … …  
    19932002
    19942003/**
    1995  * Returns whether a given list handle is valid or not.
     2004 * Returns whether a given transfer list handle is valid or not.
    19962005 *
    19972006 * @returns \c true if list handle is valid, \c false if not.
    … …  
    20522061
    20532062/**
    2054  * Sets or unsets the callback table to be used for a Shared Clipboard transfer.
     2063 * Sets or unsets the callback table to be used for a clipboard transfer.
    20552064 *
    20562065 * @returns VBox status code.
    … …  
    20942103
    20952104/**
    2096  * Clears (resets) the root list of a Shared Clipboard transfer.
     2105 * Clears (resets) the root list of a clipboard transfer.
    20972106 *
    20982107 * @param   pTransfer           Transfer to clear transfer root list for.
    … …  
    21232132
    21242133/**
    2125  * Resets a Shared Clipboard transfer.
     2134 * Resets a clipboard transfer.
    21262135 *
    21272136 * @param   pTransfer           Clipboard transfer to reset.
    … …  
    22552264
    22562265/**
    2257  * Returns the root entries of a Shared Clipboard transfer.
     2266 * Returns the root entries of a clipboard transfer.
    22582267 *
    22592268 * @returns VBox status code.
    … …  
    23252334
    23262335/**
    2327  * Sets transfer root list entries for a given transfer.
     2336 * Sets root list entries for a given clipboard transfer.
    23282337 *
    23292338 * @returns VBox status code.
    … …  
    24402449
    24412450/**
    2442  * Returns the transfer's ID.
     2451 * Returns the clipboard transfer's ID.
    24432452 *
    24442453 * @returns The transfer's ID.
    … …  
    24532462
    24542463/**
    2455  * Returns the transfer's direction.
     2464 * Returns the clipboard transfer's direction.
    24562465 *
    24572466 * @returns The transfer's direction.
    … …  
    24952504
    24962505/**
    2497  * Runs a started Shared Clipboard transfer in a dedicated thread.
     2506 * Runs a started clipboard transfer in a dedicated thread.
    24982507 *
    24992508 * @returns VBox status code.
    … …  
    25542563
    25552564/**
    2556  * Creates a thread for a Shared Clipboard transfer.
     2565 * Creates a thread for a clipboard transfer.
    25572566 *
    25582567 * @returns VBox status code.
    … …  
    25952604
    25962605/**
    2597  * Destroys a thread of a Shared Clipboard transfer.
     2606 * Destroys the thread of a clipboard transfer.
    25982607 *
    25992608 * @returns VBox status code.
    … …  
    26222631
    26232632/**
    2624  * Initializes a Shared Clipboard transfer context.
     2633 * Initializes a clipboard transfer context.
    26252634 *
    26262635 * @returns VBox status code.
    … …  
    26542663
    26552664/**
    2656  * Destroys a Shared Clipboard transfer context struct.
     2665 * Destroys a clipboard transfer context.
    26572666 *
    26582667 * @param   pTransferCtx                Transfer context to destroy.
    … …  
    26842693
    26852694/**
    2686  * Resets a Shared Clipboard transfer.
     2695 * Resets a clipboard transfer context.
    26872696 *
    26882697 * @param   pTransferCtx                Transfer context to reset.
    … …  
    27042713
    27052714/**
    2706  * Returns a specific Shared Clipboard transfer, internal version.
    2707  *
    2708  * @returns Shared Clipboard transfer, or NULL if not found.
     2715 * Returns a specific clipboard transfer, internal version.
     2716 *
     2717 * @returns Clipboard transfer found, or NULL if not found.
    27092718 * @param   pTransferCtx                Transfer context to return transfer for.
    27102719 * @param   uID                         ID of the transfer to return.
    … …  
    27232732
    27242733/**
    2725  * Returns a specific Shared Clipboard transfer by index, internal version.
    2726  *
    2727  * @returns Shared Clipboard transfer, or NULL if not found.
     2734 * Returns a specific clipboard transfer by index, internal version.
     2735 *
     2736 * @returns Clipboard transfer found, or NULL if not found.
    27282737 * @param   pTransferCtx                Transfer context to return transfer for.
    27292738 * @param   uIdx                        Index of the transfer to return.
    … …  
    27452754
    27462755/**
    2747  * Returns a Shared Clipboard transfer for a specific transfer ID.
    2748  *
    2749  * @returns Shared Clipboard transfer, or NULL if not found.
     2756 * Returns a clipboard transfer for a specific transfer ID.
     2757 *
     2758 * @returns Clipboard transfer found, or NULL if not found.
    27502759 * @param   pTransferCtx                Transfer context to return transfer for.
    27512760 * @param   uID                         ID of the transfer to return.
    … …  
    27572766
    27582767/**
    2759  * Returns a Shared Clipboard transfer for a specific list index.
    2760  *
    2761  * @returns Shared Clipboard transfer, or NULL if not found.
     2768 * Returns a clipboard transfer for a specific list index.
     2769 *
     2770 * @returns Clipboard transfer found, or NULL if not found.
    27622771 * @param   pTransferCtx                Transfer context to return transfer for.
    27632772 * @param   uIdx                        List index of the transfer to return.
    … …  
    27692778
    27702779/**
    2771  * Returns the number of running Shared Clipboard transfers.
     2780 * Returns the number of running clipboard transfers for a given transfer context.
    27722781 *
    27732782 * @returns Number of running transfers.
    … …  
    27812790
    27822791/**
    2783  * Returns the number of total Shared Clipboard transfers.
     2792 * Returns the number of total clipboard transfers for a given transfer context.
    27842793 *
    27852794 * @returns Number of total transfers.
    … …  
    27932802
    27942803/**
    2795  * Registers a Shared Clipboard transfer with a transfer context, i.e. allocates a transfer ID.
     2804 * Registers a clipboard transfer with a transfer context, i.e. allocates a transfer ID.
    27962805 *
    27972806 * @return  VBox status code.
    … …  
    28522861
    28532862/**
    2854  * Registers a Shared Clipboard transfer with a transfer context by specifying an ID for the transfer.
     2863 * Registers a clipboard transfer with a transfer context by specifying an ID for the transfer.
    28552864 *
    28562865 * @return  VBox status code.
    … …  
    31123121
    31133122/**
    3114  * Translates a Shared Clipboard transfer status (SHCLTRANSFERSTATUS_XXX) into a string.
     3123 * Translates a clipboard transfer status (SHCLTRANSFERSTATUS_XXX) into a string.
    31153124 *
    31163125 * @returns Transfer status string name.
    … …  
    31313140    return "Unknown";
    31323141}
     3142
Note: See TracChangeset for help on using the changeset viewer.

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