3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * Guest property service:
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * Common header for host service and guest clients.
c58f1213e628a545081c70e26c6b67a841cff880vboxsync * Copyright (C) 2006-2012 Oracle Corporation
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * available from http://www.virtualbox.org. This file is free software;
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * you can redistribute it and/or modify it under the terms of the GNU
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * General Public License (GPL) as published by the Free Software
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
d10b594ea1bfbfb3dbd7132080ab860abe618cb4vboxsync * The contents of this file may alternatively be used under the terms
d10b594ea1bfbfb3dbd7132080ab860abe618cb4vboxsync * of the Common Development and Distribution License Version 1.0
d10b594ea1bfbfb3dbd7132080ab860abe618cb4vboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
d10b594ea1bfbfb3dbd7132080ab860abe618cb4vboxsync * VirtualBox OSE distribution, in which case the provisions of the
d10b594ea1bfbfb3dbd7132080ab860abe618cb4vboxsync * CDDL are applicable instead of those of the GPL.
d10b594ea1bfbfb3dbd7132080ab860abe618cb4vboxsync * You may elect to license modified versions of this file under the
d10b594ea1bfbfb3dbd7132080ab860abe618cb4vboxsync * terms and conditions of either the GPL or the CDDL or both.
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync/** Everything defined in this file lives in this namespace. */
2f46a509fa35214396aedb4012d33b73fb4d6ec0vboxsync/******************************************************************************
2f46a509fa35214396aedb4012d33b73fb4d6ec0vboxsync* Typedefs, constants and inlines *
2f46a509fa35214396aedb4012d33b73fb4d6ec0vboxsync******************************************************************************/
2f46a509fa35214396aedb4012d33b73fb4d6ec0vboxsync/** Maximum length for property names */
2f46a509fa35214396aedb4012d33b73fb4d6ec0vboxsync/** Maximum length for property values */
2f46a509fa35214396aedb4012d33b73fb4d6ec0vboxsync/** Maximum number of properties per guest */
54ae7b69a9aa4256e14122eaf595699d312cf901vboxsync/** Maximum size for enumeration patterns */
d134558e26d3744503b2dbe50a75bcd3fa678432vboxsync/** Maximum number of changes we remember for guest notifications */
2f46a509fa35214396aedb4012d33b73fb4d6ec0vboxsync * The guest property flag values which are currently accepted.
dae86d7bd26c4030c4cfa21231757d1a12f50bf8vboxsync /** Transient until VM gets shut down. */
dae86d7bd26c4030c4cfa21231757d1a12f50bf8vboxsync /** Transient until VM gets a reset / restarts.
dae86d7bd26c4030c4cfa21231757d1a12f50bf8vboxsync * Implies TRANSIENT. */
ba5dd00fabaa3475fa5da200d134c73f1c961b49vboxsync * Get the name of a flag as a string.
ba5dd00fabaa3475fa5da200d134c73f1c961b49vboxsync * @returns the name, or NULL if fFlag is invalid.
ba5dd00fabaa3475fa5da200d134c73f1c961b49vboxsync * @param fFlag the flag. Must be a value from the ePropFlags enumeration
ba5dd00fabaa3475fa5da200d134c73f1c961b49vboxsync return "TRANSIENT";
ba5dd00fabaa3475fa5da200d134c73f1c961b49vboxsync return "RDONLYGUEST";
ba5dd00fabaa3475fa5da200d134c73f1c961b49vboxsync return "RDONLYHOST";
ba5dd00fabaa3475fa5da200d134c73f1c961b49vboxsync return "READONLY";
dae86d7bd26c4030c4cfa21231757d1a12f50bf8vboxsync return "TRANSRESET";
ba5dd00fabaa3475fa5da200d134c73f1c961b49vboxsync * Get the length of a flag name as returned by flagName.
ba5dd00fabaa3475fa5da200d134c73f1c961b49vboxsync * @returns the length, or 0 if fFlag is invalid.
ba5dd00fabaa3475fa5da200d134c73f1c961b49vboxsync * @param fFlag the flag. Must be a value from the ePropFlags enumeration
ba5dd00fabaa3475fa5da200d134c73f1c961b49vboxsync return RT_LIKELY(pcszName != NULL) ? strlen(pcszName) : 0;
ba5dd00fabaa3475fa5da200d134c73f1c961b49vboxsync * Maximum length for the property flags field. We only ever return one of
ba5dd00fabaa3475fa5da200d134c73f1c961b49vboxsync * RDONLYGUEST, RDONLYHOST and RDONLY
78dc0b94d7cbd4c0d9a7c80614260f72559a12b1vboxsyncenum { MAX_FLAGS_LEN = sizeof("TRANSIENT, RDONLYGUEST, TRANSRESET") };
ba5dd00fabaa3475fa5da200d134c73f1c961b49vboxsync * Parse a guest properties flags string for flag names and make sure that
ba5dd00fabaa3475fa5da200d134c73f1c961b49vboxsync * there is no junk text in the string.
2f46a509fa35214396aedb4012d33b73fb4d6ec0vboxsync * @returns IPRT status code
2f46a509fa35214396aedb4012d33b73fb4d6ec0vboxsync * @returns VERR_INVALID_PARAM if the flag string is not valid
2f46a509fa35214396aedb4012d33b73fb4d6ec0vboxsync * @param pcszFlags the flag string to parse
2f46a509fa35214396aedb4012d33b73fb4d6ec0vboxsync * @param pfFlags where to store the parse result. May not be NULL.
2f46a509fa35214396aedb4012d33b73fb4d6ec0vboxsync * @note This function is also inline because it must be accessible from
2f46a509fa35214396aedb4012d33b73fb4d6ec0vboxsync * several modules and it does not seem reasonable to put it into
2f46a509fa35214396aedb4012d33b73fb4d6ec0vboxsync * its own library.
2f46a509fa35214396aedb4012d33b73fb4d6ec0vboxsyncDECLINLINE(int) validateFlags(const char *pcszFlags, uint32_t *pfFlags)
dae86d7bd26c4030c4cfa21231757d1a12f50bf8vboxsync TRANSIENT, READONLY, RDONLYGUEST, RDONLYHOST, TRANSRESET
2f46a509fa35214396aedb4012d33b73fb4d6ec0vboxsync AssertLogRelReturn(VALID_PTR(pfFlags), VERR_INVALID_POINTER);
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync unsigned i = 0;
2f46a509fa35214396aedb4012d33b73fb4d6ec0vboxsync * Write out flags to a string.
2f46a509fa35214396aedb4012d33b73fb4d6ec0vboxsync * @returns IPRT status code
2f46a509fa35214396aedb4012d33b73fb4d6ec0vboxsync * @param fFlags the flags to write out
2f46a509fa35214396aedb4012d33b73fb4d6ec0vboxsync * @param pszFlags where to write the flags string. This must point to
ba5dd00fabaa3475fa5da200d134c73f1c961b49vboxsync * a buffer of size (at least) MAX_FLAGS_LEN.
2f46a509fa35214396aedb4012d33b73fb4d6ec0vboxsyncDECLINLINE(int) writeFlags(uint32_t fFlags, char *pszFlags)
510c603ab35097ee39fb5b6350d1c4f59d7286e3vboxsync /* Putting READONLY before the other RDONLY flags keeps the result short. */
dae86d7bd26c4030c4cfa21231757d1a12f50bf8vboxsync TRANSIENT, READONLY, RDONLYGUEST, RDONLYHOST, TRANSRESET
2f46a509fa35214396aedb4012d33b73fb4d6ec0vboxsync AssertLogRelReturn(VALID_PTR(pszFlags), VERR_INVALID_POINTER);
06913e4efbdb8192155c00fa59de4174c7a50b57vboxsync /* TRANSRESET implies TRANSIENT. For compatability with old clients we
06913e4efbdb8192155c00fa59de4174c7a50b57vboxsync always set TRANSIENT when TRANSRESET appears. */
06913e4efbdb8192155c00fa59de4174c7a50b57vboxsync for (unsigned i = 0; i < RT_ELEMENTS(s_aFlagList); ++i)
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * The service functions which are callable by host.
84918d5816927c515e57dcafa1f60f6c05241d11vboxsync * Set properties in a block. The parameters are pointers to
ad27e1d5e48ca41245120c331cc88b50464813cevboxsync * NULL-terminated arrays containing the parameters. These are, in order,
84918d5816927c515e57dcafa1f60f6c05241d11vboxsync * name, value, timestamp, flags. Strings are stored as pointers to
84918d5816927c515e57dcafa1f60f6c05241d11vboxsync * mutable utf8 data. All parameters must be supplied.
f0679993bc62dafdcee7dfa8138b5edfdffd8b0evboxsync * Get the value attached to a guest property
f0679993bc62dafdcee7dfa8138b5edfdffd8b0evboxsync * The parameter format matches that of GET_PROP.
f0679993bc62dafdcee7dfa8138b5edfdffd8b0evboxsync * Set the value attached to a guest property
b67986b52286959154244a144c62c9f40091fbbbvboxsync * The parameter format matches that of SET_PROP.
f0679993bc62dafdcee7dfa8138b5edfdffd8b0evboxsync * Set the value attached to a guest property
b67986b52286959154244a144c62c9f40091fbbbvboxsync * The parameter format matches that of SET_PROP_VALUE.
f0679993bc62dafdcee7dfa8138b5edfdffd8b0evboxsync * Remove a guest property.
b67986b52286959154244a144c62c9f40091fbbbvboxsync * The parameter format matches that of DEL_PROP.
3b6727bcf40d710e50ad98533cc3f05adaae0226vboxsync * Enumerate guest properties.
3b6727bcf40d710e50ad98533cc3f05adaae0226vboxsync * The parameter format matches that of ENUM_PROPS.
6e5bfe53da4b5c41db5c5ccdb84d733f2a5817c6vboxsync * Set global flags for the service. Currently RDONLYGUEST is supported.
6e5bfe53da4b5c41db5c5ccdb84d733f2a5817c6vboxsync * Takes one 32-bit unsigned integer parameter for the flags.
7d243573ddd18562ffc1546360a99a762b2b0ca3vboxsync * Return the pointer to a debug info function enumerating all guest properties.
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * The service functions which are called by guest. The numbers may not change,
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * so we hardcode them.
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync /** Get a guest property */
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync /** Set a guest property */
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync /** Set just the value of a guest property */
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync /** Delete a guest property */
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync /** Enumerate guest properties */
d134558e26d3744503b2dbe50a75bcd3fa678432vboxsync /** Poll for guest notifications */
d8ebb1b0155a5f076e545b7a4e52df41608e1c7dvboxsync * Data structure to pass to the service extension callback. We use this to
d8ebb1b0155a5f076e545b7a4e52df41608e1c7dvboxsync * notify the host of changes to properties.
d8ebb1b0155a5f076e545b7a4e52df41608e1c7dvboxsync /** Magic number to identify the structure */
d8ebb1b0155a5f076e545b7a4e52df41608e1c7dvboxsync /** The name of the property that was changed */
d8ebb1b0155a5f076e545b7a4e52df41608e1c7dvboxsync /** The new property value, or NULL if the property was deleted */
d8ebb1b0155a5f076e545b7a4e52df41608e1c7dvboxsync /** The timestamp of the modification */
d8ebb1b0155a5f076e545b7a4e52df41608e1c7dvboxsync /** The flags field of the modified property */
d8ebb1b0155a5f076e545b7a4e52df41608e1c7dvboxsync /** Magic number for sanity checking the HOSTCALLBACKDATA structure */
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * HGCM parameter structures. Packing is explicitly defined as this is a wire format.
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync/** The guest is requesting the value of a property */
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * The property name (IN pointer)
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * This must fit to a number of criteria, namely
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * - Only Utf8 strings are allowed
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * - Less than or equal to MAX_NAME_LEN bytes in length
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * - Zero terminated
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * The returned string data will be placed here. (OUT pointer)
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * This call returns two null-terminated strings which will be placed one
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * after another: value and flags.
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * The property timestamp. (OUT uint64_t)
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * If the buffer provided was large enough this will contain the size of
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * the returned data. Otherwise it will contain the size of the buffer
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * needed to hold the data and VERR_BUFFER_OVERFLOW will be returned.
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * (OUT uint32_t)
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync/** The guest is requesting to change a property */
f0679993bc62dafdcee7dfa8138b5edfdffd8b0evboxsync * The property name. (IN pointer)
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * This must fit to a number of criteria, namely
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * - Only Utf8 strings are allowed
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * - Less than or equal to MAX_NAME_LEN bytes in length
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * - Zero terminated
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * The value of the property (IN pointer)
f0679993bc62dafdcee7dfa8138b5edfdffd8b0evboxsync * Criteria as for the name parameter, but with length less than or equal to
3f2ab411e38c4f9aa3c3c46e8b94a34b4cad280avboxsync * MAX_VALUE_LEN.
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * The property flags (IN pointer)
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * This is a comma-separated list of the format flag=value
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * The length must be less than or equal to MAX_FLAGS_LEN and only
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * known flag names and values will be accepted.
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync/** The guest is requesting to change the value of a property */
f0679993bc62dafdcee7dfa8138b5edfdffd8b0evboxsync * The property name. (IN pointer)
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * This must fit to a number of criteria, namely
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * - Only Utf8 strings are allowed
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * - Less than or equal to MAX_NAME_LEN bytes in length
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * - Zero terminated
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * The value of the property (IN pointer)
f0679993bc62dafdcee7dfa8138b5edfdffd8b0evboxsync * Criteria as for the name parameter, but with length less than or equal to
3f2ab411e38c4f9aa3c3c46e8b94a34b4cad280avboxsync * MAX_VALUE_LEN.
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync/** The guest is requesting to remove a property */
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * The property name. This must fit to a number of criteria, namely
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * - Only Utf8 strings are allowed
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * - Less than or equal to MAX_NAME_LEN bytes in length
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * - Zero terminated
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync/** The guest is requesting to enumerate properties */
0ac96af43d9fb52c8d76d9bf8d7bb3a5021c8a99vboxsync * Array of patterns to match the properties against, separated by '|'
d59a43b735abea2db17caa9b5661d2f5118f0e02vboxsync * characters. For backwards compatibility, '\\0' is also accepted
0ac96af43d9fb52c8d76d9bf8d7bb3a5021c8a99vboxsync * as a separater.
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * (IN pointer)
0ac96af43d9fb52c8d76d9bf8d7bb3a5021c8a99vboxsync * If only a single, empty pattern is given then match all.
241541868b26b18d777209f5e6c2c0c6ad9d02eevboxsync * On success, null-separated array of strings in which the properties are
241541868b26b18d777209f5e6c2c0c6ad9d02eevboxsync * returned. (OUT pointer)
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * The number of strings in the array is always a multiple of four,
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * and in sequences of name, value, timestamp (hexadecimal string) and the
241541868b26b18d777209f5e6c2c0c6ad9d02eevboxsync * flags as a comma-separated list in the format "name=value". The list
c5cae649a77841287fd1e032d8e1e95e996e32cavboxsync * is terminated by an empty string after a "flags" entry (or at the
241541868b26b18d777209f5e6c2c0c6ad9d02eevboxsync * On success, the size of the returned data. If the buffer provided is
241541868b26b18d777209f5e6c2c0c6ad9d02eevboxsync * too small, the size of buffer needed. (OUT uint32_t)
2c52e7e2789d2c331230be72d9cf783a6fbf86b9vboxsync * The guest is polling for notifications on changes to properties, specifying
2c52e7e2789d2c331230be72d9cf783a6fbf86b9vboxsync * a set of patterns to match the names of changed properties against and
2c52e7e2789d2c331230be72d9cf783a6fbf86b9vboxsync * optionally the timestamp of the last notification seen.
d134558e26d3744503b2dbe50a75bcd3fa678432vboxsync * On success, VINF_SUCCESS will be returned and the buffer will contain
2c52e7e2789d2c331230be72d9cf783a6fbf86b9vboxsync * details of a property notification. If no new notification is available
2c52e7e2789d2c331230be72d9cf783a6fbf86b9vboxsync * which matches one of the specified patterns, the call will block until one
d134558e26d3744503b2dbe50a75bcd3fa678432vboxsync * If the last notification could not be found by timestamp, VWRN_NOT_FOUND
d134558e26d3744503b2dbe50a75bcd3fa678432vboxsync * will be returned and the oldest available notification will be returned.
2c52e7e2789d2c331230be72d9cf783a6fbf86b9vboxsync * If a zero timestamp is specified, the call will always wait for a new
2c52e7e2789d2c331230be72d9cf783a6fbf86b9vboxsync * notification to arrive.
d134558e26d3744503b2dbe50a75bcd3fa678432vboxsync * If the buffer supplied was not large enough to hold the notification,
d134558e26d3744503b2dbe50a75bcd3fa678432vboxsync * VERR_BUFFER_OVERFLOW will be returned and the size parameter will contain
d134558e26d3744503b2dbe50a75bcd3fa678432vboxsync * the size of the buffer needed.
34cd76de9b73367dfe5a4055585d2a5bb5d980a4vboxsync * The protocol for a guest to obtain notifications is to call
34cd76de9b73367dfe5a4055585d2a5bb5d980a4vboxsync * GET_NOTIFICATION in a loop. On the first call, the ingoing timestamp
34cd76de9b73367dfe5a4055585d2a5bb5d980a4vboxsync * parameter should be set to zero. On subsequent calls, it should be set to
3f2ab411e38c4f9aa3c3c46e8b94a34b4cad280avboxsync * the outgoing timestamp from the previous call.
2c52e7e2789d2c331230be72d9cf783a6fbf86b9vboxsync * A list of patterns to match the guest event name against, separated by
2c52e7e2789d2c331230be72d9cf783a6fbf86b9vboxsync * vertical bars (|) (IN pointer)
2c52e7e2789d2c331230be72d9cf783a6fbf86b9vboxsync * An empty string means match all.
d134558e26d3744503b2dbe50a75bcd3fa678432vboxsync * The timestamp of the last change seen (IN uint64_t)
d134558e26d3744503b2dbe50a75bcd3fa678432vboxsync * This may be zero, in which case the oldest available change will be
d134558e26d3744503b2dbe50a75bcd3fa678432vboxsync * sent. If the service does not remember an event matching the
d134558e26d3744503b2dbe50a75bcd3fa678432vboxsync * timestamp, then VWRN_NOT_FOUND will be returned, and the guest should
d134558e26d3744503b2dbe50a75bcd3fa678432vboxsync * assume that it has missed a certain number of notifications.
d134558e26d3744503b2dbe50a75bcd3fa678432vboxsync * The timestamp of the change being notified of (OUT uint64_t)
34cd76de9b73367dfe5a4055585d2a5bb5d980a4vboxsync * Undefined on failure.
34cd76de9b73367dfe5a4055585d2a5bb5d980a4vboxsync * The returned data, if any, will be placed here. (OUT pointer)
d134558e26d3744503b2dbe50a75bcd3fa678432vboxsync * This call returns three null-terminated strings which will be placed
d134558e26d3744503b2dbe50a75bcd3fa678432vboxsync * one after another: name, value and flags. For a delete notification,
d134558e26d3744503b2dbe50a75bcd3fa678432vboxsync * value and flags will be empty strings. Undefined on failure.
d134558e26d3744503b2dbe50a75bcd3fa678432vboxsync * On success, the size of the returned data. (OUT uint32_t)
d134558e26d3744503b2dbe50a75bcd3fa678432vboxsync * On buffer overflow, the size of the buffer needed to hold the data.
d134558e26d3744503b2dbe50a75bcd3fa678432vboxsync * Undefined on failure.
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync} /* namespace guestProp */
78059d96be5135e6d982902bab76b24f26b5ec3fvboxsync#endif /* !___VBox_HostService_GuestPropertySvc_h */