VirtualBox

Changeset 85681 in vbox for trunk/src/VBox


Ignore:
Timestamp:
Aug 11, 2020 9:36:37 AM (4 years ago)
Author:
vboxsync
Message:

DnD: Lots of documentation.

Location:
trunk/src/VBox
Files:
14 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/VBox/Additions/WINNT/VBoxTray/VBoxDnD.h

    r85371 r85681  
    2929class VBoxDnDWnd;
    3030
     31/**
     32 * Class for implementing IDataObject for VBoxTray's DnD support.
     33 */
    3134class VBoxDnDDataObject : public IDataObject
    3235{
    … …  
    8083                        LONG lindex = -1, DWORD dwAspect = DVASPECT_CONTENT, DVTARGETDEVICE *pTargetDevice = NULL);
    8184
     85    /** Current drag and drop status. */
    8286    Status      mStatus;
     87    /** Internal reference count of this object. */
    8388    LONG        mRefCount;
     89    /** Number of native formats registered. This can be a different number than supplied with m_lstFormats. */
    8490    ULONG       mcFormats;
     91    /** Array of registered FORMATETC structs. Matches m_cFormats. */
    8592    LPFORMATETC mpFormatEtc;
     93    /** Array of registered STGMEDIUM structs. Matches m_cFormats. */
    8694    LPSTGMEDIUM mpStgMedium;
     95    /** Event semaphore used for waiting on status changes. */
    8796    RTSEMEVENT  mEventDropped;
     97    /** Format of currently retrieved data. */
    8898    RTCString   mstrFormat;
     99    /** The retrieved data as a raw buffer. */
    89100    void       *mpvData;
     101    /** Raw buffer size (in bytes). */
    90102    size_t      mcbData;
    91103};
    92104
     105/**
     106 * Class for implementing IDropSource for VBoxTray's DnD support.
     107 */
    93108class VBoxDnDDropSource : public IDropSource
    94109{
    … …  
    125140};
    126141
     142/**
     143 * Class for implementing IDropTarget for VBoxTray's DnD support.
     144 */
    127145class VBoxDnDDropTarget : public IDropTarget
    128146{
    … …  
    153171public:
    154172
     173    /** Returns the data as mutable raw. Use with caution! */
    155174    void *DataMutableRaw(void) const { return mpvData; }
     175
     176    /** Returns the data size (in bytes). */
    156177    size_t DataSize(void) const { return mcbData; }
     178
    157179    RTCString Formats(void) const;
    158180    int WaitForDrop(RTMSINTERVAL msTimeout);
    … …  
    181203};
    182204
     205/**
     206 * Class for implementing IEnumFORMATETC for VBoxTray's DnD support.
     207 */
    183208class VBoxDnDEnumFormatEtc : public IEnumFORMATETC
    184209{
    … …  
    206231private:
    207232
     233    /** Reference count of this object. */
    208234    LONG        m_lRefCount;
     235    /** Current index for format iteration. */
    209236    ULONG       m_nIndex;
     237    /** Number of format this object contains. */
    210238    ULONG       m_nNumFormats;
     239    /** Array of FORMATETC formats this object contains. Matches m_nNumFormats. */
    211240    LPFORMATETC m_pFormatEtc;
    212241};
    … …  
    215244class VBoxDnDWnd;
    216245
    217 /*
     246/**
    218247 * A drag'n drop event from the host.
    219248 */
    … …  
    371400     *  window messages. */
    372401    RTTHREAD                   hThread;
     402    /** Critical section to serialize access. */
    373403    RTCRITSECT                 mCritSect;
     404    /** Event semaphore to wait for new DnD events. */
    374405    RTSEMEVENT                 mEventSem;
    375406#ifdef RT_OS_WINDOWS
    … …  
    393424    bool                       mfMouseButtonDown;
    394425# ifdef VBOX_WITH_DRAG_AND_DROP_GH
    395     /** IDropTarget implementation for guest -> host
    396      *  support. */
     426    /** Pointer to IDropTarget implementation for
     427     *  guest -> host support. */
    397428    VBoxDnDDropTarget         *pDropTarget;
    398429# endif /* VBOX_WITH_DRAG_AND_DROP_GH */

  • trunk/src/VBox/Additions/WINNT/VBoxTray/VBoxDnDDataObject.cpp

    r85371 r85681  
    173173}
    174174
    175 /**
    176  * Retrieves the data stored in this object and store the result in
    177  * pMedium.
    178  *
    179  * @return  IPRT status code.
    180  * @return  HRESULT
    181  * @param   pFormatEtc
    182  * @param   pMedium
    183  */
    184175STDMETHODIMP VBoxDnDDataObject::GetData(LPFORMATETC pFormatEtc, LPSTGMEDIUM pMedium)
    185176{
    … …  
    416407}
    417408
    418 /**
    419  * Only required for IStream / IStorage interfaces.
    420  *
    421  * @return  IPRT status code.
    422  * @return  HRESULT
    423  * @param   pFormatEtc
    424  * @param   pMedium
    425  */
    426409STDMETHODIMP VBoxDnDDataObject::GetDataHere(LPFORMATETC pFormatEtc, LPSTGMEDIUM pMedium)
    427410{
    … …  
    431414}
    432415
    433 /**
    434  * Query if this objects supports a specific format.
    435  *
    436  * @return  IPRT status code.
    437  * @return  HRESULT
    438  * @param   pFormatEtc
    439  */
    440416STDMETHODIMP VBoxDnDDataObject::QueryGetData(LPFORMATETC pFormatEtc)
    441417{
    … …  
    496472 */
    497473
     474/**
     475 * Aborts waiting for data being "dropped".
     476 *
     477 * @returns VBox status code.
     478 */
    498479int VBoxDnDDataObject::Abort(void)
    499480{
    … …  
    503484}
    504485
     486/**
     487 * Static helper function to convert a CLIPFORMAT to a string and return it.
     488 *
     489 * @returns Pointer to converted stringified CLIPFORMAT, or "unknown" if not found / invalid.
     490 * @param   fmt                 CLIPFORMAT to return string for.
     491 */
    505492/* static */
    506493const char* VBoxDnDDataObject::ClipboardFormatToString(CLIPFORMAT fmt)
    … …  
    586573}
    587574
     575/**
     576 * Checks whether a given FORMATETC is supported by this data object and returns its index.
     577 *
     578 * @returns \c true if format is supported, \c false if not.
     579 * @param   pFormatEtc          Pointer to FORMATETC to check for.
     580 * @param   puIndex             Where to store the index if format is supported.
     581 */
    588582bool VBoxDnDDataObject::LookupFormatEtc(LPFORMATETC pFormatEtc, ULONG *puIndex)
    589583{
    … …  
    632626}
    633627
     628/**
     629 * Registers a new format with this data object.
     630 *
     631 * @param   pFormatEtc          Where to store the new format into.
     632 * @param   clipFormat          Clipboard format to register.
     633 * @param   tyMed               Format medium type to register.
     634 * @param   lIndex              Format index to register.
     635 * @param   dwAspect            Format aspect to register.
     636 * @param   pTargetDevice       Format target device to register.
     637 */
    634638void VBoxDnDDataObject::RegisterFormat(LPFORMATETC pFormatEtc, CLIPFORMAT clipFormat,
    635639                                       TYMED tyMed, LONG lIndex, DWORD dwAspect,
    … …  
    648652}
    649653
     654/**
     655 * Sets the current status of this data object.
     656 *
     657 * @param   status              New status to set.
     658 */
    650659void VBoxDnDDataObject::SetStatus(Status status)
    651660{
    … …  
    654663}
    655664
     665/**
     666 * Signals that data has been "dropped".
     667 *
     668 * @returns VBox status code.
     669 * @param   strFormat           Format of data (MIME string).
     670 * @param   pvData              Pointer to data.
     671 * @param   cbData              Size (in bytes) of data.
     672 */
    656673int VBoxDnDDataObject::Signal(const RTCString &strFormat,
    657674                              const void *pvData, size_t cbData)

  • trunk/src/VBox/Additions/WINNT/VBoxTray/VBoxDnDDropTarget.cpp

    r85520 r85681  
    9494}
    9595
     96/**
     97 * Static helper function to dump supported formats of a data object.
     98 *
     99 * @param   pDataObject         Pointer to data object to dump formats for.
     100 */
    96101/* static */
    97102void VBoxDnDDropTarget::DumpFormats(IDataObject *pDataObject)
    … …  
    559564}
    560565
     566/**
     567 * Static helper function to return a drop effect for a given key state and allowed effects.
     568 *
     569 * @returns Resolved drop effect.
     570 * @param   grfKeyState         Key state to determine drop effect for.
     571 * @param   dwAllowedEffects    Allowed drop effects to determine drop effect for.
     572 */
    561573/* static */
    562574DWORD VBoxDnDDropTarget::GetDropEffect(DWORD grfKeyState, DWORD dwAllowedEffects)
    … …  
    588600}
    589601
     602/**
     603 * Resets a drop target object.
     604 */
    590605void VBoxDnDDropTarget::reset(void)
    591606{
    … …  
    604619}
    605620
     621/**
     622 * Returns the currently supported formats of a drop target.
     623 *
     624 * @returns Supported formats.
     625 */
    606626RTCString VBoxDnDDropTarget::Formats(void) const
    607627{
    … …  
    609629}
    610630
     631/**
     632 * Waits for a drop event to happen.
     633 *
     634 * @returns VBox status code.
     635 * @param   msTimeout           Timeout (in ms) to wait for drop event.
     636 */
    611637int VBoxDnDDropTarget::WaitForDrop(RTMSINTERVAL msTimeout)
    612638{

  • trunk/src/VBox/Frontends/VirtualBox/src/runtime/UIDnDDataObject_win.cpp

    r85455 r85681  
    188188}
    189189
    190 /**
    191  * Retrieves the data stored in this object and store the result in
    192  * pMedium.
    193  *
    194  * @return  IPRT status code.
    195  * @return  HRESULT
    196  * @param   pFormatEtc
    197  * @param   pMedium
    198  */
    199190STDMETHODIMP UIDnDDataObject::GetData(LPFORMATETC pFormatEtc, LPSTGMEDIUM pMedium)
    200191{
    … …  
    512503}
    513504
    514 /**
    515  * Only required for IStream / IStorage interfaces.
    516  *
    517  * @return  IPRT status code.
    518  * @return  HRESULT
    519  * @param   pFormatEtc
    520  * @param   pMedium
    521  */
    522505STDMETHODIMP UIDnDDataObject::GetDataHere(LPFORMATETC pFormatEtc, LPSTGMEDIUM pMedium)
    523506{
    … …  
    527510}
    528511
    529 /**
    530  * Query if this objects supports a specific format.
    531  *
    532  * @return  IPRT status code.
    533  * @return  HRESULT
    534  * @param   pFormatEtc
    535  */
    536512STDMETHODIMP UIDnDDataObject::QueryGetData(LPFORMATETC pFormatEtc)
    537513{
    … …  
    594570 */
    595571
     572/**
     573 * Aborts waiting for data being "dropped".
     574 *
     575 * @returns VBox status code.
     576 */
    596577int UIDnDDataObject::Abort(void)
    597578{
    … …  
    601582}
    602583
     584/**
     585 * Static helper function to convert a CLIPFORMAT to a string and return it.
     586 *
     587 * @returns Pointer to converted stringified CLIPFORMAT, or "unknown" if not found / invalid.
     588 * @param   fmt                 CLIPFORMAT to return string for.
     589 */
    603590/* static */
    604591const char* UIDnDDataObject::ClipboardFormatToString(CLIPFORMAT fmt)
    … …  
    682669}
    683670
     671/**
     672 * Checks whether a given FORMATETC is supported by this data object and returns its index.
     673 *
     674 * @returns \c true if format is supported, \c false if not.
     675 * @param   pFormatEtc          Pointer to FORMATETC to check for.
     676 * @param   puIndex             Where to store the index if format is supported.
     677 */
    684678bool UIDnDDataObject::LookupFormatEtc(LPFORMATETC pFormatEtc, ULONG *puIndex)
    685679{
    … …  
    712706}
    713707
     708/**
     709 * Registers a new format with this data object.
     710 *
     711 * @param   pFormatEtc          Where to store the new format into.
     712 * @param   clipFormat          Clipboard format to register.
     713 * @param   tyMed               Format medium type to register.
     714 * @param   lIndex              Format index to register.
     715 * @param   dwAspect            Format aspect to register.
     716 * @param   pTargetDevice       Format target device to register.
     717 */
    714718void UIDnDDataObject::RegisterFormat(LPFORMATETC pFormatEtc, CLIPFORMAT clipFormat,
    715719                                     TYMED tyMed, LONG lIndex, DWORD dwAspect,
    … …  
    728732}
    729733
     734/**
     735 * Sets the current status of this data object.
     736 *
     737 * @param   enmStatus           New status to set.
     738 */
    730739void UIDnDDataObject::SetStatus(DnDDataObjectStatus enmStatus)
    731740{
    … …  
    734743}
    735744
     745/**
     746 * Signals that data has been "dropped".
     747 *
     748 ** @todo r=andy Remove?
     749 */
    736750void UIDnDDataObject::Signal(void)
    737751{
    … …  
    739753}
    740754
     755/**
     756 * Signals that data has been "dropped".
     757 *
     758 * @returns VBox status code.
     759 * @param   strFormat           Format of data (MIME string).
     760 * @param   pvData              Pointer to data.
     761 * @param   cbData              Size (in bytes) of data.
     762 */
    741763int UIDnDDataObject::Signal(const QString &strFormat,
    742764                            const void *pvData, uint32_t cbData)

  • trunk/src/VBox/Frontends/VirtualBox/src/runtime/UIDnDDataObject_win.h

    r82968 r85681  
    9595    /** Internal reference count of this object. */
    9696    LONG                    m_cRefs;
    97     /** Number of native formats registered. This can be a different number than supplied with mlstFormats. */
     97    /** Number of native formats registered. This can be a different number than supplied with m_lstFormats. */
    9898    ULONG                   m_cFormats;
     99    /** Array of registered FORMATETC structs. Matches m_cFormats. */
    99100    FORMATETC              *m_pFormatEtc;
     101    /** Array of registered STGMEDIUM structs. Matches m_cFormats. */
    100102    STGMEDIUM              *m_pStgMedium;
     103    /** Event semaphore used for waiting on status changes. */
    101104    RTSEMEVENT              m_SemEvent;
     105    /** List of supported formats. */
    102106    QStringList             m_lstFormats;
     107    /** Format of currently retrieved data. */
    103108    QString                 m_strFormat;
    104109    /** The retrieved data as a QVariant. Needed for buffering in case a second format needs the same data,

  • trunk/src/VBox/Frontends/VirtualBox/src/runtime/UIDnDDropSource_win.h

    r82968 r85681  
    5656    /** Pointer to parent widget. */
    5757    QWidget         *m_pParent;
     58    /** Pointer to current data object. */
    5859    UIDnDDataObject *m_pDataObject;
    5960    /** The current reference count. */

  • trunk/src/VBox/Frontends/VirtualBox/src/runtime/UIDnDHandler.cpp

    r85475 r85681  
    601601                                     QVector<uint8_t> &vecData)
    602602{
     603    /** @todo r=andy Locking required? */
     604
    603605    if (!strMIMEType.compare("application/x-qt-mime-type-name", Qt::CaseInsensitive))
    604606        return VINF_SUCCESS;
    … …  
    713715}
    714716
     717/**
     718 * Sets the current DnD operation mode.
     719 *
     720 * Note: Only one mode (guest->host *or* host->guest) can be active at the same time.
     721 *
     722 * @param   enmMode             Current operation mode to set.
     723 */
    715724void UIDnDHandler::setOpMode(DNDOPMODE enmMode)
    716725{
    717726    QMutexLocker AutoWriteLock(&m_WriteLock);
     727
     728    /** @todo r=andy Check for old (current) mode and refuse new mode? */
     729
    718730    m_enmOpMode = enmMode;
    719731    LogFunc(("Operation mode is now: %RU32\n", m_enmOpMode));
    … …  
    734746 */
    735747
     748/**
     749 * Static helper function to convert a Qt drop action to an internal DnD drop action.
     750 *
     751 * @returns Converted internal drop action.
     752 * @param   action              Qt drop action to convert.
     753 */
    736754/* static */
    737755KDnDAction UIDnDHandler::toVBoxDnDAction(Qt::DropAction action)
    … …  
    747765}
    748766
     767/**
     768 * Static helper function to convert Qt drop actions to internal DnD drop actions.
     769 *
     770 * @returns Vector of converted internal drop actions.
     771 * @param   actions             Qt drop actions to convert.
     772 */
    749773/* static */
    750774QVector<KDnDAction> UIDnDHandler::toVBoxDnDActions(Qt::DropActions actions)
    … …  
    763787}
    764788
     789/**
     790 * Static helper function to convert an internal drop action to a Qt drop action.
     791 *
     792 * @returns Converted Qt drop action.
     793 * @param   actions             Internal drop action to convert.
     794 */
    765795/* static */
    766796Qt::DropAction UIDnDHandler::toQtDnDAction(KDnDAction action)
    … …  
    778808}
    779809
     810/**
     811 * Static helper function to convert a vector of internal drop actions to Qt drop actions.
     812 *
     813 * @returns Converted Qt drop actions.
     814 * @param   vecActions          Internal drop actions to convert.
     815 */
    780816/* static */
    781817Qt::DropActions UIDnDHandler::toQtDnDActions(const QVector<KDnDAction> &vecActions)

  • trunk/src/VBox/Frontends/VirtualBox/src/runtime/UIDnDHandler.h

    r82968 r85681  
    3838class UISession;
    3939
     40/**
     41 * Main class for implementing Drag'n'Drop in the frontend.
     42 */
    4043class UIDnDHandler: public QObject
    4144{

  • trunk/src/VBox/GuestHost/DragAndDrop/DnDDroppedFiles.cpp

    r85456 r85681  
    4040
    4141
     42/**
     43 * Initializes a DnD Dropped Files struct, internal version.
     44 *
     45 * @returns VBox status code.
     46 * @param   pDF                 DnD Dropped Files to initialize.
     47 */
    4248static int dndDroppedFilesInitInternal(PDNDDROPPEDFILES pDF)
    4349{
    … …  
    5258}
    5359
     60/**
     61 * Initializes a DnD Dropped Files struct, extended version.
     62 *
     63 * @returns VBox status code.
     64 * @param   pDF                 DnD Dropped Files to initialize.
     65 * @param   fFlags              Dropped Files flags to use for initialization.
     66 */
    5467int DnDDroppedFilesInitEx(PDNDDROPPEDFILES pDF,
    5568                          const char *pszPath, DNDURIDROPPEDFILEFLAGS fFlags /* = DNDURIDROPPEDFILE_FLAGS_NONE */)
    … …  
    6275}
    6376
     77/**
     78 * Initializes a DnD Dropped Files struct.
     79 *
     80 * @returns VBox status code.
     81 * @param   pDF                 DnD Dropped Files to initialize.
     82 */
    6483int DnDDroppedFilesInit(PDNDDROPPEDFILES pDF)
    6584{
    … …  
    6786}
    6887
     88/**
     89 * Destroys a DnD Dropped Files struct.
     90 *
     91 * Note: This does *not* (physically) delete any added content.
     92 *       Make sure to call DnDDroppedFilesReset() then.
     93 *
     94 * @param   pDF                 DnD Dropped Files to destroy.
     95 */
    6996void DnDDroppedFilesDestroy(PDNDDROPPEDFILES pDF)
    7097{
    … …  
    78105
    79106/**
    80  * Adds a file reference to a dropped files directory.
    81  *
    82  * @returns VBox status code.
     107 * Adds a file reference to a Dropped Files directory.
     108 *
     109 * @returns VBox status code.
     110 * @param   pDF                 DnD Dropped Files to add file to.
    83111 * @param   pszFile             Path of file entry to add.
    84112 */
    … …  
    103131
    104132/**
    105  * Adds a directory reference to a dropped files directory.
     133 * Adds a directory reference to a Dropped Files directory.
     134 *
    106135 * Note: This does *not* (recursively) add sub entries.
    107136 *
    108137 * @returns VBox status code.
     138 * @param   pDF                 DnD Dropped Files to add directory to.
    109139 * @param   pszDir              Path of directory entry to add.
    110140 */
    … …  
    132162 *
    133163 * @returns VBox status code.
     164 * @param   pDF                 DnD Dropped Files to close.
    134165 */
    135166static int dndDroppedFilesCloseInternal(PDNDDROPPEDFILES pDF)
    … …  
    153184 *
    154185 * @returns VBox status code.
     186 * @param   pDF                 DnD Dropped Files to close.
    155187 */
    156188int DnDDroppedFilesClose(PDNDDROPPEDFILES pDF)
    … …  
    163195 *
    164196 * @returns Pointer to absolute path of the dropped files directory.
     197 * @param   pDF                 DnD Dropped Files return absolute path of the dropped files directory for.
    165198 */
    166199const char *DnDDroppedFilesGetDirAbs(PDNDDROPPEDFILES pDF)
    … …  
    173206 *
    174207 * @returns \c true if open, \c false if not.
     208 * @param   pDF                 DnD Dropped Files to return open status for.
    175209 */
    176210bool DnDDroppedFilesIsOpen(PDNDDROPPEDFILES pDF)
    … …  
    183217 *
    184218 * @returns VBox status code.
     219 * @param   pDF                 DnD Dropped Files to open.
    185220 * @param   pszPath             Absolute path where to create the dropped files directory.
    186221 * @param   fFlags              Dropped files flags to use for this directory.
    … …  
    259294 *
    260295 * @returns VBox status code.
     296 * @param   pDF                 DnD Dropped Files to open.
    261297 * @param   fFlags              Dropped files flags to use for this directory.
    262298 */
    … …  
    278314}
    279315
     316/**
     317 * Free's an internal DnD Dropped Files entry.
     318 *
     319 * @param   pEntry              Pointer to entry to free. The pointer will be invalid after calling.
     320 */
    280321static void dndDroppedFilesEntryFree(PDNDDROPPEDFILESENTRY pEntry)
    281322{
    … …  
    287328}
    288329
     330/**
     331 * Resets an internal DnD Dropped Files list.
     332 *
     333 * @param   pListAnchor         Pointer to list (anchor) to reset.
     334 */
    289335static void dndDroppedFilesResetList(PRTLISTANCHOR pListAnchor)
    290336{
    … …  
    299345 *
    300346 * @returns VBox status code.
     347 * @param   pDF                 DnD Dropped Files to reset.
    301348 * @param   fDelete             Whether to physically delete the directory and its content
    302349 *                              or just clear the internal references.
    … …  
    326373 *
    327374 * @returns VBox status code, or VERR_NOT_FOUND if the dropped files directory has not been opened before.
     375 * @param   pDF                 DnD Dropped Files to re-open.
    328376 */
    329377int DnDDroppedFilesReopen(PDNDDROPPEDFILES pDF)
    … …  
    340388 *
    341389 * @returns VBox status code.
     390 * @param   pDF                 DnD Dropped Files to roll back.
    342391 */
    343392int DnDDroppedFilesRollback(PDNDDROPPEDFILES pDF)

  • trunk/src/VBox/GuestHost/DragAndDrop/DnDMIME.cpp

    r85371 r85681  
    2626
    2727
     28/**
     29 * Returns whether a given MIME format contains file URLs we can work with or not.
     30 *
     31 * @returns \c true if the format contains file URLs, \c false if not.
     32 * @param   pcszFormat          MIME format to check.
     33 * @param   cchFormatMax        Maximum characters of MIME format to check.
     34 */
    2835bool DnDMIMEHasFileURLs(const char *pcszFormat, size_t cchFormatMax)
    2936{
    … …  
    3340}
    3441
     42/**
     43 * Returns whether a given MIME format needs an own "Dropped Files" directory or not.
     44 *
     45 * @returns \c true if the format needs an own "Dropped Files" directory, \c false if not.
     46 * @param   pcszFormat          MIME format to check.
     47 * @param   cchFormatMax        Maximum characters of MIME format to check.
     48 */
    3549bool DnDMIMENeedsDropDir(const char *pcszFormat, size_t cchFormatMax)
    3650{

  • trunk/src/VBox/HostServices/DragAndDrop/VBoxDragAndDropSvc.cpp

    r85407 r85681  
    1818/** @page pg_svc_dnd    Drag and drop HGCM Service
    1919 *
    20  * TODO
     20 * @sa See src/VBox/Main/src-client/GuestDnDPrivate.cpp for more information.
    2121 */
    2222

  • trunk/src/VBox/Main/src-client/GuestDnDPrivate.cpp

    r85561 r85681  
    5555 *
    5656 * 1. GUI: Uses the Qt classes for Drag and Drop and mainly forward the content
    57  *    of it to the Main IGuest interface (see UIDnDHandler.cpp).
     57 *    of it to the Main IGuest / IGuestDnDSource / IGuestDnDTarget interfaces.
    5858 * 2. Main: Public interface for doing Drag and Drop. Also manage the IProgress
    5959 *    interfaces for blocking the caller by showing a progress dialog (see
    … …  
    6262 *    encapsulate the internal communication details (see dndmanager.cpp and
    6363 *    friends).
    64  * 4. Guest additions: Split into the platform neutral part (see
     64 * 4. Guest Additions: Split into the platform neutral part (see
    6565 *    VBoxGuestR3LibDragAndDrop.cpp) and the guest OS specific parts.
    6666 *    Receive/send message from/to the HGCM service and does all guest specific
    67  *    operations. Currently only X11 is supported (see draganddrop.cpp within
    68  *    VBoxClient).
     67 *    operations. For Windows guests VBoxTray is in charge, whereas on UNIX-y guests
     68 *    VBoxClient will be used.
     69 *
     70 * Terminology:
     71 *
     72 * All transfers contain a MIME format and according meta data. This meta data then can
     73 * be interpreted either as raw meta data or something else. When raw meta data is
     74 * being handled, this gets passed through to the destination (guest / host) without
     75 * modification. Other meta data (like URI lists) can and will be modified by the
     76 * receiving side before passing to OS. How and when modifications will be applied
     77 * depends on the MIME format.
    6978 *
    7079 * Host -> Guest:
    7180 * 1. There are DnD Enter, Move, Leave events which are send exactly like this
    72  *    to the guest. The info includes the pos, mimetypes and allowed actions.
     81 *    to the guest. The info includes the position, MIME types and allowed actions.
    7382 *    The guest has to respond with an action it would accept, so the GUI could
    74  *    change the cursor.
     83 *    change the cursor accordingly.
    7584 * 2. On drop, first a drop event is sent. If this is accepted a drop data
    7685 *    event follows. This blocks the GUI and shows some progress indicator.
    … …  
    8594 *    shows some progress indicator.
    8695 *
    87  * Some hints:
     96 * Implementation hints:
    8897 * m_strSupportedFormats here in this file defines the allowed mime-types.
    8998 * This is necessary because we need special handling for some of the
    … …  
    104113 * same has to be done in the G->H direction when it is implemented.
    105114 *
    106  * Of course only regularly files are supported. Symlinks are resolved and
    107  * transfered as regularly files. First we don't know if the other side support
    108  * symlinks at all and second they could point to somewhere in a directory tree
    109  * which not exists on the other side.
    110  *
    111  * The code tries to preserve the file modes of the transfered dirs/files. This
    112  * is useful (and maybe necessary) for two things:
     115 * Only regular files are supported; symlinks are not allowed.
     116 *
     117 * Transfers currently are an all-succeed or all-fail operation (see todos).
     118 *
     119 * On MacOS hosts we had to implement own DnD "promises" support for file transfers,
     120 * as Qt does not support this out-of-the-box.
     121 *
     122 * The code tries to preserve the file modes of the transfered directories / files.
     123 * This is useful (and maybe necessary) for two things:
    113124 * 1. If a file is executable, it should be also after the transfer, so the
    114125 *    user can just execute it, without manually tweaking the modes first.
    … …  
    118129 * ourself, in e.g. for a cleanup case after cancel).
    119130 *
    120  * Cancel is supported in both directions and cleans up all previous steps
    121  * (thats is: deleting already transfered dirs/files).
    122  *
    123  * In general I propose the following changes in the VBox HGCM infrastructure
    124  * for the future:
    125  * - Currently it isn't really possible to send messages to the guest from the
    126  *   host. The host informs the guest just that there is something, the guest
    127  *   than has to ask which message and depending on that send the appropriate
    128  *   message to the host, which is filled with the right data.
    129  * - There is no generic interface for sending bigger memory blocks to/from the
    130  *   guest. This is now done here, but I guess was also necessary for e.g.
    131  *   guest execution. So something generic which brake this up into smaller
    132  *   blocks and send it would be nice (with all the error handling and such
    133  *   ofc).
    134  * - I developed a "protocol" for the DnD communication here. So the host and
    135  *   the guest have always to match in the revision. This is ofc bad, because
    136  *   the additions could be outdated easily. So some generic protocol number
    137  *   support in HGCM for asking the host and the guest of the support version,
    138  *   would be nice. Ofc at least the host should be able to talk to the guest,
    139  *   even when the version is below the host one.
    140  * All this stuff would be useful for the current services, but also for future
    141  * onces.
     131 * ACEs / ACLs currently are not supported.
     132 *
     133 * Cancelling ongoing transfers is supported in both directions by the guest
     134 * and/or host side and cleans up all previous steps. This also involves
     135 * removing partially transferred directories / files in the temporary directory.
    142136 *
    143137 ** @todo
    144138 * - ESC doesn't really work (on Windows guests it's already implemented)
    145  *   ... in any case it seems a little bit difficult to handle from the Qt
    146  *   side. Maybe also a host specific implementation becomes necessary ...
    147  *   this would be really worst ofc.
    148  * - Add support for more mime-types (especially images, csv)
     139 *   ... in any case it seems a little bit difficult to handle from the Qt side.
     140 * - Transfers currently do not have any interactive (UI) callbacks / hooks which
     141 *   e.g. would allow to skip / replace / rename and entry, or abort the operation on failure.
     142 * - Add support for more MIME types (especially images, csv)
    149143 * - Test unusual behavior:
    150144 *   - DnD service crash in the guest during a DnD op (e.g. crash of VBoxClient or X11)
    … …  
    152146 * - Security considerations: We transfer a lot of memory between the guest and
    153147 *   the host and even allow the creation of dirs/files. Maybe there should be
    154  *   limits introduced to preventing DOS attacks or filling up all the memory
     148 *   limits introduced to preventing DoS attacks or filling up all the memory
    155149 *   (both in the host and the guest).
    156150 */

  • trunk/src/VBox/Main/src-client/GuestDnDSourceImpl.cpp

    r85564 r85681  
    5757    virtual ~GuestDnDSourceTask(void) { }
    5858
     59    /** Returns the overall result of the task. */
    5960    int getRC(void) const { return mRC; }
     61    /** Returns if the overall result of the task is ok (succeeded) or not. */
    6062    bool isOk(void) const { return RT_SUCCESS(mRC); }
    6163
    6264protected:
    6365
     66    /** COM object pointer to the parent (source). */
    6467    const ComObjPtr<GuestDnDSource>     mSource;
     68    /** Overall result of the task. */
    6569    int                                 mRC;
    6670};
    … …  
    507511/////////////////////////////////////////////////////////////////////////////
    508512
     513/**
     514 * Returns an error string from a guest DnD error.
     515 *
     516 * @returns Error string.
     517 * @param   guestRc             Guest error to return error string for.
     518 */
    509519/* static */
    510520Utf8Str GuestDnDSource::i_guestErrorToString(int guestRc)
    … …  
    545555}
    546556
     557/**
     558 * Returns an error string from a host DnD error.
     559 *
     560 * @returns Error string.
     561 * @param   hostRc              Host error to return error string for.
     562 */
    547563/* static */
    548564Utf8Str GuestDnDSource::i_hostErrorToString(int hostRc)
    … …  
    583599}
    584600
     601/**
     602 * Resets all internal data and state.
     603 */
    585604void GuestDnDSource::i_reset(void)
    586605{
    … …  
    632651
    633652/**
    634  * Handles receiving a send data block from the guest.
     653 * Main function for receiving data from the guest.
    635654 *
    636655 * @returns VBox status code.
    … …  
    762781    return rc;
    763782}
     783
    764784
    765785int GuestDnDSource::i_onReceiveDir(GuestDnDRecvCtx *pCtx, const char *pszPath, uint32_t cbPath, uint32_t fMode)
    … …  
    904924}
    905925
     926/**
     927 * Receives file data from the guest.
     928 *
     929 * @returns VBox status code.
     930 * @param   pCtx                Receive context to use.
     931 * @param   pvData              Pointer to file data received from the guest.
     932 * @param   pCtx                Size (in bytes) of file data received from the guest.
     933 */
    906934int GuestDnDSource::i_onReceiveFileData(GuestDnDRecvCtx *pCtx, const void *pvData, uint32_t cbData)
    907935{
    … …  
    971999
    9721000/**
    973  * @returns VBox status code that the caller ignores. Not sure if that's
    974  *          intentional or not.
     1001 * Main function to receive DnD data from the guest.
     1002 *
     1003 * @returns VBox status code.
     1004 * @param   pCtx                Receive context to use.
     1005 * @param   msTimeout           Timeout (in ms) to wait for receiving data.
    9751006 */
    9761007int GuestDnDSource::i_receiveData(GuestDnDRecvCtx *pCtx, RTMSINTERVAL msTimeout)
    … …  
    10661097}
    10671098
     1099/**
     1100 * Receives raw (meta) data from the guest.
     1101 *
     1102 * @returns VBox status code.
     1103 * @param   pCtx                Receive context to use.
     1104 * @param   msTimeout           Timeout (in ms) to wait for receiving data.
     1105 */
    10681106int GuestDnDSource::i_receiveRawData(GuestDnDRecvCtx *pCtx, RTMSINTERVAL msTimeout)
    10691107{
    … …  
    11711209}
    11721210
     1211/**
     1212 * Receives transfer data (files / directories / ...) from the guest.
     1213 *
     1214 * @returns VBox status code.
     1215 * @param   pCtx                Receive context to use.
     1216 * @param   msTimeout           Timeout (in ms) to wait for receiving data.
     1217 */
    11731218int GuestDnDSource::i_receiveTransferData(GuestDnDRecvCtx *pCtx, RTMSINTERVAL msTimeout)
    11741219{
    … …  
    13051350}
    13061351
     1352/**
     1353 * Static HGCM service callback which handles receiving raw data.
     1354 *
     1355 * @returns VBox status code. Will get sent back to the host service.
     1356 * @param   uMsg                HGCM message ID (function number).
     1357 * @param   pvParms             Pointer to additional message data. Optional and can be NULL.
     1358 * @param   cbParms             Size (in bytes) additional message data. Optional and can be 0.
     1359 * @param   pvUser              User-supplied pointer on callback registration.
     1360 */
    13071361/* static */
    13081362DECLCALLBACK(int) GuestDnDSource::i_receiveRawDataCallback(uint32_t uMsg, void *pvParms, size_t cbParms, void *pvUser)
    … …  
    14341488}
    14351489
     1490/**
     1491 * Static HGCM service callback which handles receiving transfer data from the guest.
     1492 *
     1493 * @returns VBox status code. Will get sent back to the host service.
     1494 * @param   uMsg                HGCM message ID (function number).
     1495 * @param   pvParms             Pointer to additional message data. Optional and can be NULL.
     1496 * @param   cbParms             Size (in bytes) additional message data. Optional and can be 0.
     1497 * @param   pvUser              User-supplied pointer on callback registration.
     1498 */
    14361499/* static */
    14371500DECLCALLBACK(int) GuestDnDSource::i_receiveTransferDataCallback(uint32_t uMsg, void *pvParms, size_t cbParms, void *pvUser)

  • trunk/src/VBox/Main/src-client/GuestDnDTargetImpl.cpp

    r85564 r85681  
    6060    virtual ~GuestDnDTargetTask(void) { }
    6161
     62    /** Returns the overall result of the task. */
    6263    int getRC(void) const { return mRC; }
     64    /** Returns if the overall result of the task is ok (succeeded) or not. */
    6365    bool isOk(void) const { return RT_SUCCESS(mRC); }
    6466
    6567protected:
    6668
     69    /** COM object pointer to the parent (source). */
    6770    const ComObjPtr<GuestDnDTarget>     mTarget;
     71    /** Overall result of the task. */
    6872    int                                 mRC;
    6973};
    … …  
    670674}
    671675
     676/**
     677 * Returns an error string from a guest DnD error.
     678 *
     679 * @returns Error string.
     680 * @param   guestRc             Guest error to return error string for.
     681 */
    672682/* static */
    673683Utf8Str GuestDnDTarget::i_guestErrorToString(int guestRc)
    … …  
    708718}
    709719
     720/**
     721 * Returns an error string from a host DnD error.
     722 *
     723 * @returns Error string.
     724 * @param   hostRc              Host error to return error string for.
     725 */
    710726/* static */
    711727Utf8Str GuestDnDTarget::i_hostErrorToString(int hostRc)
    … …  
    742758}
    743759
     760/**
     761 * Resets all internal data and state.
     762 */
    744763void GuestDnDTarget::i_reset(void)
    745764{
    … …  
    919938}
    920939
     940/**
     941 * Sends a directory entry to the guest.
     942 *
     943 * @returns VBox status code.
     944 * @param   pCtx                Send context to use.
     945 * @param   pObj                Transfer object to send. Must be a directory.
     946 * @param   pMsg                Where to store the message to send.
     947 */
    921948int GuestDnDTarget::i_sendDirectory(GuestDnDSendCtx *pCtx, PDNDTRANSFEROBJECT pObj, GuestDnDMsg *pMsg)
    922949{
    … …  
    942969
    943970/**
    944  * Sends a transfer file to the guest.
     971 * Sends a file to the guest.
    945972 *
    946973 * @returns VBox status code.
    947  * @param   pCtx
    948  * @param   pObj
    949  * @param   pMsg
     974 * @param   pCtx                Send context to use.
     975 * @param   pObj                Transfer object to send. Must be a file.
     976 * @param   pMsg                Where to store the message to send.
    950977 */
    951978int GuestDnDTarget::i_sendFile(GuestDnDSendCtx *pCtx,
    … …  
    10341061}
    10351062
     1063/**
     1064 * Helper function to send actual file data to the guest.
     1065 *
     1066 * @returns VBox status code.
     1067 * @param   pCtx                Send context to use.
     1068 * @param   pObj                Transfer object to send. Must be a file.
     1069 * @param   pMsg                Where to store the message to send.
     1070 */
    10361071int GuestDnDTarget::i_sendFileData(GuestDnDSendCtx *pCtx,
    10371072                                   PDNDTRANSFEROBJECT pObj, GuestDnDMsg *pMsg)
    … …  
    11131148}
    11141149
     1150/**
     1151 * Static HGCM service callback which handles sending transfer data to the guest.
     1152 *
     1153 * @returns VBox status code. Will get sent back to the host service.
     1154 * @param   uMsg                HGCM message ID (function number).
     1155 * @param   pvParms             Pointer to additional message data. Optional and can be NULL.
     1156 * @param   cbParms             Size (in bytes) additional message data. Optional and can be 0.
     1157 * @param   pvUser              User-supplied pointer on callback registration.
     1158 */
    11151159/* static */
    11161160DECLCALLBACK(int) GuestDnDTarget::i_sendTransferDataCallback(uint32_t uMsg, void *pvParms, size_t cbParms, void *pvUser)
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