Adding upstream version 7.0.6-dfsg.upstream/7.0.6-dfsgupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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