VirtualBox

Changeset 74333 in vbox for trunk/src


Ignore:
Timestamp:
Sep 18, 2018 9:19:57 AM (6 years ago)
Author:
vboxsync
Message:

DnD/VbglR3: Documentation.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/VBox/Additions/common/VBoxGuest/lib/VBoxGuestR3LibDragAndDrop.cpp

    r74140 r74333  
    55
    66/*
    7  * Copyright (C) 2011-2017 Oracle Corporation
     7 * Copyright (C) 2011-2018 Oracle Corporation
    88 *
    99 * This file is part of VirtualBox Open Source Edition (OSE), as
    … …  
    5757*********************************************************************************************************************************/
    5858
     59/**
     60 * Receives the next upcoming message for a given DnD context.
     61 *
     62 * @returns IPRT status code.
     63 * @param   pCtx                DnD context to use.
     64 * @param   puMsg               Where to store the message type.
     65 * @param   pcParms             Where to store the number of parameters required for receiving the message.
     66 * @param   fWait               Whether to wait (block) for a new message to arrive or not.
     67 */
    5968static int vbglR3DnDGetNextMsgType(PVBGLR3GUESTDNDCMDCTX pCtx, uint32_t *puMsg, uint32_t *pcParms, bool fWait)
    6069{
    … …  
    8089}
    8190
    82 /** @todo r=andy Clean up the parameter list. */
     91/**
     92 * Host -> Guest
     93 * Utility function to receive a so-called "action message" from the host.
     94 * Certain DnD messages use the same amount / sort of parameters and grouped as "action messages".
     95 *
     96 * @returns IPRT status code.
     97 * @param   pCtx                DnD context to use.
     98 * @param   uMsg                Which kind of message to receive.
     99 * @param   puScreenID          Where to store the host screen ID the message is bound to.
     100 * @param   puX                 Where to store the absolute X coordinates.
     101 * @param   puY                 Where to store the absolute Y coordinates.
     102 * @param   puDefAction         Where to store the default action to perform.
     103 * @param   puAllActions        Where to store the available actions.
     104 * @param   ppszFormats         Where to store List of formats.
     105 * @param   pcbFormats          Size (in bytes) of where to store the list of formats.
     106 *
     107 * @todo r=andy Get rid of this function as soon as we resolved the protocol TODO #1.
     108 *              This was part of the initial protocol and needs to go.
     109 */
    83110static int vbglR3DnDHGRecvAction(PVBGLR3GUESTDNDCMDCTX pCtx,
    84111                                 uint32_t  uMsg,
    … …  
    157184}
    158185
     186/**
     187 * Host -> Guest
     188 * Utility function to receive a HOST_DND_HG_EVT_LEAVE message from the host.
     189 *
     190 * @returns IPRT status code.
     191 * @param   pCtx                DnD context to use.
     192 */
    159193static int vbglR3DnDHGRecvLeave(PVBGLR3GUESTDNDCMDCTX pCtx)
    160194{
    … …  
    175209}
    176210
     211/**
     212 * Host -> Guest
     213 * Utility function to receive a HOST_DND_HG_EVT_CANCEL message from the host.
     214 *
     215 * @returns IPRT status code.
     216 * @param   pCtx                DnD context to use.
     217 */
    177218static int vbglR3DnDHGRecvCancel(PVBGLR3GUESTDNDCMDCTX pCtx)
    178219{
    … …  
    193234}
    194235
     236/**
     237 * Host -> Guest
     238 * Utility function to receive a HOST_DND_HG_SND_DIR message from the host.
     239 *
     240 * @returns IPRT status code.
     241 * @param   pCtx                DnD context to use.
     242 * @param   pszDirname          Where to store the directory name of the directory being created.
     243 * @param   cbDirname           Size (in bytes) of where to store the directory name of the directory being created.
     244 * @param   pcbDirnameRecv      Size (in bytes) of the actual directory name received.
     245 * @param   pfMode              Where to store the directory creation mode.
     246 */
    195247static int vbglR3DnDHGRecvDir(PVBGLR3GUESTDNDCMDCTX pCtx,
    196248                              char     *pszDirname,
    … …  
    245297}
    246298
     299/**
     300 * Host -> Guest
     301 * Utility function to receive a HOST_DND_HG_SND_FILE_DATA message from the host.
     302 *
     303 * @returns IPRT status code.
     304 * @param   pCtx                DnD context to use.
     305 * @param   pszFilename         Where to store the file name of the file being transferred.
     306 *                              Only needed for protocol v1.
     307 * @param   cbFilename          Size (in bytes) of where to store the file name of the file being transferred.
     308 *                              Only needed for protocol v1.
     309 * @param   pcbFilenameRev      Size (in bytes) of the actual file name received.
     310 *                              Only needed for protocol v1.
     311 * @param   pvData              Where to store the file data chunk.
     312 * @param   cbData              Size (in bytes) of where to store the data chunk.
     313 * @param   pcbDataRecv         Size (in bytes) of the actual data chunk size received.
     314 * @param   pfMode              Where to store the file creation mode.
     315 *                              Only needed for protocol v1.
     316 */
    247317static int vbglR3DnDHGRecvFileData(PVBGLR3GUESTDNDCMDCTX pCtx,
    248318                                   char                 *pszFilename,
    … …  
    325395}
    326396
     397/**
     398 * Host -> Guest
     399 * Utility function to receive the HOST_DND_HG_SND_FILE_HDR message from the host.
     400 *
     401 * @returns IPRT status code.
     402 * @param   pCtx                DnD context to use.
     403 * @param   pszFilename         Where to store the file name of the file being transferred.
     404 * @param   cbFilename          Size (in bytes) of where to store the file name of the file being transferred.
     405 * @param   puFlags             File transfer flags. Currently not being used.
     406 * @param   pfMode              Where to store the file creation mode.
     407 * @param   pcbTotal            Where to store the file size (in bytes).
     408 */
    327409static int vbglR3DnDHGRecvFileHdr(PVBGLR3GUESTDNDCMDCTX  pCtx,
    328410                                  char                  *pszFilename,
    … …  
    370452}
    371453
     454/**
     455 * Host -> Guest
     456 * Helper function for receiving URI data from the host. Do not call directly.
     457 * This function also will take care of the file creation / locking on the guest.
     458 *
     459 * @returns IPRT status code.
     460 * @param   pCtx                DnD context to use.
     461 * @param   pDataHdr            DnD data header to use. Needed for accounting.
     462 * @param   pDroppedFiles       Dropped files object to use for maintaining the file creation / locking.
     463 */
    372464static int vbglR3DnDHGRecvURIData(PVBGLR3GUESTDNDCMDCTX pCtx, PVBOXDNDSNDDATAHDR pDataHdr, DnDDroppedFiles *pDroppedFiles)
    373465{
    … …  
    687779}
    688780
     781/**
     782 * Host -> Guest
     783 * Utility function to receive the HOST_DND_HG_SND_DATA message from the host.
     784 *
     785 * @returns IPRT status code.
     786 * @param   pCtx                DnD context to use.
     787 * @param   pDataHdr            DnD data header to use. Need for accounting and stuff.
     788 * @param   pvData              Where to store the received data from the host.
     789 * @param   cbData              Size (in bytes) of where to store the received data.
     790 * @param   pcbDataRecv         Where to store the received amount of data (in bytes).
     791 */
    689792static int vbglR3DnDHGRecvDataRaw(PVBGLR3GUESTDNDCMDCTX pCtx, PVBOXDNDSNDDATAHDR pDataHdr,
    690793                                  void *pvData, uint32_t cbData, uint32_t *pcbDataRecv)
    … …  
    789892}
    790893
     894/**
     895 * Host -> Guest
     896 * Utility function to receive the HOST_DND_HG_SND_DATA_HDR message from the host.
     897 *
     898 * @returns IPRT status code.
     899 * @param   pCtx                DnD context to use.
     900 * @param   pDataHdr            Where to store the receivd DnD data header.
     901 */
    791902static int vbglR3DnDHGRecvDataHdr(PVBGLR3GUESTDNDCMDCTX pCtx, PVBOXDNDSNDDATAHDR pDataHdr)
    792903{
    … …  
    831942}
    832943
    833 /** @todo Deprecated function; will be removed. */
     944/**
     945 * Host -> Guest
     946 * Helper function for receiving the actual DnD data from the host. Do not call directly.
     947 *
     948 * @returns IPRT status code.
     949 * @param   pCtx                DnD context to use.
     950 * @param   pvData              Where to store the receivd DnD data.
     951 * @param   cbData              Size (in bytes) of where to store the received DnD data.
     952 * @param   pcbDataRecv         Where to store how much bytes of data actually was received.
     953 *
     954 * @remark  Deprecated function and not being used since protocl 3 anymore; will be removed.
     955 */
    834956static int vbglR3DnDHGRecvMoreData(PVBGLR3GUESTDNDCMDCTX pCtx, void *pvData, uint32_t cbData, uint32_t *pcbDataRecv)
    835957{
    … …  
    855977}
    856978
     979/**
     980 * Host -> Guest
     981 * Helper function for receiving the actual DnD data from the host. Do not call directly.
     982 *
     983 * @returns IPRT status code.
     984 * @param   pCtx                DnD context to use.
     985 * @param   pDataHdr            Where to store the data header data.
     986 * @param   ppvData             Returns the received meta data. Needs to be free'd by the caller.
     987 * @param   pcbData             Where to store the size (in bytes) of the received meta data.
     988 */
    857989static int vbglR3DnDHGRecvDataLoop(PVBGLR3GUESTDNDCMDCTX pCtx, PVBOXDNDSNDDATAHDR pDataHdr,
    858990                                   void **ppvData, uint64_t *pcbData)
    … …  
    10031135}
    10041136
    1005 /** @todo Replace the parameters (except pCtx) with PVBOXDNDSNDDATAHDR. Later. */
    1006 /** @todo Hand in the DnDURIList + DnDDroppedFiles objects so that this function
    1007  *        can fill it directly instead of passing huge blobs of data around. */
     1137/**
     1138 * Host -> Guest
     1139 * Main function for receiving the actual DnD data from the host, extended version.
     1140 *
     1141 * @returns IPRT status code.
     1142 * @param   pCtx                DnD context to use.
     1143 * @param   pEnmType            Where to store the meta data type.
     1144 * @param   ppvData             Returns the received meta data. Needs to be free'd by the caller.
     1145 * @param   pcbData             Where to store the size (in bytes) of the received meta data.
     1146 */
    10081147static int vbglR3DnDHGRecvDataMain(PVBGLR3GUESTDNDCMDCTX  pCtx,
    10091148                                   uint32_t              *puScreenId,
    … …  
    11171256}
    11181257
     1258#ifdef VBOX_WITH_DRAG_AND_DROP_GH
     1259/**
     1260 * Guest -> Host
     1261 * Utility function to receive the HOST_DND_GH_REQ_PENDING message from the host.
     1262 *
     1263 * @returns IPRT status code.
     1264 * @param   pCtx                DnD context to use.
     1265 * @param   puScreenId          For which screen on the host the request is for.
     1266 */
    11191267static int vbglR3DnDGHRecvPending(PVBGLR3GUESTDNDCMDCTX pCtx, uint32_t *puScreenId)
    11201268{
    … …  
    11541302}
    11551303
     1304/**
     1305 * Guest -> Host
     1306 * Utility function to receive the HOST_DND_GH_EVT_DROPPED message from the host.
     1307 *
     1308 * @returns IPRT status code.
     1309 * @param   pCtx                DnD context to use.
     1310 * @param   pszFormat           Requested data format from the host.
     1311 * @param   cbFormat            Size of requested data format (in bytes).
     1312 * @param   pcbFormatRecv       Actual size of requested data format (in bytes).
     1313 * @param   puAction            Requested action from the host.
     1314 */
    11561315static int vbglR3DnDGHRecvDropped(PVBGLR3GUESTDNDCMDCTX pCtx,
    11571316                                  char     *pszFormat,
    … …  
    12041363    return rc;
    12051364}
     1365#endif /* VBOX_WITH_DRAG_AND_DROP_GH */
    12061366
    12071367
    … …  
    12101370*********************************************************************************************************************************/
    12111371
     1372/**
     1373 * Connects a DnD context to the DnD host service.
     1374 *
     1375 * @returns IPRT status code.
     1376 * @param   pCtx                DnD context to connect.
     1377 */
    12121378VBGLR3DECL(int) VbglR3DnDConnect(PVBGLR3GUESTDNDCMDCTX pCtx)
    12131379{
    … …  
    12991465}
    13001466
     1467/**
     1468 * Disconnects a given DnD context from the DnD host service.
     1469 *
     1470 * @returns IPRT status code.
     1471 * @param   pCtx                DnD context to use.
     1472 *                              The context is invalid afterwards on successful disconnection.
     1473 */
    13011474VBGLR3DECL(int) VbglR3DnDDisconnect(PVBGLR3GUESTDNDCMDCTX pCtx)
    13021475{
    … …  
    13081481}
    13091482
     1483/**
     1484 * Receives the next upcoming event for a given DnD context.
     1485 *
     1486 * @returns IPRT status code.
     1487 * @param   pCtx                DnD context to use.
     1488 * @param   pEvent              Where to return the received DnD event on success.
     1489 */
    13101490VBGLR3DECL(int) VbglR3DnDRecvNextMsg(PVBGLR3GUESTDNDCMDCTX pCtx, CPVBGLR3DNDHGCMEVENT pEvent)
    13111491{
    … …  
    14381618}
    14391619
     1620/**
     1621 * Host -> Guest
     1622 * Acknowledges that a pending DnD operation from the host can be dropped
     1623 * on the currently selected area on the guest.
     1624 *
     1625 * @returns IPRT status code.
     1626 * @param   pCtx                DnD context to use.
     1627 * @param   uAction             Action to acknowledge.
     1628 */
    14401629VBGLR3DECL(int) VbglR3DnDHGSendAckOp(PVBGLR3GUESTDNDCMDCTX pCtx, uint32_t uAction)
    14411630{
    … …  
    14611650}
    14621651
     1652/**
     1653 * Host -> Guest
     1654 * Requests the actual DnD data to be sent from the host.
     1655 *
     1656 * @returns IPRT status code.
     1657 * @param   pCtx                DnD context to use.
     1658 * @param   pcszFormat          Format to request the data from the host in.
     1659 */
    14631660VBGLR3DECL(int) VbglR3DnDHGSendReqData(PVBGLR3GUESTDNDCMDCTX pCtx, const char* pcszFormat)
    14641661{
    … …  
    14891686}
    14901687
     1688/**
     1689 * Host -> Guest
     1690 * Reports back its progress back to the host.
     1691 *
     1692 * @returns IPRT status code.
     1693 * @param   pCtx                DnD context to use.
     1694 * @param   uStatus             DnD status to report.
     1695 * @param   uPercent            Overall progress (in percent) to report.
     1696 * @param   rcErr               Error code (IPRT-style) to report.
     1697 */
    14911698VBGLR3DECL(int) VbglR3DnDHGSendProgress(PVBGLR3GUESTDNDCMDCTX pCtx, uint32_t uStatus, uint8_t uPercent, int rcErr)
    14921699{
    … …  
    15171724
    15181725#ifdef VBOX_WITH_DRAG_AND_DROP_GH
    1519 
     1726/**
     1727 * Guest -> Host
     1728 * Acknowledges that there currently is a drag'n drop operation in progress on the guest,
     1729 * which eventually could be dragged over to the host.
     1730 *
     1731 * @returns IPRT status code.
     1732 * @param   pCtx                DnD context to use.
     1733 * @param   uDefAction          Default action for the operation to report.
     1734 * @param   uAllActions         All available actions for the operation to report.
     1735 * @param   pcszFormats         Available formats for the operation to report.
     1736 * @param   cbFormats           Size (in bytes) of formats to report.
     1737 */
    15201738VBGLR3DECL(int) VbglR3DnDGHSendAckPending(PVBGLR3GUESTDNDCMDCTX pCtx,
    15211739                                          uint32_t uDefAction, uint32_t uAllActions, const char* pcszFormats, uint32_t cbFormats)
    … …  
    15511769}
    15521770
     1771/**
     1772 * Guest -> Host
     1773 * Utility function to send DnD data from guest to the host.
     1774 *
     1775 * @returns IPRT status code.
     1776 * @param   pCtx                DnD context to use.
     1777 * @param   pvData              Data block to send.
     1778 * @param   cbData              Size (in bytes) of data block to send.
     1779 * @param   pDataHdr            Data header to use -- needed for accounting.
     1780 */
    15531781static int vbglR3DnDGHSendDataInternal(PVBGLR3GUESTDNDCMDCTX pCtx,
    15541782                                       void *pvData, uint64_t cbData, PVBOXDNDSNDDATAHDR pDataHdr)
    … …  
    16411869}
    16421870
     1871/**
     1872 * Guest -> Host
     1873 * Utility function to send a guest directory to the host.
     1874 *
     1875 * @returns IPRT status code.
     1876 * @param   pCtx                DnD context to use.
     1877 * @param   pObj                URI object containing the directory to send.
     1878 */
    16431879static int vbglR3DnDGHSendDir(PVBGLR3GUESTDNDCMDCTX pCtx, DnDURIObject *pObj)
    16441880{
    … …  
    16811917}
    16821918
     1919/**
     1920 * Guest -> Host
     1921 * Utility function to send a file from the guest to the host.
     1922 *
     1923 * @returns IPRT status code.
     1924 * @param   pCtx                DnD context to use.
     1925 * @param   pObj                URI object containing the file to send.
     1926 */
    16831927static int vbglR3DnDGHSendFile(PVBGLR3GUESTDNDCMDCTX pCtx, DnDURIObject *pObj)
    16841928{
    … …  
    18182062}
    18192063
     2064/**
     2065 * Guest -> Host
     2066 * Utility function to send an URI object from guest to the host.
     2067 *
     2068 * @returns IPRT status code.
     2069 * @param   pCtx                DnD context to use.
     2070 * @param   pObj                URI object to send from guest to the host.
     2071 */
    18202072static int vbglR3DnDGHSendURIObject(PVBGLR3GUESTDNDCMDCTX pCtx, DnDURIObject *pObj)
    18212073{
    … …  
    18442096}
    18452097
     2098/**
     2099 * Guest -> Host
     2100 * Utility function to send raw data from guest to the host.
     2101 *
     2102 * @returns IPRT status code.
     2103 * @param   pCtx                DnD context to use.
     2104 * @param   pvData              Block to raw data to send.
     2105 * @param   cbData              Size (in bytes) of raw data to send.
     2106 */
    18462107static int vbglR3DnDGHSendRawData(PVBGLR3GUESTDNDCMDCTX pCtx, void *pvData, size_t cbData)
    18472108{
    … …  
    18592120}
    18602121
     2122/**
     2123 * Guest -> Host
     2124 * Utility function to send URI data from guest to the host.
     2125 *
     2126 * @returns IPRT status code.
     2127 * @param   pCtx                DnD context to use.
     2128 * @param   pvData              Block to URI data to send.
     2129 * @param   cbData              Size (in bytes) of URI data to send.
     2130 */
    18612131static int vbglR3DnDGHSendURIData(PVBGLR3GUESTDNDCMDCTX pCtx, const void *pvData, size_t cbData)
    18622132{
    … …  
    19262196}
    19272197
     2198/**
     2199 * Guest -> Host
     2200 * Sends data, which either can be raw or URI data, from guest to the host. This function
     2201 * initiates the actual data transfer from guest to the host.
     2202 *
     2203 * @returns IPRT status code.
     2204 * @param   pCtx                DnD context to use.
     2205 * @param   pszFormat           In which format the data will be sent.
     2206 * @param   pvData              Data block to send.
     2207 * @param   cbData              Size (in bytes) of data block to send.
     2208 */
    19282209VBGLR3DECL(int) VbglR3DnDGHSendData(PVBGLR3GUESTDNDCMDCTX pCtx, const char *pszFormat, void *pvData, uint32_t cbData)
    19292210{
    … …  
    19542235}
    19552236
     2237/**
     2238 * Guest -> Host
     2239 * Send an error back to the host.
     2240 *
     2241 * @returns IPRT status code.
     2242 * @param   pCtx                DnD context to use.
     2243 * @param   rcErr               Error (IPRT-style) to send.
     2244 */
    19562245VBGLR3DECL(int) VbglR3DnDGHSendError(PVBGLR3GUESTDNDCMDCTX pCtx, int rcErr)
    19572246{
    … …  
    19912280    return rc;
    19922281}
    1993 
    19942282#endif /* VBOX_WITH_DRAG_AND_DROP_GH */
    19952283
Note: See TracChangeset for help on using the changeset viewer.

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