GuestPropertySvc.h revision d10b594ea1bfbfb3dbd7132080ab860abe618cb4
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * Guest property service:
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * Common header for host service and guest clients.
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * Copyright (C) 2006-2007 Sun Microsystems, Inc.
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 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * Clara, CA 95054 USA or visit http://www.sun.com if you need
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * additional information or have any questions.
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync/** Everything defined in this file lives in this namespace. */
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * The service functions which are callable by host.
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync /** Pass the address of the cfgm node used by the service as a database. */
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * Get the value attached to a configuration property key
b67986b52286959154244a144c62c9f40091fbbbvboxsync * The parameter format matches that of GET_PROP.
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * Set the value attached to a configuration property key
b67986b52286959154244a144c62c9f40091fbbbvboxsync * The parameter format matches that of SET_PROP.
b67986b52286959154244a144c62c9f40091fbbbvboxsync * Set the value attached to a configuration property key
b67986b52286959154244a144c62c9f40091fbbbvboxsync * The parameter format matches that of SET_PROP_VALUE.
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * Remove the value attached to a configuration property key
b67986b52286959154244a144c62c9f40091fbbbvboxsync * The parameter format matches that of DEL_PROP.
3b6727bcf40d710e50ad98533cc3f05adaae0226vboxsync * Enumerate guest properties.
3b6727bcf40d710e50ad98533cc3f05adaae0226vboxsync * The parameter format matches that of ENUM_PROPS.
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 */
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync/** Prefix for extra data keys used by the get and set key value functions */
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync/** Helper macro for the length of the prefix VBOX_SHARED_INFO_KEY_PREFIX */
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync#define VBOX_SHARED_INFO_PREFIX_LEN (sizeof(VBOX_SHARED_INFO_KEY_PREFIX) - 1)
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync/** Maximum length for property names */
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync/** Maximum length for property values */
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync/** Maximum length for extra data key values used by the get and set key value functions */
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync/** Maximum number of properties per guest */
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * HGCM parameter structures. Packing is explicitly defined as this is a wire format.
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync/** The guest is requesting the value of a property */
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsynctypedef struct _GetProperty
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 */
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsynctypedef struct _SetProperty
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * The property key. (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)
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * Criteria as for the key parameter, but with length less than or equal to
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * 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 */
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * The property key. (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)
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * Criteria as for the key parameter, but with length less than or equal to
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * MAX_VALUE_LEN.
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync/** The guest is requesting to remove a property */
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsynctypedef struct _DelProperty
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 */
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * Null-separated array of patterns to match the properties against.
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync * (IN pointer)
241541868b26b18d777209f5e6c2c0c6ad9d02eevboxsync * If no patterns are given then return all. The list is terminated by an
241541868b26b18d777209f5e6c2c0c6ad9d02eevboxsync * empty string.
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)
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync} /* namespace guestProp */
3c3a5ab35783f4d31cb5d3a15db9daadeb804daavboxsync#endif /* ___VBox_HostService_GuestPropertySvc_h defined */