VirtualBox

Changeset 10797 in vbox for trunk/include


Ignore:
Timestamp:
Jul 22, 2008 8:12:42 AM (17 years ago)
Author:
vboxsync
Message:

Guest properties: initial commit of new interface

Location:
trunk/include/VBox
Files:
1 edited
1 moved

Legend:

Unmodified
Added
Removed

  • trunk/include/VBox/HostServices/GuestPropertySvc.h

    r10665 r10797  
    11/** @file
    2  * Shared information services:
     2 * Guest property service:
    33 * Common header for host service and guest clients.
    44 */
    … …  
    2020 */
    2121
    22 #ifndef ___VBox_HostService_VBoxSharedInfoSvc_h
    23 #define ___VBox_HostService_VBoxSharedInfoSvc_h
     22#ifndef ___VBox_HostService_GuestPropertyService_h
     23#define ___VBox_HostService_GuestPropertyService_h
    2424
    2525#include <VBox/types.h>
    … …  
    2828
    2929/** Everything defined in this file lives in this namespace. */
    30 namespace svcInfo {
     30namespace guestProp {
    3131
    3232/*
    … …  
    3535enum eHostFn
    3636{
    37     /** Pass the address of the console object from Main to the service */
     37    /** Pass the address of the cfgm node used by the service as a database. */
    3838    SET_CFGM_NODE = 1,
    3939    /**
    … …  
    6060enum eGuestFn
    6161{
    62     /** Get the value attached to a configuration property key */
    63     GET_CONFIG_KEY = 1,
    64     /** Set the value attached to a configuration property key */
    65     SET_CONFIG_KEY = 2,
    66     /** Remove the value attached to a configuration property key */
    67     DEL_CONFIG_KEY = 3
     62    /** Get a guest property */
     63    GET_PROP = 1,
     64    /** Set a guest property */
     65    SET_PROP = 2,
     66    /** Set just the value of a guest property */
     67    SET_PROP_VALUE = 3,
     68    /** Delete a guest property */
     69    DEL_PROP = 4,
     70    /** Enumerate guest properties */
     71    ENUM_PROPS = 5
    6872};
    6973
    … …  
    7276/** Helper macro for the length of the prefix VBOX_SHARED_INFO_KEY_PREFIX */
    7377#define VBOX_SHARED_INFO_PREFIX_LEN          (sizeof(VBOX_SHARED_INFO_KEY_PREFIX) - 1)
    74 /** Maximum length for extra data keys used by the get and set key value functions */
    75 enum { KEY_MAX_LEN = 64 };
     78/** Maximum length for property names */
     79enum { MAX_NAME_LEN = 64 };
     80/** Maximum length for property values */
     81enum { MAX_VALUE_LEN = 128 };
    7682/** Maximum length for extra data key values used by the get and set key value functions */
    77 enum { KEY_MAX_VALUE_LEN = 128 };
    78 /** Maximum number of extra data keys per guest */
    79 enum { KEY_MAX_KEYS = 256 };
     83enum { MAX_FLAGS_LEN = 128 };
     84/** Maximum number of properties per guest */
     85enum { MAX_KEYS = 256 };
    8086
    8187/**
    … …  
    8389 */
    8490#pragma pack (1)
    85 /** The guest is requesting the value of a configuration key */
    86 typedef struct _GetConfigKey
    87 {
    88     VBoxGuestHGCMCallInfo hdr;
    89 
    90     /**
    91      * The key to look up (IN pointer)
     91/** The guest is requesting the value of a property */
     92typedef struct _GetProperty
     93{
     94    VBoxGuestHGCMCallInfo hdr;
     95
     96    /**
     97     * The property name (IN pointer)
    9298     * This must fit to a number of criteria, namely
    93      *  - Only ASCII characters with no spaces
    94      *  - Less than or equal to VBOX_SHARED_INFO_KEY_MAX_LEN bytes in length
    95      *  - Zero terminated
    96      */
    97     HGCMFunctionParameter key;
    98 
    99     /**
    100      * The value of the key (OUT pointer)
     99     *  - Only Utf8 strings are allowed
     100     *  - Less than or equal to MAX_NAME_LEN bytes in length
     101     *  - Zero terminated
     102     */
     103    HGCMFunctionParameter name;
     104
     105    /**
     106     * The returned string data will be placed here.  (OUT pointer)
     107     * This call returns two null-terminated strings which will be placed one
     108     * after another: value and flags.
     109     */
     110    HGCMFunctionParameter buffer;
     111
     112    /**
     113     * The property timestamp.  (OUT uint64_t)
     114     */
     115
     116    HGCMFunctionParameter timestamp;
     117
     118    /**
     119     * If the buffer provided was large enough this will contain the size of
     120     * the returned data.  Otherwise it will contain the size of the buffer
     121     * needed to hold the data and VERR_BUFFER_OVERFLOW will be returned.
     122     * (OUT uint32_t)
     123     */
     124    HGCMFunctionParameter size;
     125} GetProperty;
     126
     127/** The guest is requesting to change a property */
     128typedef struct _SetProperty
     129{
     130    VBoxGuestHGCMCallInfo hdr;
     131
     132    /**
     133     * The property key.  (IN pointer)
     134     * This must fit to a number of criteria, namely
     135     *  - Only Utf8 strings are allowed
     136     *  - Less than or equal to MAX_NAME_LEN bytes in length
     137     *  - Zero terminated
     138     */
     139    HGCMFunctionParameter name;
     140
     141    /**
     142     * The value of the property (IN pointer)
     143     * Criteria as for the key parameter, but with length less than or equal to
     144     * MAX_VALUE_LEN. 
    101145     */
    102146    HGCMFunctionParameter value;
    103147
    104148    /**
    105      * The size of the value.  If this is greater than the size of the array
    106      * supplied in the second parameter then no data was transferred and the
    107      * call must be repeated.  If it is zero then no value was found.
    108      * (OUT uint32_t)
    109      */
    110     HGCMFunctionParameter size;
    111 } GetConfigKey;
    112 
    113 /** The guest is requesting to change the value of a configuration key */
    114 typedef struct _SetConfigKey
    115 {
    116     VBoxGuestHGCMCallInfo hdr;
    117 
    118     /**
    119      * The key to change up.  This must fit to a number of criteria, namely
    120      *  - Only ASCII characters with no spaces
    121      *  - Less than or equal to VBOX_SHARED_INFO_KEY_MAX_LEN bytes in length
    122      *  - Zero terminated
    123      */
    124     HGCMFunctionParameter key;
    125 
    126     /**
    127      * The value of the key (IN pointer)
    128      * Criteria as for the key parameter, but with length less that or equal to
    129      * VBOX_SHARED_INFO_KEY_MAX_VALUE_LEN.  A null pointer causes the value to
    130      * be removed from the database.
     149     * The property flags (IN pointer)
     150     * This is a comma-separated list of the format flag=value
     151     * The length must be less than or equal to MAX_FLAGS_LEN and only
     152     * known flag names and values will be accepted.
     153     */
     154    HGCMFunctionParameter flags;
     155} SetProperty;
     156
     157/** The guest is requesting to change the value of a property */
     158typedef struct _SetPropertyValue
     159{
     160    VBoxGuestHGCMCallInfo hdr;
     161
     162    /**
     163     * The property key.  (IN pointer)
     164     * This must fit to a number of criteria, namely
     165     *  - Only Utf8 strings are allowed
     166     *  - Less than or equal to MAX_NAME_LEN bytes in length
     167     *  - Zero terminated
     168     */
     169    HGCMFunctionParameter name;
     170
     171    /**
     172     * The value of the property (IN pointer)
     173     * Criteria as for the key parameter, but with length less than or equal to
     174     * MAX_VALUE_LEN. 
    131175     */
    132176    HGCMFunctionParameter value;
    133 } SetConfigKey;
    134 
    135 /** The guest is requesting to remove a configuration key */
    136 typedef struct _DelConfigKey
    137 {
    138     VBoxGuestHGCMCallInfo hdr;
    139 
    140     /**
    141      * The key to change up.  This must fit to a number of criteria, namely
    142      *  - Only ASCII characters with no spaces
    143      *  - Less than or equal to VBOX_SHARED_INFO_KEY_MAX_LEN bytes in length
    144      *  - Zero terminated
    145      */
    146     HGCMFunctionParameter key;
    147 } DelConfigKey;
     177} SetPropertyValue;
     178
     179/** The guest is requesting to remove a property */
     180typedef struct _DelProperty
     181{
     182    VBoxGuestHGCMCallInfo hdr;
     183
     184    /**
     185     * The property name.  This must fit to a number of criteria, namely
     186     *  - Only Utf8 strings are allowed
     187     *  - Less than or equal to MAX_NAME_LEN bytes in length
     188     *  - Zero terminated
     189     */
     190    HGCMFunctionParameter name;
     191} DelProperty;
     192
     193/** The guest is requesting to enumerate properties */
     194typedef struct _EnumProperties
     195{
     196    VBoxGuestHGCMCallInfo hdr;
     197
     198    /**
     199     * Null-separated array of patterns to match the properties against.
     200     * (IN pointer)
     201     * If no patterns are given then return all.
     202     */
     203    HGCMFunctionParameter patterns;
     204    /**
     205     * Null-separated array of strings in which the properties are returned.
     206     * (OUT pointer)
     207     * The number of strings in the array is always a multiple of four,
     208     * and in sequences of name, value, timestamp (hexadecimal string) and the
     209     * flags as a comma-separated list in the format "name=value"
     210     */
     211    HGCMFunctionParameter strings;
     212} EnumProperties;
    148213#pragma pack ()
    149214
    150 } /* namespace svcInfo */
    151 
    152 #endif  /* ___VBox_HostService_VBoxSharedInfoSvc_h defined */
     215} /* namespace guestProp */
     216
     217#endif  /* ___VBox_HostService_GuestPropertySvc_h defined */

  • trunk/include/VBox/VBoxGuest.h

    r10651 r10797  
    15281528/** @}  */
    15291529
    1530 #ifdef VBOX_WITH_INFO_SVC
    1531 /** @name Information Services
     1530#ifdef VBOX_WITH_GUEST_PROPS
     1531/** @name Guest properties
    15321532 * @{ */
    1533 VBGLR3DECL(int)     VbglR3InfoSvcConnect(uint32_t *pu32ClientId);
    1534 VBGLR3DECL(int)     VbglR3InfoSvcDisconnect(uint32_t u32ClientId);
    1535 VBGLR3DECL(int)     VbglR3InfoSvcWriteKey(uint32_t u32ClientId, char *pszKey, char *pszValue);
    1536 VBGLR3DECL(int)     VbglR3InfoSvcReadKey(uint32_t u32ClientId, char *pszKey, char *pszValue, uint32_t cbValue, uint32_t *pcbActual);
     1533VBGLR3DECL(int)     VbglR3GuestPropConnect(uint32_t *pu32ClientId);
     1534VBGLR3DECL(int)     VbglR3GuestPropDisconnect(uint32_t u32ClientId);
     1535VBGLR3DECL(int)     VbglR3GuestPropWrite(uint32_t u32ClientId, char *pszName, char *pszValue, char *pszFlags);
     1536VBGLR3DECL(int)     VbglR3GuestPropWriteValue(uint32_t u32ClientId, char *pszName, char *pszValue);
     1537VBGLR3DECL(int)     VbglR3GuestPropRead(uint32_t u32ClientId, const char *pszName, void *pvBuf, uint32_t cbBuf, char **ppszValue, uint64_t *pu64Timestamp, char **ppszFlags, uint32_t *pcbBufActual);
     1538VBGLR3DECL(int)     VbglR3GuestPropReadValue(uint32_t ClientId, const char *pszName, char *pszValue, uint32_t cchValue, uint32_t *pcchValueActual);
     1539VBGLR3DECL(int)     VbglR3GuestPropReadValueAlloc(uint32_t u32ClientId, const char *pszName, char **ppszValue);
     1540VBGLR3DECL(void)    VbglR3GuestPropReadValueFree(char *pszValue);
    15371541/** @}  */
    1538 #endif /* VBOX_WITH_INFO_SVC defined */
     1542#endif /* VBOX_WITH_GUEST_PROPS defined */
    15391543
    15401544
Note: See TracChangeset for help on using the changeset viewer.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette