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

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

1 files changed, 553 insertions, 0 deletions

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 */
+