[9727] | 1 | /** @file
|
---|
[70064] | 2 | * Guest property service - Common header for host service and guest clients.
|
---|
[9727] | 3 | */
|
---|
| 4 |
|
---|
| 5 | /*
|
---|
[98103] | 6 | * Copyright (C) 2006-2023 Oracle and/or its affiliates.
|
---|
[9727] | 7 | *
|
---|
[96407] | 8 | * This file is part of VirtualBox base platform packages, as
|
---|
| 9 | * available from https://www.virtualbox.org.
|
---|
[9727] | 10 | *
|
---|
[96407] | 11 | * This program is free software; you can redistribute it and/or
|
---|
| 12 | * modify it under the terms of the GNU General Public License
|
---|
| 13 | * as published by the Free Software Foundation, in version 3 of the
|
---|
| 14 | * License.
|
---|
| 15 | *
|
---|
| 16 | * This program is distributed in the hope that it will be useful, but
|
---|
| 17 | * WITHOUT ANY WARRANTY; without even the implied warranty of
|
---|
| 18 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
---|
| 19 | * General Public License for more details.
|
---|
| 20 | *
|
---|
| 21 | * You should have received a copy of the GNU General Public License
|
---|
| 22 | * along with this program; if not, see <https://www.gnu.org/licenses>.
|
---|
| 23 | *
|
---|
[11934] | 24 | * The contents of this file may alternatively be used under the terms
|
---|
| 25 | * of the Common Development and Distribution License Version 1.0
|
---|
[96407] | 26 | * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
|
---|
| 27 | * in the VirtualBox distribution, in which case the provisions of the
|
---|
[11934] | 28 | * CDDL are applicable instead of those of the GPL.
|
---|
| 29 | *
|
---|
| 30 | * You may elect to license modified versions of this file under the
|
---|
| 31 | * terms and conditions of either the GPL or the CDDL or both.
|
---|
[96407] | 32 | *
|
---|
| 33 | * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
|
---|
[9727] | 34 | */
|
---|
| 35 |
|
---|
[76558] | 36 | #ifndef VBOX_INCLUDED_HostServices_GuestPropertySvc_h
|
---|
| 37 | #define VBOX_INCLUDED_HostServices_GuestPropertySvc_h
|
---|
[76507] | 38 | #ifndef RT_WITHOUT_PRAGMA_ONCE
|
---|
| 39 | # pragma once
|
---|
| 40 | #endif
|
---|
[9727] | 41 |
|
---|
[68660] | 42 | #include <VBox/VMMDevCoreTypes.h>
|
---|
[68656] | 43 | #include <VBox/VBoxGuestCoreTypes.h>
|
---|
[68667] | 44 | #include <VBox/log.h>
|
---|
[76395] | 45 | #include <iprt/err.h>
|
---|
[70060] | 46 | #include <iprt/assertcompile.h>
|
---|
[13928] | 47 | #include <iprt/string.h>
|
---|
[9727] | 48 |
|
---|
| 49 |
|
---|
[95334] | 50 | /** Maximum size for property names (including the terminator). */
|
---|
[70058] | 51 | #define GUEST_PROP_MAX_NAME_LEN 64
|
---|
[95334] | 52 | /** Maximum size for property values (including the terminator). */
|
---|
[95228] | 53 | #define GUEST_PROP_MAX_VALUE_LEN 1024
|
---|
[75992] | 54 | /** Maximum number of properties per guest. */
|
---|
[70058] | 55 | #define GUEST_PROP_MAX_PROPS 256
|
---|
[95334] | 56 | /** Maximum size for enumeration patterns (including the terminators). */
|
---|
[70058] | 57 | #define GUEST_PROP_MAX_PATTERN_LEN 1024
|
---|
[75992] | 58 | /** Maximum number of changes we remember for guest notifications. */
|
---|
[70058] | 59 | #define GUEST_PROP_MAX_GUEST_NOTIFICATIONS 256
|
---|
[75992] | 60 | /** Maximum number of current pending waits per client. */
|
---|
| 61 | #define GUEST_PROP_MAX_GUEST_CONCURRENT_WAITS 16
|
---|
[13293] | 62 |
|
---|
[70058] | 63 |
|
---|
| 64 | /** @name GUEST_PROP_F_XXX - The guest property flag values which are currently accepted.
|
---|
| 65 | * @{
|
---|
[13293] | 66 | */
|
---|
[70058] | 67 | #define GUEST_PROP_F_NILFLAG UINT32_C(0)
|
---|
| 68 | /** Transient until VM gets shut down. */
|
---|
| 69 | #define GUEST_PROP_F_TRANSIENT RT_BIT_32(1)
|
---|
| 70 | #define GUEST_PROP_F_RDONLYGUEST RT_BIT_32(2)
|
---|
| 71 | #define GUEST_PROP_F_RDONLYHOST RT_BIT_32(3)
|
---|
| 72 | /** Transient until VM gets a reset / restarts.
|
---|
| 73 | * Implies TRANSIENT. */
|
---|
| 74 | #define GUEST_PROP_F_TRANSRESET RT_BIT_32(4)
|
---|
| 75 | #define GUEST_PROP_F_READONLY (GUEST_PROP_F_RDONLYGUEST | GUEST_PROP_F_RDONLYHOST)
|
---|
| 76 | #define GUEST_PROP_F_ALLFLAGS (GUEST_PROP_F_TRANSIENT | GUEST_PROP_F_READONLY | GUEST_PROP_F_TRANSRESET)
|
---|
| 77 | /** @} */
|
---|
[13293] | 78 |
|
---|
| 79 | /**
|
---|
[93891] | 80 | * Check that a string fits our criteria for a property name.
|
---|
| 81 | *
|
---|
| 82 | * @returns IPRT status code
|
---|
[95338] | 83 | * @param pszName The string to check, must be valid Utf8
|
---|
| 84 | * @param cbName The number of bytes @a pszName points to, including the
|
---|
| 85 | * terminating character.
|
---|
[93891] | 86 | */
|
---|
[95338] | 87 | DECLINLINE(int) GuestPropValidateName(const char *pszName, size_t cbName)
|
---|
[93891] | 88 | {
|
---|
| 89 | /* Property name is expected to be at least 1 charecter long plus terminating character. */
|
---|
| 90 | AssertReturn(cbName >= 2, VERR_INVALID_PARAMETER);
|
---|
[95334] | 91 | AssertReturn(cbName <= GUEST_PROP_MAX_NAME_LEN, VERR_INVALID_PARAMETER);
|
---|
[93891] | 92 |
|
---|
| 93 | AssertPtrReturn(pszName, VERR_INVALID_POINTER);
|
---|
| 94 |
|
---|
| 95 | AssertReturn(memchr(pszName, '*', cbName) == NULL, VERR_INVALID_PARAMETER);
|
---|
| 96 | AssertReturn(memchr(pszName, '?', cbName) == NULL, VERR_INVALID_PARAMETER);
|
---|
| 97 | AssertReturn(memchr(pszName, '|', cbName) == NULL, VERR_INVALID_PARAMETER);
|
---|
| 98 |
|
---|
| 99 | return VINF_SUCCESS;
|
---|
| 100 | }
|
---|
| 101 |
|
---|
| 102 | /**
|
---|
| 103 | * Check a string fits our criteria for the value of a guest property.
|
---|
| 104 | *
|
---|
| 105 | * @returns IPRT status code
|
---|
[95228] | 106 | * @retval VINF_SUCCESS if guest property value corresponds to all criteria.
|
---|
| 107 | * @retval VERR_TOO_MUCH_DATA if guest property value size exceeds limits.
|
---|
| 108 | * @retval VERR_INVALID_PARAMETER if guest property does not correspond to all other criteria.
|
---|
[95338] | 109 | * @param pszValue The string to check, must be valid utf-8.
|
---|
| 110 | * @param cbValue The size of of @a pszValue in bytes, including the
|
---|
| 111 | * terminator.
|
---|
[93891] | 112 | * @thread HGCM
|
---|
| 113 | */
|
---|
[95338] | 114 | DECLINLINE(int) GuestPropValidateValue(const char *pszValue, size_t cbValue)
|
---|
[93891] | 115 | {
|
---|
| 116 | AssertPtrReturn(pszValue, VERR_INVALID_POINTER);
|
---|
| 117 |
|
---|
| 118 | /* Zero-length values are possible, however buffer should contain terminating character at least. */
|
---|
| 119 | AssertReturn(cbValue > 0, VERR_INVALID_PARAMETER);
|
---|
[95334] | 120 | AssertReturn(cbValue <= GUEST_PROP_MAX_VALUE_LEN, VERR_TOO_MUCH_DATA);
|
---|
[93891] | 121 |
|
---|
| 122 | return VINF_SUCCESS;
|
---|
| 123 | }
|
---|
| 124 |
|
---|
| 125 | /**
|
---|
[13574] | 126 | * Get the name of a flag as a string.
|
---|
| 127 | * @returns the name, or NULL if fFlag is invalid.
|
---|
[70222] | 128 | * @param fFlag The flag, GUEST_PROP_F_XXX.
|
---|
| 129 | * @param pcchName Where to return the name length.
|
---|
[13293] | 130 | */
|
---|
[70222] | 131 | DECLINLINE(const char *) GuestPropFlagNameAndLen(uint32_t fFlag, size_t *pcchName)
|
---|
[13293] | 132 | {
|
---|
[36178] | 133 | switch (fFlag)
|
---|
[13574] | 134 | {
|
---|
[70058] | 135 | case GUEST_PROP_F_TRANSIENT:
|
---|
[70222] | 136 | *pcchName = sizeof("TRANSIENT") - 1;
|
---|
[13574] | 137 | return "TRANSIENT";
|
---|
[70058] | 138 | case GUEST_PROP_F_RDONLYGUEST:
|
---|
[70222] | 139 | *pcchName = sizeof("RDONLYGUEST") - 1;
|
---|
[13574] | 140 | return "RDONLYGUEST";
|
---|
[70058] | 141 | case GUEST_PROP_F_RDONLYHOST:
|
---|
[70222] | 142 | *pcchName = sizeof("RDONLYHOST") - 1;
|
---|
[13574] | 143 | return "RDONLYHOST";
|
---|
[70058] | 144 | case GUEST_PROP_F_READONLY:
|
---|
[70222] | 145 | *pcchName = sizeof("READONLY") - 1;
|
---|
[13574] | 146 | return "READONLY";
|
---|
[70058] | 147 | case GUEST_PROP_F_TRANSRESET:
|
---|
[70222] | 148 | *pcchName = sizeof("TRANSRESET") - 1;
|
---|
[36219] | 149 | return "TRANSRESET";
|
---|
[13574] | 150 | default:
|
---|
[70222] | 151 | *pcchName = 0;
|
---|
| 152 | return NULL;
|
---|
[13574] | 153 | }
|
---|
| 154 | }
|
---|
| 155 |
|
---|
| 156 | /**
|
---|
| 157 | * Maximum length for the property flags field. We only ever return one of
|
---|
| 158 | * RDONLYGUEST, RDONLYHOST and RDONLY
|
---|
| 159 | */
|
---|
[70058] | 160 | #define GUEST_PROP_MAX_FLAGS_LEN sizeof("TRANSIENT, RDONLYGUEST, TRANSRESET")
|
---|
[13293] | 161 |
|
---|
| 162 | /**
|
---|
[13574] | 163 | * Parse a guest properties flags string for flag names and make sure that
|
---|
| 164 | * there is no junk text in the string.
|
---|
[70058] | 165 | *
|
---|
[13293] | 166 | * @returns IPRT status code
|
---|
[70058] | 167 | * @retval VERR_INVALID_PARAMETER if the flag string is not valid
|
---|
[13293] | 168 | * @param pcszFlags the flag string to parse
|
---|
| 169 | * @param pfFlags where to store the parse result. May not be NULL.
|
---|
| 170 | * @note This function is also inline because it must be accessible from
|
---|
| 171 | * several modules and it does not seem reasonable to put it into
|
---|
| 172 | * its own library.
|
---|
| 173 | */
|
---|
[70058] | 174 | DECLINLINE(int) GuestPropValidateFlags(const char *pcszFlags, uint32_t *pfFlags)
|
---|
[13293] | 175 | {
|
---|
[24666] | 176 | static const uint32_t s_aFlagList[] =
|
---|
[13574] | 177 | {
|
---|
[70058] | 178 | GUEST_PROP_F_TRANSIENT, GUEST_PROP_F_READONLY, GUEST_PROP_F_RDONLYGUEST, GUEST_PROP_F_RDONLYHOST, GUEST_PROP_F_TRANSRESET
|
---|
[13574] | 179 | };
|
---|
[13293] | 180 | const char *pcszNext = pcszFlags;
|
---|
| 181 | int rc = VINF_SUCCESS;
|
---|
| 182 | uint32_t fFlags = 0;
|
---|
[90792] | 183 | AssertLogRelReturn(RT_VALID_PTR(pfFlags), VERR_INVALID_POINTER);
|
---|
[22173] | 184 |
|
---|
| 185 | if (pcszFlags)
|
---|
[13293] | 186 | {
|
---|
[70222] | 187 | while (*pcszNext == ' ')
|
---|
[22173] | 188 | ++pcszNext;
|
---|
| 189 | while ((*pcszNext != '\0') && RT_SUCCESS(rc))
|
---|
[13293] | 190 | {
|
---|
[70222] | 191 | unsigned i;
|
---|
| 192 | rc = VERR_PARSE_ERROR;
|
---|
| 193 | for (i = 0; i < RT_ELEMENTS(s_aFlagList); ++i)
|
---|
| 194 | {
|
---|
| 195 | size_t cchFlagName;
|
---|
| 196 | const char *pszFlagName = GuestPropFlagNameAndLen(s_aFlagList[i], &cchFlagName);
|
---|
[71010] | 197 | if (RTStrNICmpAscii(pcszNext, pszFlagName, cchFlagName) == 0)
|
---|
[70222] | 198 | {
|
---|
| 199 | char ch;
|
---|
| 200 | fFlags |= s_aFlagList[i];
|
---|
| 201 | pcszNext += cchFlagName;
|
---|
| 202 | while ((ch = *pcszNext) == ' ')
|
---|
| 203 | ++pcszNext;
|
---|
| 204 | rc = VINF_SUCCESS;
|
---|
| 205 | if (ch == ',')
|
---|
| 206 | {
|
---|
| 207 | ++pcszNext;
|
---|
| 208 | while (*pcszNext == ' ')
|
---|
| 209 | ++pcszNext;
|
---|
| 210 | }
|
---|
| 211 | else if (ch != '\0')
|
---|
| 212 | rc = VERR_PARSE_ERROR;
|
---|
[22173] | 213 | break;
|
---|
[70222] | 214 | }
|
---|
[22173] | 215 | }
|
---|
[13293] | 216 | }
|
---|
| 217 | }
|
---|
| 218 | if (RT_SUCCESS(rc))
|
---|
| 219 | *pfFlags = fFlags;
|
---|
| 220 | return rc;
|
---|
| 221 | }
|
---|
| 222 |
|
---|
[70058] | 223 |
|
---|
[13293] | 224 | /**
|
---|
| 225 | * Write out flags to a string.
|
---|
| 226 | * @returns IPRT status code
|
---|
[70221] | 227 | * @param fFlags the flags to write out
|
---|
| 228 | * @param pszFlags where to write the flags string. This must point to
|
---|
[70222] | 229 | * a buffer of size (at least) GUEST_PROP_MAX_FLAGS_LEN.
|
---|
[13293] | 230 | */
|
---|
[70221] | 231 | DECLINLINE(int) GuestPropWriteFlags(uint32_t fFlags, char *pszFlags)
|
---|
[13293] | 232 | {
|
---|
[36413] | 233 | /* Putting READONLY before the other RDONLY flags keeps the result short. */
|
---|
[24666] | 234 | static const uint32_t s_aFlagList[] =
|
---|
[13574] | 235 | {
|
---|
[70058] | 236 | GUEST_PROP_F_TRANSIENT, GUEST_PROP_F_READONLY, GUEST_PROP_F_RDONLYGUEST, GUEST_PROP_F_RDONLYHOST, GUEST_PROP_F_TRANSRESET
|
---|
[13574] | 237 | };
|
---|
[13293] | 238 | int rc = VINF_SUCCESS;
|
---|
[36412] | 239 |
|
---|
[90792] | 240 | AssertLogRelReturn(RT_VALID_PTR(pszFlags), VERR_INVALID_POINTER);
|
---|
[70058] | 241 | if ((fFlags & ~GUEST_PROP_F_ALLFLAGS) == GUEST_PROP_F_NILFLAG)
|
---|
[13293] | 242 | {
|
---|
[70221] | 243 | char *pszNext;
|
---|
[70090] | 244 | unsigned i;
|
---|
| 245 |
|
---|
[36412] | 246 | /* TRANSRESET implies TRANSIENT. For compatability with old clients we
|
---|
| 247 | always set TRANSIENT when TRANSRESET appears. */
|
---|
[70058] | 248 | if (fFlags & GUEST_PROP_F_TRANSRESET)
|
---|
| 249 | fFlags |= GUEST_PROP_F_TRANSIENT;
|
---|
[36412] | 250 |
|
---|
[70221] | 251 | pszNext = pszFlags;
|
---|
[70089] | 252 | for (i = 0; i < RT_ELEMENTS(s_aFlagList); ++i)
|
---|
[13293] | 253 | {
|
---|
[24666] | 254 | if (s_aFlagList[i] == (fFlags & s_aFlagList[i]))
|
---|
[13293] | 255 | {
|
---|
[70222] | 256 | size_t cchFlagName;
|
---|
| 257 | const char *pszFlagName = GuestPropFlagNameAndLen(s_aFlagList[i], &cchFlagName);
|
---|
| 258 | memcpy(pszNext, pszFlagName, cchFlagName);
|
---|
| 259 | pszNext += cchFlagName;
|
---|
[24666] | 260 | fFlags &= ~s_aFlagList[i];
|
---|
[70058] | 261 | if (fFlags != GUEST_PROP_F_NILFLAG)
|
---|
[70090] | 262 | {
|
---|
[70222] | 263 | *pszNext++ = ',';
|
---|
| 264 | *pszNext++ = ' ';
|
---|
[70090] | 265 | }
|
---|
[13293] | 266 | }
|
---|
| 267 | }
|
---|
[70221] | 268 | *pszNext = '\0';
|
---|
[36412] | 269 |
|
---|
[70222] | 270 | Assert((uintptr_t)(pszNext - pszFlags) < GUEST_PROP_MAX_FLAGS_LEN);
|
---|
[70058] | 271 | Assert(fFlags == GUEST_PROP_F_NILFLAG); /* bad s_aFlagList */
|
---|
[13293] | 272 | }
|
---|
[36412] | 273 | else
|
---|
| 274 | rc = VERR_INVALID_PARAMETER;
|
---|
[13293] | 275 | return rc;
|
---|
| 276 | }
|
---|
| 277 |
|
---|
[70058] | 278 |
|
---|
| 279 | /** @name The service functions which are callable by host.
|
---|
| 280 | * @{
|
---|
[9727] | 281 | */
|
---|
[70058] | 282 | /** Set properties in a block.
|
---|
| 283 | * The parameters are pointers to NULL-terminated arrays containing the
|
---|
| 284 | * parameters. These are, in order, name, value, timestamp, flags. Strings are
|
---|
| 285 | * stored as pointers to mutable utf8 data. All parameters must be supplied. */
|
---|
[70063] | 286 | #define GUEST_PROP_FN_HOST_SET_PROPS 1
|
---|
[70058] | 287 | /** Get the value attached to a guest property.
|
---|
| 288 | * The parameter format matches that of GET_PROP. */
|
---|
[70063] | 289 | #define GUEST_PROP_FN_HOST_GET_PROP 2
|
---|
[70058] | 290 | /** Set the value attached to a guest property.
|
---|
| 291 | * The parameter format matches that of SET_PROP. */
|
---|
[70063] | 292 | #define GUEST_PROP_FN_HOST_SET_PROP 3
|
---|
[70058] | 293 | /** Set the value attached to a guest property.
|
---|
| 294 | * The parameter format matches that of SET_PROP_VALUE. */
|
---|
[70063] | 295 | #define GUEST_PROP_FN_HOST_SET_PROP_VALUE 4
|
---|
[70058] | 296 | /** Remove a guest property.
|
---|
| 297 | * The parameter format matches that of DEL_PROP. */
|
---|
[70063] | 298 | #define GUEST_PROP_FN_HOST_DEL_PROP 5
|
---|
[70058] | 299 | /** Enumerate guest properties.
|
---|
| 300 | * The parameter format matches that of ENUM_PROPS. */
|
---|
[70063] | 301 | #define GUEST_PROP_FN_HOST_ENUM_PROPS 6
|
---|
[70058] | 302 | /** Set global flags for the service.
|
---|
| 303 | * Currently RDONLYGUEST is supported. Takes one 32-bit unsigned integer
|
---|
| 304 | * parameter for the flags. */
|
---|
[70063] | 305 | #define GUEST_PROP_FN_HOST_SET_GLOBAL_FLAGS 7
|
---|
[70058] | 306 | /** @} */
|
---|
[24703] | 307 |
|
---|
[40767] | 308 |
|
---|
[70058] | 309 | /** @name The service functions which are called by guest.
|
---|
| 310 | *
|
---|
| 311 | * @note The numbers may not change!
|
---|
| 312 | * @{
|
---|
[9727] | 313 | */
|
---|
[70058] | 314 | /** Get a guest property */
|
---|
| 315 | #define GUEST_PROP_FN_GET_PROP 1
|
---|
| 316 | /** Set a guest property */
|
---|
| 317 | #define GUEST_PROP_FN_SET_PROP 2
|
---|
| 318 | /** Set just the value of a guest property */
|
---|
| 319 | #define GUEST_PROP_FN_SET_PROP_VALUE 3
|
---|
| 320 | /** Delete a guest property */
|
---|
| 321 | #define GUEST_PROP_FN_DEL_PROP 4
|
---|
| 322 | /** Enumerate guest properties */
|
---|
| 323 | #define GUEST_PROP_FN_ENUM_PROPS 5
|
---|
| 324 | /** Poll for guest notifications */
|
---|
| 325 | #define GUEST_PROP_FN_GET_NOTIFICATION 6
|
---|
| 326 | /** @} */
|
---|
[9727] | 327 |
|
---|
[70058] | 328 |
|
---|
[9727] | 329 | /**
|
---|
[70058] | 330 | * Data structure to pass to the service extension callback.
|
---|
| 331 | * We use this to notify the host of changes to properties.
|
---|
[13376] | 332 | */
|
---|
[70058] | 333 | typedef struct GUESTPROPHOSTCALLBACKDATA
|
---|
[13376] | 334 | {
|
---|
[70058] | 335 | /** Magic number to identify the structure (GUESTPROPHOSTCALLBACKDATA_MAGIC). */
|
---|
| 336 | uint32_t u32Magic;
|
---|
[13376] | 337 | /** The name of the property that was changed */
|
---|
[70058] | 338 | const char *pcszName;
|
---|
[13376] | 339 | /** The new property value, or NULL if the property was deleted */
|
---|
[70058] | 340 | const char *pcszValue;
|
---|
[13376] | 341 | /** The timestamp of the modification */
|
---|
[70058] | 342 | uint64_t u64Timestamp;
|
---|
[13376] | 343 | /** The flags field of the modified property */
|
---|
[70058] | 344 | const char *pcszFlags;
|
---|
| 345 | } GUESTPROPHOSTCALLBACKDATA;
|
---|
| 346 | /** Poitner to a data structure to pass to the service extension callback. */
|
---|
| 347 | typedef GUESTPROPHOSTCALLBACKDATA *PGUESTPROPHOSTCALLBACKDATA;
|
---|
[13376] | 348 |
|
---|
[70058] | 349 | /** Magic number for sanity checking the HOSTCALLBACKDATA structure */
|
---|
| 350 | #define GUESTPROPHOSTCALLBACKDATA_MAGIC UINT32_C(0x69c87a78)
|
---|
[13376] | 351 |
|
---|
| 352 | /**
|
---|
[9727] | 353 | * HGCM parameter structures. Packing is explicitly defined as this is a wire format.
|
---|
| 354 | */
|
---|
[10797] | 355 | /** The guest is requesting the value of a property */
|
---|
[70061] | 356 | typedef struct GuestPropMsgGetProperty
|
---|
[9727] | 357 | {
|
---|
[68550] | 358 | VBGLIOCHGCMCALL hdr;
|
---|
[9727] | 359 |
|
---|
| 360 | /**
|
---|
[10797] | 361 | * The property name (IN pointer)
|
---|
[9727] | 362 | * This must fit to a number of criteria, namely
|
---|
[10797] | 363 | * - Only Utf8 strings are allowed
|
---|
| 364 | * - Less than or equal to MAX_NAME_LEN bytes in length
|
---|
[9727] | 365 | * - Zero terminated
|
---|
| 366 | */
|
---|
[10797] | 367 | HGCMFunctionParameter name;
|
---|
[9727] | 368 |
|
---|
| 369 | /**
|
---|
[10797] | 370 | * The returned string data will be placed here. (OUT pointer)
|
---|
| 371 | * This call returns two null-terminated strings which will be placed one
|
---|
| 372 | * after another: value and flags.
|
---|
[9727] | 373 | */
|
---|
[10797] | 374 | HGCMFunctionParameter buffer;
|
---|
[9727] | 375 |
|
---|
| 376 | /**
|
---|
[10797] | 377 | * The property timestamp. (OUT uint64_t)
|
---|
| 378 | */
|
---|
| 379 | HGCMFunctionParameter timestamp;
|
---|
| 380 |
|
---|
| 381 | /**
|
---|
| 382 | * If the buffer provided was large enough this will contain the size of
|
---|
| 383 | * the returned data. Otherwise it will contain the size of the buffer
|
---|
| 384 | * needed to hold the data and VERR_BUFFER_OVERFLOW will be returned.
|
---|
[9882] | 385 | * (OUT uint32_t)
|
---|
[9727] | 386 | */
|
---|
| 387 | HGCMFunctionParameter size;
|
---|
[70061] | 388 | } GuestPropMsgGetProperty;
|
---|
| 389 | AssertCompileSize(GuestPropMsgGetProperty, 40 + 4 * (ARCH_BITS == 64 ? 16 : 12));
|
---|
[9727] | 390 |
|
---|
[10797] | 391 | /** The guest is requesting to change a property */
|
---|
[70061] | 392 | typedef struct GuestPropMsgSetProperty
|
---|
[9727] | 393 | {
|
---|
[68550] | 394 | VBGLIOCHGCMCALL hdr;
|
---|
[9727] | 395 |
|
---|
| 396 | /**
|
---|
[13159] | 397 | * The property name. (IN pointer)
|
---|
[10797] | 398 | * This must fit to a number of criteria, namely
|
---|
| 399 | * - Only Utf8 strings are allowed
|
---|
| 400 | * - Less than or equal to MAX_NAME_LEN bytes in length
|
---|
[9727] | 401 | * - Zero terminated
|
---|
| 402 | */
|
---|
[10797] | 403 | HGCMFunctionParameter name;
|
---|
[9727] | 404 |
|
---|
| 405 | /**
|
---|
[10797] | 406 | * The value of the property (IN pointer)
|
---|
[13159] | 407 | * Criteria as for the name parameter, but with length less than or equal to
|
---|
[13995] | 408 | * MAX_VALUE_LEN.
|
---|
[9727] | 409 | */
|
---|
| 410 | HGCMFunctionParameter value;
|
---|
[10003] | 411 |
|
---|
[10797] | 412 | /**
|
---|
| 413 | * The property flags (IN pointer)
|
---|
| 414 | * This is a comma-separated list of the format flag=value
|
---|
[70222] | 415 | * The length must be less than or equal to GUEST_PROP_MAX_FLAGS_LEN and only
|
---|
[10797] | 416 | * known flag names and values will be accepted.
|
---|
| 417 | */
|
---|
| 418 | HGCMFunctionParameter flags;
|
---|
[70061] | 419 | } GuestPropMsgSetProperty;
|
---|
| 420 | AssertCompileSize(GuestPropMsgSetProperty, 40 + 3 * (ARCH_BITS == 64 ? 16 : 12));
|
---|
[10797] | 421 |
|
---|
| 422 | /** The guest is requesting to change the value of a property */
|
---|
[70061] | 423 | typedef struct GuestPropMsgSetPropertyValue
|
---|
[10003] | 424 | {
|
---|
[68550] | 425 | VBGLIOCHGCMCALL hdr;
|
---|
[10003] | 426 |
|
---|
| 427 | /**
|
---|
[13159] | 428 | * The property name. (IN pointer)
|
---|
[10797] | 429 | * This must fit to a number of criteria, namely
|
---|
| 430 | * - Only Utf8 strings are allowed
|
---|
| 431 | * - Less than or equal to MAX_NAME_LEN bytes in length
|
---|
[10003] | 432 | * - Zero terminated
|
---|
| 433 | */
|
---|
[10797] | 434 | HGCMFunctionParameter name;
|
---|
| 435 |
|
---|
| 436 | /**
|
---|
| 437 | * The value of the property (IN pointer)
|
---|
[13159] | 438 | * Criteria as for the name parameter, but with length less than or equal to
|
---|
[13995] | 439 | * MAX_VALUE_LEN.
|
---|
[10797] | 440 | */
|
---|
| 441 | HGCMFunctionParameter value;
|
---|
[70061] | 442 | } GuestPropMsgSetPropertyValue;
|
---|
| 443 | AssertCompileSize(GuestPropMsgSetPropertyValue, 40 + 2 * (ARCH_BITS == 64 ? 16 : 12));
|
---|
[10797] | 444 |
|
---|
| 445 | /** The guest is requesting to remove a property */
|
---|
[70061] | 446 | typedef struct GuestPropMsgDelProperty
|
---|
[10797] | 447 | {
|
---|
[68550] | 448 | VBGLIOCHGCMCALL hdr;
|
---|
[10797] | 449 |
|
---|
| 450 | /**
|
---|
| 451 | * The property name. This must fit to a number of criteria, namely
|
---|
| 452 | * - Only Utf8 strings are allowed
|
---|
| 453 | * - Less than or equal to MAX_NAME_LEN bytes in length
|
---|
| 454 | * - Zero terminated
|
---|
| 455 | */
|
---|
| 456 | HGCMFunctionParameter name;
|
---|
[70061] | 457 | } GuestPropMsgDelProperty;
|
---|
| 458 | AssertCompileSize(GuestPropMsgDelProperty, 40 + 1 * (ARCH_BITS == 64 ? 16 : 12));
|
---|
[10797] | 459 |
|
---|
| 460 | /** The guest is requesting to enumerate properties */
|
---|
[70061] | 461 | typedef struct GuestPropMsgEnumProperties
|
---|
[10797] | 462 | {
|
---|
[68550] | 463 | VBGLIOCHGCMCALL hdr;
|
---|
[10797] | 464 |
|
---|
| 465 | /**
|
---|
[13558] | 466 | * Array of patterns to match the properties against, separated by '|'
|
---|
[25647] | 467 | * characters. For backwards compatibility, '\\0' is also accepted
|
---|
[13558] | 468 | * as a separater.
|
---|
[10797] | 469 | * (IN pointer)
|
---|
[13558] | 470 | * If only a single, empty pattern is given then match all.
|
---|
[10797] | 471 | */
|
---|
| 472 | HGCMFunctionParameter patterns;
|
---|
| 473 | /**
|
---|
[10929] | 474 | * On success, null-separated array of strings in which the properties are
|
---|
| 475 | * returned. (OUT pointer)
|
---|
[10797] | 476 | * The number of strings in the array is always a multiple of four,
|
---|
| 477 | * and in sequences of name, value, timestamp (hexadecimal string) and the
|
---|
[10929] | 478 | * flags as a comma-separated list in the format "name=value". The list
|
---|
[11040] | 479 | * is terminated by an empty string after a "flags" entry (or at the
|
---|
| 480 | * start).
|
---|
[10797] | 481 | */
|
---|
| 482 | HGCMFunctionParameter strings;
|
---|
[10929] | 483 | /**
|
---|
| 484 | * On success, the size of the returned data. If the buffer provided is
|
---|
| 485 | * too small, the size of buffer needed. (OUT uint32_t)
|
---|
| 486 | */
|
---|
| 487 | HGCMFunctionParameter size;
|
---|
[70061] | 488 | } GuestPropMsgEnumProperties;
|
---|
| 489 | AssertCompileSize(GuestPropMsgEnumProperties, 40 + 3 * (ARCH_BITS == 64 ? 16 : 12));
|
---|
[13916] | 490 |
|
---|
| 491 | /**
|
---|
[14104] | 492 | * The guest is polling for notifications on changes to properties, specifying
|
---|
| 493 | * a set of patterns to match the names of changed properties against and
|
---|
| 494 | * optionally the timestamp of the last notification seen.
|
---|
[13916] | 495 | * On success, VINF_SUCCESS will be returned and the buffer will contain
|
---|
[14104] | 496 | * details of a property notification. If no new notification is available
|
---|
| 497 | * which matches one of the specified patterns, the call will block until one
|
---|
| 498 | * is.
|
---|
[13916] | 499 | * If the last notification could not be found by timestamp, VWRN_NOT_FOUND
|
---|
| 500 | * will be returned and the oldest available notification will be returned.
|
---|
[14104] | 501 | * If a zero timestamp is specified, the call will always wait for a new
|
---|
| 502 | * notification to arrive.
|
---|
[13916] | 503 | * If the buffer supplied was not large enough to hold the notification,
|
---|
| 504 | * VERR_BUFFER_OVERFLOW will be returned and the size parameter will contain
|
---|
| 505 | * the size of the buffer needed.
|
---|
[13971] | 506 | *
|
---|
| 507 | * The protocol for a guest to obtain notifications is to call
|
---|
| 508 | * GET_NOTIFICATION in a loop. On the first call, the ingoing timestamp
|
---|
| 509 | * parameter should be set to zero. On subsequent calls, it should be set to
|
---|
[13995] | 510 | * the outgoing timestamp from the previous call.
|
---|
[13916] | 511 | */
|
---|
[70061] | 512 | typedef struct GuestPropMsgGetNotification
|
---|
[13916] | 513 | {
|
---|
[68550] | 514 | VBGLIOCHGCMCALL hdr;
|
---|
[13916] | 515 |
|
---|
| 516 | /**
|
---|
[14104] | 517 | * A list of patterns to match the guest event name against, separated by
|
---|
| 518 | * vertical bars (|) (IN pointer)
|
---|
| 519 | * An empty string means match all.
|
---|
| 520 | */
|
---|
| 521 | HGCMFunctionParameter patterns;
|
---|
| 522 | /**
|
---|
[13916] | 523 | * The timestamp of the last change seen (IN uint64_t)
|
---|
| 524 | * This may be zero, in which case the oldest available change will be
|
---|
| 525 | * sent. If the service does not remember an event matching the
|
---|
| 526 | * timestamp, then VWRN_NOT_FOUND will be returned, and the guest should
|
---|
| 527 | * assume that it has missed a certain number of notifications.
|
---|
| 528 | *
|
---|
| 529 | * The timestamp of the change being notified of (OUT uint64_t)
|
---|
[13971] | 530 | * Undefined on failure.
|
---|
[13916] | 531 | */
|
---|
| 532 | HGCMFunctionParameter timestamp;
|
---|
| 533 |
|
---|
| 534 | /**
|
---|
[13971] | 535 | * The returned data, if any, will be placed here. (OUT pointer)
|
---|
[13916] | 536 | * This call returns three null-terminated strings which will be placed
|
---|
| 537 | * one after another: name, value and flags. For a delete notification,
|
---|
| 538 | * value and flags will be empty strings. Undefined on failure.
|
---|
| 539 | */
|
---|
| 540 | HGCMFunctionParameter buffer;
|
---|
| 541 |
|
---|
| 542 | /**
|
---|
| 543 | * On success, the size of the returned data. (OUT uint32_t)
|
---|
| 544 | * On buffer overflow, the size of the buffer needed to hold the data.
|
---|
| 545 | * Undefined on failure.
|
---|
| 546 | */
|
---|
| 547 | HGCMFunctionParameter size;
|
---|
[70061] | 548 | } GuestPropMsgGetNotification;
|
---|
| 549 | AssertCompileSize(GuestPropMsgGetNotification, 40 + 4 * (ARCH_BITS == 64 ? 16 : 12));
|
---|
[9727] | 550 |
|
---|
| 551 |
|
---|
[76585] | 552 | #endif /* !VBOX_INCLUDED_HostServices_GuestPropertySvc_h */
|
---|
[37980] | 553 |
|
---|