GuestPropertySvc.h revision becc792d9dba0285c944cac07a3bc4571d155e76
45e9809aff7304721fddb95654901b32195c9c7avboxsync/** @file
45e9809aff7304721fddb95654901b32195c9c7avboxsync * Guest property service:
45e9809aff7304721fddb95654901b32195c9c7avboxsync * Common header for host service and guest clients.
45e9809aff7304721fddb95654901b32195c9c7avboxsync */
45e9809aff7304721fddb95654901b32195c9c7avboxsync
45e9809aff7304721fddb95654901b32195c9c7avboxsync/*
45e9809aff7304721fddb95654901b32195c9c7avboxsync * Copyright (C) 2006-2007 Sun Microsystems, Inc.
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
45e9809aff7304721fddb95654901b32195c9c7avboxsync * available from http://www.virtualbox.org. This file is free software;
45e9809aff7304721fddb95654901b32195c9c7avboxsync * you can redistribute it and/or modify it under the terms of the GNU
45e9809aff7304721fddb95654901b32195c9c7avboxsync * General Public License (GPL) as published by the Free Software
45e9809aff7304721fddb95654901b32195c9c7avboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
45e9809aff7304721fddb95654901b32195c9c7avboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
45e9809aff7304721fddb95654901b32195c9c7avboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * The contents of this file may alternatively be used under the terms
45e9809aff7304721fddb95654901b32195c9c7avboxsync * of the Common Development and Distribution License Version 1.0
45e9809aff7304721fddb95654901b32195c9c7avboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
45e9809aff7304721fddb95654901b32195c9c7avboxsync * VirtualBox OSE distribution, in which case the provisions of the
45e9809aff7304721fddb95654901b32195c9c7avboxsync * CDDL are applicable instead of those of the GPL.
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * You may elect to license modified versions of this file under the
45e9809aff7304721fddb95654901b32195c9c7avboxsync * terms and conditions of either the GPL or the CDDL or both.
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
45e9809aff7304721fddb95654901b32195c9c7avboxsync * Clara, CA 95054 USA or visit http://www.sun.com if you need
45e9809aff7304721fddb95654901b32195c9c7avboxsync * additional information or have any questions.
45e9809aff7304721fddb95654901b32195c9c7avboxsync */
45e9809aff7304721fddb95654901b32195c9c7avboxsync
45e9809aff7304721fddb95654901b32195c9c7avboxsync#ifndef ___VBox_HostService_GuestPropertyService_h
45e9809aff7304721fddb95654901b32195c9c7avboxsync#define ___VBox_HostService_GuestPropertyService_h
45e9809aff7304721fddb95654901b32195c9c7avboxsync
45e9809aff7304721fddb95654901b32195c9c7avboxsync#include <VBox/types.h>
45e9809aff7304721fddb95654901b32195c9c7avboxsync#include <VBox/VBoxGuest.h>
45e9809aff7304721fddb95654901b32195c9c7avboxsync#include <VBox/hgcmsvc.h>
45e9809aff7304721fddb95654901b32195c9c7avboxsync#include <VBox/log.h>
45e9809aff7304721fddb95654901b32195c9c7avboxsync#include <iprt/assert.h>
45e9809aff7304721fddb95654901b32195c9c7avboxsync
45e9809aff7304721fddb95654901b32195c9c7avboxsync#include <string.h>
45e9809aff7304721fddb95654901b32195c9c7avboxsync
45e9809aff7304721fddb95654901b32195c9c7avboxsync#ifdef RT_OS_WINDOWS
45e9809aff7304721fddb95654901b32195c9c7avboxsync# define strncasecmp strnicmp
45e9809aff7304721fddb95654901b32195c9c7avboxsync#endif
45e9809aff7304721fddb95654901b32195c9c7avboxsync
45e9809aff7304721fddb95654901b32195c9c7avboxsync/** Everything defined in this file lives in this namespace. */
45e9809aff7304721fddb95654901b32195c9c7avboxsyncnamespace guestProp {
/******************************************************************************
* Typedefs, constants and inlines *
******************************************************************************/
/** Maximum length for property names */
enum { MAX_NAME_LEN = 64 };
/** Maximum length for property values */
enum { MAX_VALUE_LEN = 128 };
/** Maximum number of properties per guest */
enum { MAX_PROPS = 256 };
/** Maximum size for enumeration patterns */
enum { MAX_PATTERN_LEN = 1024 };
/**
* The guest property flag values which are currently accepted.
*/
enum ePropFlags
{
NILFLAG = 0,
TRANSIENT = RT_BIT(1),
HOSTWRITE = RT_BIT(2),
GUESTWRITE = RT_BIT(3),
READONLY = RT_BIT(4)
};
/**
* A structure to map the guest property flag values to names. I know it is
* ugly to have constants inline, but it has to be accessible in different
* modules and it does not seem reasonable to put it into its own library.
*/
const struct
{
/** The flag value */
uint32_t fFlag;
/** And the name of the flag */
const char *pcszName;
} flagNames[] =
{
{ TRANSIENT, "TRANSIENT" },
{ HOSTWRITE, "HOSTWRITE" },
{ GUESTWRITE, "GUESTWRITE" },
{ READONLY, "READONLY" },
{ NILFLAG, NULL }
};
/** Maximum length for the property flags field */
enum { MAX_FLAGS_LEN = sizeof(flagNames[0]) + 2 /* + 2 for ", " */
+ sizeof(flagNames[1]) + 2
+ sizeof(flagNames[2]) + 2
+ sizeof(flagNames[3]) + 1 /* + 1 for '\0' */
};
/**
* Parse a guest properties flags string for the flags in flagNames.
* @returns IPRT status code
* @returns VERR_INVALID_PARAM 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) validateFlags(const char *pcszFlags, uint32_t *pfFlags)
{
const char *pcszNext = pcszFlags;
int rc = VINF_SUCCESS;
uint32_t fFlags = 0;
AssertLogRelReturn(VALID_PTR(pfFlags), VERR_INVALID_POINTER);
AssertLogRelReturn(VALID_PTR(pcszFlags), VERR_INVALID_POINTER);
while (' ' == *pcszNext)
++pcszNext;
while ((*pcszNext != '\0') && RT_SUCCESS(rc))
{
int i = 0;
for (; flagNames[i].fFlag != NILFLAG; ++i)
if (strncasecmp(pcszNext, flagNames[i].pcszName,
strlen(flagNames[i].pcszName)) == 0)
break;
if (NILFLAG == flagNames[i].fFlag)
rc = VERR_INVALID_PARAMETER;
else
{
fFlags |= flagNames[i].fFlag;
pcszNext += strlen(flagNames[i].pcszName);
}
while (' ' == *pcszNext)
++pcszNext;
if (',' == *pcszNext)
++pcszNext;
while (' ' == *pcszNext)
++pcszNext;
}
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) MAX_FLAGS_LEN + 1.
*/
DECLINLINE(int) writeFlags(uint32_t fFlags, char *pszFlags)
{
char *pszNext = pszFlags;
int rc = VINF_SUCCESS;
AssertLogRelReturn(VALID_PTR(pszFlags), VERR_INVALID_POINTER);
int i = 0;
for (; flagNames[i].fFlag != NILFLAG; ++i)
{
if (fFlags & flagNames[i].fFlag)
{
strcpy(pszNext, flagNames[i].pcszName);
pszNext += strlen(flagNames[i].pcszName);
fFlags &= ~flagNames[i].fFlag;
if ((flagNames[i + 1].fFlag != NILFLAG) && (fFlags != NILFLAG))
{
strcpy(pszNext, ", ");
pszNext += 2;
}
}
}
*pszNext = '\0';
if (fFlags != NILFLAG)
rc = VERR_INVALID_PARAMETER; /* But pszFlags will still be set right. */
return rc;
}
/*
* The service functions which are callable by host.
*/
enum eHostFn
{
/** Pass the address of the cfgm node used by the service as a database. */
SET_CFGM_NODE = 1,
/**
* Get the value attached to a guest property
* The parameter format matches that of GET_PROP.
*/
GET_PROP_HOST = 2,
/**
* Set the value attached to a guest property
* The parameter format matches that of SET_PROP.
*/
SET_PROP_HOST = 3,
/**
* Set the value attached to a guest property
* The parameter format matches that of SET_PROP_VALUE.
*/
SET_PROP_VALUE_HOST = 4,
/**
* Remove a guest property.
* The parameter format matches that of DEL_PROP.
*/
DEL_PROP_HOST = 5,
/**
* Enumerate guest properties.
* The parameter format matches that of ENUM_PROPS.
*/
ENUM_PROPS_HOST = 6
};
/**
* The service functions which are called by guest. The numbers may not change,
* so we hardcode them.
*/
enum eGuestFn
{
/** Get a guest property */
GET_PROP = 1,
/** Set a guest property */
SET_PROP = 2,
/** Set just the value of a guest property */
SET_PROP_VALUE = 3,
/** Delete a guest property */
DEL_PROP = 4,
/** Enumerate guest properties */
ENUM_PROPS = 5
};
/**
* Data structure to pass to the service extension callback. We use this to
* notify the host of changes to properties.
*/
typedef struct _HOSTCALLBACKDATA
{
/** Magic number to identify the structure */
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;
} HOSTCALLBACKDATA, *PHOSTCALLBACKDATA;
enum
{
/** Magic number for sanity checking the HOSTCALLBACKDATA structure */
HOSTCALLBACKMAGIC = 0x69c87a78
};
/**
* HGCM parameter structures. Packing is explicitly defined as this is a wire format.
*/
#pragma pack (1)
/** The guest is requesting the value of a property */
typedef struct _GetProperty
{
VBoxGuestHGCMCallInfo 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;
} GetProperty;
/** The guest is requesting to change a property */
typedef struct _SetProperty
{
VBoxGuestHGCMCallInfo 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 MAX_FLAGS_LEN and only
* known flag names and values will be accepted.
*/
HGCMFunctionParameter flags;
} SetProperty;
/** The guest is requesting to change the value of a property */
typedef struct _SetPropertyValue
{
VBoxGuestHGCMCallInfo 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;
} SetPropertyValue;
/** The guest is requesting to remove a property */
typedef struct _DelProperty
{
VBoxGuestHGCMCallInfo 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;
} DelProperty;
/** The guest is requesting to enumerate properties */
typedef struct _EnumProperties
{
VBoxGuestHGCMCallInfo hdr;
/**
* Null-separated array of patterns to match the properties against.
* (IN pointer)
* If no patterns are given then return all. The list is terminated by an
* empty string.
*/
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;
} EnumProperties;
#pragma pack ()
} /* namespace guestProp */
#endif /* ___VBox_HostService_GuestPropertySvc_h defined */