horok/virtualbox
1
0
Fork 0
Code Activity
virtualbox/include/VBox/HostServices/DragAndDropSvc.h
Daniel Baumann df1bda4fe9
Adding upstream version 7.0.20-dfsg. 
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
2025-06-22 09:56:04 +02:00

1198 lines
40 KiB
C++
Raw Permalink Blame History

/* $Id: DragAndDropSvc.h $ */
/** @file
* Drag and Drop service - Common header for host service and guest clients.
*/
/*
* Copyright (C) 2011-2023 Oracle and/or its affiliates.
*
* This file is part of VirtualBox base platform packages, as
* available from https://www.virtualbox.org.
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License
* as published by the Free Software Foundation, in version 3 of the
* License.
*
* This program is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, see <https://www.gnu.org/licenses>.
*
* The contents of this file may alternatively be used under the terms
* of the Common Development and Distribution License Version 1.0
* (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
* in the VirtualBox distribution, in which case the provisions of the
* CDDL are applicable instead of those of the GPL.
*
* You may elect to license modified versions of this file under the
* terms and conditions of either the GPL or the CDDL or both.
*
* SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
*/
/**
* Protocol handling and notes:
* All client/server components should be backwards compatible.
*
******************************************************************************
*
* Protocol changelog:
*
* Protocol v1 (VBox < 5.0, deprecated):
* | Initial implementation which only implemented host to guest transfers.
* | For file transfers all file information such as the file name and file size were
* transferred with every file data chunk being sent.
*
* Protocol v2 (VBox 5.0 - VBox 5.0.8, deprecated):
* + Added support for guest to host transfers.
* + Added protocol version support through VBOXDNDCONNECTMSG. The host takes the installed
* Guest Additions version as indicator which protocol to use for communicating with the guest.
* The guest itself uses VBOXDNDCONNECTMSG to report its supported protocol version to the DnD service.
*
* Protocol v3 (VBox 5.0.10 and up, deprecated):
* + Added VBOXDNDDISCONNECTMSG for being able to track client disconnects on host side (Main).
* + Added context IDs for every HGCM message. Not used yet and must be 0.
* + Added VBOXDNDSNDDATAHDR and VBOXDNDCBSNDDATAHDRDATA to support (simple) accounting of objects
* being transferred, along with supplying separate meta data size (which is part of the total size being sent).
* + Added new HOST_DND_FN_HG_SND_DATA_HDR + GUEST_DND_FN_GH_SND_DATA_HDR commands which now allow specifying an optional
* compression type and defining a checksum for the overall data transfer.
* + Enhannced VBOXDNDGHSENDDATAMSG to support (rolling) checksums for the supplied data block.
* + VBOXDNDHGSENDDATAMSG and VBOXDNDGHSENDDATAMSG can now contain an optional checksum for the current data block.
* | VBOXDNDHGSENDFILEDATAMSG and VBOXDNDGHSENDFILEDATAMSG are now sharing the same HGCM mesasge.
* - Removed unused HOST_DND_FN_GH_RECV_DIR, HOST_DND_FN_GH_RECV_FILE_DATA and HOST_DND_FN_GH_RECV_FILE_HDR commands.
*
* VBox 6.1.x and up, current:
* + Added GUEST_DND_FN_QUERY_FEATURES + GUEST_DND_FN_REPORT_FEATURES.
* - Protocol versioning support in VBOXDNDCONNECTMSG is now marked as being deprecated.
*
** @todo:
* - Split up messages which use VBOXDNDHGACTIONMSG into own functions and remove parameters which
* are not actually needed / used by a function. Why does HOST_DND_FN_HG_EVT_MOVE need all the format stuff, for example?
*/
#ifndef VBOX_INCLUDED_HostServices_DragAndDropSvc_h
#define VBOX_INCLUDED_HostServices_DragAndDropSvc_h
#ifndef RT_WITHOUT_PRAGMA_ONCE
# pragma once
#endif
#include <VBox/hgcmsvc.h>
#include <VBox/VMMDevCoreTypes.h>
#include <VBox/VBoxGuestCoreTypes.h>
#include <VBox/GuestHost/DragAndDropDefs.h>
namespace DragAndDropSvc {
/******************************************************************************
* Typedefs, constants and inlines *
******************************************************************************/
/**
* The service functions which are callable by host.
* Note: When adding new functions to this table, make sure that the actual ID
* does *not* overlap with the eGuestFn enumeration below!
*/
enum eHostFn
{
/** The host sets a new DnD mode. */
HOST_DND_FN_SET_MODE = 100,
/** The host requests to cancel the current DnD operation on
* the guest side. This can happen on user request on the host's
* UI side or due to some host error which has happened.
*
* Note: This is a fire-and-forget message, as the host should
* not rely on an answer from the guest side in order to
* properly cancel the operation. */
HOST_DND_FN_CANCEL = 204,
/*
* Host -> Guest messages
*/
/** The host enters the VM window for starting an actual
* DnD operation. */
HOST_DND_FN_HG_EVT_ENTER = 200,
/** The host's DnD cursor moves within the VM window. */
HOST_DND_FN_HG_EVT_MOVE = 201,
/** The host leaves the guest VM window. */
HOST_DND_FN_HG_EVT_LEAVE = 202,
/** The host issues a "drop" event, meaning that the host is
* ready to transfer data over to the guest. */
HOST_DND_FN_HG_EVT_DROPPED = 203,
/** The host sends the data header at the beginning of a (new)
* data transfer. */
HOST_DND_FN_HG_SND_DATA_HDR = 210,
/**
* The host sends the actual meta data, based on
* the format(s) specified by HOST_DND_FN_HG_EVT_ENTER.
*
* Protocol v1/v2: If the guest supplied buffer too small to send
* the actual data, the host will send a HOST_DND_FN_HG_SND_MORE_DATA
* message as follow-up.
* Protocol v3+: The incoming meta data size is specified upfront in the
* HOST_DND_FN_HG_SND_DATA_HDR message and must be handled accordingly.
*/
HOST_DND_FN_HG_SND_DATA = 205,
/** The host sends more data in case the data did not entirely fit in
* the HOST_DND_FN_HG_SND_DATA message. */
/** @todo Deprecated function; do not use anymore. */
HOST_DND_FN_HG_SND_MORE_DATA = 206,
/** The host sends a directory entry to the guest. */
HOST_DND_FN_HG_SND_DIR = 207,
/** The host sends a file data chunk to the guest. */
HOST_DND_FN_HG_SND_FILE_DATA = 208,
/** The host sends a file header to the guest.
* Note: Only for protocol version 2 and up (>= VBox 5.0). */
HOST_DND_FN_HG_SND_FILE_HDR = 209,
/*
* Guest -> Host messages
*/
/** The host asks the guest whether a DnD operation
* is in progress when the mouse leaves the guest window. */
HOST_DND_FN_GH_REQ_PENDING = 600,
/** The host informs the guest that a DnD drop operation
* has been started and that the host wants the data in
* a specific MIME type. */
HOST_DND_FN_GH_EVT_DROPPED = 601,
/** Blow the type up to 32-bit. */
HOST_DND_FN_32BIT_HACK = 0x7fffffff
};
/**
* The service functions which are called by guest.
* Note: When adding new functions to this table, make sure that the actual ID
* does *not* overlap with the eHostFn enumeration above!
*/
enum eGuestFn
{
/**
* The guest sends a connection request to the HGCM service,
* along with some additional information like supported
* protocol version and flags.
* Note: New since protocol version 2. */
GUEST_DND_FN_CONNECT = 10,
/** The guest client disconnects from the HGCM service. */
GUEST_DND_FN_DISCONNECT = 11,
/** Report guest side feature flags and retrieve the host ones.
*
* Two 64-bit parameters are passed in from the guest with the guest features
* (VBOX_DND_GF_XXX), the host replies by replacing the parameter values with
* the host ones (VBOX_DND_HF_XXX).
*
* @retval VINF_SUCCESS on success.
* @retval VERR_INVALID_CLIENT_ID
* @retval VERR_WRONG_PARAMETER_COUNT
* @retval VERR_WRONG_PARAMETER_TYPE
* @since 6.1.x
*/
GUEST_DND_FN_REPORT_FEATURES = 12,
/** Query the host ones feature masks.
*
* That way the guest (client) can get hold of the features from the host.
* Again, it is prudent to set the 127 bit and observe it being cleared on
* success, as older hosts might return success without doing anything.
*
* @retval VINF_SUCCESS on success.
* @retval VERR_INVALID_CLIENT_ID
* @retval VERR_WRONG_PARAMETER_COUNT
* @retval VERR_WRONG_PARAMETER_TYPE
* @since 6.1.x
*/
GUEST_DND_FN_QUERY_FEATURES = 13,
/**
* The guest waits for a new message the host wants to process
* on the guest side. This can be a blocking call.
*/
GUEST_DND_FN_GET_NEXT_HOST_MSG = 300,
/** Reports back an error to the host.
*
* Note: Don't change the ID to also support older hosts
* (was GUEST_DND_FN_GH_EVT_ERROR before < 7.0, only for G->H transfers).
*
* This was changed to GUEST_DND_FN_EVT_ERROR to be a generic event
* that also can be used for H->G transfers.
*
* @retval VINF_SUCCESS on success.
* @retval VERR_INVALID_CLIENT_ID
* @retval VERR_WRONG_PARAMETER_COUNT
* @retval VERR_WRONG_PARAMETER_TYPE
* @since 7.0.x
*/
GUEST_DND_FN_EVT_ERROR = 502,
/*
* Host -> Guest operation messages.
*/
/** The guest acknowledges that a pending DnD operation from the host
* can be dropped on the currently selected area on the guest. */
GUEST_DND_FN_HG_ACK_OP = 400,
/** The guest requests the actual DnD data to be sent from the host. */
GUEST_DND_FN_HG_REQ_DATA = 401,
/** The guest reports back its progress back to the host. */
GUEST_DND_FN_HG_EVT_PROGRESS = 402,
/*
* Guest -> Host operation messages.
*/
/**
* The guests acknowledges that it currently has a drag'n drop
* operation in progress on the guest, which eventually could be
* dragged over to the host.
*/
GUEST_DND_FN_GH_ACK_PENDING = 500,
/** The guest sends the data header at the beginning of a (new)
* data transfer. */
GUEST_DND_FN_GH_SND_DATA_HDR = 503,
/**
* The guest sends data of the requested format to the host. There can
* be more than one message if the actual data does not fit
* into one.
*/
GUEST_DND_FN_GH_SND_DATA = 501,
/** The guest sends a directory entry to the host. */
GUEST_DND_FN_GH_SND_DIR = 700,
/** The guest sends file data to the host.
* Note: On protocol version 1 this also contains the file name
* and other attributes. */
GUEST_DND_FN_GH_SND_FILE_DATA = 701,
/** The guest sends a file header to the host, marking the
* beginning of a (new) file transfer.
* Note: Available since protocol version 2 (VBox 5.0). */
GUEST_DND_FN_GH_SND_FILE_HDR = 702,
/** Blow the type up to 32-bit. */
GUEST_DND_FN_32BIT_HACK = 0x7fffffff
};
/** @name VBOX_DND_GF_XXX - Guest features.
* @sa GUEST_DND_FN_REPORT_FEATURES
* @{ */
/** No flags set. */
#define VBOX_DND_GF_NONE 0
/** Bit that must be set in the 2nd parameter, will be cleared if the host reponds
* correctly (old hosts might not). */
#define VBOX_DND_GF_1_MUST_BE_ONE RT_BIT_64(63)
/** @} */
/** @name VBOX_DND_HF_XXX - Host features.
* @sa DND_GUEST_REPORT_FEATURES
* @{ */
/** No flags set. */
#define VBOX_DND_HF_NONE 0
/** @} */
/**
* DnD operation progress states.
*/
typedef enum DNDPROGRESS
{
DND_PROGRESS_UNKNOWN = 0,
DND_PROGRESS_RUNNING = 1,
DND_PROGRESS_COMPLETE,
DND_PROGRESS_CANCELLED,
DND_PROGRESS_ERROR,
/** Blow the type up to 32-bit. */
DND_PROGRESS_32BIT_HACK = 0x7fffffff
} DNDPROGRESS, *PDNDPROGRESS;
#pragma pack (1)
/*
* Host events
*/
/**
* Action message for telling the guest about the currently ongoing
* drag and drop action when entering the guest's area, moving around in it
* and dropping content into it from the host.
*
* Used by:
* HOST_DND_FN_HG_EVT_ENTER
* HOST_DND_FN_HG_EVT_MOVE
* HOST_DND_FN_HG_EVT_DROPPED
*/
typedef struct HGCMMsgHGAction
{
VBGLIOCHGCMCALL hdr;
union
{
struct
{
HGCMFunctionParameter uScreenId; /* OUT uint32_t */
HGCMFunctionParameter uX; /* OUT uint32_t */
HGCMFunctionParameter uY; /* OUT uint32_t */
HGCMFunctionParameter uDefAction; /* OUT uint32_t */
HGCMFunctionParameter uAllActions; /* OUT uint32_t */
HGCMFunctionParameter pvFormats; /* OUT ptr */
HGCMFunctionParameter cbFormats; /* OUT uint32_t */
} v1;
struct
{
/** Context ID. */
HGCMFunctionParameter uContext;
HGCMFunctionParameter uScreenId; /* OUT uint32_t */
HGCMFunctionParameter uX; /* OUT uint32_t */
HGCMFunctionParameter uY; /* OUT uint32_t */
HGCMFunctionParameter uDefAction; /* OUT uint32_t */
HGCMFunctionParameter uAllActions; /* OUT uint32_t */
HGCMFunctionParameter pvFormats; /* OUT ptr */
HGCMFunctionParameter cbFormats; /* OUT uint32_t */
} v3;
} u;
} HGCMMsgHGAction;
/**
* Tells the guest that the host has left its drag and drop area on the guest.
*
* Used by:
* HOST_DND_FN_HG_EVT_LEAVE
*/
typedef struct HGCMMsgHGLeave
{
VBGLIOCHGCMCALL hdr;
union
{
struct
{
/** Context ID. */
HGCMFunctionParameter uContext;
} v3;
} u;
} HGCMMsgHGLeave;
/**
* Tells the guest that the host wants to cancel the current drag and drop operation.
*
* Used by:
* HOST_DND_FN_HG_EVT_CANCEL
*/
typedef struct HGCMMsgHGCancel
{
VBGLIOCHGCMCALL hdr;
union
{
struct
{
/** Context ID. */
HGCMFunctionParameter uContext;
} v3;
} u;
} HGCMMsgHGCancel;
/**
* Sends the header of an incoming (meta) data block.
*
* Used by:
* HOST_DND_FN_HG_SND_DATA_HDR
* GUEST_DND_FN_GH_SND_DATA_HDR
*
* New since protocol v3.
*/
typedef struct HGCMMsgHGSendDataHdr
{
VBGLIOCHGCMCALL hdr;
/** Context ID. Unused at the moment. */
HGCMFunctionParameter uContext; /* OUT uint32_t */
/** Data transfer flags. Not yet used and must be 0. */
HGCMFunctionParameter uFlags; /* OUT uint32_t */
/** Screen ID where the data originates from. */
HGCMFunctionParameter uScreenId; /* OUT uint32_t */
/** Total size (in bytes) to transfer. */
HGCMFunctionParameter cbTotal; /* OUT uint64_t */
/**
* Total meta data size (in bytes) to transfer.
* This size also is part of cbTotal already, so:
*
* cbTotal = cbMeta + additional size for files etc.
*/
HGCMFunctionParameter cbMeta; /* OUT uint64_t */
/** Meta data format. */
HGCMFunctionParameter pvMetaFmt; /* OUT ptr */
/** Size (in bytes) of meta data format. */
HGCMFunctionParameter cbMetaFmt; /* OUT uint32_t */
/* Number of objects (files/directories) to transfer. */
HGCMFunctionParameter cObjects; /* OUT uint64_t */
/** Compression type. */
HGCMFunctionParameter enmCompression; /* OUT uint32_t */
/** Checksum type. */
HGCMFunctionParameter enmChecksumType; /* OUT uint32_t */
/** Checksum buffer for the entire data to be transferred. */
HGCMFunctionParameter pvChecksum; /* OUT ptr */
/** Size (in bytes) of checksum. */
HGCMFunctionParameter cbChecksum; /* OUT uint32_t */
} HGCMMsgHGSendDataHdr;
/**
* Sends a (meta) data block to the guest.
*
* Used by:
* HOST_DND_FN_HG_SND_DATA
*/
typedef struct HGCMMsgHGSendData
{
VBGLIOCHGCMCALL hdr;
union
{
struct
{
HGCMFunctionParameter uScreenId; /* OUT uint32_t */
HGCMFunctionParameter pvFormat; /* OUT ptr */
HGCMFunctionParameter cbFormat; /* OUT uint32_t */
HGCMFunctionParameter pvData; /* OUT ptr */
HGCMFunctionParameter cbData; /* OUT uint32_t */
} v1;
/* No changes in v2. */
struct
{
/** Context ID. Unused at the moment. */
HGCMFunctionParameter uContext; /* OUT uint32_t */
/** Data block to send. */
HGCMFunctionParameter pvData; /* OUT ptr */
/** Size (in bytes) of data block to send. */
HGCMFunctionParameter cbData; /* OUT uint32_t */
/** Checksum of data block, based on the checksum
* type in the data header. Optional. */
HGCMFunctionParameter pvChecksum; /* OUT ptr */
/** Size (in bytes) of checksum to send. */
HGCMFunctionParameter cbChecksum; /* OUT uint32_t */
} v3;
} u;
} HGCMMsgHGSendData;
/**
* Sends more (meta) data in case the data didn't fit
* into the current XXX_DND_HG_SND_DATA message.
*
** @todo Deprecated since protocol v3. Don't use! Will be removed.
*
* Used by:
* HOST_DND_FN_HG_SND_MORE_DATA
*/
typedef struct HGCMMsgHGSendMoreData
{
VBGLIOCHGCMCALL hdr;
HGCMFunctionParameter pvData; /* OUT ptr */
HGCMFunctionParameter cbData; /* OUT uint32_t */
} HGCMMsgHGSendMoreData;
/**
* Directory entry event.
*
* Used by:
* HOST_DND_FN_HG_SND_DIR
* GUEST_DND_FN_GH_SND_DIR
*/
typedef struct HGCMMsgHGSendDir
{
VBGLIOCHGCMCALL hdr;
union
{
struct
{
/** Directory name. */
HGCMFunctionParameter pvName; /* OUT ptr */
/** Size (in bytes) of directory name. */
HGCMFunctionParameter cbName; /* OUT uint32_t */
/** Directory mode. */
HGCMFunctionParameter fMode; /* OUT uint32_t */
} v1;
struct
{
/** Context ID. Unused at the moment. */
HGCMFunctionParameter uContext; /* OUT uint32_t */
/** Directory name. */
HGCMFunctionParameter pvName; /* OUT ptr */
/** Size (in bytes) of directory name. */
HGCMFunctionParameter cbName; /* OUT uint32_t */
/** Directory mode. */
HGCMFunctionParameter fMode; /* OUT uint32_t */
} v3;
} u;
} HGCMMsgHGSendDir;
/**
* File header message, marking the start of transferring a new file.
* Note: Only for protocol version 2 and up.
*
* Used by:
* HOST_DND_FN_HG_SND_FILE_HDR
* GUEST_DND_FN_GH_SND_FILE_HDR
*/
typedef struct HGCMMsgHGSendFileHdr
{
VBGLIOCHGCMCALL hdr;
/** Context ID. Unused at the moment. */
HGCMFunctionParameter uContext; /* OUT uint32_t */
/** File path. */
HGCMFunctionParameter pvName; /* OUT ptr */
/** Size (in bytes) of file path. */
HGCMFunctionParameter cbName; /* OUT uint32_t */
/** Optional flags; unused at the moment. */
HGCMFunctionParameter uFlags; /* OUT uint32_t */
/** File creation mode. */
HGCMFunctionParameter fMode; /* OUT uint32_t */
/** Total size (in bytes). */
HGCMFunctionParameter cbTotal; /* OUT uint64_t */
} HGCMMsgHGSendFileHdr;
/**
* HG: File data (chunk) event.
*
* Used by:
* HOST_DND_FN_HG_SND_FILE
*/
typedef struct HGCMMsgHGSendFileData
{
VBGLIOCHGCMCALL hdr;
union
{
/* Note: Protocol v1 sends the file name + file mode
* every time a file data chunk is being sent. */
struct
{
/** File name. */
HGCMFunctionParameter pvName; /* OUT ptr */
/** Size (in bytes) of file name. */
HGCMFunctionParameter cbName; /* OUT uint32_t */
/** Current data chunk. */
HGCMFunctionParameter pvData; /* OUT ptr */
/** Size (in bytes) of current data chunk. */
HGCMFunctionParameter cbData; /* OUT uint32_t */
/** File mode. */
HGCMFunctionParameter fMode; /* OUT uint32_t */
} v1;
struct
{
/** Note: pvName is now part of the VBOXDNDHGSENDFILEHDRMSG message. */
/** Note: cbName is now part of the VBOXDNDHGSENDFILEHDRMSG message. */
/** Context ID. Unused at the moment. */
HGCMFunctionParameter uContext; /* OUT uint32_t */
/** Current data chunk. */
HGCMFunctionParameter pvData; /* OUT ptr */
/** Size (in bytes) of current data chunk. */
HGCMFunctionParameter cbData; /* OUT uint32_t */
/** Note: fMode is now part of the VBOXDNDHGSENDFILEHDRMSG message. */
} v2;
struct
{
/** Context ID. Unused at the moment. */
HGCMFunctionParameter uContext; /* OUT uint32_t */
/** Current data chunk. */
HGCMFunctionParameter pvData; /* OUT ptr */
/** Size (in bytes) of current data chunk. */
HGCMFunctionParameter cbData; /* OUT uint32_t */
/** Checksum of data block, based on the checksum
* type in the data header. Optional. */
HGCMFunctionParameter pvChecksum; /* OUT ptr */
/** Size (in bytes) of curren data chunk checksum. */
HGCMFunctionParameter cbChecksum; /* OUT uint32_t */
} v3;
} u;
} HGCMMsgHGSendFileData;
/**
* Asks the guest if a guest->host DnD operation is in progress.
*
* Used by:
* HOST_DND_FN_GH_REQ_PENDING
*/
typedef struct HGCMMsgGHReqPending
{
VBGLIOCHGCMCALL hdr;
union
{
struct
{
/** Screen ID. */
HGCMFunctionParameter uScreenId; /* OUT uint32_t */
} v1;
struct
{
/** Context ID. Unused at the moment. */
HGCMFunctionParameter uContext; /* OUT uint32_t */
/** Screen ID. */
HGCMFunctionParameter uScreenId; /* OUT uint32_t */
} v3;
} u;
} HGCMMsgGHReqPending;
/**
* Tells the guest that the host has dropped the ongoing guest->host
* DnD operation on a valid target on the host.
*
* Used by:
* HOST_DND_FN_GH_EVT_DROPPED
*/
typedef struct HGCMMsgGHDropped
{
VBGLIOCHGCMCALL hdr;
union
{
struct
{
/** Requested format for sending the data. */
HGCMFunctionParameter pvFormat; /* OUT ptr */
/** Size (in bytes) of requested format. */
HGCMFunctionParameter cbFormat; /* OUT uint32_t */
/** Drop action peformed on the host. */
HGCMFunctionParameter uAction; /* OUT uint32_t */
} v1;
struct
{
/** Context ID. Unused at the moment. */
HGCMFunctionParameter uContext; /* OUT uint32_t */
/** Requested format for sending the data. */
HGCMFunctionParameter pvFormat; /* OUT ptr */
/** Size (in bytes) of requested format. */
HGCMFunctionParameter cbFormat; /* OUT uint32_t */
/** Drop action peformed on the host. */
HGCMFunctionParameter uAction; /* OUT uint32_t */
} v3;
} u;
} HGCMMsgGHDropped;
/*
* Guest events
*/
/**
* Asks the host for the next command to process, along
* with the needed amount of parameters and an optional blocking
* flag.
*
* Used by:
* GUEST_DND_FN_GET_NEXT_HOST_MSG
*/
typedef struct HGCMMsgGetNext
{
VBGLIOCHGCMCALL hdr;
/** Message ID. */
HGCMFunctionParameter uMsg; /* OUT uint32_t */
/** Number of parameters the message needs. */
HGCMFunctionParameter cParms; /* OUT uint32_t */
/** Whether or not to block (wait) for a
* new message to arrive. */
HGCMFunctionParameter fBlock; /* OUT uint32_t */
} HGCMMsgGetNext;
/**
* Guest connection request. Used to tell the DnD protocol
* version to the (host) service.
*
* Used by:
* GUEST_DND_FN_CONNECT
*/
typedef struct HGCMMsgConnect
{
VBGLIOCHGCMCALL hdr;
union
{
struct
{
/** Protocol version to use.
* Deprecated since VBox 6.1.x. Do not use / rely on it anymore. */
HGCMFunctionParameter uProtocol; /* OUT uint32_t */
/** Connection flags. Optional. */
HGCMFunctionParameter uFlags; /* OUT uint32_t */
} v2;
struct
{
/** Context ID. Unused at the moment. */
HGCMFunctionParameter uContext; /* OUT uint32_t */
/** Protocol version to use.
* Deprecated since VBox 6.1.x. Do not use / rely on it anymore. */
HGCMFunctionParameter uProtocol; /* OUT uint32_t */
/** Connection flags. Optional. */
HGCMFunctionParameter uFlags; /* OUT uint32_t */
} v3;
} u;
} HGCMMsgConnect;
/**
* Acknowledges a host operation along with the allowed
* action(s) on the guest.
*
* Used by:
* GUEST_DND_FN_HG_ACK_OP
*/
typedef struct HGCMMsgHGAck
{
VBGLIOCHGCMCALL hdr;
union
{
struct
{
HGCMFunctionParameter uAction; /* OUT uint32_t */
} v1;
struct
{
/** Context ID. Unused at the moment. */
HGCMFunctionParameter uContext; /* OUT uint32_t */
HGCMFunctionParameter uAction; /* OUT uint32_t */
} v3;
} u;
} HGCMMsgHGAck;
/**
* Requests data to be sent to the guest.
*
* Used by:
* GUEST_DND_FN_HG_REQ_DATA
*/
typedef struct HGCMMsgHGReqData
{
VBGLIOCHGCMCALL hdr;
union
{
struct
{
HGCMFunctionParameter pvFormat; /* OUT ptr */
} v1;
struct
{
/** Context ID. Unused at the moment. */
HGCMFunctionParameter uContext; /* OUT uint32_t */
HGCMFunctionParameter pvFormat; /* OUT ptr */
HGCMFunctionParameter cbFormat; /* OUT uint32_t */
} v3;
} u;
} HGCMMsgHGReqData;
typedef struct HGCMMsgHGProgress
{
VBGLIOCHGCMCALL hdr;
union
{
struct
{
HGCMFunctionParameter uStatus; /* OUT uint32_t */
HGCMFunctionParameter uPercent; /* OUT uint32_t */
HGCMFunctionParameter rc; /* OUT uint32_t */
} v1;
struct
{
/** Context ID. Unused at the moment. */
HGCMFunctionParameter uContext; /* OUT uint32_t */
HGCMFunctionParameter uStatus; /* OUT uint32_t */
HGCMFunctionParameter uPercent; /* OUT uint32_t */
HGCMFunctionParameter rc; /* OUT uint32_t */
} v3;
} u;
} HGCMMsgHGProgress;
/**
* Acknowledges a pending guest drag and drop event to the host.
*
* Used by:
* GUEST_DND_FN_GH_ACK_PENDING
*/
typedef struct HGCMMsgGHAckPending
{
VBGLIOCHGCMCALL hdr;
union
{
struct
{
HGCMFunctionParameter uDefAction; /* OUT uint32_t */
HGCMFunctionParameter uAllActions; /* OUT uint32_t */
HGCMFunctionParameter pvFormats; /* OUT ptr */
} v1;
struct
{
/** Context ID. Unused at the moment. */
HGCMFunctionParameter uContext; /* OUT uint32_t */
HGCMFunctionParameter uDefAction; /* OUT uint32_t */
HGCMFunctionParameter uAllActions; /* OUT uint32_t */
HGCMFunctionParameter pvFormats; /* OUT ptr */
HGCMFunctionParameter cbFormats; /* OUT uint32_t */
} v3;
} u;
} HGCMMsgGHAckPending;
/**
* Sends the header of an incoming data block
* to the host.
*
* Used by:
* GUEST_DND_FN_GH_SND_DATA_HDR
*
* New since protocol v3.
*/
typedef struct HGCMMsgHGSendDataHdr HGCMMsgGHSendDataHdr;
/**
* Sends a (meta) data block to the host.
*
* Used by:
* GUEST_DND_FN_GH_SND_DATA
*/
typedef struct HGCMMsgGHSendData
{
VBGLIOCHGCMCALL hdr;
union
{
struct
{
HGCMFunctionParameter pvData; /* OUT ptr */
/** Total bytes to send. This can be more than
* the data block specified in pvData above, e.g.
* when sending over file objects afterwards. */
HGCMFunctionParameter cbTotalBytes; /* OUT uint32_t */
} v1;
struct
{
/** Context ID. Unused at the moment. */
HGCMFunctionParameter uContext; /* OUT uint32_t */
/** Data block to send. */
HGCMFunctionParameter pvData; /* OUT ptr */
/** Size (in bytes) of data block to send. */
HGCMFunctionParameter cbData; /* OUT uint32_t */
/** (Rolling) Checksum, based on checksum type in data header. */
HGCMFunctionParameter pvChecksum; /* OUT ptr */
/** Size (in bytes) of checksum. */
HGCMFunctionParameter cbChecksum; /* OUT uint32_t */
} v3;
} u;
} HGCMMsgGHSendData;
/**
* Sends a directory entry to the host.
*
* Used by:
* GUEST_DND_FN_GH_SND_DIR
*/
typedef struct HGCMMsgHGSendDir HGCMMsgGHSendDir;
/**
* Sends a file header to the host.
*
* Used by:
* GUEST_DND_FN_GH_SND_FILE_HDR
*
* New since protocol v2.
*/
typedef struct HGCMMsgHGSendFileHdr HGCMMsgGHSendFileHdr;
/**
* Sends file data to the host.
*
* Used by:
* GUEST_DND_FN_GH_SND_FILE_DATA
*/
typedef struct HGCMMsgHGSendFileData HGCMMsgGHSendFileData;
/**
* Sends a guest error event to the host.
*
* Used by:
* GUEST_DND_FN_GH_EVT_ERROR
*/
typedef struct HGCMMsgGHError
{
VBGLIOCHGCMCALL hdr;
union
{
struct
{
HGCMFunctionParameter rc; /* OUT uint32_t */
} v1;
struct
{
/** Context ID. Unused at the moment. */
HGCMFunctionParameter uContext; /* OUT uint32_t */
HGCMFunctionParameter rc; /* OUT uint32_t */
} v3;
} u;
} HGCMMsgGHError;
#pragma pack()
/** Builds a callback magic out of the function ID and the version
* of the callback data. */
#define VBOX_DND_CB_MAGIC_MAKE(uFn, uVer) \
RT_MAKE_U32(uVer, uFn)
/*
* Callback magics.
*/
enum eDnDCallbackMagics
{
CB_MAGIC_DND_CONNECT = VBOX_DND_CB_MAGIC_MAKE(GUEST_DND_FN_CONNECT, 0),
CB_MAGIC_DND_REPORT_FEATURES = VBOX_DND_CB_MAGIC_MAKE(GUEST_DND_FN_REPORT_FEATURES, 0),
CB_MAGIC_DND_EVT_ERROR = VBOX_DND_CB_MAGIC_MAKE(GUEST_DND_FN_EVT_ERROR, 0),
CB_MAGIC_DND_HG_GET_NEXT_HOST_MSG = VBOX_DND_CB_MAGIC_MAKE(GUEST_DND_FN_GET_NEXT_HOST_MSG, 0),
CB_MAGIC_DND_HG_ACK_OP = VBOX_DND_CB_MAGIC_MAKE(GUEST_DND_FN_HG_ACK_OP, 0),
CB_MAGIC_DND_HG_REQ_DATA = VBOX_DND_CB_MAGIC_MAKE(GUEST_DND_FN_HG_REQ_DATA, 0),
CB_MAGIC_DND_HG_EVT_PROGRESS = VBOX_DND_CB_MAGIC_MAKE(GUEST_DND_FN_HG_EVT_PROGRESS, 0),
CB_MAGIC_DND_GH_ACK_PENDING = VBOX_DND_CB_MAGIC_MAKE(GUEST_DND_FN_GH_ACK_PENDING, 0),
CB_MAGIC_DND_GH_SND_DATA = VBOX_DND_CB_MAGIC_MAKE(GUEST_DND_FN_GH_SND_DATA, 0),
CB_MAGIC_DND_GH_SND_DATA_HDR = VBOX_DND_CB_MAGIC_MAKE(GUEST_DND_FN_GH_SND_DATA_HDR, 0),
CB_MAGIC_DND_GH_SND_DIR = VBOX_DND_CB_MAGIC_MAKE(GUEST_DND_FN_GH_SND_DIR, 0),
CB_MAGIC_DND_GH_SND_FILE_HDR = VBOX_DND_CB_MAGIC_MAKE(GUEST_DND_FN_GH_SND_FILE_HDR, 0),
CB_MAGIC_DND_GH_SND_FILE_DATA = VBOX_DND_CB_MAGIC_MAKE(GUEST_DND_FN_GH_SND_FILE_DATA, 0)
};
typedef struct VBOXDNDCBHEADERDATA
{
/** Magic number to identify the structure. */
uint32_t uMagic;
/** Context ID to identify callback data. */
uint32_t uContextID;
} VBOXDNDCBHEADERDATA, *PVBOXDNDCBHEADERDATA;
typedef struct VBOXDNDCBCONNECTDATA
{
/** Callback data header. */
VBOXDNDCBHEADERDATA hdr;
/** Protocol version to use.
* Deprecated since VBox 6.1.x. Do not use / rely on it anymore. */
uint32_t uProtocolVersion;
/** Connection flags; currently unused. */
uint32_t fFlags;
} VBOXDNDCBCONNECTDATA, *PVBOXDNDCBCONNECTDATA;
typedef struct VBOXDNDCBREPORTFEATURESDATA
{
/** Callback data header. */
VBOXDNDCBHEADERDATA hdr;
uint32_t fGuestFeatures0;
} VBOXDNDCBREPORTFEATURESDATA, *PVBOXDNDCBREPORTFEATURESDATA;
typedef struct VBOXDNDCBDISCONNECTMSGDATA
{
/** Callback data header. */
VBOXDNDCBHEADERDATA hdr;
} VBOXDNDCBDISCONNECTMSGDATA, *PVBOXDNDCBDISCONNECTMSGDATA;
typedef struct VBOXDNDCBHGGETNEXTHOSTMSG
{
/** Callback data header. */
VBOXDNDCBHEADERDATA hdr;
uint32_t uMsg;
uint32_t cParms;
} VBOXDNDCBHGGETNEXTHOSTMSG, *PVBOXDNDCBHGGETNEXTHOSTMSG;
typedef struct VBOXDNDCBHGGETNEXTHOSTMSGDATA
{
/** Callback data header. */
VBOXDNDCBHEADERDATA hdr;
uint32_t uMsg;
uint32_t cParms;
PVBOXHGCMSVCPARM paParms;
} VBOXDNDCBHGGETNEXTHOSTMSGDATA, *PVBOXDNDCBHGGETNEXTHOSTMSGDATA;
typedef struct VBOXDNDCBHGACKOPDATA
{
/** Callback data header. */
VBOXDNDCBHEADERDATA hdr;
uint32_t uAction;
} VBOXDNDCBHGACKOPDATA, *PVBOXDNDCBHGACKOPDATA;
typedef struct VBOXDNDCBHGREQDATADATA
{
/** Callback data header. */
VBOXDNDCBHEADERDATA hdr;
char *pszFormat;
uint32_t cbFormat;
} VBOXDNDCBHGREQDATADATA, *PVBOXDNDCBHGREQDATADATA;
typedef struct VBOXDNDCBHGEVTPROGRESSDATA
{
/** Callback data header. */
VBOXDNDCBHEADERDATA hdr;
uint32_t uPercentage;
uint32_t uStatus;
uint32_t rc;
} VBOXDNDCBHGEVTPROGRESSDATA, *PVBOXDNDCBHGEVTPROGRESSDATA;
typedef struct VBOXDNDCBGHACKPENDINGDATA
{
/** Callback data header. */
VBOXDNDCBHEADERDATA hdr;
uint32_t uDefAction;
uint32_t uAllActions;
char *pszFormat;
uint32_t cbFormat;
} VBOXDNDCBGHACKPENDINGDATA, *PVBOXDNDCBGHACKPENDINGDATA;
/**
* Data header.
* New since protocol v3.
*/
typedef struct VBOXDNDDATAHDR
{
/** Data transfer flags. Not yet used and must be 0. */
uint32_t uFlags;
/** Screen ID where the data originates from. */
uint32_t uScreenId;
/** Total size (in bytes) to transfer. */
uint64_t cbTotal;
/** Meta data size (in bytes) to transfer.
* This size also is part of cbTotal already. */
uint32_t cbMeta;
/** Meta format buffer. */
void *pvMetaFmt;
/** Size (in bytes) of meta format buffer. */
uint32_t cbMetaFmt;
/** Number of objects (files/directories) to transfer. */
uint64_t cObjects;
/** Compression type. Currently unused, so specify 0.
**@todo Add IPRT compression type enumeration as soon as it's available. */
uint32_t enmCompression;
/** Checksum type. Currently unused, so specify RTDIGESTTYPE_INVALID. */
RTDIGESTTYPE enmChecksumType;
/** The actual checksum buffer for the entire data to be transferred,
* based on enmChksumType. If RTDIGESTTYPE_INVALID is specified,
* no checksum is being used and pvChecksum will be NULL. */
void *pvChecksum;
/** Size (in bytes) of checksum. */
uint32_t cbChecksum;
} VBOXDNDDATAHDR, *PVBOXDNDSNDDATAHDR;
/* New since protocol v3. */
typedef struct VBOXDNDCBSNDDATAHDRDATA
{
/** Callback data header. */
VBOXDNDCBHEADERDATA hdr;
/** Actual header data. */
VBOXDNDDATAHDR data;
} VBOXDNDCBSNDDATAHDRDATA, *PVBOXDNDCBSNDDATAHDRDATA;
typedef struct VBOXDNDSNDDATA
{
union
{
struct
{
/** Data block buffer. */
void *pvData;
/** Size (in bytes) of data block. */
uint32_t cbData;
/** Total metadata size (in bytes). This is transmitted
* with every message because the size can change. */
uint32_t cbTotalSize;
} v1;
/* Protocol v2: No changes. */
struct
{
/** Data block buffer. */
void *pvData;
/** Size (in bytes) of data block. */
uint32_t cbData;
/** (Rolling) Checksum. Not yet implemented. */
void *pvChecksum;
/** Size (in bytes) of checksum. Not yet implemented. */
uint32_t cbChecksum;
} v3;
} u;
} VBOXDNDSNDDATA, *PVBOXDNDSNDDATA;
typedef struct VBOXDNDCBSNDDATADATA
{
/** Callback data header. */
VBOXDNDCBHEADERDATA hdr;
/** Actual data. */
VBOXDNDSNDDATA data;
} VBOXDNDCBSNDDATADATA, *PVBOXDNDCBSNDDATADATA;
typedef struct VBOXDNDCBSNDDIRDATA
{
/** Callback data header. */
VBOXDNDCBHEADERDATA hdr;
/** Directory path. */
char *pszPath;
/** Size (in bytes) of path. */
uint32_t cbPath;
/** Directory creation mode. */
uint32_t fMode;
} VBOXDNDCBSNDDIRDATA, *PVBOXDNDCBSNDDIRDATA;
/* Note: Only for protocol version 2 and up (>= VBox 5.0). */
typedef struct VBOXDNDCBSNDFILEHDRDATA
{
/** Callback data header. */
VBOXDNDCBHEADERDATA hdr;
/** File path (name). */
char *pszFilePath;
/** Size (in bytes) of file path. */
uint32_t cbFilePath;
/** Total size (in bytes) of this file. */
uint64_t cbSize;
/** File (creation) mode. */
uint32_t fMode;
/** Additional flags. Not used at the moment. */
uint32_t fFlags;
} VBOXDNDCBSNDFILEHDRDATA, *PVBOXDNDCBSNDFILEHDRDATA;
typedef struct VBOXDNDCBSNDFILEDATADATA
{
/** Callback data header. */
VBOXDNDCBHEADERDATA hdr;
/** Current file data chunk. */
void *pvData;
/** Size (in bytes) of current data chunk. */
uint32_t cbData;
union
{
struct
{
/** File path (name). */
char *pszFilePath;
/** Size (in bytes) of file path. */
uint32_t cbFilePath;
/** File (creation) mode. */
uint32_t fMode;
} v1;
/* Protocol v2 + v3: Have the file attributes (name, size, mode, ...)
in the VBOXDNDCBSNDFILEHDRDATA structure. */
struct
{
/** Checksum for current file data chunk. */
void *pvChecksum;
/** Size (in bytes) of current data chunk. */
uint32_t cbChecksum;
} v3;
} u;
} VBOXDNDCBSNDFILEDATADATA, *PVBOXDNDCBSNDFILEDATADATA;
typedef struct VBOXDNDCBEVTERRORDATA
{
/** Callback data header. */
VBOXDNDCBHEADERDATA hdr;
int32_t rc;
} VBOXDNDCBEVTERRORDATA, *PVBOXDNDCBEVTERRORDATA;
} /* namespace DragAndDropSvc */
#endif /* !VBOX_INCLUDED_HostServices_DragAndDropSvc_h */
View git blame Copy permalink