diff options
Diffstat (limited to 'include/VBox/HostServices')
| -rw-r--r-- | include/VBox/HostServices/DragAndDropSvc.h | 1198 | ||||
| -rw-r--r-- | include/VBox/HostServices/GuestControlSvc.h | 1500 | ||||
| -rw-r--r-- | include/VBox/HostServices/GuestPropertySvc.h | 553 | ||||
| -rw-r--r-- | include/VBox/HostServices/Makefile.kup | 0 | ||||
| -rw-r--r-- | include/VBox/HostServices/Service.h | 358 | ||||
| -rw-r--r-- | include/VBox/HostServices/VBoxClipboardExt.h | 66 | ||||
| -rw-r--r-- | include/VBox/HostServices/VBoxClipboardSvc.h | 1220 | ||||
| -rw-r--r-- | include/VBox/HostServices/VBoxHostChannel.h | 229 |
8 files changed, 5124 insertions, 0 deletions
diff --git a/include/VBox/HostServices/DragAndDropSvc.h b/include/VBox/HostServices/DragAndDropSvc.h new file mode 100644 index 00000000..1a86f191 --- /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-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 */ + diff --git a/include/VBox/HostServices/GuestControlSvc.h b/include/VBox/HostServices/GuestControlSvc.h new file mode 100644 index 00000000..afa249bd --- /dev/null +++ b/include/VBox/HostServices/GuestControlSvc.h @@ -0,0 +1,1500 @@ +/* $Id: GuestControlSvc.h $ */ +/** @file + * Guest control 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 + */ + +#ifndef VBOX_INCLUDED_HostServices_GuestControlSvc_h +#define VBOX_INCLUDED_HostServices_GuestControlSvc_h +#ifndef RT_WITHOUT_PRAGMA_ONCE +# pragma once +#endif + +#include <VBox/VMMDevCoreTypes.h> +#include <VBox/VBoxGuestCoreTypes.h> +#include <VBox/hgcmsvc.h> +#include <iprt/assert.h> + +/* Everything defined in this file lives in this namespace. */ +namespace guestControl { + +/****************************************************************************** +* Typedefs, constants and inlines * +******************************************************************************/ + +#define HGCMSERVICE_NAME "VBoxGuestControlSvc" + +/** Maximum number of concurrent guest sessions a VM can have. */ +#define VBOX_GUESTCTRL_MAX_SESSIONS 32 +/** Maximum number of concurrent guest objects (processes, files, ...) + * a guest session can have. */ +#define VBOX_GUESTCTRL_MAX_OBJECTS _2K +/** Maximum of callback contexts a guest process can have. */ +#define VBOX_GUESTCTRL_MAX_CONTEXTS _64K + +/** Base (start) of guest control session IDs. Session + * ID 0 is reserved for the root process which + * hosts all other guest session processes. */ +#define VBOX_GUESTCTRL_SESSION_ID_BASE 1 + +/** Builds a context ID out of the session ID, object ID and an + * increasing count. */ +#define VBOX_GUESTCTRL_CONTEXTID_MAKE(uSession, uObject, uCount) \ + ( (uint32_t)((uSession) & 0x1f) << 27 \ + | (uint32_t)((uObject) & 0x7ff) << 16 \ + | (uint32_t)((uCount) & 0xffff) \ + ) +/** Creates a context ID out of a session ID. */ +#define VBOX_GUESTCTRL_CONTEXTID_MAKE_SESSION(uSession) \ + ((uint32_t)((uSession) & 0x1f) << 27) +/** Gets the session ID out of a context ID. */ +#define VBOX_GUESTCTRL_CONTEXTID_GET_SESSION(uContextID) \ + (((uContextID) >> 27) & 0x1f) +/** Gets the process ID out of a context ID. */ +#define VBOX_GUESTCTRL_CONTEXTID_GET_OBJECT(uContextID) \ + (((uContextID) >> 16) & 0x7ff) +/** Gets the context count of a process out of a context ID. */ +#define VBOX_GUESTCTRL_CONTEXTID_GET_COUNT(uContextID) \ + ((uContextID) & 0xffff) +/** Filter context IDs by session. Can be used in conjunction + * with VbglR3GuestCtrlMsgFilterSet(). */ +#define VBOX_GUESTCTRL_FILTER_BY_SESSION(uSession) \ + (VBOX_GUESTCTRL_CONTEXTID_MAKE_SESSION(uSession) | 0xF8000000) + +/** + * Structure keeping the context of a host callback. + */ +typedef struct VBOXGUESTCTRLHOSTCBCTX +{ + /** HGCM message number. */ + uint32_t uMessage; + /** The context ID. */ + uint32_t uContextID; + /** Protocol version of this guest session. Might + * be 0 if not supported. */ + uint32_t uProtocol; +} VBOXGUESTCTRLHOSTCBCTX, *PVBOXGUESTCTRLHOSTCBCTX; + +/** + * Structure for low level HGCM host callback from + * the guest. No deep copy. */ +typedef struct VBOXGUESTCTRLHOSTCALLBACK +{ + /** Number of HGCM parameters. */ + uint32_t mParms; + /** Actual HGCM parameters. */ + PVBOXHGCMSVCPARM mpaParms; +} VBOXGUESTCTRLHOSTCALLBACK, *PVBOXGUESTCTRLHOSTCALLBACK; + +/** @name Host message destination flags. + * + * This is ORed into the context ID parameter Main after extending it to 64-bit. + * + * @internal Host internal. + * @{ */ +#define VBOX_GUESTCTRL_DST_ROOT_SVC RT_BIT_64(63) +#define VBOX_GUESTCTRL_DST_SESSION RT_BIT_64(62) +#define VBOX_GUESTCTRL_DST_BOTH ( VBOX_GUESTCTRL_DST_ROOT_SVC | VBOX_GUESTCTRL_DST_SESSION ) +/** @} */ + + +/** + * The service messages which are callable by host. + */ +enum eHostMsg +{ + /** + * The host asks the client to cancel all pending waits and exit. + */ + HOST_MSG_CANCEL_PENDING_WAITS = 0, + /** + * The host wants to create a guest session. + */ + HOST_MSG_SESSION_CREATE = 20, + /** + * The host wants to close a guest session. + */ + HOST_MSG_SESSION_CLOSE = 21, + /** + * The host wants to execute something in the guest. This can be a command + * line or starting a program. + */ + HOST_MSG_EXEC_CMD = 100, + /** + * Sends input data for stdin to a running process executed by HOST_EXEC_CMD. + */ + HOST_MSG_EXEC_SET_INPUT = 101, + /** + * Gets the current status of a running process, e.g. + * new data on stdout/stderr, process terminated etc. + */ + HOST_MSG_EXEC_GET_OUTPUT = 102, + /** + * Terminates a running guest process. + */ + HOST_MSG_EXEC_TERMINATE = 110, + /** + * Waits for a certain event to happen. This can be an input, output + * or status event. + */ + HOST_MSG_EXEC_WAIT_FOR = 120, + /** + * Opens a guest file. + */ + HOST_MSG_FILE_OPEN = 240, + /** + * Closes a guest file. + */ + HOST_MSG_FILE_CLOSE, + /** + * Reads from an opened guest file. + */ + HOST_MSG_FILE_READ = 250, + /** + * Reads from an opened guest file at a specified offset. + */ + HOST_MSG_FILE_READ_AT, + /** + * Write to an opened guest file. + */ + HOST_MSG_FILE_WRITE = 260, + /** + * Write to an opened guest file at a specified offset. + */ + HOST_MSG_FILE_WRITE_AT, + /** + * Changes the read & write position of an opened guest file. + */ + HOST_MSG_FILE_SEEK = 270, + /** + * Gets the current file position of an opened guest file. + */ + HOST_MSG_FILE_TELL, + /** + * Changes the file size. + */ + HOST_MSG_FILE_SET_SIZE, + /** + * Removes a directory on the guest. + */ + HOST_MSG_DIR_REMOVE = 320, + /** + * Renames a path on the guest. + */ + HOST_MSG_PATH_RENAME = 330, + /** + * Retrieves the user's documents directory. + */ + HOST_MSG_PATH_USER_DOCUMENTS, + /** + * Retrieves the user's home directory. + */ + HOST_MSG_PATH_USER_HOME, + /** + * Issues a shutdown / reboot of the guest OS. + */ + HOST_MSG_SHUTDOWN, + + /** Blow the type up to 32-bits. */ + HOST_MSG_32BIT_HACK = 0x7fffffff +}; + + +/** + * Translates a guest control host message enum to a string. + * + * @returns Enum string name. + * @param enmMsg The message to translate. + */ +DECLINLINE(const char *) GstCtrlHostMsgtoStr(enum eHostMsg enmMsg) +{ + switch (enmMsg) + { + RT_CASE_RET_STR(HOST_MSG_CANCEL_PENDING_WAITS); + RT_CASE_RET_STR(HOST_MSG_SESSION_CREATE); + RT_CASE_RET_STR(HOST_MSG_SESSION_CLOSE); + RT_CASE_RET_STR(HOST_MSG_EXEC_CMD); + RT_CASE_RET_STR(HOST_MSG_EXEC_SET_INPUT); + RT_CASE_RET_STR(HOST_MSG_EXEC_GET_OUTPUT); + RT_CASE_RET_STR(HOST_MSG_EXEC_TERMINATE); + RT_CASE_RET_STR(HOST_MSG_EXEC_WAIT_FOR); + RT_CASE_RET_STR(HOST_MSG_FILE_OPEN); + RT_CASE_RET_STR(HOST_MSG_FILE_CLOSE); + RT_CASE_RET_STR(HOST_MSG_FILE_READ); + RT_CASE_RET_STR(HOST_MSG_FILE_READ_AT); + RT_CASE_RET_STR(HOST_MSG_FILE_WRITE); + RT_CASE_RET_STR(HOST_MSG_FILE_WRITE_AT); + RT_CASE_RET_STR(HOST_MSG_FILE_SEEK); + RT_CASE_RET_STR(HOST_MSG_FILE_TELL); + RT_CASE_RET_STR(HOST_MSG_FILE_SET_SIZE); + RT_CASE_RET_STR(HOST_MSG_DIR_REMOVE); + RT_CASE_RET_STR(HOST_MSG_PATH_RENAME); + RT_CASE_RET_STR(HOST_MSG_PATH_USER_DOCUMENTS); + RT_CASE_RET_STR(HOST_MSG_PATH_USER_HOME); + RT_CASE_RET_STR(HOST_MSG_SHUTDOWN); + RT_CASE_RET_STR(HOST_MSG_32BIT_HACK); + } + return "Unknown"; +} + + +/** + * The service messages which are callable by the guest. + * + * @note The message numbers cannot be changed. Please use the first non-zero + * number that's not in use when adding new messages. + * + * @note Remember to update service.cpp when adding new messages for Main, + * as it validates all incoming messages before passing them on. + */ +enum eGuestMsg +{ + /** Guest waits for a new message the host wants to process on the guest side. + * This is a blocking call and can be deferred. + * + * @note This message is rather odd. The above description isn't really + * correct. Yes, it (1) waits for a new message and will return the + * mesage number and parameter count when one is available. However, it + * is also (2) used to retrieve the message parameters. For some weird + * reasons it was decided that it should always return VERR_TOO_MUCH_DATA + * when used in the first capacity. + * + * @note Has a problem if the guest kernel module cancels the HGCM call, as the + * guest cannot resume waiting till the host issues a message for it and + * the cancelled call returns. The new message may potentially end up in + * /dev/null depending and hang the message conversation between the guest + * and the host (SIGCHLD). + * + * @deprecated Replaced by GUEST_MSG_PEEK_WAIT, GUEST_MSG_GET and + * GUEST_MSG_CANCEL. + */ + GUEST_MSG_WAIT = 1, + /** Cancels pending calls for this client session. + * + * This should be used if a GUEST_MSG_PEEK_WAIT or GUEST_MSG_WAIT call gets + * interrupted on the client end, so as to prevent being rebuffed with + * VERR_RESOURCE_BUSY when restarting the call. + * + * @retval VINF_SUCCESS if cancelled any calls. + * @retval VWRN_NOT_FOUND if no callers. + * @retval VERR_INVALID_CLIENT_ID + * @retval VERR_WRONG_PARAMETER_COUNT + * @since 6.0 + */ + GUEST_MSG_CANCEL = 2, + /** Guest disconnected (terminated normally or due to a crash HGCM + * detected when calling service::clientDisconnect(). + * + * @note This is a host side notification message that has no business in this + * enum. The guest cannot use this message number, host will reject it. + */ + GUEST_MSG_DISCONNECTED = 3, + /** Sets a message filter to only get messages which have a certain + * context ID scheme (that is, a specific session, object etc). + * Since VBox 4.3+. + * @deprecated Replaced by GUEST_SESSION_ACCEPT. + */ + GUEST_MSG_FILTER_SET = 4, + /** Unsets (and resets) a previously set message filter. + * @retval VERR_NOT_IMPLEMENTED since 6.0. + * @deprecated Never needed or used, + */ + GUEST_MSG_FILTER_UNSET = 5, + /** Peeks at the next message, returning immediately. + * + * Returns two 32-bit parameters, first is the message ID and the second the + * parameter count. May optionally return additional 32-bit parameters with the + * sizes of respective message parameters. To distinguish buffer sizes from + * integer parameters, the latter gets their sizes inverted (uint32_t is ~4U, + * uint64_t is ~8U). + * + * Does also support the VM restore checking as in GUEST_MSG_PEEK_WAIT (64-bit + * param \# 0), see documentation there. + * + * @retval VINF_SUCCESS if a message was pending and is being returned. + * @retval VERR_TRY_AGAIN if no message pending. + * @retval VERR_VM_RESTORED if first parameter is a non-zero 64-bit value that + * does not match VbglR3GetSessionId() any more. The new value is + * returned. + * @retval VERR_INVALID_CLIENT_ID + * @retval VERR_WRONG_PARAMETER_COUNT + * @retval VERR_WRONG_PARAMETER_TYPE + * @since 6.0 + */ + GUEST_MSG_PEEK_NOWAIT = 6, + /** Peeks at the next message, waiting for one to arrive. + * + * Returns two 32-bit parameters, first is the message ID and the second the + * parameter count. May optionally return additional 32-bit parameters with the + * sizes of respective message parameters. To distinguish buffer sizes from + * integer parameters, the latter gets their sizes inverted (uint32_t is ~4U, + * uint64_t is ~8U). + * + * To facilitate VM restore checking, the first parameter can be a 64-bit + * integer holding the VbglR3GetSessionId() value the guest knowns. The + * function will then check this before going to sleep and return + * VERR_VM_RESTORED if it doesn't match, same thing happens when the VM is + * restored. + * + * @retval VINF_SUCCESS if info about an pending message is being returned. + * @retval VINF_TRY_AGAIN and message set to HOST_CANCEL_PENDING_WAITS if + * cancelled by GUEST_MSG_CANCEL. + * @retval VERR_RESOURCE_BUSY if another thread already made a waiting call. + * @retval VERR_VM_RESTORED if first parameter is a non-zero 64-bit value that + * does not match VbglR3GetSessionId() any more. The new value is + * returned. + * @retval VERR_INVALID_CLIENT_ID + * @retval VERR_WRONG_PARAMETER_COUNT + * @retval VERR_WRONG_PARAMETER_TYPE + * @note This replaces GUEST_MSG_WAIT. + * @since 6.0 + */ + GUEST_MSG_PEEK_WAIT = 7, + /** Gets the next message, returning immediately. + * + * All parameters are specific to the message being retrieved, however if the + * first one is an integer value it shall be an input parameter holding the + * ID of the message being retrieved. While it would be nice to add a separate + * parameter for this purpose, this is difficult without breaking GUEST_MSG_WAIT + * compatibility. + * + * @retval VINF_SUCCESS if message retrieved and removed from the pending queue. + * @retval VERR_TRY_AGAIN if no message pending. + * @retval VERR_MISMATCH if the incoming message ID does not match the pending. + * @retval VERR_BUFFER_OVERFLOW if a parmeter buffer is too small. The buffer + * size was updated to reflect the required size. + * @retval VERR_INVALID_CLIENT_ID + * @retval VERR_WRONG_PARAMETER_COUNT + * @retval VERR_WRONG_PARAMETER_TYPE + * @note This replaces GUEST_MSG_WAIT. + * @since 6.0 + */ + GUEST_MSG_GET = 8, + /** Skip message. + * + * This skips the current message, replying to the main backend as best it can. + * Takes between zero and two parameters. The first parameter is the 32-bit + * VBox status code to pass onto Main when skipping the message, defaults to + * VERR_NOT_SUPPORTED. The second parameter is the 32-bit message ID of the + * message to skip, by default whatever is first in the queue is removed. This + * is also the case if UINT32_MAX is specified. + * + * @retval VINF_SUCCESS on success. + * @retval VERR_NOT_FOUND if no message pending. + * @retval VERR_MISMATCH if the specified message ID didn't match. + * @retval VERR_INVALID_CLIENT_ID + * @retval VERR_WRONG_PARAMETER_COUNT + * @since 6.0 + */ + GUEST_MSG_SKIP = 9, + /** + * Skips the current assigned message returned by GUEST_MSG_WAIT. + * Needed for telling the host service to not keep stale + * host messages in the queue. + * @deprecated Replaced by GUEST_MSG_SKIP. + */ + GUEST_MSG_SKIP_OLD = 10, + /** General reply to a host message. + * Only contains basic data along with a simple payload. + * @todo proper docs. + */ + GUEST_MSG_REPLY = 11, + /** General message for updating a pending progress for a long task. + * @todo proper docs. + */ + GUEST_MSG_PROGRESS_UPDATE = 12, + /** Sets the caller as the master. + * + * Called by the root VBoxService to explicitly tell the host that's the master + * service. Required to use main VBoxGuest device node. No parameters. + * + * @retval VINF_SUCCESS on success. + * @retval VERR_ACCESS_DENIED if not using main VBoxGuest device not + * @retval VERR_RESOURCE_BUSY if there is already a master. + * @retval VERR_VERSION_MISMATCH if VBoxGuest didn't supply requestor info. + * @retval VERR_INVALID_CLIENT_ID + * @retval VERR_WRONG_PARAMETER_COUNT + * @since 6.0 + */ + GUEST_MSG_MAKE_ME_MASTER = 13, + /** Prepares the starting of a session. + * + * VBoxService makes this call before spawning a session process (must be + * master). The first parameter is the session ID and the second is a one time + * key for identifying the right session process. First parameter is a 32-bit + * session ID with a value between 1 and 0xfff0. The second parameter is a byte + * buffer containing a key that GUEST_SESSION_ACCEPT checks against, minimum + * length is 64 bytes, maximum 16384 bytes. + * + * @retval VINF_SUCCESS on success. + * @retval VERR_OUT_OF_RESOURCES if too many pending sessions hanging around. + * @retval VERR_OUT_OF_RANGE if the session ID outside the allowed range. + * @retval VERR_BUFFER_OVERFLOW if key too large. + * @retval VERR_BUFFER_UNDERFLOW if key too small. + * @retval VERR_ACCESS_DENIED if not master or in legacy mode. + * @retval VERR_DUPLICATE if the session ID has been prepared already. + * @retval VERR_INVALID_CLIENT_ID + * @retval VERR_WRONG_PARAMETER_COUNT + * @retval VERR_WRONG_PARAMETER_TYPE + * @since 6.0 + */ + GUEST_MSG_SESSION_PREPARE = 14, + /** Cancels a prepared session. + * + * VBoxService makes this call to clean up after spawning a session process + * failed. One parameter, 32-bit session ID. If UINT32_MAX is passed, all + * prepared sessions are cancelled. + * + * @retval VINF_SUCCESS on success. + * @retval VWRN_NOT_FOUND if no session with the specified ID. + * @retval VERR_ACCESS_DENIED if not master or in legacy mode. + * @retval VERR_INVALID_CLIENT_ID + * @retval VERR_WRONG_PARAMETER_COUNT + * @retval VERR_WRONG_PARAMETER_TYPE + * @since 6.0 + */ + GUEST_MSG_SESSION_CANCEL_PREPARED = 15, + /** Accepts a prepared session. + * + * The session processes makes this call to accept a prepared session. The + * session ID is then uniquely associated with the HGCM client ID of the caller. + * The parameters must be identical to the matching GUEST_SESSION_PREPARE call. + * + * @retval VINF_SUCCESS on success. + * @retval VERR_NOT_FOUND if the specified session ID wasn't found. + * @retval VERR_OUT_OF_RANGE if the session ID outside the allowed range. + * @retval VERR_BUFFER_OVERFLOW if key too large. + * @retval VERR_BUFFER_UNDERFLOW if key too small. + * @retval VERR_ACCESS_DENIED if we're in legacy mode or is master. + * @retval VERR_RESOURCE_BUSY if the client is already associated with a session. + * @retval VERR_MISMATCH if the key didn't match. + * @retval VERR_INVALID_CLIENT_ID + * @retval VERR_WRONG_PARAMETER_COUNT + * @retval VERR_WRONG_PARAMETER_TYPE + * @since 6.0 + */ + GUEST_MSG_SESSION_ACCEPT = 16, + /** + * Guest reports back a guest session status. + * @todo proper docs. + */ + GUEST_MSG_SESSION_NOTIFY = 20, + /** + * Guest wants to close a specific guest session. + * @todo proper docs. + */ + GUEST_MSG_SESSION_CLOSE = 21, + + /** Report guest side feature flags and retrieve the host ones. + * + * VBoxService makes this call right after becoming master to indicate to the + * host what features it support in addition. In return the host will return + * features the host supports. Two 64-bit parameters are passed in from the + * guest with the guest features (VBOX_GUESTCTRL_GF_XXX), the host replies by + * replacing the parameter values with the host ones (VBOX_GUESTCTRL_HF_XXX). + * + * @retval VINF_SUCCESS on success. + * @retval VERR_ACCESS_DENIED it not master. + * @retval VERR_INVALID_CLIENT_ID + * @retval VERR_WRONG_PARAMETER_COUNT + * @retval VERR_WRONG_PARAMETER_TYPE + * @since 6.0.10, 5.2.32 + */ + GUEST_MSG_REPORT_FEATURES, + /** Query the host ones feature masks. + * + * This is for the session sub-process so that it 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.0.10, 5.2.32 + */ + GUEST_MSG_QUERY_FEATURES, + + /** + * Guests sends output from an executed process. + * @todo proper docs. + */ + GUEST_MSG_EXEC_OUTPUT = 100, + /** + * Guest sends a status update of an executed process to the host. + * @todo proper docs. + */ + GUEST_MSG_EXEC_STATUS = 101, + /** + * Guests sends an input status notification to the host. + * @todo proper docs. + */ + GUEST_MSG_EXEC_INPUT_STATUS = 102, + /** + * Guest notifies the host about some I/O event. This can be + * a stdout, stderr or a stdin event. The actual event only tells + * how many data is available / can be sent without actually + * transmitting the data. + * @todo proper docs. + */ + GUEST_MSG_EXEC_IO_NOTIFY = 210, + /** + * Guest notifies the host about some directory event. + * @todo proper docs. + */ + GUEST_MSG_DIR_NOTIFY = 230, + /** + * Guest notifies the host about some file event. + * @todo proper docs. + */ + GUEST_MSG_FILE_NOTIFY = 240 +}; + +/** + * Translates a guest control guest message enum to a string. + * + * @returns Enum string name. + * @param enmMsg The message to translate. + */ +DECLINLINE(const char *) GstCtrlGuestMsgToStr(enum eGuestMsg enmMsg) +{ + switch (enmMsg) + { + RT_CASE_RET_STR(GUEST_MSG_WAIT); + RT_CASE_RET_STR(GUEST_MSG_CANCEL); + RT_CASE_RET_STR(GUEST_MSG_DISCONNECTED); + RT_CASE_RET_STR(GUEST_MSG_FILTER_SET); + RT_CASE_RET_STR(GUEST_MSG_FILTER_UNSET); + RT_CASE_RET_STR(GUEST_MSG_PEEK_NOWAIT); + RT_CASE_RET_STR(GUEST_MSG_PEEK_WAIT); + RT_CASE_RET_STR(GUEST_MSG_GET); + RT_CASE_RET_STR(GUEST_MSG_SKIP_OLD); + RT_CASE_RET_STR(GUEST_MSG_REPLY); + RT_CASE_RET_STR(GUEST_MSG_PROGRESS_UPDATE); + RT_CASE_RET_STR(GUEST_MSG_SKIP); + RT_CASE_RET_STR(GUEST_MSG_MAKE_ME_MASTER); + RT_CASE_RET_STR(GUEST_MSG_SESSION_PREPARE); + RT_CASE_RET_STR(GUEST_MSG_SESSION_CANCEL_PREPARED); + RT_CASE_RET_STR(GUEST_MSG_SESSION_ACCEPT); + RT_CASE_RET_STR(GUEST_MSG_SESSION_NOTIFY); + RT_CASE_RET_STR(GUEST_MSG_SESSION_CLOSE); + RT_CASE_RET_STR(GUEST_MSG_REPORT_FEATURES); + RT_CASE_RET_STR(GUEST_MSG_QUERY_FEATURES); + RT_CASE_RET_STR(GUEST_MSG_EXEC_OUTPUT); + RT_CASE_RET_STR(GUEST_MSG_EXEC_STATUS); + RT_CASE_RET_STR(GUEST_MSG_EXEC_INPUT_STATUS); + RT_CASE_RET_STR(GUEST_MSG_EXEC_IO_NOTIFY); + RT_CASE_RET_STR(GUEST_MSG_DIR_NOTIFY); + RT_CASE_RET_STR(GUEST_MSG_FILE_NOTIFY); + } + return "Unknown"; +} + + +/** + * Guest session notification types. + * @sa HGCMMsgSessionNotify. + */ +enum GUEST_SESSION_NOTIFYTYPE +{ + GUEST_SESSION_NOTIFYTYPE_UNDEFINED = 0, + /** Something went wrong (see rc). */ + GUEST_SESSION_NOTIFYTYPE_ERROR = 1, + /** Guest session has been started. */ + GUEST_SESSION_NOTIFYTYPE_STARTED = 11, + /** Guest session terminated normally. */ + GUEST_SESSION_NOTIFYTYPE_TEN = 20, + /** Guest session terminated via signal. */ + GUEST_SESSION_NOTIFYTYPE_TES = 30, + /** Guest session terminated abnormally. */ + GUEST_SESSION_NOTIFYTYPE_TEA = 40, + /** Guest session timed out and was killed. */ + GUEST_SESSION_NOTIFYTYPE_TOK = 50, + /** Guest session timed out and was not killed successfully. */ + GUEST_SESSION_NOTIFYTYPE_TOA = 60, + /** Service/OS is stopping, process was killed. */ + GUEST_SESSION_NOTIFYTYPE_DWN = 150 +}; + +/** + * Guest directory notification types. + * @sa HGCMMsgDirNotify. + */ +enum GUEST_DIR_NOTIFYTYPE +{ + GUEST_DIR_NOTIFYTYPE_UNKNOWN = 0, + /** Something went wrong (see rc). */ + GUEST_DIR_NOTIFYTYPE_ERROR = 1, + /** Guest directory opened. */ + GUEST_DIR_NOTIFYTYPE_OPEN = 10, + /** Guest directory closed. */ + GUEST_DIR_NOTIFYTYPE_CLOSE = 20, + /** Information about an open guest directory. */ + GUEST_DIR_NOTIFYTYPE_INFO = 40, + /** Guest directory created. */ + GUEST_DIR_NOTIFYTYPE_CREATE = 70, + /** Guest directory deleted. */ + GUEST_DIR_NOTIFYTYPE_REMOVE = 80 +}; + +/** + * Guest file notification types. + * @sa HGCMMsgFileNotify. + */ +enum GUEST_FILE_NOTIFYTYPE +{ + GUEST_FILE_NOTIFYTYPE_UNKNOWN = 0, + GUEST_FILE_NOTIFYTYPE_ERROR = 1, + GUEST_FILE_NOTIFYTYPE_OPEN = 10, + GUEST_FILE_NOTIFYTYPE_CLOSE = 20, + GUEST_FILE_NOTIFYTYPE_READ = 30, + GUEST_FILE_NOTIFYTYPE_READ_OFFSET, /**< @since 6.0.10, 5.2.32 - VBOX_GUESTCTRL_HF_0_NOTIFY_RDWR_OFFSET */ + GUEST_FILE_NOTIFYTYPE_WRITE = 40, + GUEST_FILE_NOTIFYTYPE_WRITE_OFFSET, /**< @since 6.0.10, 5.2.32 - VBOX_GUESTCTRL_HF_0_NOTIFY_RDWR_OFFSET */ + GUEST_FILE_NOTIFYTYPE_SEEK = 50, + GUEST_FILE_NOTIFYTYPE_TELL = 60, + GUEST_FILE_NOTIFYTYPE_SET_SIZE +}; + +/** + * Guest file seeking types. Has to match FileSeekType in Main. + * + * @note This is not compatible with RTFileSeek, which is an unncessary pain. + */ +enum GUEST_FILE_SEEKTYPE +{ + GUEST_FILE_SEEKTYPE_BEGIN = 1, + GUEST_FILE_SEEKTYPE_CURRENT = 4, + GUEST_FILE_SEEKTYPE_END = 8 +}; + +/** @name VBOX_GUESTCTRL_GF_XXX - Guest features. + * @sa GUEST_MSG_REPORT_FEATURES + * @{ */ +/** Supports HOST_MSG_FILE_SET_SIZE. */ +#define VBOX_GUESTCTRL_GF_0_SET_SIZE RT_BIT_64(0) +/** Supports passing process arguments starting at argv[0] rather than argv[1]. + * Guest additions which doesn't support this feature will instead use the + * executable image path as argv[0]. + * @sa VBOX_GUESTCTRL_HF_0_PROCESS_ARGV0 + * @since 6.1.6 */ +#define VBOX_GUESTCTRL_GF_0_PROCESS_ARGV0 RT_BIT_64(1) +/** Supports passing cmd / arguments / environment blocks bigger than + * GUESTPROCESS_DEFAULT_CMD_LEN / GUESTPROCESS_DEFAULT_ARGS_LEN / GUESTPROCESS_DEFAULT_ENV_LEN (bytes, in total). */ +#define VBOX_GUESTCTRL_GF_0_PROCESS_DYNAMIC_SIZES RT_BIT_64(2) +/** Supports shutting down / rebooting the guest. */ +#define VBOX_GUESTCTRL_GF_0_SHUTDOWN RT_BIT_64(3) +/** Bit that must be set in the 2nd parameter, will be cleared if the host reponds + * correctly (old hosts might not). */ +#define VBOX_GUESTCTRL_GF_1_MUST_BE_ONE RT_BIT_64(63) +/** @} */ + +/** @name VBOX_GUESTCTRL_HF_XXX - Host features. + * @sa GUEST_MSG_REPORT_FEATURES + * @{ */ +/** Host supports the GUEST_FILE_NOTIFYTYPE_READ_OFFSET and + * GUEST_FILE_NOTIFYTYPE_WRITE_OFFSET notification types. */ +#define VBOX_GUESTCTRL_HF_0_NOTIFY_RDWR_OFFSET RT_BIT_64(0) +/** Host supports process passing arguments starting at argv[0] rather than + * argv[1], when the guest additions reports VBOX_GUESTCTRL_GF_0_PROCESS_ARGV0. + * @since 6.1.6 */ +#define VBOX_GUESTCTRL_HF_0_PROCESS_ARGV0 RT_BIT_64(1) +/** @} */ + + +/* + * HGCM parameter structures. + */ +#pragma pack (1) + +/** + * Waits for a host message to arrive. The structure then contains the + * actual message type + required number of parameters needed to successfully + * retrieve that host message (in a next round). + */ +typedef struct HGCMMsgWaitFor +{ + VBGLIOCHGCMCALL hdr; + /** The returned message the host wants to run on the guest. */ + HGCMFunctionParameter msg; /* OUT uint32_t */ + /** Number of parameters the message needs. */ + HGCMFunctionParameter num_parms; /* OUT uint32_t */ +} HGCMMsgWaitFor; + +/** + * Asks the guest control host service to set a message + * filter for this client. This filter will then only + * deliver messages to the client which match the + * wanted context ID (ranges). + */ +typedef struct HGCMMsgFilterSet +{ + VBGLIOCHGCMCALL hdr; + /** Value to filter for after filter mask was applied. */ + HGCMFunctionParameter value; /* IN uint32_t */ + /** Mask to add to the current set filter. */ + HGCMFunctionParameter mask_add; /* IN uint32_t */ + /** Mask to remove from the current set filter. */ + HGCMFunctionParameter mask_remove; /* IN uint32_t */ + /** Filter flags; currently unused. */ + HGCMFunctionParameter flags; /* IN uint32_t */ +} HGCMMsgFilterSet; + +/** + * Asks the guest control host service to disable + * a previously set message filter again. + */ +typedef struct HGCMMsgFilterUnset +{ + VBGLIOCHGCMCALL hdr; + /** Unset flags; currently unused. */ + HGCMFunctionParameter flags; /* IN uint32_t */ +} HGCMMsgFilterUnset; + +/** + * Asks the guest control host service to skip the + * currently assigned host message returned by + * VbglR3GuestCtrlMsgWaitFor(). + */ +typedef struct HGCMMsgSkip +{ + VBGLIOCHGCMCALL hdr; + /** Skip flags; currently unused. */ + HGCMFunctionParameter flags; /* IN uint32_t */ +} HGCMMsgSkip; + +/** + * Asks the guest control host service to cancel all pending (outstanding) + * waits which were not processed yet. This is handy for a graceful shutdown. + */ +typedef struct HGCMMsgCancelPendingWaits +{ + VBGLIOCHGCMCALL hdr; +} HGCMMsgCancelPendingWaits; + +typedef struct HGCMMsgReply +{ + VBGLIOCHGCMCALL hdr; + /** Context ID. */ + HGCMFunctionParameter context; + /** Message type. */ + HGCMFunctionParameter type; + /** IPRT result of overall operation. */ + HGCMFunctionParameter rc; + /** Optional payload to this reply. */ + HGCMFunctionParameter payload; +} HGCMMsgReply; + +/** + * Creates a guest session. + */ +typedef struct HGCMMsgSessionOpen +{ + VBGLIOCHGCMCALL hdr; + /** Context ID. */ + HGCMFunctionParameter context; + /** The guest control protocol version this + * session is about to use. */ + HGCMFunctionParameter protocol; + /** The user name to run the guest session under. */ + HGCMFunctionParameter username; + /** The user's password. */ + HGCMFunctionParameter password; + /** The domain to run the guest session under. */ + HGCMFunctionParameter domain; + /** Session creation flags. */ + HGCMFunctionParameter flags; +} HGCMMsgSessionOpen; + +/** + * Terminates (closes) a guest session. + */ +typedef struct HGCMMsgSessionClose +{ + VBGLIOCHGCMCALL hdr; + /** Context ID. */ + HGCMFunctionParameter context; + /** Session termination flags. */ + HGCMFunctionParameter flags; +} HGCMMsgSessionClose; + +/** + * Reports back a guest session's status. + */ +typedef struct HGCMMsgSessionNotify +{ + VBGLIOCHGCMCALL hdr; + /** Context ID. */ + HGCMFunctionParameter context; + /** Notification type. */ + HGCMFunctionParameter type; + /** Notification result. */ + HGCMFunctionParameter result; +} HGCMMsgSessionNotify; + +typedef struct HGCMMsgPathRename +{ + VBGLIOCHGCMCALL hdr; + /** UInt32: Context ID. */ + HGCMFunctionParameter context; + /** Source to rename. */ + HGCMFunctionParameter source; + /** Destination to rename source to. */ + HGCMFunctionParameter dest; + /** UInt32: Rename flags. */ + HGCMFunctionParameter flags; +} HGCMMsgPathRename; + +typedef struct HGCMMsgPathUserDocuments +{ + VBGLIOCHGCMCALL hdr; + /** UInt32: Context ID. */ + HGCMFunctionParameter context; +} HGCMMsgPathUserDocuments; + +typedef struct HGCMMsgPathUserHome +{ + VBGLIOCHGCMCALL hdr; + /** UInt32: Context ID. */ + HGCMFunctionParameter context; +} HGCMMsgPathUserHome; + +/** + * Shuts down / reboots the guest. + */ +typedef struct HGCMMsgShutdown +{ + VBGLIOCHGCMCALL hdr; + /** UInt32: Context ID. */ + HGCMFunctionParameter context; + /** UInt32: Action flags. */ + HGCMFunctionParameter action; +} HGCMMsgShutdown; + +/** + * Executes a command inside the guest. + */ +typedef struct HGCMMsgProcExec +{ + VBGLIOCHGCMCALL hdr; + /** Context ID. */ + HGCMFunctionParameter context; + /** The command to execute on the guest. */ + HGCMFunctionParameter cmd; + /** Execution flags (see IGuest::ProcessCreateFlag_*). */ + HGCMFunctionParameter flags; + /** Number of arguments. */ + HGCMFunctionParameter num_args; + /** The actual arguments. */ + HGCMFunctionParameter args; + /** Number of environment value pairs. */ + HGCMFunctionParameter num_env; + /** Size (in bytes) of environment block, including terminating zeros. */ + HGCMFunctionParameter cb_env; + /** The actual environment block. */ + HGCMFunctionParameter env; + union + { + struct + { + /** The user name to run the executed command under. + * Only for VBox < 4.3 hosts. */ + HGCMFunctionParameter username; + /** The user's password. + * Only for VBox < 4.3 hosts. */ + HGCMFunctionParameter password; + /** Timeout (in msec) which either specifies the + * overall lifetime of the process or how long it + * can take to bring the process up and running - + * (depends on the IGuest::ProcessCreateFlag_*). */ + HGCMFunctionParameter timeout; + } v1; + struct + { + /** Timeout (in ms) which either specifies the + * overall lifetime of the process or how long it + * can take to bring the process up and running - + * (depends on the IGuest::ProcessCreateFlag_*). */ + HGCMFunctionParameter timeout; + /** Process priority. */ + HGCMFunctionParameter priority; + /** Number of process affinity blocks. */ + HGCMFunctionParameter num_affinity; + /** Pointer to process affinity blocks (uint64_t). */ + HGCMFunctionParameter affinity; + } v2; + } u; +} HGCMMsgProcExec; + +/** + * Sends input to a guest process via stdin. + */ +typedef struct HGCMMsgProcInput +{ + VBGLIOCHGCMCALL hdr; + /** Context ID. */ + HGCMFunctionParameter context; + /** The process ID (PID) to send the input to. */ + HGCMFunctionParameter pid; + /** Input flags (see IGuest::ProcessInputFlag_*). */ + HGCMFunctionParameter flags; + /** Data buffer. */ + HGCMFunctionParameter data; + /** Actual size of data (in bytes). */ + HGCMFunctionParameter size; +} HGCMMsgProcInput; + +/** + * Retrieves ouptut from a previously executed process + * from stdout/stderr. + */ +typedef struct HGCMMsgProcOutput +{ + VBGLIOCHGCMCALL hdr; + /** Context ID. */ + HGCMFunctionParameter context; + /** The process ID (PID). */ + HGCMFunctionParameter pid; + /** The pipe handle ID (stdout/stderr). */ + HGCMFunctionParameter handle; + /** Optional flags. */ + HGCMFunctionParameter flags; + /** Data buffer. */ + HGCMFunctionParameter data; +} HGCMMsgProcOutput; + +/** + * Reports the current status of a guest process. + */ +typedef struct HGCMMsgProcStatus +{ + VBGLIOCHGCMCALL hdr; + /** Context ID. */ + HGCMFunctionParameter context; + /** The process ID (PID). */ + HGCMFunctionParameter pid; + /** The process status. */ + HGCMFunctionParameter status; + /** Optional flags (based on status). */ + HGCMFunctionParameter flags; + /** Optional data buffer (not used atm). */ + HGCMFunctionParameter data; +} HGCMMsgProcStatus; + +/** + * Reports back the status of data written to a process. + */ +typedef struct HGCMMsgProcStatusInput +{ + VBGLIOCHGCMCALL hdr; + /** Context ID. */ + HGCMFunctionParameter context; + /** The process ID (PID). */ + HGCMFunctionParameter pid; + /** Status of the operation. */ + HGCMFunctionParameter status; + /** Optional flags. */ + HGCMFunctionParameter flags; + /** Data written. */ + HGCMFunctionParameter written; +} HGCMMsgProcStatusInput; + +/* + * Guest control 2.0 messages. + */ + +/** + * Terminates a guest process. + */ +typedef struct HGCMMsgProcTerminate +{ + VBGLIOCHGCMCALL hdr; + /** Context ID. */ + HGCMFunctionParameter context; + /** The process ID (PID). */ + HGCMFunctionParameter pid; +} HGCMMsgProcTerminate; + +/** + * Waits for certain events to happen. + */ +typedef struct HGCMMsgProcWaitFor +{ + VBGLIOCHGCMCALL hdr; + /** Context ID. */ + HGCMFunctionParameter context; + /** The process ID (PID). */ + HGCMFunctionParameter pid; + /** Wait (event) flags. */ + HGCMFunctionParameter flags; + /** Timeout (in ms). */ + HGCMFunctionParameter timeout; +} HGCMMsgProcWaitFor; + +typedef struct HGCMMsgDirRemove +{ + VBGLIOCHGCMCALL hdr; + /** UInt32: Context ID. */ + HGCMFunctionParameter context; + /** Directory to remove. */ + HGCMFunctionParameter path; + /** UInt32: Removement flags. */ + HGCMFunctionParameter flags; +} HGCMMsgDirRemove; + +/** + * Opens a guest file. + */ +typedef struct HGCMMsgFileOpen +{ + VBGLIOCHGCMCALL hdr; + /** UInt32: Context ID. */ + HGCMFunctionParameter context; + /** File to open. */ + HGCMFunctionParameter filename; + /** Open mode. */ + HGCMFunctionParameter openmode; + /** Disposition mode. */ + HGCMFunctionParameter disposition; + /** Sharing mode. */ + HGCMFunctionParameter sharing; + /** UInt32: Creation mode. */ + HGCMFunctionParameter creationmode; + /** UInt64: Initial offset. */ + HGCMFunctionParameter offset; +} HGCMMsgFileOpen; + +/** + * Closes a guest file. + */ +typedef struct HGCMMsgFileClose +{ + VBGLIOCHGCMCALL hdr; + /** Context ID. */ + HGCMFunctionParameter context; + /** File handle to close. */ + HGCMFunctionParameter handle; +} HGCMMsgFileClose; + +/** + * Reads from a guest file. + */ +typedef struct HGCMMsgFileRead +{ + VBGLIOCHGCMCALL hdr; + /** Context ID. */ + HGCMFunctionParameter context; + /** File handle to read from. */ + HGCMFunctionParameter handle; + /** Size (in bytes) to read. */ + HGCMFunctionParameter size; +} HGCMMsgFileRead; + +/** + * Reads at a specified offset from a guest file. + */ +typedef struct HGCMMsgFileReadAt +{ + VBGLIOCHGCMCALL hdr; + /** Context ID. */ + HGCMFunctionParameter context; + /** File handle to read from. */ + HGCMFunctionParameter handle; + /** Offset where to start reading from. */ + HGCMFunctionParameter offset; + /** Actual size of data (in bytes). */ + HGCMFunctionParameter size; +} HGCMMsgFileReadAt; + +/** + * Writes to a guest file. + */ +typedef struct HGCMMsgFileWrite +{ + VBGLIOCHGCMCALL hdr; + /** Context ID. */ + HGCMFunctionParameter context; + /** File handle to write to. */ + HGCMFunctionParameter handle; + /** Actual size of data (in bytes). */ + HGCMFunctionParameter size; + /** Data buffer to write to the file. */ + HGCMFunctionParameter data; +} HGCMMsgFileWrite; + +/** + * Writes at a specified offset to a guest file. + */ +typedef struct HGCMMsgFileWriteAt +{ + VBGLIOCHGCMCALL hdr; + /** Context ID. */ + HGCMFunctionParameter context; + /** File handle to write to. */ + HGCMFunctionParameter handle; + /** Offset where to start reading from. */ + HGCMFunctionParameter offset; + /** Actual size of data (in bytes). */ + HGCMFunctionParameter size; + /** Data buffer to write to the file. */ + HGCMFunctionParameter data; +} HGCMMsgFileWriteAt; + +/** + * Seeks the read/write position of a guest file. + */ +typedef struct HGCMMsgFileSeek +{ + VBGLIOCHGCMCALL hdr; + /** Context ID. */ + HGCMFunctionParameter context; + /** File handle to seek. */ + HGCMFunctionParameter handle; + /** The seeking method. */ + HGCMFunctionParameter method; + /** The seeking offset. */ + HGCMFunctionParameter offset; +} HGCMMsgFileSeek; + +/** + * Tells the current read/write position of a guest file. + */ +typedef struct HGCMMsgFileTell +{ + VBGLIOCHGCMCALL hdr; + /** Context ID. */ + HGCMFunctionParameter context; + /** File handle to get the current position for. */ + HGCMFunctionParameter handle; +} HGCMMsgFileTell; + +/** + * Changes the file size. + */ +typedef struct HGCMMsgFileSetSize +{ + VBGLIOCHGCMCALL Hdr; + /** Context ID. */ + HGCMFunctionParameter id32Context; + /** File handle to seek. */ + HGCMFunctionParameter id32Handle; + /** The new file size. */ + HGCMFunctionParameter cb64NewSize; +} HGCMMsgFileSetSize; + + +/****************************************************************************** +* HGCM replies from the guest. These are handled in Main's low-level HGCM * +* callbacks and dispatched to the appropriate guest object. * +******************************************************************************/ + +typedef struct HGCMReplyFileNotify +{ + VBGLIOCHGCMCALL hdr; + /** Context ID. */ + HGCMFunctionParameter context; + /** Notification type. */ + HGCMFunctionParameter type; + /** IPRT result of overall operation. */ + HGCMFunctionParameter rc; + union + { + struct + { + /** Guest file handle. */ + HGCMFunctionParameter handle; + } open; + /** Note: Close does not have any additional data (yet). */ + struct + { + /** Actual data read (if any). */ + HGCMFunctionParameter data; + } read; + struct + { + /** Actual data read (if any). */ + HGCMFunctionParameter pvData; + /** The new file offset (signed). Negative value if non-seekable files. */ + HGCMFunctionParameter off64New; + } ReadOffset; + struct + { + /** How much data (in bytes) have been successfully written. */ + HGCMFunctionParameter written; + } write; + struct + { + /** Number of bytes that was successfully written. */ + HGCMFunctionParameter cb32Written; + /** The new file offset (signed). Negative value if non-seekable files. */ + HGCMFunctionParameter off64New; + } WriteOffset; + struct + { + HGCMFunctionParameter offset; + } seek; + struct + { + HGCMFunctionParameter offset; + } tell; + struct + { + HGCMFunctionParameter cb64Size; + } SetSize; + } u; +} HGCMReplyFileNotify; + +typedef struct HGCMReplyDirNotify +{ + VBGLIOCHGCMCALL hdr; + /** Context ID. */ + HGCMFunctionParameter context; + /** Notification type. */ + HGCMFunctionParameter type; + /** IPRT result of overall operation. */ + HGCMFunctionParameter rc; + union + { + struct + { + /** Directory information. */ + HGCMFunctionParameter objInfo; + } info; + struct + { + /** Guest directory handle. */ + HGCMFunctionParameter handle; + } open; + struct + { + /** Current read directory entry. */ + HGCMFunctionParameter entry; + /** Extended entry object information. Optional. */ + HGCMFunctionParameter objInfo; + } read; + } u; +} HGCMReplyDirNotify; + +#pragma pack () + +/****************************************************************************** +* Callback data structures. * +******************************************************************************/ + +/** + * The guest control callback data header. Must come first + * on each callback structure defined below this struct. + */ +typedef struct CALLBACKDATA_HEADER +{ + /** Context ID to identify callback data. This is + * and *must* be the very first parameter in this + * structure to still be backwards compatible. */ + uint32_t uContextID; +} CALLBACKDATA_HEADER, *PCALLBACKDATA_HEADER; + +/* + * These structures make up the actual low level HGCM callback data sent from + * the guest back to the host. + */ + +typedef struct CALLBACKDATA_CLIENT_DISCONNECTED +{ + /** Callback data header. */ + CALLBACKDATA_HEADER hdr; +} CALLBACKDATA_CLIENT_DISCONNECTED, *PCALLBACKDATA_CLIENT_DISCONNECTED; + +typedef struct CALLBACKDATA_MSG_REPLY +{ + /** Callback data header. */ + CALLBACKDATA_HEADER hdr; + /** Notification type. */ + uint32_t uType; + /** Notification result. Note: int vs. uint32! */ + uint32_t rc; + /** Pointer to optional payload. */ + void *pvPayload; + /** Payload size (in bytes). */ + uint32_t cbPayload; +} CALLBACKDATA_MSG_REPLY, *PCALLBACKDATA_MSG_REPLY; + +typedef struct CALLBACKDATA_SESSION_NOTIFY +{ + /** Callback data header. */ + CALLBACKDATA_HEADER hdr; + /** Notification type. */ + uint32_t uType; + /** Notification result. Note: int vs. uint32! */ + uint32_t uResult; +} CALLBACKDATA_SESSION_NOTIFY, *PCALLBACKDATA_SESSION_NOTIFY; + +typedef struct CALLBACKDATA_PROC_STATUS +{ + /** Callback data header. */ + CALLBACKDATA_HEADER hdr; + /** The process ID (PID). */ + uint32_t uPID; + /** The process status. */ + uint32_t uStatus; + /** Optional flags, varies, based on u32Status. */ + uint32_t uFlags; + /** Optional data buffer (not used atm). */ + void *pvData; + /** Size of optional data buffer (not used atm). */ + uint32_t cbData; +} CALLBACKDATA_PROC_STATUS, *PCALLBACKDATA_PROC_STATUS; + +typedef struct CALLBACKDATA_PROC_OUTPUT +{ + /** Callback data header. */ + CALLBACKDATA_HEADER hdr; + /** The process ID (PID). */ + uint32_t uPID; + /** The handle ID (stdout/stderr). */ + uint32_t uHandle; + /** Optional flags (not used atm). */ + uint32_t uFlags; + /** Optional data buffer. */ + void *pvData; + /** Size (in bytes) of optional data buffer. */ + uint32_t cbData; +} CALLBACKDATA_PROC_OUTPUT, *PCALLBACKDATA_PROC_OUTPUT; + +typedef struct CALLBACKDATA_PROC_INPUT +{ + /** Callback data header. */ + CALLBACKDATA_HEADER hdr; + /** The process ID (PID). */ + uint32_t uPID; + /** Current input status. */ + uint32_t uStatus; + /** Optional flags. */ + uint32_t uFlags; + /** Size (in bytes) of processed input data. */ + uint32_t uProcessed; +} CALLBACKDATA_PROC_INPUT, *PCALLBACKDATA_PROC_INPUT; + +/** + * General guest directory notification callback. + */ +typedef struct CALLBACKDATA_DIR_NOTIFY +{ + /** Callback data header. */ + CALLBACKDATA_HEADER hdr; + /** Notification type. */ + uint32_t uType; + /** IPRT result of overall operation. */ + uint32_t rc; + union + { + struct + { + /** Size (in bytes) of directory information. */ + uint32_t cbObjInfo; + /** Pointer to directory information. */ + void *pvObjInfo; + } info; + struct + { + /** Guest directory handle. */ + uint32_t uHandle; + } open; + /** Note: Close does not have any additional data (yet). */ + struct + { + /** Size (in bytes) of directory entry information. */ + uint32_t cbEntry; + /** Pointer to directory entry information. */ + void *pvEntry; + /** Size (in bytes) of directory entry object information. */ + uint32_t cbObjInfo; + /** Pointer to directory entry object information. */ + void *pvObjInfo; + } read; + } u; +} CALLBACKDATA_DIR_NOTIFY, *PCALLBACKDATA_DIR_NOTIFY; + +/** + * General guest file notification callback. + */ +typedef struct CALLBACKDATA_FILE_NOTIFY +{ + /** Callback data header. */ + CALLBACKDATA_HEADER hdr; + /** Notification type. */ + uint32_t uType; + /** IPRT result of overall operation. */ + uint32_t rc; + union + { + struct + { + /** Guest file handle. */ + uint32_t uHandle; + } open; + /** Note: Close does not have any additional data (yet). */ + struct + { + /** How much data (in bytes) have been read. */ + uint32_t cbData; + /** Actual data read (if any). */ + void *pvData; + } read; + struct + { + /** How much data (in bytes) have been successfully written. */ + uint32_t cbWritten; + } write; + struct + { + /** New file offset after successful seek. */ + uint64_t uOffActual; + } seek; + struct + { + /** New file offset after successful tell. */ + uint64_t uOffActual; + } tell; + struct + { + /** The new file siz.e */ + uint64_t cbSize; + } SetSize; + } u; +} CALLBACKDATA_FILE_NOTIFY, *PCALLBACKDATA_FILE_NOTIFY; + +} /* namespace guestControl */ + +#endif /* !VBOX_INCLUDED_HostServices_GuestControlSvc_h */ + diff --git a/include/VBox/HostServices/GuestPropertySvc.h b/include/VBox/HostServices/GuestPropertySvc.h new file mode 100644 index 00000000..cdafee28 --- /dev/null +++ b/include/VBox/HostServices/GuestPropertySvc.h @@ -0,0 +1,553 @@ +/** @file + * Guest property service - Common header for host service and guest clients. + */ + +/* + * Copyright (C) 2006-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 + */ + +#ifndef VBOX_INCLUDED_HostServices_GuestPropertySvc_h +#define VBOX_INCLUDED_HostServices_GuestPropertySvc_h +#ifndef RT_WITHOUT_PRAGMA_ONCE +# pragma once +#endif + +#include <VBox/VMMDevCoreTypes.h> +#include <VBox/VBoxGuestCoreTypes.h> +#include <VBox/log.h> +#include <iprt/err.h> +#include <iprt/assertcompile.h> +#include <iprt/string.h> + + +/** Maximum size for property names (including the terminator). */ +#define GUEST_PROP_MAX_NAME_LEN 64 +/** Maximum size for property values (including the terminator). */ +#define GUEST_PROP_MAX_VALUE_LEN 1024 +/** Maximum number of properties per guest. */ +#define GUEST_PROP_MAX_PROPS 256 +/** Maximum size for enumeration patterns (including the terminators). */ +#define GUEST_PROP_MAX_PATTERN_LEN 1024 +/** Maximum number of changes we remember for guest notifications. */ +#define GUEST_PROP_MAX_GUEST_NOTIFICATIONS 256 +/** Maximum number of current pending waits per client. */ +#define GUEST_PROP_MAX_GUEST_CONCURRENT_WAITS 16 + + +/** @name GUEST_PROP_F_XXX - The guest property flag values which are currently accepted. + * @{ + */ +#define GUEST_PROP_F_NILFLAG UINT32_C(0) +/** Transient until VM gets shut down. */ +#define GUEST_PROP_F_TRANSIENT RT_BIT_32(1) +#define GUEST_PROP_F_RDONLYGUEST RT_BIT_32(2) +#define GUEST_PROP_F_RDONLYHOST RT_BIT_32(3) +/** Transient until VM gets a reset / restarts. + * Implies TRANSIENT. */ +#define GUEST_PROP_F_TRANSRESET RT_BIT_32(4) +#define GUEST_PROP_F_READONLY (GUEST_PROP_F_RDONLYGUEST | GUEST_PROP_F_RDONLYHOST) +#define GUEST_PROP_F_ALLFLAGS (GUEST_PROP_F_TRANSIENT | GUEST_PROP_F_READONLY | GUEST_PROP_F_TRANSRESET) +/** @} */ + +/** + * Check that a string fits our criteria for a property name. + * + * @returns IPRT status code + * @param pszName The string to check, must be valid Utf8 + * @param cbName The number of bytes @a pszName points to, including the + * terminating character. + */ +DECLINLINE(int) GuestPropValidateName(const char *pszName, size_t cbName) +{ + /* Property name is expected to be at least 1 charecter long plus terminating character. */ + AssertReturn(cbName >= 2, VERR_INVALID_PARAMETER); + AssertReturn(cbName <= GUEST_PROP_MAX_NAME_LEN, VERR_INVALID_PARAMETER); + + AssertPtrReturn(pszName, VERR_INVALID_POINTER); + + AssertReturn(memchr(pszName, '*', cbName) == NULL, VERR_INVALID_PARAMETER); + AssertReturn(memchr(pszName, '?', cbName) == NULL, VERR_INVALID_PARAMETER); + AssertReturn(memchr(pszName, '|', cbName) == NULL, VERR_INVALID_PARAMETER); + + return VINF_SUCCESS; +} + +/** + * Check a string fits our criteria for the value of a guest property. + * + * @returns IPRT status code + * @retval VINF_SUCCESS if guest property value corresponds to all criteria. + * @retval VERR_TOO_MUCH_DATA if guest property value size exceeds limits. + * @retval VERR_INVALID_PARAMETER if guest property does not correspond to all other criteria. + * @param pszValue The string to check, must be valid utf-8. + * @param cbValue The size of of @a pszValue in bytes, including the + * terminator. + * @thread HGCM + */ +DECLINLINE(int) GuestPropValidateValue(const char *pszValue, size_t cbValue) +{ + AssertPtrReturn(pszValue, VERR_INVALID_POINTER); + + /* Zero-length values are possible, however buffer should contain terminating character at least. */ + AssertReturn(cbValue > 0, VERR_INVALID_PARAMETER); + AssertReturn(cbValue <= GUEST_PROP_MAX_VALUE_LEN, VERR_TOO_MUCH_DATA); + + return VINF_SUCCESS; +} + +/** + * Get the name of a flag as a string. + * @returns the name, or NULL if fFlag is invalid. + * @param fFlag The flag, GUEST_PROP_F_XXX. + * @param pcchName Where to return the name length. + */ +DECLINLINE(const char *) GuestPropFlagNameAndLen(uint32_t fFlag, size_t *pcchName) +{ + switch (fFlag) + { + case GUEST_PROP_F_TRANSIENT: + *pcchName = sizeof("TRANSIENT") - 1; + return "TRANSIENT"; + case GUEST_PROP_F_RDONLYGUEST: + *pcchName = sizeof("RDONLYGUEST") - 1; + return "RDONLYGUEST"; + case GUEST_PROP_F_RDONLYHOST: + *pcchName = sizeof("RDONLYHOST") - 1; + return "RDONLYHOST"; + case GUEST_PROP_F_READONLY: + *pcchName = sizeof("READONLY") - 1; + return "READONLY"; + case GUEST_PROP_F_TRANSRESET: + *pcchName = sizeof("TRANSRESET") - 1; + return "TRANSRESET"; + default: + *pcchName = 0; + return NULL; + } +} + +/** + * Maximum length for the property flags field. We only ever return one of + * RDONLYGUEST, RDONLYHOST and RDONLY + */ +#define GUEST_PROP_MAX_FLAGS_LEN sizeof("TRANSIENT, RDONLYGUEST, TRANSRESET") + +/** + * Parse a guest properties flags string for flag names and make sure that + * there is no junk text in the string. + * + * @returns IPRT status code + * @retval VERR_INVALID_PARAMETER if the flag string is not valid + * @param pcszFlags the flag string to parse + * @param pfFlags where to store the parse result. May not be NULL. + * @note This function is also inline because it must be accessible from + * several modules and it does not seem reasonable to put it into + * its own library. + */ +DECLINLINE(int) GuestPropValidateFlags(const char *pcszFlags, uint32_t *pfFlags) +{ + static const uint32_t s_aFlagList[] = + { + GUEST_PROP_F_TRANSIENT, GUEST_PROP_F_READONLY, GUEST_PROP_F_RDONLYGUEST, GUEST_PROP_F_RDONLYHOST, GUEST_PROP_F_TRANSRESET + }; + const char *pcszNext = pcszFlags; + int rc = VINF_SUCCESS; + uint32_t fFlags = 0; + AssertLogRelReturn(RT_VALID_PTR(pfFlags), VERR_INVALID_POINTER); + + if (pcszFlags) + { + while (*pcszNext == ' ') + ++pcszNext; + while ((*pcszNext != '\0') && RT_SUCCESS(rc)) + { + unsigned i; + rc = VERR_PARSE_ERROR; + for (i = 0; i < RT_ELEMENTS(s_aFlagList); ++i) + { + size_t cchFlagName; + const char *pszFlagName = GuestPropFlagNameAndLen(s_aFlagList[i], &cchFlagName); + if (RTStrNICmpAscii(pcszNext, pszFlagName, cchFlagName) == 0) + { + char ch; + fFlags |= s_aFlagList[i]; + pcszNext += cchFlagName; + while ((ch = *pcszNext) == ' ') + ++pcszNext; + rc = VINF_SUCCESS; + if (ch == ',') + { + ++pcszNext; + while (*pcszNext == ' ') + ++pcszNext; + } + else if (ch != '\0') + rc = VERR_PARSE_ERROR; + break; + } + } + } + } + if (RT_SUCCESS(rc)) + *pfFlags = fFlags; + return rc; +} + + +/** + * Write out flags to a string. + * @returns IPRT status code + * @param fFlags the flags to write out + * @param pszFlags where to write the flags string. This must point to + * a buffer of size (at least) GUEST_PROP_MAX_FLAGS_LEN. + */ +DECLINLINE(int) GuestPropWriteFlags(uint32_t fFlags, char *pszFlags) +{ + /* Putting READONLY before the other RDONLY flags keeps the result short. */ + static const uint32_t s_aFlagList[] = + { + GUEST_PROP_F_TRANSIENT, GUEST_PROP_F_READONLY, GUEST_PROP_F_RDONLYGUEST, GUEST_PROP_F_RDONLYHOST, GUEST_PROP_F_TRANSRESET + }; + int rc = VINF_SUCCESS; + + AssertLogRelReturn(RT_VALID_PTR(pszFlags), VERR_INVALID_POINTER); + if ((fFlags & ~GUEST_PROP_F_ALLFLAGS) == GUEST_PROP_F_NILFLAG) + { + char *pszNext; + unsigned i; + + /* TRANSRESET implies TRANSIENT. For compatability with old clients we + always set TRANSIENT when TRANSRESET appears. */ + if (fFlags & GUEST_PROP_F_TRANSRESET) + fFlags |= GUEST_PROP_F_TRANSIENT; + + pszNext = pszFlags; + for (i = 0; i < RT_ELEMENTS(s_aFlagList); ++i) + { + if (s_aFlagList[i] == (fFlags & s_aFlagList[i])) + { + size_t cchFlagName; + const char *pszFlagName = GuestPropFlagNameAndLen(s_aFlagList[i], &cchFlagName); + memcpy(pszNext, pszFlagName, cchFlagName); + pszNext += cchFlagName; + fFlags &= ~s_aFlagList[i]; + if (fFlags != GUEST_PROP_F_NILFLAG) + { + *pszNext++ = ','; + *pszNext++ = ' '; + } + } + } + *pszNext = '\0'; + + Assert((uintptr_t)(pszNext - pszFlags) < GUEST_PROP_MAX_FLAGS_LEN); + Assert(fFlags == GUEST_PROP_F_NILFLAG); /* bad s_aFlagList */ + } + else + rc = VERR_INVALID_PARAMETER; + return rc; +} + + +/** @name The service functions which are callable by host. + * @{ + */ +/** Set properties in a block. + * The parameters are pointers to NULL-terminated arrays containing the + * parameters. These are, in order, name, value, timestamp, flags. Strings are + * stored as pointers to mutable utf8 data. All parameters must be supplied. */ +#define GUEST_PROP_FN_HOST_SET_PROPS 1 +/** Get the value attached to a guest property. + * The parameter format matches that of GET_PROP. */ +#define GUEST_PROP_FN_HOST_GET_PROP 2 +/** Set the value attached to a guest property. + * The parameter format matches that of SET_PROP. */ +#define GUEST_PROP_FN_HOST_SET_PROP 3 +/** Set the value attached to a guest property. + * The parameter format matches that of SET_PROP_VALUE. */ +#define GUEST_PROP_FN_HOST_SET_PROP_VALUE 4 +/** Remove a guest property. + * The parameter format matches that of DEL_PROP. */ +#define GUEST_PROP_FN_HOST_DEL_PROP 5 +/** Enumerate guest properties. + * The parameter format matches that of ENUM_PROPS. */ +#define GUEST_PROP_FN_HOST_ENUM_PROPS 6 +/** Set global flags for the service. + * Currently RDONLYGUEST is supported. Takes one 32-bit unsigned integer + * parameter for the flags. */ +#define GUEST_PROP_FN_HOST_SET_GLOBAL_FLAGS 7 +/** @} */ + + +/** @name The service functions which are called by guest. + * + * @note The numbers may not change! + * @{ + */ +/** Get a guest property */ +#define GUEST_PROP_FN_GET_PROP 1 +/** Set a guest property */ +#define GUEST_PROP_FN_SET_PROP 2 +/** Set just the value of a guest property */ +#define GUEST_PROP_FN_SET_PROP_VALUE 3 +/** Delete a guest property */ +#define GUEST_PROP_FN_DEL_PROP 4 +/** Enumerate guest properties */ +#define GUEST_PROP_FN_ENUM_PROPS 5 +/** Poll for guest notifications */ +#define GUEST_PROP_FN_GET_NOTIFICATION 6 +/** @} */ + + +/** + * Data structure to pass to the service extension callback. + * We use this to notify the host of changes to properties. + */ +typedef struct GUESTPROPHOSTCALLBACKDATA +{ + /** Magic number to identify the structure (GUESTPROPHOSTCALLBACKDATA_MAGIC). */ + uint32_t u32Magic; + /** The name of the property that was changed */ + const char *pcszName; + /** The new property value, or NULL if the property was deleted */ + const char *pcszValue; + /** The timestamp of the modification */ + uint64_t u64Timestamp; + /** The flags field of the modified property */ + const char *pcszFlags; +} GUESTPROPHOSTCALLBACKDATA; +/** Poitner to a data structure to pass to the service extension callback. */ +typedef GUESTPROPHOSTCALLBACKDATA *PGUESTPROPHOSTCALLBACKDATA; + +/** Magic number for sanity checking the HOSTCALLBACKDATA structure */ +#define GUESTPROPHOSTCALLBACKDATA_MAGIC UINT32_C(0x69c87a78) + +/** + * HGCM parameter structures. Packing is explicitly defined as this is a wire format. + */ +/** The guest is requesting the value of a property */ +typedef struct GuestPropMsgGetProperty +{ + VBGLIOCHGCMCALL hdr; + + /** + * The property name (IN pointer) + * This must fit to a number of criteria, namely + * - Only Utf8 strings are allowed + * - Less than or equal to MAX_NAME_LEN bytes in length + * - Zero terminated + */ + HGCMFunctionParameter name; + + /** + * The returned string data will be placed here. (OUT pointer) + * This call returns two null-terminated strings which will be placed one + * after another: value and flags. + */ + HGCMFunctionParameter buffer; + + /** + * The property timestamp. (OUT uint64_t) + */ + HGCMFunctionParameter timestamp; + + /** + * If the buffer provided was large enough this will contain the size of + * the returned data. Otherwise it will contain the size of the buffer + * needed to hold the data and VERR_BUFFER_OVERFLOW will be returned. + * (OUT uint32_t) + */ + HGCMFunctionParameter size; +} GuestPropMsgGetProperty; +AssertCompileSize(GuestPropMsgGetProperty, 40 + 4 * (ARCH_BITS == 64 ? 16 : 12)); + +/** The guest is requesting to change a property */ +typedef struct GuestPropMsgSetProperty +{ + VBGLIOCHGCMCALL hdr; + + /** + * The property name. (IN pointer) + * This must fit to a number of criteria, namely + * - Only Utf8 strings are allowed + * - Less than or equal to MAX_NAME_LEN bytes in length + * - Zero terminated + */ + HGCMFunctionParameter name; + + /** + * The value of the property (IN pointer) + * Criteria as for the name parameter, but with length less than or equal to + * MAX_VALUE_LEN. + */ + HGCMFunctionParameter value; + + /** + * The property flags (IN pointer) + * This is a comma-separated list of the format flag=value + * The length must be less than or equal to GUEST_PROP_MAX_FLAGS_LEN and only + * known flag names and values will be accepted. + */ + HGCMFunctionParameter flags; +} GuestPropMsgSetProperty; +AssertCompileSize(GuestPropMsgSetProperty, 40 + 3 * (ARCH_BITS == 64 ? 16 : 12)); + +/** The guest is requesting to change the value of a property */ +typedef struct GuestPropMsgSetPropertyValue +{ + VBGLIOCHGCMCALL hdr; + + /** + * The property name. (IN pointer) + * This must fit to a number of criteria, namely + * - Only Utf8 strings are allowed + * - Less than or equal to MAX_NAME_LEN bytes in length + * - Zero terminated + */ + HGCMFunctionParameter name; + + /** + * The value of the property (IN pointer) + * Criteria as for the name parameter, but with length less than or equal to + * MAX_VALUE_LEN. + */ + HGCMFunctionParameter value; +} GuestPropMsgSetPropertyValue; +AssertCompileSize(GuestPropMsgSetPropertyValue, 40 + 2 * (ARCH_BITS == 64 ? 16 : 12)); + +/** The guest is requesting to remove a property */ +typedef struct GuestPropMsgDelProperty +{ + VBGLIOCHGCMCALL hdr; + + /** + * The property name. This must fit to a number of criteria, namely + * - Only Utf8 strings are allowed + * - Less than or equal to MAX_NAME_LEN bytes in length + * - Zero terminated + */ + HGCMFunctionParameter name; +} GuestPropMsgDelProperty; +AssertCompileSize(GuestPropMsgDelProperty, 40 + 1 * (ARCH_BITS == 64 ? 16 : 12)); + +/** The guest is requesting to enumerate properties */ +typedef struct GuestPropMsgEnumProperties +{ + VBGLIOCHGCMCALL hdr; + + /** + * Array of patterns to match the properties against, separated by '|' + * characters. For backwards compatibility, '\\0' is also accepted + * as a separater. + * (IN pointer) + * If only a single, empty pattern is given then match all. + */ + HGCMFunctionParameter patterns; + /** + * On success, null-separated array of strings in which the properties are + * returned. (OUT pointer) + * The number of strings in the array is always a multiple of four, + * and in sequences of name, value, timestamp (hexadecimal string) and the + * flags as a comma-separated list in the format "name=value". The list + * is terminated by an empty string after a "flags" entry (or at the + * start). + */ + HGCMFunctionParameter strings; + /** + * On success, the size of the returned data. If the buffer provided is + * too small, the size of buffer needed. (OUT uint32_t) + */ + HGCMFunctionParameter size; +} GuestPropMsgEnumProperties; +AssertCompileSize(GuestPropMsgEnumProperties, 40 + 3 * (ARCH_BITS == 64 ? 16 : 12)); + +/** + * The guest is polling for notifications on changes to properties, specifying + * a set of patterns to match the names of changed properties against and + * optionally the timestamp of the last notification seen. + * On success, VINF_SUCCESS will be returned and the buffer will contain + * details of a property notification. If no new notification is available + * which matches one of the specified patterns, the call will block until one + * is. + * If the last notification could not be found by timestamp, VWRN_NOT_FOUND + * will be returned and the oldest available notification will be returned. + * If a zero timestamp is specified, the call will always wait for a new + * notification to arrive. + * If the buffer supplied was not large enough to hold the notification, + * VERR_BUFFER_OVERFLOW will be returned and the size parameter will contain + * the size of the buffer needed. + * + * The protocol for a guest to obtain notifications is to call + * GET_NOTIFICATION in a loop. On the first call, the ingoing timestamp + * parameter should be set to zero. On subsequent calls, it should be set to + * the outgoing timestamp from the previous call. + */ +typedef struct GuestPropMsgGetNotification +{ + VBGLIOCHGCMCALL hdr; + + /** + * A list of patterns to match the guest event name against, separated by + * vertical bars (|) (IN pointer) + * An empty string means match all. + */ + HGCMFunctionParameter patterns; + /** + * The timestamp of the last change seen (IN uint64_t) + * This may be zero, in which case the oldest available change will be + * sent. If the service does not remember an event matching the + * timestamp, then VWRN_NOT_FOUND will be returned, and the guest should + * assume that it has missed a certain number of notifications. + * + * The timestamp of the change being notified of (OUT uint64_t) + * Undefined on failure. + */ + HGCMFunctionParameter timestamp; + + /** + * The returned data, if any, will be placed here. (OUT pointer) + * This call returns three null-terminated strings which will be placed + * one after another: name, value and flags. For a delete notification, + * value and flags will be empty strings. Undefined on failure. + */ + HGCMFunctionParameter buffer; + + /** + * On success, the size of the returned data. (OUT uint32_t) + * On buffer overflow, the size of the buffer needed to hold the data. + * Undefined on failure. + */ + HGCMFunctionParameter size; +} GuestPropMsgGetNotification; +AssertCompileSize(GuestPropMsgGetNotification, 40 + 4 * (ARCH_BITS == 64 ? 16 : 12)); + + +#endif /* !VBOX_INCLUDED_HostServices_GuestPropertySvc_h */ + diff --git a/include/VBox/HostServices/Makefile.kup b/include/VBox/HostServices/Makefile.kup new file mode 100644 index 00000000..e69de29b --- /dev/null +++ b/include/VBox/HostServices/Makefile.kup diff --git a/include/VBox/HostServices/Service.h b/include/VBox/HostServices/Service.h new file mode 100644 index 00000000..bc5f680b --- /dev/null +++ b/include/VBox/HostServices/Service.h @@ -0,0 +1,358 @@ +/** @file + * Base class for an host-guest service. + */ + +/* + * 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 + */ + +#ifndef VBOX_INCLUDED_HostServices_Service_h +#define VBOX_INCLUDED_HostServices_Service_h +#ifndef RT_WITHOUT_PRAGMA_ONCE +# pragma once +#endif + +#include <VBox/log.h> +#include <VBox/hgcmsvc.h> + +#include <iprt/assert.h> +#include <iprt/alloc.h> +#include <iprt/cpp/utils.h> + +#include <new> + + +namespace HGCM +{ + +/** + * Structure for keeping a HGCM service context. + */ +typedef struct VBOXHGCMSVCTX +{ + /** HGCM helper functions. */ + PVBOXHGCMSVCHELPERS pHelpers; + /** + * Callback function supplied by the host for notification of updates + * to properties. + */ + PFNHGCMSVCEXT pfnHostCallback; + /** User data pointer to be supplied to the host callback function. */ + void *pvHostData; +} VBOXHGCMSVCTX, *PVBOXHGCMSVCTX; + +/** + * Base class encapsulating and working with a HGCM message. + */ +class Message +{ +public: + Message(void); + Message(uint32_t uMsg, uint32_t cParms, VBOXHGCMSVCPARM aParms[]); + virtual ~Message(void); + + uint32_t GetParamCount(void) const RT_NOEXCEPT; + int GetData(uint32_t uMsg, uint32_t cParms, VBOXHGCMSVCPARM aParms[]) const RT_NOEXCEPT; + int GetParmU32(uint32_t uParm, uint32_t *pu32Info) const RT_NOEXCEPT; + int GetParmU64(uint32_t uParm, uint64_t *pu64Info) const RT_NOEXCEPT; + int GetParmPtr(uint32_t uParm, void **ppvAddr, uint32_t *pcbSize) const RT_NOEXCEPT; + uint32_t GetType(void) const RT_NOEXCEPT; + +public: + static int CopyParms(PVBOXHGCMSVCPARM paParmsDst, uint32_t cParmsDst, + PVBOXHGCMSVCPARM paParmsSrc, uint32_t cParmsSrc, + bool fDeepCopy) RT_NOEXCEPT; + +protected: + int initData(uint32_t uMsg, uint32_t cParms, VBOXHGCMSVCPARM aParms[]) RT_NOEXCEPT; + void reset() RT_NOEXCEPT; + +protected: + + /** Stored message type. */ + uint32_t m_uMsg; + /** Number of stored HGCM parameters. */ + uint32_t m_cParms; + /** Stored HGCM parameters. */ + PVBOXHGCMSVCPARM m_paParms; +}; + +/** + * Class for keeping and tracking a HGCM client. + */ +class Client +{ +public: + Client(uint32_t idClient); + virtual ~Client(void); + +public: + int Complete(VBOXHGCMCALLHANDLE hHandle, int rcOp = VINF_SUCCESS) RT_NOEXCEPT; + int CompleteDeferred(int rcOp = VINF_SUCCESS) RT_NOEXCEPT; + uint32_t GetClientID(void) const RT_NOEXCEPT; + VBOXHGCMCALLHANDLE GetHandle(void) const RT_NOEXCEPT; + uint32_t GetMsgType(void) const RT_NOEXCEPT; + uint32_t GetMsgParamCount(void) const RT_NOEXCEPT; + bool IsDeferred(void) const RT_NOEXCEPT; + void SetDeferred(VBOXHGCMCALLHANDLE hHandle, uint32_t u32Function, uint32_t cParms, VBOXHGCMSVCPARM paParms[]) RT_NOEXCEPT; + void SetSvcContext(const VBOXHGCMSVCTX &SvcCtx) RT_NOEXCEPT; + +public: + int SetDeferredMsgInfo(uint32_t uMsg, uint32_t cParms) RT_NOEXCEPT; + int SetDeferredMsgInfo(const Message *pMessage) RT_NOEXCEPT; + +protected: + int completeInternal(VBOXHGCMCALLHANDLE hHandle, int rcOp) RT_NOEXCEPT; + void reset(void) RT_NOEXCEPT; + +protected: + /** The client's HGCM client ID. */ + uint32_t m_idClient; + /** The HGCM service context this client is bound to. */ + VBOXHGCMSVCTX m_SvcCtx; + /** Flag indicating whether this client currently is deferred mode, + * meaning that it did not return to the caller yet. */ + bool m_fDeferred; + /** Structure for keeping the client's deferred state. + * A client is in a deferred state when it asks for the next HGCM message, + * but the service can't provide it yet. That way a client will block (on the guest side, does not return) + * until the service can complete the call. */ + struct + { + /** The client's HGCM call handle. Needed for completing a deferred call. */ + VBOXHGCMCALLHANDLE hHandle; + /** Message type (function number) to use when completing the deferred call. + * @todo r=bird: uType or uMsg? Make up your mind (Message::m_uMsg). */ + uint32_t uType; + /** Parameter count to use when completing the deferred call. */ + uint32_t cParms; + /** Parameters to use when completing the deferred call. */ + PVBOXHGCMSVCPARM paParms; + } m_Deferred; +}; + +template <class T> +class AbstractService : public RTCNonCopyable +{ +public: + /** + * @copydoc FNVBOXHGCMSVCLOAD + */ + static DECLCALLBACK(int) svcLoad(VBOXHGCMSVCFNTABLE *pTable) + { + LogFlowFunc(("ptable = %p\n", pTable)); + int rc = VINF_SUCCESS; + + if (!RT_VALID_PTR(pTable)) + rc = VERR_INVALID_PARAMETER; + else + { + LogFlowFunc(("ptable->cbSize = %d, ptable->u32Version = 0x%08X\n", pTable->cbSize, pTable->u32Version)); + + if ( pTable->cbSize != sizeof (VBOXHGCMSVCFNTABLE) + || pTable->u32Version != VBOX_HGCM_SVC_VERSION) + rc = VERR_VERSION_MISMATCH; + else + { + AbstractService *pService = NULL; + /* No exceptions may propagate outside (callbacks like this one are nothrow/noexcept). */ + try { pService = new T(pTable->pHelpers); } + catch (std::bad_alloc &) { rc = VERR_NO_MEMORY; } + catch (...) { rc = VERR_UNEXPECTED_EXCEPTION; } + if (RT_SUCCESS(rc)) + { + /* We don't need an additional client data area on the host, + because we're a class which can have members for that :-). */ + /** @todo r=bird: What the comment above says is that we can duplicate the + * work of associating data with a client ID already done by the HGCM and create + * additional bugs because we think that's cool. It's not. Utterly + * appalling as well as inefficient. Just a structure with a pointer to a + * client base class would go a long way here. */ + pTable->cbClient = 0; + + /* These functions are mandatory */ + pTable->pfnUnload = svcUnload; + pTable->pfnConnect = svcConnect; + pTable->pfnDisconnect = svcDisconnect; + pTable->pfnCall = svcCall; + /* Clear obligatory functions. */ + pTable->pfnHostCall = NULL; + pTable->pfnSaveState = NULL; + pTable->pfnLoadState = NULL; + pTable->pfnRegisterExtension = NULL; + + /* Let the service itself initialize. */ + rc = pService->init(pTable); + if (RT_SUCCESS(rc)) + pTable->pvService = pService; + else + delete pService; + } + } + } + + LogFlowFunc(("returning %Rrc\n", rc)); + return rc; + } + virtual ~AbstractService() {}; + +protected: + explicit AbstractService(PVBOXHGCMSVCHELPERS pHelpers) + { + RT_ZERO(m_SvcCtx); + m_SvcCtx.pHelpers = pHelpers; + } + virtual int init(VBOXHGCMSVCFNTABLE *ptable) RT_NOEXCEPT + { RT_NOREF1(ptable); return VINF_SUCCESS; } + virtual int uninit() RT_NOEXCEPT + { return VINF_SUCCESS; } + virtual int clientConnect(uint32_t idClient, void *pvClient) RT_NOEXCEPT = 0; + virtual int clientDisconnect(uint32_t idClient, void *pvClient) RT_NOEXCEPT = 0; + virtual void guestCall(VBOXHGCMCALLHANDLE callHandle, uint32_t idClient, void *pvClient, uint32_t eFunction, + uint32_t cParms, VBOXHGCMSVCPARM paParms[]) RT_NOEXCEPT = 0; + virtual int hostCall(uint32_t eFunction, uint32_t cParms, VBOXHGCMSVCPARM paParms[]) RT_NOEXCEPT + { RT_NOREF3(eFunction, cParms, paParms); return VINF_SUCCESS; } + + /** Type definition for use in callback functions. */ + typedef AbstractService SELF; + /** The HGCM service context this service is bound to. */ + VBOXHGCMSVCTX m_SvcCtx; + + /** + * @copydoc VBOXHGCMSVCFNTABLE::pfnUnload + * Simply deletes the service object + */ + static DECLCALLBACK(int) svcUnload(void *pvService) + { + AssertLogRelReturn(RT_VALID_PTR(pvService), VERR_INVALID_PARAMETER); + SELF *pSelf = reinterpret_cast<SELF *>(pvService); + int rc = pSelf->uninit(); + AssertRC(rc); + if (RT_SUCCESS(rc)) + delete pSelf; + return rc; + } + + /** + * @copydoc VBOXHGCMSVCFNTABLE::pfnConnect + * Stub implementation of pfnConnect and pfnDisconnect. + */ + static DECLCALLBACK(int) svcConnect(void *pvService, + uint32_t idClient, + void *pvClient, + uint32_t fRequestor, + bool fRestoring) + { + RT_NOREF(fRequestor, fRestoring); + AssertLogRelReturn(RT_VALID_PTR(pvService), VERR_INVALID_PARAMETER); + LogFlowFunc(("pvService=%p, idClient=%u, pvClient=%p\n", pvService, idClient, pvClient)); + SELF *pSelf = reinterpret_cast<SELF *>(pvService); + int rc = pSelf->clientConnect(idClient, pvClient); + LogFlowFunc(("rc=%Rrc\n", rc)); + return rc; + } + + /** + * @copydoc VBOXHGCMSVCFNTABLE::pfnConnect + * Stub implementation of pfnConnect and pfnDisconnect. + */ + static DECLCALLBACK(int) svcDisconnect(void *pvService, + uint32_t idClient, + void *pvClient) + { + AssertLogRelReturn(RT_VALID_PTR(pvService), VERR_INVALID_PARAMETER); + LogFlowFunc(("pvService=%p, idClient=%u, pvClient=%p\n", pvService, idClient, pvClient)); + SELF *pSelf = reinterpret_cast<SELF *>(pvService); + int rc = pSelf->clientDisconnect(idClient, pvClient); + LogFlowFunc(("rc=%Rrc\n", rc)); + return rc; + } + + /** + * @copydoc VBOXHGCMSVCFNTABLE::pfnCall + * Wraps to the call member function + */ + static DECLCALLBACK(void) svcCall(void *pvService, + VBOXHGCMCALLHANDLE callHandle, + uint32_t idClient, + void *pvClient, + uint32_t u32Function, + uint32_t cParms, + VBOXHGCMSVCPARM paParms[], + uint64_t tsArrival) + { + AssertLogRelReturnVoid(RT_VALID_PTR(pvService)); + LogFlowFunc(("pvService=%p, callHandle=%p, idClient=%u, pvClient=%p, u32Function=%u, cParms=%u, paParms=%p\n", + pvService, callHandle, idClient, pvClient, u32Function, cParms, paParms)); + SELF *pSelf = reinterpret_cast<SELF *>(pvService); + pSelf->guestCall(callHandle, idClient, pvClient, u32Function, cParms, paParms); + LogFlowFunc(("returning\n")); + RT_NOREF_PV(tsArrival); + } + + /** + * @copydoc VBOXHGCMSVCFNTABLE::pfnHostCall + * Wraps to the hostCall member function + */ + static DECLCALLBACK(int) svcHostCall(void *pvService, + uint32_t u32Function, + uint32_t cParms, + VBOXHGCMSVCPARM paParms[]) + { + AssertLogRelReturn(RT_VALID_PTR(pvService), VERR_INVALID_PARAMETER); + LogFlowFunc(("pvService=%p, u32Function=%u, cParms=%u, paParms=%p\n", pvService, u32Function, cParms, paParms)); + SELF *pSelf = reinterpret_cast<SELF *>(pvService); + int rc = pSelf->hostCall(u32Function, cParms, paParms); + LogFlowFunc(("rc=%Rrc\n", rc)); + return rc; + } + + /** + * @copydoc VBOXHGCMSVCFNTABLE::pfnRegisterExtension + * Installs a host callback for notifications of property changes. + */ + static DECLCALLBACK(int) svcRegisterExtension(void *pvService, + PFNHGCMSVCEXT pfnExtension, + void *pvExtension) + { + AssertLogRelReturn(RT_VALID_PTR(pvService), VERR_INVALID_PARAMETER); + LogFlowFunc(("pvService=%p, pfnExtension=%p, pvExtention=%p\n", pvService, pfnExtension, pvExtension)); + SELF *pSelf = reinterpret_cast<SELF *>(pvService); + pSelf->m_SvcCtx.pfnHostCallback = pfnExtension; + pSelf->m_SvcCtx.pvHostData = pvExtension; + return VINF_SUCCESS; + } + + DECLARE_CLS_COPY_CTOR_ASSIGN_NOOP(AbstractService); +}; + +} +#endif /* !VBOX_INCLUDED_HostServices_Service_h */ + diff --git a/include/VBox/HostServices/VBoxClipboardExt.h b/include/VBox/HostServices/VBoxClipboardExt.h new file mode 100644 index 00000000..2865da2d --- /dev/null +++ b/include/VBox/HostServices/VBoxClipboardExt.h @@ -0,0 +1,66 @@ +/** @file + * Shared Clipboard - Common header for the service extension. + */ + +/* + * Copyright (C) 2006-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 + */ + +#ifndef VBOX_INCLUDED_HostServices_VBoxClipboardExt_h +#define VBOX_INCLUDED_HostServices_VBoxClipboardExt_h +#ifndef RT_WITHOUT_PRAGMA_ONCE +# pragma once +#endif + +#include <VBox/types.h> +#ifdef VBOX_WITH_SHARED_CLIPBOARD_TRANSFERS +# include <VBox/GuestHost/SharedClipboard-transfers.h> +#endif + +#define VBOX_CLIPBOARD_EXT_FN_SET_CALLBACK (0) +#define VBOX_CLIPBOARD_EXT_FN_FORMAT_ANNOUNCE (1) +#define VBOX_CLIPBOARD_EXT_FN_DATA_READ (2) +#define VBOX_CLIPBOARD_EXT_FN_DATA_WRITE (3) + +typedef DECLCALLBACKTYPE(int, FNVRDPCLIPBOARDEXTCALLBACK,(uint32_t u32Function, uint32_t u32Format, void *pvData, uint32_t cbData)); +typedef FNVRDPCLIPBOARDEXTCALLBACK *PFNVRDPCLIPBOARDEXTCALLBACK; + +typedef struct _SHCLEXTPARMS +{ + uint32_t uFormat; + union + { + void *pvData; + PFNVRDPCLIPBOARDEXTCALLBACK pfnCallback; + } u; + uint32_t cbData; +} SHCLEXTPARMS; + +#endif /* !VBOX_INCLUDED_HostServices_VBoxClipboardExt_h */ diff --git a/include/VBox/HostServices/VBoxClipboardSvc.h b/include/VBox/HostServices/VBoxClipboardSvc.h new file mode 100644 index 00000000..72184711 --- /dev/null +++ b/include/VBox/HostServices/VBoxClipboardSvc.h @@ -0,0 +1,1220 @@ +/** @file + * Shared Clipboard - Common header for host service and guest clients. + * + * Protocol history notes (incomplete): + * + * - VirtualBox 6.1.0 betas: Started work on adding support for copying & + * pasting files and directories, refactoring the protocol in the process. + * - Adds guest/host feature flags. + * - Adds context IDs (via guest feature flags). + * - Borrowed the message handling from guest controls. + * - Adds a multitude of functions and messages for dealing with file & dir + * copying, most inte + * + * - VirtualBox x.x.x: Missing a lot of gradual improvements here. + * + * - VirtualBox 1.3.2 (r17182): Initial implementation, supporting text. + */ + +/* + * Copyright (C) 2006-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 + */ + +#ifndef VBOX_INCLUDED_HostServices_VBoxClipboardSvc_h +#define VBOX_INCLUDED_HostServices_VBoxClipboardSvc_h +#ifndef RT_WITHOUT_PRAGMA_ONCE +# pragma once +#endif + +#include <VBox/VMMDevCoreTypes.h> +#include <VBox/VBoxGuestCoreTypes.h> +#include <VBox/hgcmsvc.h> + + +/** @name VBOX_SHCL_MODE_XXX - The Shared Clipboard modes of operation. + * @{ + */ +/** Shared Clipboard is disabled completely. */ +#define VBOX_SHCL_MODE_OFF 0 +/** Only transfers from host to the guest are possible. */ +#define VBOX_SHCL_MODE_HOST_TO_GUEST 1 +/** Only transfers from guest to the host are possible. */ +#define VBOX_SHCL_MODE_GUEST_TO_HOST 2 +/** Bidirectional transfers between guest and host are possible. */ +#define VBOX_SHCL_MODE_BIDIRECTIONAL 3 +/** @} */ + +/** @name VBOX_SHCL_TRANSFER_MODE_XXX - The Shared Clipboard file transfer mode (bit field). + * @{ + */ +/** Shared Clipboard file transfers are disabled. */ +#define VBOX_SHCL_TRANSFER_MODE_DISABLED UINT32_C(0) +/** Shared Clipboard file transfers are enabled. */ +#define VBOX_SHCL_TRANSFER_MODE_ENABLED RT_BIT(0) +/** Shared Clipboard file transfer mode valid mask. */ +#define VBOX_SHCL_TRANSFER_MODE_VALID_MASK UINT32_C(0x1) +/** @} */ + + +/** @name VBOX_SHCL_HOST_FN_XXX - The service functions which are callable by host. + * @note These are not sacred and can be modified at will as long as all host + * clients are updated accordingly (probably just Main). + * @{ + */ +/** Sets the current Shared Clipboard operation mode. */ +#define VBOX_SHCL_HOST_FN_SET_MODE 1 +/** Sets the current Shared Clipboard (file) transfers mode. + * Operates on the VBOX_SHCL_TRANSFERS_XXX defines. + * @since 6.1 */ +#define VBOX_SHCL_HOST_FN_SET_TRANSFER_MODE 2 +/** Run headless on the host, i.e. do not touch the host clipboard. */ +#define VBOX_SHCL_HOST_FN_SET_HEADLESS 3 + +/** Reports cancellation of the current operation to the guest. + * @since 6.1 - still a todo */ +#define VBOX_SHCL_HOST_FN_CANCEL 4 +/** Reports an error to the guest. + * @since 6.1 - still a todo */ +#define VBOX_SHCL_HOST_FN_ERROR 5 +/** @} */ + + +/** @name VBOX_SHCL_HOST_MSG_XXX - The host messages for the guest. + * @{ + */ +/** Returned only when the HGCM client session is closed (by different thread). + * + * This can require no futher host interaction since the session has been + * closed. + * + * @since 1.3.2 + */ +#define VBOX_SHCL_HOST_MSG_QUIT 1 +/** Request data for a specific format from the guest. + * + * Two parameters, first the 32-bit message ID followed by a 32-bit format bit + * (VBOX_SHCL_FMT_XXX). The guest will respond by issuing a + * VBOX_SHCL_GUEST_FN_DATA_WRITE. + * + * @note The host may sometimes incorrectly set more than one format bit, in + * which case it's up to the guest to pick which to write back. + * @since 1.3.2 + */ +#define VBOX_SHCL_HOST_MSG_READ_DATA 2 +/** Reports available clipboard format on the host to the guest. + * + * Two parameters, first the 32-bit message ID followed by a 32-bit format mask + * containing zero or more VBOX_SHCL_FMT_XXX flags. The guest is not require to + * respond to the host when receiving this message. + * + * @since 1.3.2 + */ +#define VBOX_SHCL_HOST_MSG_FORMATS_REPORT 3 +/** Message PEEK or GET operation was canceled, try again. + * + * This is returned by VBOX_SHCL_GUEST_FN_MSG_PEEK_WAIT and + * VBOX_SHCL_GUEST_FN_MSG_OLD_GET_WAIT in response to the guest calling + * VBOX_SHCL_GUEST_FN_MSG_CANCEL. The 2nd parameter is set to zero (be it + * thought of as a parameter count or a format mask). + * + * @since 6.1.0 + */ +#define VBOX_SHCL_HOST_MSG_CANCELED 4 + +/** Request data for a specific format from the guest with context ID. + * + * This is send instead of the VBOX_SHCL_HOST_MSG_READ_DATA message to guest + * that advertises VBOX_SHCL_GF_0_CONTEXT_ID. The first parameter is a 64-bit + * context ID which is to be used when issuing VBOX_SHCL_GUEST_F_DATA_WRITE, and + * the second parameter is a 32-bit format bit (VBOX_SHCL_FMT_XXX). The guest + * will respond by issuing a VBOX_SHCL_GUEST_F_DATA_WRITE. + * + * @note The host may sometimes incorrectly set more than one format bit, in + * which case it's up to the guest to pick which to write back. + * @since 6.1.2 + */ +#define VBOX_SHCL_HOST_MSG_READ_DATA_CID 5 + +/** Sends a transfer status to the guest side. + * @since 6.1.? + */ +#define VBOX_SHCL_HOST_MSG_TRANSFER_STATUS 50 +/** Reads the root list header from the guest. + * @since 6.1.? + */ +#define VBOX_SHCL_HOST_MSG_TRANSFER_ROOT_LIST_HDR_READ 51 +/** Writes the root list header to the guest. + * @since 6.1.? + */ +#define VBOX_SHCL_HOST_MSG_TRANSFER_ROOT_LIST_HDR_WRITE 52 +/** Reads a root list entry from the guest. + * @since 6.1.? + */ +#define VBOX_SHCL_HOST_MSG_TRANSFER_ROOT_LIST_ENTRY_READ 53 +/** Writes a root list entry to the guest. + * @since 6.1.? + */ +#define VBOX_SHCL_HOST_MSG_TRANSFER_ROOT_LIST_ENTRY_WRITE 54 +/** Open a transfer list on the guest side. + * @since 6.1.? + */ +#define VBOX_SHCL_HOST_MSG_TRANSFER_LIST_OPEN 55 +/** Closes a formerly opened transfer list on the guest side. + * @since 6.1.? + */ +#define VBOX_SHCL_HOST_MSG_TRANSFER_LIST_CLOSE 56 +/** Reads a list header from the guest. + * @since 6.1.? + */ +#define VBOX_SHCL_HOST_MSG_TRANSFER_LIST_HDR_READ 57 +/** Writes a list header to the guest. + * @since 6.1.? + */ +#define VBOX_SHCL_HOST_MSG_TRANSFER_LIST_HDR_WRITE 58 +/** Reads a list entry from the guest. + * @since 6.1.? + */ +#define VBOX_SHCL_HOST_MSG_TRANSFER_LIST_ENTRY_READ 59 +/** Writes a list entry to the guest. + * @since 6.1.? + */ +#define VBOX_SHCL_HOST_MSG_TRANSFER_LIST_ENTRY_WRITE 60 +/** Open a transfer object on the guest side. + * @since 6.1.? + */ +#define VBOX_SHCL_HOST_MSG_TRANSFER_OBJ_OPEN 61 +/** Closes a formerly opened transfer object on the guest side. + * @since 6.1.? + */ +#define VBOX_SHCL_HOST_MSG_TRANSFER_OBJ_CLOSE 62 +/** Reads from an object on the guest side. + * @since 6.1.? + */ +#define VBOX_SHCL_HOST_MSG_TRANSFER_OBJ_READ 63 +/** Writes to an object on the guest side. + * @since 6.1.? + */ +#define VBOX_SHCL_HOST_MSG_TRANSFER_OBJ_WRITE 64 +/** Indicates that the host has canceled a transfer. + * @since 6.1.? + */ +#define VBOX_SHCL_HOST_MSG_TRANSFER_CANCEL 65 +/** Indicates that the an unrecoverable error on the host occurred. + * @since 6.1.? + */ +#define VBOX_SHCL_HOST_MSG_TRANSFER_ERROR 66 +/** @} */ + + +/** @name VBOX_SHCL_GUEST_FN_XXX - The service functions which are called by guest. + * @{ + */ +/** Calls the host and waits (blocking) for an host event VBOX_SHCL_HOST_MSG_XXX. + * + * @deprecated Replaced by VBOX_SHCL_GUEST_FN_MSG_PEEK_WAIT, + * VBOX_SHCL_GUEST_FN_MSG_GET, VBOX_SHCL_GUEST_FN_MSG_CANCEL. + * @since 1.3.2 + */ +#define VBOX_SHCL_GUEST_FN_MSG_OLD_GET_WAIT 1 +/** Sends a list of available formats to the host. + * + * This function takes a single parameter, a 32-bit set of formats + * (VBOX_SHCL_FMT_XXX), this can be zero if the clipboard is empty or previously + * reported formats are no longer avaible (logout, shutdown, whatever). + * + * There was a period during 6.1 development where it would take three + * parameters, a 64-bit context ID preceeded the formats and a 32-bit MBZ flags + * parameter was appended. This is still accepted, though deprecated. + * + * @returns May return informational statuses indicating partial success, just + * ignore it. + * @retval VINF_SUCCESS on success. + * @retval VERR_INVALID_CLIENT_ID + * @retval VERR_WRONG_PARAMETER_COUNT + * @retval VERR_WRONG_PARAMETER_TYPE + * @retval VERR_NOT_SUPPORTED if all the formats are unsupported, host + * clipboard will be empty. + * @since 1.3.2 + */ +#define VBOX_SHCL_GUEST_FN_REPORT_FORMATS 2 +/** Reads data in specified format from the host. + * + * This function takes three parameters, a 32-bit format bit + * (VBOX_SHCL_FMT_XXX), a buffer and 32-bit number of bytes read (output). + * + * There was a period during 6.1 development where it would take five parameters + * when VBOX_SHCL_GF_0_CONTEXT_ID was reported by the guest. A 64-bit context + * ID (ignored as purpose undefined), a 32-bit unused flag (MBZ), then the + * 32-bit format bits, number of bytes read (output), and the buffer. This + * format is still accepted. + * + * @retval VINF_SUCCESS on success. + * @retval VINF_BUFFER_OVERLFLOW (VBox >= 6.1 only) if not enough buffer space + * has been given to retrieve the actual data, no data actually copied. + * The call then must be repeated with a buffer size returned from the + * host in cbData. + * @retval VERR_INVALID_CLIENT_ID + * @retval VERR_WRONG_PARAMETER_COUNT + * @retval VERR_WRONG_PARAMETER_TYPE + * @since 1.3.2 + */ +#define VBOX_SHCL_GUEST_FN_DATA_READ 3 +/** Writes requested data to the host. + * + * This function takes either 2 or 3 parameters. The last two parameters are a + * 32-bit format bit (VBOX_SHCL_FMT_XXX) and a data buffer holding the related + * data. The three parameter variant have a context ID first, which shall be a + * copy of the ID in the data request message. + * + * There was a period during 6.1 development where there would be a 5 parameter + * version of this, inserting an unused flags parameter between the context ID + * and the format bit, as well as a 32-bit data buffer size repate between the + * format bit and the data buffer. This format is still accepted, though + * deprecated. + * + * @retval VINF_SUCCESS on success. + * @retval VERR_INVALID_CLIENT_ID + * @retval VERR_WRONG_PARAMETER_COUNT + * @retval VERR_WRONG_PARAMETER_TYPE + * @retval VERR_INVALID_CONTEXT if the context ID didn't match up. + * @since 1.3.2 + */ +#define VBOX_SHCL_GUEST_FN_DATA_WRITE 4 + +/** This is a left-over from the 6.1 dev cycle and will always fail. + * + * It used to take three 32-bit parameters, only one of which was actually used. + * + * It was replaced by VBOX_SHCL_GUEST_FN_REPORT_FEATURES and + * VBOX_SHCL_GUEST_FN_NEGOTIATE_CHUNK_SIZE. + * + * @retval VERR_NOT_IMPLEMENTED + * @since 6.1 + */ +#define VBOX_SHCL_GUEST_FN_CONNECT 5 +/** 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_SHCL_GF_XXX), the host replies by replacing the parameter values with + * the host ones (VBOX_SHCL_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.0 + */ +#define VBOX_SHCL_GUEST_FN_REPORT_FEATURES 6 +/** 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.0 + */ +#define VBOX_SHCL_GUEST_FN_QUERY_FEATURES 7 +/** Peeks at the next message, returning immediately. + * + * Returns two 32-bit parameters, first is the message ID and the second the + * parameter count. May optionally return additional 32-bit parameters with the + * sizes of respective message parameters. To distinguish buffer sizes from + * integer parameters, the latter gets their sizes inverted (uint32_t is ~4U, + * uint64_t is ~8U). + * + * Does also support the VM restore checking as in VBOX_SHCL_GUEST_FN_MSG_PEEK_WAIT + * (64-bit param \# 0), see documentation there. + * + * @retval VINF_SUCCESS if a message was pending and is being returned. + * @retval VERR_TRY_AGAIN if no message pending. + * @retval VERR_VM_RESTORED if first parameter is a non-zero 64-bit value that + * does not match VbglR3GetSessionId() any more. The new value is + * returned. + * @retval VERR_INVALID_CLIENT_ID + * @retval VERR_WRONG_PARAMETER_COUNT + * @retval VERR_WRONG_PARAMETER_TYPE + * @since 6.1.0 + */ +#define VBOX_SHCL_GUEST_FN_MSG_PEEK_NOWAIT 8 +/** Peeks at the next message, waiting for one to arrive. + * + * Returns two 32-bit parameters, first is the message ID and the second the + * parameter count. May optionally return additional 32-bit parameters with the + * sizes of respective message parameters. To distinguish buffer sizes from + * integer parameters, the latter gets their sizes inverted (uint32_t is ~4U, + * uint64_t is ~8U). + * + * To facilitate VM restore checking, the first parameter can be a 64-bit + * integer holding the VbglR3GetSessionId() value the guest knowns. The + * function will then check this before going to sleep and return + * VERR_VM_RESTORED if it doesn't match, same thing happens when the VM is + * restored. + * + * @retval VINF_SUCCESS if info about an pending message is being returned. + * @retval VINF_TRY_AGAIN and message set to VBOX_SHCL_HOST_MSG_CANCELED if + * cancelled by VBOX_SHCL_GUEST_FN_MSG_CANCEL. + * @retval VERR_RESOURCE_BUSY if another thread already made a waiting call. + * @retval VERR_VM_RESTORED if first parameter is a non-zero 64-bit value that + * does not match VbglR3GetSessionId() any more. The new value is + * returned. + * @retval VERR_INVALID_CLIENT_ID + * @retval VERR_WRONG_PARAMETER_COUNT + * @retval VERR_WRONG_PARAMETER_TYPE + * @note This replaces VBOX_SHCL_GUEST_FN_MSG_OLD_GET_WAIT. + * @since 6.1.0 + */ +#define VBOX_SHCL_GUEST_FN_MSG_PEEK_WAIT 9 +/** Gets the next message, returning immediately. + * + * All parameters are specific to the message being retrieved, however if the + * first one is an integer value it shall be an input parameter holding the + * ID of the message being retrieved. While it would be nice to add a separate + * parameter for this purpose, this is done so because the code was liften from + * Guest Controls which had backwards compatibilities to consider and we just + * kept it like that. + * + * @retval VINF_SUCCESS if message retrieved and removed from the pending queue. + * @retval VERR_TRY_AGAIN if no message pending. + * @retval VERR_MISMATCH if the incoming message ID does not match the pending. + * @retval VERR_BUFFER_OVERFLOW if a parmeter buffer is too small. The buffer + * size was updated to reflect the required size. + * @retval VERR_INVALID_CLIENT_ID + * @retval VERR_WRONG_PARAMETER_COUNT + * @retval VERR_WRONG_PARAMETER_TYPE + * @note This replaces VBOX_SHCL_GUEST_FN_MSG_OLD_GET_WAIT. + * @since 6.1.0 + */ +#define VBOX_SHCL_GUEST_FN_MSG_GET 10 +/** Cancels pending calls for this client session. + * + * This should be used if a VBOX_SHCL_GUEST_FN__MSG_PEEK_WAIT or + * VBOX_SHCL_GUEST_FN_MSG_OLD_GET_WAIT call gets interrupted on the client end, + * so as to prevent being rebuffed with VERR_RESOURCE_BUSY when restarting the + * call. + * + * @retval VINF_SUCCESS if cancelled any calls. + * @retval VWRN_NOT_FOUND if no callers. + * @retval VERR_INVALID_CLIENT_ID + * @retval VERR_WRONG_PARAMETER_COUNT + * @since 6.1.0 + */ +#define VBOX_SHCL_GUEST_FN_MSG_CANCEL 26 + +/** Replies to a function from the host. + * + * @retval VINF_SUCCESS on success. + * @retval VERR_INVALID_CLIENT_ID + * @retval VERR_WRONG_PARAMETER_COUNT + * @retval VERR_WRONG_PARAMETER_TYPE + * @since 6.1.x + */ +#define VBOX_SHCL_GUEST_FN_REPLY 11 +/** Gets the root list header from the host. + * + * @retval VINF_SUCCESS on success. + * @retval VERR_INVALID_CLIENT_ID + * @retval VERR_WRONG_PARAMETER_COUNT + * @retval VERR_WRONG_PARAMETER_TYPE + * @since 6.1.x + */ +#define VBOX_SHCL_GUEST_FN_ROOT_LIST_HDR_READ 12 +/** Sends the root list header to the host. + * + * @retval VINF_SUCCESS on success. + * @retval VERR_INVALID_CLIENT_ID + * @retval VERR_WRONG_PARAMETER_COUNT + * @retval VERR_WRONG_PARAMETER_TYPE + * @since 6.1.x + */ +#define VBOX_SHCL_GUEST_FN_ROOT_LIST_HDR_WRITE 13 +/** Gets a root list root entry from the host. + * + * @retval VINF_SUCCESS on success. + * @retval VERR_INVALID_CLIENT_ID + * @retval VERR_WRONG_PARAMETER_COUNT + * @retval VERR_WRONG_PARAMETER_TYPE + * @since 6.1.x + */ +#define VBOX_SHCL_GUEST_FN_ROOT_LIST_ENTRY_READ 14 +/** Sends a root list root entry to the host. + * + * @retval VINF_SUCCESS on success. + * @retval VERR_INVALID_CLIENT_ID + * @retval VERR_WRONG_PARAMETER_COUNT + * @retval VERR_WRONG_PARAMETER_TYPE + * @since 6.1.x + */ +#define VBOX_SHCL_GUEST_FN_ROOT_LIST_ENTRY_WRITE 15 +/** Opens / gets a list handle from the host. + * + * @retval VINF_SUCCESS on success. + * @retval VERR_INVALID_CLIENT_ID + * @retval VERR_WRONG_PARAMETER_COUNT + * @retval VERR_WRONG_PARAMETER_TYPE + * @since 6.1.x + */ +#define VBOX_SHCL_GUEST_FN_LIST_OPEN 16 +/** Closes a list handle from the host. + * + * @retval VINF_SUCCESS on success. + * @retval VERR_INVALID_CLIENT_ID + * @retval VERR_WRONG_PARAMETER_COUNT + * @retval VERR_WRONG_PARAMETER_TYPE + * @since 6.1.x + */ +#define VBOX_SHCL_GUEST_FN_LIST_CLOSE 17 +/** Reads a list header from the host. + * + * @retval VINF_SUCCESS on success. + * @retval VERR_INVALID_CLIENT_ID + * @retval VERR_WRONG_PARAMETER_COUNT + * @retval VERR_WRONG_PARAMETER_TYPE + * @since 6.1.x + */ +#define VBOX_SHCL_GUEST_FN_LIST_HDR_READ 18 +/** Writes a list header to the host. + * + * @retval VINF_SUCCESS on success. + * @retval VERR_INVALID_CLIENT_ID + * @retval VERR_WRONG_PARAMETER_COUNT + * @retval VERR_WRONG_PARAMETER_TYPE + * @since 6.1.x + */ +#define VBOX_SHCL_GUEST_FN_LIST_HDR_WRITE 19 +/** Reads a list entry from the host. + * + * @retval VINF_SUCCESS on success. + * @retval VERR_INVALID_CLIENT_ID + * @retval VERR_WRONG_PARAMETER_COUNT + * @retval VERR_WRONG_PARAMETER_TYPE + * @since 6.1.x + */ +#define VBOX_SHCL_GUEST_FN_LIST_ENTRY_READ 20 +/** Sends a list entry to the host. + * + * @retval VINF_SUCCESS on success. + * @retval VERR_INVALID_CLIENT_ID + * @retval VERR_WRONG_PARAMETER_COUNT + * @retval VERR_WRONG_PARAMETER_TYPE + * @since 6.1.x + */ +#define VBOX_SHCL_GUEST_FN_LIST_ENTRY_WRITE 21 +/** Opens an object on the host. + * + * @retval VINF_SUCCESS on success. + * @retval VERR_INVALID_CLIENT_ID + * @retval VERR_WRONG_PARAMETER_COUNT + * @retval VERR_WRONG_PARAMETER_TYPE + * @since 6.1.x + */ +#define VBOX_SHCL_GUEST_FN_OBJ_OPEN 22 +/** Closes an object on the host. + * + * @retval VINF_SUCCESS on success. + * @retval VERR_INVALID_CLIENT_ID + * @retval VERR_WRONG_PARAMETER_COUNT + * @retval VERR_WRONG_PARAMETER_TYPE + * @since 6.1.x + */ +#define VBOX_SHCL_GUEST_FN_OBJ_CLOSE 23 +/** Reads from an object on the host. + * + * @retval VINF_SUCCESS on success. + * @retval VERR_INVALID_CLIENT_ID + * @retval VERR_WRONG_PARAMETER_COUNT + * @retval VERR_WRONG_PARAMETER_TYPE + * @since 6.1.x + */ +#define VBOX_SHCL_GUEST_FN_OBJ_READ 24 +/** Writes to an object on the host. + * + * @retval VINF_SUCCESS on success. + * @retval VERR_INVALID_CLIENT_ID + * @retval VERR_WRONG_PARAMETER_COUNT + * @retval VERR_WRONG_PARAMETER_TYPE + * @since 6.1.x + */ +#define VBOX_SHCL_GUEST_FN_OBJ_WRITE 25 +/** Reports an error to the host. + * + * @todo r=bird: Smells like GUEST_MSG_SKIP + * + * @retval VINF_SUCCESS on success. + * @retval VERR_INVALID_CLIENT_ID + * @retval VERR_WRONG_PARAMETER_COUNT + * @retval VERR_WRONG_PARAMETER_TYPE + * @since 6.1 + */ +#define VBOX_SHCL_GUEST_FN_ERROR 27 + +/** For negotiating a chunk size between the guest and host. + * + * Takes two 32-bit parameters both being byte counts, the first one gives the + * maximum chunk size the guest can handle and the second the preferred choice + * of the guest. Upon return, the host will have updated both of them to + * reflect the maximum and default chunk sizes this client connect. The guest + * may set the 2nd value to zero and let the host choose. + * + * @retval VINF_SUCCESS on success. + * @retval VERR_INVALID_CLIENT_ID + * @retval VERR_WRONG_PARAMETER_COUNT + * @retval VERR_WRONG_PARAMETER_TYPE + * @retval VERR_INVALID_PARAMETER if the 2nd parameter is larger than the + * first one + * @since 6.1 + */ +#define VBOX_SHCL_GUEST_FN_NEGOTIATE_CHUNK_SIZE 28 + +/** The last function number (used for validation/sanity). */ +#define VBOX_SHCL_GUEST_FN_LAST VBOX_SHCL_GUEST_FN_NEGOTIATE_CHUNK_SIZE +/** @} */ + + +/** Maximum chunk size for a single data transfer. */ +#define VBOX_SHCL_MAX_CHUNK_SIZE VMMDEV_MAX_HGCM_DATA_SIZE - _4K +/** Default chunk size for a single data transfer. */ +#define VBOX_SHCL_DEFAULT_CHUNK_SIZE RT_MIN(_64K, VBOX_SHCL_MAX_CHUNK_SIZE); + + +/** @name VBOX_SHCL_GF_XXX - Guest features. + * @sa VBOX_SHCL_GUEST_FN_REPORT_FEATURES + * @{ */ +/** No flags set. */ +#define VBOX_SHCL_GF_NONE 0 +/** The guest can handle context IDs where applicable. */ +#define VBOX_SHCL_GF_0_CONTEXT_ID RT_BIT_64(0) +/** The guest can copy & paste files and directories. + * @since 6.x */ +#define VBOX_SHCL_GF_0_TRANSFERS RT_BIT_64(1) +/** The guest supports a (guest OS-)native frontend for showing and handling file transfers. + * If not set, the host will show a modal progress dialog instead and transferring file to + * a guest-specific temporary location first. + * Currently only supported for Windows guests (integrated into Windows Explorer via IDataObject). */ +#define VBOX_SHCL_GF_0_TRANSFERS_FRONTEND RT_BIT_64(2) +/** Bit that must be set in the 2nd parameter, will be cleared if the host reponds + * correctly (old hosts might not). */ +#define VBOX_SHCL_GF_1_MUST_BE_ONE RT_BIT_64(63) +/** @} */ + +/** @name VBOX_GUESTCTRL_HF_XXX - Host features. + * @sa VBOX_SHCL_GUEST_FN_REPORT_FEATURES + * @{ */ +/** No flags set. */ +#define VBOX_SHCL_HF_NONE 0 +/** The host can handle context IDs where applicable as well as the new + * message handling functions. */ +#define VBOX_SHCL_HF_0_CONTEXT_ID RT_BIT_64(0) +/** The host can copy & paste files and directories. + * This includes messages like + * @since 6.1.? */ +#define VBOX_SHCL_HF_0_TRANSFERS RT_BIT_64(1) +/** @} */ + +/** @name Context ID related macros and limits + * @{ */ +/** + * Creates a context ID out of a client ID, a transfer ID and an event ID (count). + */ +#define VBOX_SHCL_CONTEXTID_MAKE(a_idSession, a_idTransfer, a_idEvent) \ + ( ((uint64_t)((a_idSession) & 0xffff) << 48) \ + | ((uint64_t)((a_idTransfer) & 0xffff) << 32) \ + | ((uint32_t) (a_idEvent)) \ + ) +/** Creates a context ID out of a session ID. */ +#define VBOX_SHCL_CONTEXTID_MAKE_SESSION(a_idSession) VBOX_SHCL_CONTEXTID_MAKE(a_idSession, 0, 0) +/** Gets the session ID out of a context ID. */ +#define VBOX_SHCL_CONTEXTID_GET_SESSION(a_idContext) ( (uint16_t)(((a_idContext) >> 48) & UINT16_MAX) ) +/** Gets the transfer ID out of a context ID. */ +#define VBOX_SHCL_CONTEXTID_GET_TRANSFER(a_idContext) ( (uint16_t)(((a_idContext) >> 32) & UINT16_MAX) ) +/** Gets the transfer event out of a context ID. */ +#define VBOX_SHCL_CONTEXTID_GET_EVENT(a_idContext) ( (uint32_t)( (a_idContext) & UINT32_MAX) ) + +/** Maximum number of concurrent Shared Clipboard client sessions a VM can have. */ +#define VBOX_SHCL_MAX_SESSIONS (UINT16_MAX - 1) +/** Maximum number of concurrent Shared Clipboard transfers a single client can have. */ +#define VBOX_SHCL_MAX_TRANSFERS (UINT16_MAX - 1) +/** Maximum number of events a single Shared Clipboard transfer can have. */ +#define VBOX_SHCL_MAX_EVENTS (UINT32_MAX - 1) +/** @} */ + + +/* + * HGCM parameter structures. + */ +/** @todo r=bird: These structures are mostly pointless, as they're only + * ever used by the VbglR3 part. The host service does not use these + * structures for decoding guest requests, instead it's all hardcoded. */ +#pragma pack(1) +/** + * Waits (blocking) for a new host message to arrive. + * Deprecated; do not use anymore. + * Kept for maintaining compatibility with older Guest Additions. + */ +typedef struct _VBoxShClGetHostMsgOld +{ + VBGLIOCHGCMCALL hdr; + + /** uint32_t, out: Host message type. */ + HGCMFunctionParameter msg; + /** uint32_t, out: VBOX_SHCL_FMT_*, depends on the 'msg'. + * r=andy This actual can have *different* meanings, depending on the host message type. */ + HGCMFunctionParameter formats; /* OUT uint32_t */ +} VBoxShClGetHostMsgOld; + +#define VBOX_SHCL_CPARMS_GET_HOST_MSG_OLD 2 + +/** @name VBOX_SHCL_GUEST_FN_REPORT_FORMATS + * @{ */ +/** VBOX_SHCL_GUEST_FN_REPORT_FORMATS parameters. */ +typedef struct VBoxShClParmReportFormats +{ + /** uint32_t, int: Zero or more VBOX_SHCL_FMT_XXX bits. */ + HGCMFunctionParameter f32Formats; +} VBoxShClParmReportFormats; + +#define VBOX_SHCL_CPARMS_REPORT_FORMATS 1 /**< The parameter count for VBOX_SHCL_GUEST_FN_REPORT_FORMATS. */ +#define VBOX_SHCL_CPARMS_REPORT_FORMATS_61B 3 /**< The 6.1 dev cycle variant, see VBOX_SHCL_GUEST_FN_REPORT_FORMATS. */ +/** @} */ + +/** @name VBOX_SHCL_GUEST_FN_DATA_READ + * @{ */ +/** VBOX_SHCL_GUEST_FN_DATA_READ parameters. */ +typedef struct VBoxShClParmDataRead +{ + /** uint32_t, in: Requested format (VBOX_SHCL_FMT_XXX). */ + HGCMFunctionParameter f32Format; + /** ptr, out: The data buffer to put the data in on success. */ + HGCMFunctionParameter pData; + /** uint32_t, out: Size of returned data, if larger than the buffer, then no + * data was actually transferred and the guest must repeat the call. */ + HGCMFunctionParameter cb32Needed; +} VBoxShClParmDataRead; + +#define VBOX_SHCL_CPARMS_DATA_READ 3 /**< The parameter count for VBOX_SHCL_GUEST_FN_DATA_READ. */ +#define VBOX_SHCL_CPARMS_DATA_READ_61B 5 /**< The 6.1 dev cycle variant, see VBOX_SHCL_GUEST_FN_DATA_READ. */ +/** @} */ + +/** @name + * @{ */ + +/** VBOX_SHCL_GUEST_FN_DATA_WRITE parameters. */ +typedef struct VBoxShClParmDataWrite +{ + /** uint64_t, in: Context ID from VBOX_SHCL_HOST_MSG_READ_DATA. */ + HGCMFunctionParameter id64Context; + /** uint32_t, in: The data format (VBOX_SHCL_FMT_XXX). */ + HGCMFunctionParameter f32Format; + /** ptr, in: The data. */ + HGCMFunctionParameter pData; +} VBoxShClParmDataWrite; + +/** Old VBOX_SHCL_GUEST_FN_DATA_WRITE parameters. */ +typedef struct VBoxShClParmDataWriteOld +{ + /** uint32_t, in: The data format (VBOX_SHCL_FMT_XXX). */ + HGCMFunctionParameter f32Format; + /** ptr, in: The data. */ + HGCMFunctionParameter pData; +} VBoxShClParmDataWriteOld; + +#define VBOX_SHCL_CPARMS_DATA_WRITE 3 /**< The variant used when VBOX_SHCL_GF_0_CONTEXT_ID is reported. */ +#define VBOX_SHCL_CPARMS_DATA_WRITE_OLD 2 /**< The variant used when VBOX_SHCL_GF_0_CONTEXT_ID isn't reported. */ +#define VBOX_SHCL_CPARMS_DATA_WRITE_61B 5 /**< The 6.1 dev cycle variant, see VBOX_SHCL_GUEST_FN_DATA_WRITE. */ +/** @} */ + +/** + * Reports a transfer status. + */ +typedef struct _VBoxShClTransferStatusMsg +{ + VBGLIOCHGCMCALL hdr; + + /** uint64_t, out: Context ID. */ + HGCMFunctionParameter uContext; + /** uint32_t, out: Direction of transfer; of type SHCLTRANSFERDIR_. */ + HGCMFunctionParameter enmDir; + /** uint32_t, out: Status to report; of type SHCLTRANSFERSTATUS_. */ + HGCMFunctionParameter enmStatus; + /** uint32_t, out: Result code to report. Optional. */ + HGCMFunctionParameter rc; + /** uint32_t, out: Reporting flags. Currently unused and must be 0. */ + HGCMFunctionParameter fFlags; +} VBoxShClTransferStatusMsg; + +#define VBOX_SHCL_CPARMS_TRANSFER_STATUS 5 + +/** + * Asks the host for the next command to process, along + * with the needed amount of parameters and an optional blocking + * flag. + * + * Used by: VBOX_SHCL_GUEST_FN_GET_HOST_MSG + * + */ +typedef struct _VBoxShClGetHostMsg +{ + VBGLIOCHGCMCALL hdr; + + /** uint32_t, out: Message ID. */ + HGCMFunctionParameter uMsg; + /** uint32_t, out: Number of parameters the message needs. */ + HGCMFunctionParameter cParms; + /** uint32_t, in: Whether or not to block (wait) for a new message to arrive. */ + HGCMFunctionParameter fBlock; +} VBoxShClPeekMsg; + +#define VBOX_SHCL_CPARMS_GET_HOST_MSG 3 + +/** No listing flags specified. */ +#define VBOX_SHCL_LIST_FLAG_NONE 0 +/** Only returns one entry per read. */ +#define VBOX_SHCL_LIST_FLAG_RETURN_ONE RT_BIT(0) +/** Restarts reading a list from the beginning. */ +#define VBOX_SHCL_LIST_FLAG_RESTART RT_BIT(1) + +#define VBOX_SHCL_LISTHDR_FLAG_NONE 0 + +/** No additional information provided. */ +#define VBOX_SHCL_INFO_FLAG_NONE 0 +/** Get object information of type SHCLFSOBJINFO. */ +#define VBOX_SHCL_INFO_FLAG_FSOBJINFO RT_BIT(0) + +/** + * Status message for lists and objects. + */ +typedef struct _VBoxShClStatusMsg +{ + VBGLIOCHGCMCALL hdr; + + /** uint64_t, in: Context ID. */ + HGCMFunctionParameter uContext; + /** uint32_t, in: Transfer status of type SHCLTRANSFERSTATUS. */ + HGCMFunctionParameter uStatus; + /** pointer, in: Optional payload of this status, based on the status type. */ + HGCMFunctionParameter pvPayload; +} VBoxShClStatusMsg; + +#define VBOX_SHCL_CPARMS_STATUS 3 + +/** Invalid message type, do not use. */ +#define VBOX_SHCL_REPLYMSGTYPE_INVALID 0 +/** Replies a transfer status. */ +#define VBOX_SHCL_REPLYMSGTYPE_TRANSFER_STATUS 1 +/** Replies a list open status. */ +#define VBOX_SHCL_REPLYMSGTYPE_LIST_OPEN 2 +/** Replies a list close status. */ +#define VBOX_SHCL_REPLYMSGTYPE_LIST_CLOSE 3 +/** Replies an object open status. */ +#define VBOX_SHCL_REPLYMSGTYPE_OBJ_OPEN 4 +/** Replies an object close status. */ +#define VBOX_SHCL_REPLYMSGTYPE_OBJ_CLOSE 5 + +/** + * Generic reply message. + */ +typedef struct _VBoxShClReplyMsg +{ + VBGLIOCHGCMCALL hdr; + + /** uint64_t, out: Context ID. */ + HGCMFunctionParameter uContext; + /** uint32_t, out: Message type of type VBOX_SHCL_REPLYMSGTYPE_XXX. */ + HGCMFunctionParameter enmType; + /** uint32_t, out: IPRT result of overall operation. */ + HGCMFunctionParameter rc; + /** pointer, out: Optional payload of this reply, based on the message type. */ + HGCMFunctionParameter pvPayload; + union + { + struct + { + HGCMFunctionParameter enmStatus; + } TransferStatus; + struct + { + HGCMFunctionParameter uHandle; + } ListOpen; + struct + { + HGCMFunctionParameter uHandle; + } ObjOpen; + struct + { + HGCMFunctionParameter uHandle; + } ObjClose; + } u; +} VBoxShClReplyMsg; + +/** Minimum parameters (HGCM function parameters minus the union) a reply message must have. */ +#define VBOX_SHCL_CPARMS_REPLY_MIN 4 + +/** + * Structure for keeping root list message parameters. + */ +typedef struct _VBoxShClRootListParms +{ + /** uint64_t, in: Context ID. */ + HGCMFunctionParameter uContext; + /** uint32_t, in: Roots listing flags; unused at the moment. */ + HGCMFunctionParameter fRoots; +} VBoxShClRootListParms; + +#define VBOX_SHCL_CPARMS_ROOT_LIST 2 + +/** + * Requests to read the root list header. + */ +typedef struct _VBoxShClRootListReadReqMsg +{ + VBGLIOCHGCMCALL hdr; + + VBoxShClRootListParms ReqParms; +} VBoxShClRootListReadReqMsg; + +#define VBOX_SHCL_CPARMS_ROOT_LIST_HDR_READ_REQ VBOX_SHCL_CPARMS_ROOT_LIST + +/** + * Reads / Writes a root list header. + */ +typedef struct _VBoxShClRootListHdrMsg +{ + VBGLIOCHGCMCALL hdr; + + VBoxShClRootListParms ReqParms; + /** uint64_t, in/out: Number of total root list entries. */ + HGCMFunctionParameter cRoots; +} VBoxShClRootListHdrMsg; + +#define VBOX_SHCL_CPARMS_ROOT_LIST_HDR_READ VBOX_SHCL_CPARMS_ROOT_LIST + 1 +#define VBOX_SHCL_CPARMS_ROOT_LIST_HDR_WRITE VBOX_SHCL_CPARMS_ROOT_LIST + 1 + +/** + * Structure for keeping list entry message parameters. + */ +typedef struct _VBoxShClRootListEntryParms +{ + /** uint64_t, in: Context ID. */ + HGCMFunctionParameter uContext; + /** uint32_t, in: VBOX_SHCL_INFO_FLAG_XXX. */ + HGCMFunctionParameter fInfo; + /** uint32_t, in: Index of root list entry to get (zero-based). */ + HGCMFunctionParameter uIndex; +} VBoxShClRootListEntryParms; + +#define VBOX_SHCL_CPARMS_ROOT_LIST_ENTRY 3 + +/** + * Request to read a list root entry. + */ +typedef struct _VBoxShClRootListEntryReadReqMsg +{ + VBGLIOCHGCMCALL hdr; + + /** in: Request parameters. */ + VBoxShClRootListEntryParms Parms; +} VBoxShClRootListEntryReadReqMsg; + +#define VBOX_SHCL_CPARMS_ROOT_LIST_ENTRY_READ_REQ VBOX_SHCL_CPARMS_ROOT_LIST_ENTRY + +/** + * Reads / Writes a root list entry. + */ +typedef struct _VBoxShClRootListEntryMsg +{ + VBGLIOCHGCMCALL hdr; + + /** in/out: Request parameters. */ + VBoxShClRootListEntryParms Parms; + /** pointer, in/out: Entry name. */ + HGCMFunctionParameter szName; + /** uint32_t, out: Bytes to be used for information/How many bytes were used. */ + HGCMFunctionParameter cbInfo; + /** pointer, in/out: Information to be set/get (SHCLFSOBJINFO only currently). + * Do not forget to set the SHCLFSOBJINFO::Attr::enmAdditional for Get operation as well. */ + HGCMFunctionParameter pvInfo; +} VBoxShClRootListEntryMsg; + +#define VBOX_SHCL_CPARMS_ROOT_LIST_ENTRY_READ VBOX_SHCL_CPARMS_ROOT_LIST_ENTRY + 3 +#define VBOX_SHCL_CPARMS_ROOT_LIST_ENTRY_WRITE VBOX_SHCL_CPARMS_ROOT_LIST_ENTRY + 3 + +/** + * Opens a list. + */ +typedef struct _VBoxShClListOpenMsg +{ + VBGLIOCHGCMCALL hdr; + + /** uint64_t, in: Context ID. */ + HGCMFunctionParameter uContext; + /** uint32_t, in: Listing flags (see VBOX_SHCL_LIST_FLAG_XXX). */ + HGCMFunctionParameter fList; + /** pointer, in: Filter string. */ + HGCMFunctionParameter pvFilter; + /** pointer, in: Listing poth. If empty or NULL the listing's root path will be opened. */ + HGCMFunctionParameter pvPath; + /** uint64_t, out: List handle. */ + HGCMFunctionParameter uHandle; +} VBoxShClListOpenMsg; + +#define VBOX_SHCL_CPARMS_LIST_OPEN 5 + +/** + * Closes a list. + */ +typedef struct _VBoxShClListCloseMsg +{ + VBGLIOCHGCMCALL hdr; + + /** uint64_t, in/out: Context ID. */ + HGCMFunctionParameter uContext; + /** uint64_t, in: List handle. */ + HGCMFunctionParameter uHandle; +} VBoxShClListCloseMsg; + +#define VBOX_SHCL_CPARMS_LIST_CLOSE 2 + +typedef struct _VBoxShClListHdrReqParms +{ + /** uint64_t, in: Context ID. */ + HGCMFunctionParameter uContext; + /** uint64_t, in: List handle. */ + HGCMFunctionParameter uHandle; + /** uint32_t, in: Flags of type VBOX_SHCL_LISTHDR_FLAG_XXX. */ + HGCMFunctionParameter fFlags; +} VBoxShClListHdrReqParms; + +#define VBOX_SHCL_CPARMS_LIST_HDR_REQ 3 + +/** + * Request to read a list header. + */ +typedef struct _VBoxShClListHdrReadReqMsg +{ + VBGLIOCHGCMCALL hdr; + + VBoxShClListHdrReqParms ReqParms; +} VBoxShClListHdrReadReqMsg; + +#define VBOX_SHCL_CPARMS_LIST_HDR_READ_REQ VBOX_SHCL_CPARMS_LIST_HDR_REQ + +/** + * Reads / Writes a list header. + */ +typedef struct _VBoxShClListHdrMsg +{ + VBGLIOCHGCMCALL hdr; + + VBoxShClListHdrReqParms ReqParms; + /** uint32_t, in/out: Feature flags (see VBOX_SHCL_FEATURE_FLAG_XXX). */ + HGCMFunctionParameter fFeatures; + /** uint64_t, in/out: Number of total objects to transfer. */ + HGCMFunctionParameter cTotalObjects; + /** uint64_t, in/out: Number of total bytes to transfer. */ + HGCMFunctionParameter cbTotalSize; +} VBoxShClListHdrMsg; + +#define VBOX_SHCL_CPARMS_LIST_HDR VBOX_SHCL_CPARMS_LIST_HDR_REQ + 3 + +typedef struct _VBoxShClListEntryReqParms +{ + /** uint64_t, in: Context ID. */ + HGCMFunctionParameter uContext; + /** uint64_t, in: List handle. */ + HGCMFunctionParameter uHandle; + /** uint32_t, in: VBOX_SHCL_INFO_FLAG_XXX. */ + HGCMFunctionParameter fInfo; +} VBoxShClListEntryReqParms; + +#define VBOX_SHCL_CPARMS_LIST_ENTRY_REQ 3 + +/** + * Request to read a list entry. + */ +typedef struct _VBoxShClListEntryReadReqMsg +{ + VBGLIOCHGCMCALL hdr; + + VBoxShClListEntryReqParms ReqParms; +} VBoxShClListEntryReadReqMsg; + +#define VBOX_SHCL_CPARMS_LIST_ENTRY_READ VBOX_SHCL_CPARMS_LIST_ENTRY_REQ + +/** + * Reads / Writes a list entry. + */ +typedef struct _VBoxShClListEntryMsg +{ + VBGLIOCHGCMCALL hdr; + + /** in/out: Request parameters. */ + VBoxShClListEntryReqParms ReqParms; + /** pointer, in/out: Entry name. */ + HGCMFunctionParameter szName; + /** uint32_t, out: Bytes to be used for information/How many bytes were used. */ + HGCMFunctionParameter cbInfo; + /** pointer, in/out: Information to be set/get (SHCLFSOBJINFO only currently). + * Do not forget to set the SHCLFSOBJINFO::Attr::enmAdditional for Get operation as well. */ + HGCMFunctionParameter pvInfo; +} VBoxShClListEntryMsg; + +#define VBOX_SHCL_CPARMS_LIST_ENTRY VBOX_SHCL_CPARMS_LIST_ENTRY_REQ + 3 + +/** + * Opens a Shared Clipboard object. + */ +typedef struct _VBoxShClObjOpenMsg +{ + VBGLIOCHGCMCALL hdr; + + /** uint64_t, in/out: Context ID. */ + HGCMFunctionParameter uContext; + /** uint64_t, out: Object handle. */ + HGCMFunctionParameter uHandle; + /** pointer, in: Absoulte path of object to open/create. */ + HGCMFunctionParameter szPath; + /** uint32_t in: Open / Create flags of type SHCL_OBJ_CF_. */ + HGCMFunctionParameter fCreate; +} VBoxShClObjOpenMsg; + +#define VBOX_SHCL_CPARMS_OBJ_OPEN 4 + +/** + * Closes a Shared Clipboard object. + */ +typedef struct _VBoxShClObjCloseMsg +{ + VBGLIOCHGCMCALL hdr; + + /** uint64_t, in/out: Context ID. */ + HGCMFunctionParameter uContext; + /** uint64_t, in: SHCLOBJHANDLE of object to close. */ + HGCMFunctionParameter uHandle; +} VBoxShClObjCloseMsg; + +#define VBOX_SHCL_CPARMS_OBJ_CLOSE 2 + +/** + * Structure for keeping read parameters of a Shared Clipboard object. + */ +typedef struct _VBoxShClObjReadReqParms +{ + /** uint64_t, in: Context ID. */ + HGCMFunctionParameter uContext; + /** uint64_t, in: SHCLOBJHANDLE of object to write to. */ + HGCMFunctionParameter uHandle; + /** uint32_t, in: How many bytes to read. */ + HGCMFunctionParameter cbToRead; + /** uint32_t, in: Read flags. Currently unused and must be 0. */ + HGCMFunctionParameter fRead; +} VBoxShClObjReadReqParms; + +/** + * Reads from a Shared Clipboard object. + */ +typedef struct _VBoxShClObjReadReqMsg +{ + VBGLIOCHGCMCALL hdr; + + VBoxShClObjReadReqParms ReqParms; +} VBoxShClObjReadReqMsg; + +#define VBOX_SHCL_CPARMS_OBJ_READ_REQ 4 + +/** + * Reads / writes data of / to an object. + * + * Used by: + * VBOX_SHCL_FN_OBJ_READ + * VBOX_SHCL_FN_OBJ_WRITE + */ +typedef struct _VBoxShClObjReadWriteMsg +{ + VBGLIOCHGCMCALL hdr; + + /** uint64_t, in/out: Context ID. */ + HGCMFunctionParameter uContext; + /** uint64_t, in/out: SHCLOBJHANDLE of object to write to. */ + HGCMFunctionParameter uHandle; + /** uint32_t, out: Size (in bytes) read/written. */ + HGCMFunctionParameter cbData; + /** pointer, in/out: Current data chunk. */ + HGCMFunctionParameter pvData; + /** uint32_t, in/out: Size (in bytes) of current data chunk checksum. */ + HGCMFunctionParameter cbChecksum; + /** pointer, in/out: Checksum of data block, based on the checksum + * type in the data header. Optional. */ + HGCMFunctionParameter pvChecksum; +} VBoxShClObjReadWriteMsg; + +#define VBOX_SHCL_CPARMS_OBJ_READ 6 +#define VBOX_SHCL_CPARMS_OBJ_WRITE 6 + +/** + * Sends an error event. + * + * Used by: + * VBOX_SHCL_FN_WRITE_ERROR + */ +typedef struct _VBoxShClErrorMsg +{ + VBGLIOCHGCMCALL hdr; + + /** uint64_t, in: Context ID. */ + HGCMFunctionParameter uContext; + /** uint32_t, in: The error code (IPRT-style). */ + HGCMFunctionParameter rc; +} VBoxShClWriteErrorMsg; + +#define VBOX_SHCL_CPARMS_ERROR 2 + +/** @name VBOX_SHCL_GUEST_FN_NEGOTIATE_CHUNK_SIZE + * @{ */ +/** VBOX_SHCL_GUEST_FN_NEGOTIATE_CHUNK_SIZE parameters. */ +typedef struct _VBoxShClParmNegotiateChunkSize +{ + VBGLIOCHGCMCALL hdr; + + /** uint32_t, in: Maximum chunk size. */ + HGCMFunctionParameter cb32MaxChunkSize; + /** uint32_t, in: Default chunk size. */ + HGCMFunctionParameter cb32ChunkSize; +} VBoxShClParmNegotiateChunkSize; + +#define VBOX_SHCL_CPARMS_NEGOTIATE_CHUNK_SIZE 2 +/** @} */ + +#pragma pack() + +#endif /* !VBOX_INCLUDED_HostServices_VBoxClipboardSvc_h */ + diff --git a/include/VBox/HostServices/VBoxHostChannel.h b/include/VBox/HostServices/VBoxHostChannel.h new file mode 100644 index 00000000..29ffa06c --- /dev/null +++ b/include/VBox/HostServices/VBoxHostChannel.h @@ -0,0 +1,229 @@ +/** @file + * + * Host Channel: the service definition. + */ + +/* + * Copyright (C) 2012-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 + */ + +#ifndef VBOX_INCLUDED_HostServices_VBoxHostChannel_h +#define VBOX_INCLUDED_HostServices_VBoxHostChannel_h +#ifndef RT_WITHOUT_PRAGMA_ONCE +# pragma once +#endif + +#include <VBox/VMMDevCoreTypes.h> +#include <VBox/VBoxGuestCoreTypes.h> +#include <VBox/hgcmsvc.h> + +/* + * Host calls. + */ +#define VBOX_HOST_CHANNEL_HOST_FN_REGISTER 1 +#define VBOX_HOST_CHANNEL_HOST_FN_UNREGISTER 2 + +/* + * Guest calls. + */ +#define VBOX_HOST_CHANNEL_FN_ATTACH 1 /* Attach to a channel. */ +#define VBOX_HOST_CHANNEL_FN_DETACH 2 /* Detach from the channel. */ +#define VBOX_HOST_CHANNEL_FN_SEND 3 /* Send data to the host. */ +#define VBOX_HOST_CHANNEL_FN_RECV 4 /* Receive data from the host. */ +#define VBOX_HOST_CHANNEL_FN_CONTROL 5 /* Generic data exchange using a channel instance. */ +#define VBOX_HOST_CHANNEL_FN_EVENT_WAIT 6 /* Blocking wait for a host event. */ +#define VBOX_HOST_CHANNEL_FN_EVENT_CANCEL 7 /* Cancel the blocking wait. */ +#define VBOX_HOST_CHANNEL_FN_QUERY 8 /* Generic data exchange using a channel name. */ + +/* + * The host event ids for the guest. + */ +#define VBOX_HOST_CHANNEL_EVENT_CANCELLED 0 /* Event was cancelled by FN_EVENT_CANCEL. */ +#define VBOX_HOST_CHANNEL_EVENT_UNREGISTERED 1 /* Channel was unregistered on host. */ +#define VBOX_HOST_CHANNEL_EVENT_RECV 2 /* Data is available for receiving. */ +#define VBOX_HOST_CHANNEL_EVENT_USER 1000 /* Base of channel specific events. */ + +/* + * The common control code ids for the VBOX_HOST_CHANNEL_FN_[CONTROL|QUERY] + */ +#define VBOX_HOST_CHANNEL_CTRL_EXISTS 0 /* Whether the channel instance or provider exists. */ +#define VBOX_HOST_CHANNEL_CTRL_USER 1000 /* Base of channel specific events. */ + +#pragma pack(1) + +/* Parameter of VBOX_HOST_CHANNEL_EVENT_RECV */ +typedef struct VBOXHOSTCHANNELEVENTRECV +{ + uint32_t u32SizeAvailable; /* How many bytes can be read from the channel. */ +} VBOXHOSTCHANNELEVENTRECV; + +/* + * Guest calls. + */ + +typedef struct VBoxHostChannelAttach +{ + VBGLIOCHGCMCALL hdr; + HGCMFunctionParameter name; /* IN linear ptr: Channel name utf8 nul terminated. */ + HGCMFunctionParameter flags; /* IN uint32_t: Channel specific flags. */ + HGCMFunctionParameter handle; /* OUT uint32_t: The channel handle. */ +} VBoxHostChannelAttach; + +typedef struct VBoxHostChannelDetach +{ + VBGLIOCHGCMCALL hdr; + HGCMFunctionParameter handle; /* IN uint32_t: The channel handle. */ +} VBoxHostChannelDetach; + +typedef struct VBoxHostChannelSend +{ + VBGLIOCHGCMCALL hdr; + HGCMFunctionParameter handle; /* IN uint32_t: The channel handle. */ + HGCMFunctionParameter data; /* IN linear pointer: Data to be sent. */ +} VBoxHostChannelSend; + +typedef struct VBoxHostChannelRecv +{ + VBGLIOCHGCMCALL hdr; + HGCMFunctionParameter handle; /* IN uint32_t: The channel handle. */ + HGCMFunctionParameter data; /* OUT linear pointer: Buffer for data to be received. */ + HGCMFunctionParameter sizeReceived; /* OUT uint32_t: Bytes received. */ + HGCMFunctionParameter sizeRemaining; /* OUT uint32_t: Bytes remaining in the channel. */ +} VBoxHostChannelRecv; + +typedef struct VBoxHostChannelControl +{ + VBGLIOCHGCMCALL hdr; + HGCMFunctionParameter handle; /* IN uint32_t: The channel handle. */ + HGCMFunctionParameter code; /* IN uint32_t: The channel specific control code. */ + HGCMFunctionParameter parm; /* IN linear pointer: Parameters of the function. */ + HGCMFunctionParameter data; /* OUT linear pointer: Buffer for results. */ + HGCMFunctionParameter sizeDataReturned; /* OUT uint32_t: Bytes returned in the 'data' buffer. */ +} VBoxHostChannelControl; + +typedef struct VBoxHostChannelEventWait +{ + VBGLIOCHGCMCALL hdr; + HGCMFunctionParameter handle; /* OUT uint32_t: The channel which generated the event. */ + HGCMFunctionParameter id; /* OUT uint32_t: The event VBOX_HOST_CHANNEL_EVENT_*. */ + HGCMFunctionParameter parm; /* OUT linear pointer: Parameters of the event. */ + HGCMFunctionParameter sizeReturned; /* OUT uint32_t: Size of the parameters. */ +} VBoxHostChannelEventWait; + +typedef struct VBoxHostChannelEventCancel +{ + VBGLIOCHGCMCALL hdr; +} VBoxHostChannelEventCancel; + +typedef struct VBoxHostChannelQuery +{ + VBGLIOCHGCMCALL hdr; + HGCMFunctionParameter name; /* IN linear ptr: Channel name utf8 nul terminated. */ + HGCMFunctionParameter code; /* IN uint32_t: The control code. */ + HGCMFunctionParameter parm; /* IN linear pointer: Parameters of the function. */ + HGCMFunctionParameter data; /* OUT linear pointer: Buffer for results. */ + HGCMFunctionParameter sizeDataReturned; /* OUT uint32_t: Bytes returned in the 'data' buffer. */ +} VBoxHostChannelQuery; + + +/* + * Host calls + */ + +typedef struct VBoxHostChannelHostRegister +{ + VBOXHGCMSVCPARM name; /* IN ptr: Channel name utf8 nul terminated. */ + VBOXHGCMSVCPARM iface; /* IN ptr: VBOXHOSTCHANNELINTERFACE. */ +} VBoxHostChannelHostRegister; + +typedef struct VBoxHostChannelHostUnregister +{ + VBOXHGCMSVCPARM name; /* IN ptr: Channel name utf8 nul terminated */ +} VBoxHostChannelHostUnregister; + +/* The channel provider will invoke this callback to report channel events. */ +typedef struct VBOXHOSTCHANNELCALLBACKS +{ + /* A channel event occured. + * + * @param pvCallbacks The callback context specified in HostChannelAttach. + * @param pvChannel The channel instance returned by HostChannelAttach. + * @param u32Id The event id. + * @param pvEvent The event parameters. + * @param cbEvent The size of event parameters. + */ + DECLR3CALLBACKMEMBER(void, HostChannelCallbackEvent, (void *pvCallbacks, void *pvChannel, + uint32_t u32Id, const void *pvEvent, uint32_t cbEvent)); + + /* The channel has been deleted by the provider. pvCallback will not be used anymore. + * + * @param pvCallbacks The callback context specified in HostChannelAttach. + * @param pvChannel The channel instance returned by HostChannelAttach. + */ + DECLR3CALLBACKMEMBER(void, HostChannelCallbackDeleted, (void *pvCallbacks, void *pvChannel)); +} VBOXHOSTCHANNELCALLBACKS; + +typedef struct VBOXHOSTCHANNELINTERFACE +{ + /* The channel provider context. */ + void *pvProvider; + + /* A new channel is requested. + * + * @param pvProvider The provider context VBOXHOSTCHANNELINTERFACE::pvProvider. + * @param ppvChannel Where to store pointer to the channel instance created by the provider. + * @param u32Flags Channel specific flags. + * @param pCallbacks Callbacks to be invoked by the channel provider. + * @param pvCallbacks The context of callbacks. + */ + DECLR3CALLBACKMEMBER(int, HostChannelAttach, (void *pvProvider, void **ppvChannel, uint32_t u32Flags, + VBOXHOSTCHANNELCALLBACKS *pCallbacks, void *pvCallbacks)); + + /* The channel is closed. */ + DECLR3CALLBACKMEMBER(void, HostChannelDetach, (void *pvChannel)); + + /* The guest sends data to the channel. */ + DECLR3CALLBACKMEMBER(int, HostChannelSend, (void *pvChannel, const void *pvData, uint32_t cbData)); + + /* The guest reads data from the channel. */ + DECLR3CALLBACKMEMBER(int, HostChannelRecv, (void *pvChannel, void *pvData, uint32_t cbData, + uint32_t *pcbReceived, uint32_t *pcbRemaining)); + + /* The guest talks to the provider of the channel. + * @param pvChannel The channel instance. NULL if the target is the provider, rather than a channel. + */ + DECLR3CALLBACKMEMBER(int, HostChannelControl, (void *pvChannel, uint32_t u32Code, + const void *pvParm, uint32_t cbParm, + const void *pvData, uint32_t cbData, uint32_t *pcbDataReturned)); +} VBOXHOSTCHANNELINTERFACE; + +#pragma pack() + +#endif /* !VBOX_INCLUDED_HostServices_VBoxHostChannel_h */ |