diff options
Diffstat (limited to 'include/VBox/HostServices/DragAndDropSvc.h')
| -rw-r--r-- | include/VBox/HostServices/DragAndDropSvc.h | 1198 |
1 files changed, 1198 insertions, 0 deletions
diff --git a/include/VBox/HostServices/DragAndDropSvc.h b/include/VBox/HostServices/DragAndDropSvc.h new file mode 100644 index 00000000..ba42cdef --- /dev/null +++ b/include/VBox/HostServices/DragAndDropSvc.h @@ -0,0 +1,1198 @@ +/* $Id: DragAndDropSvc.h $ */ +/** @file + * Drag and Drop service - Common header for host service and guest clients. + */ + +/* + * Copyright (C) 2011-2022 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 */ + |