VirtualBox

Changeset 70058 in vbox for trunk/include/VBox/HostServices


Ignore:
Timestamp:
Dec 11, 2017 3:02:07 PM (7 years ago)
Author:
vboxsync
svn:sync-xref-src-repo-rev:
119600
Message:

GuestPropertySvc.h: Working on making it usable from C (VBoxGuest, ++)

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r69107 r70058  
    3535#include <iprt/string.h>
    3636
    37 /** Everything defined in this file lives in this namespace. */
    38 namespace guestProp {
    39 
    40 /******************************************************************************
    41 * Typedefs, constants and inlines                                             *
    42 ******************************************************************************/
    4337
    4438/** Maximum length for property names */
    45 enum { MAX_NAME_LEN = 64 };
     39#define GUEST_PROP_MAX_NAME_LEN             64
    4640/** Maximum length for property values */
    47 enum { MAX_VALUE_LEN = 128 };
     41#define GUEST_PROP_MAX_VALUE_LEN            128
    4842/** Maximum number of properties per guest */
    49 enum { MAX_PROPS = 256 };
     43#define GUEST_PROP_MAX_PROPS                256
    5044/** Maximum size for enumeration patterns */
    51 enum { MAX_PATTERN_LEN = 1024 };
     45#define GUEST_PROP_MAX_PATTERN_LEN          1024
    5246/** Maximum number of changes we remember for guest notifications */
    53 enum { MAX_GUEST_NOTIFICATIONS = 256 };
    54 
    55 /**
    56  * The guest property flag values which are currently accepted.
    57  */
    58 enum ePropFlags
    59 {
    60     NILFLAG          = 0,
    61     /** Transient until VM gets shut down. */
    62     TRANSIENT        = RT_BIT(1),
    63     RDONLYGUEST      = RT_BIT(2),
    64     RDONLYHOST       = RT_BIT(3),
    65     /** Transient until VM gets a reset / restarts.
    66      *  Implies TRANSIENT. */
    67     TRANSRESET       = RT_BIT(4),
    68     READONLY         = RDONLYGUEST | RDONLYHOST,
    69     ALLFLAGS         = TRANSIENT | READONLY | TRANSRESET
    70 };
     47#define GUEST_PROP_MAX_GUEST_NOTIFICATIONS  256
     48
     49
     50/** @name GUEST_PROP_F_XXX - The guest property flag values which are currently accepted.
     51 * @{
     52 */
     53#define GUEST_PROP_F_NILFLAG          UINT32_C(0)
     54/** Transient until VM gets shut down. */
     55#define GUEST_PROP_F_TRANSIENT        RT_BIT_32(1)
     56#define GUEST_PROP_F_RDONLYGUEST      RT_BIT_32(2)
     57#define GUEST_PROP_F_RDONLYHOST       RT_BIT_32(3)
     58/** Transient until VM gets a reset / restarts.
     59 *  Implies TRANSIENT. */
     60#define GUEST_PROP_F_TRANSRESET       RT_BIT_32(4)
     61#define GUEST_PROP_F_READONLY         (GUEST_PROP_F_RDONLYGUEST | GUEST_PROP_F_RDONLYHOST)
     62#define GUEST_PROP_F_ALLFLAGS         (GUEST_PROP_F_TRANSIENT | GUEST_PROP_F_READONLY | GUEST_PROP_F_TRANSRESET)
     63/** @} */
    7164
    7265/**
    … …  
    7669 *                 list.
    7770 */
    78 DECLINLINE(const char *) flagName(uint32_t fFlag)
     71DECLINLINE(const char *) GuestPropFlagName(uint32_t fFlag)
    7972{
    8073    switch (fFlag)
    8174    {
    82         case TRANSIENT:
     75        case GUEST_PROP_F_TRANSIENT:
    8376            return "TRANSIENT";
    84         case RDONLYGUEST:
     77        case GUEST_PROP_F_RDONLYGUEST:
    8578            return "RDONLYGUEST";
    86         case RDONLYHOST:
     79        case GUEST_PROP_F_RDONLYHOST:
    8780            return "RDONLYHOST";
    88         case READONLY:
     81        case GUEST_PROP_F_READONLY:
    8982            return "READONLY";
    90         case TRANSRESET:
     83        case GUEST_PROP_F_TRANSRESET:
    9184            return "TRANSRESET";
    9285        default:
    … …  
    10295 *                 list.
    10396 */
    104 DECLINLINE(size_t) flagNameLen(uint32_t fFlag)
    105 {
    106     const char *pcszName = flagName(fFlag);
     97DECLINLINE(size_t) GuestPropFlagNameLen(uint32_t fFlag)
     98{
     99    const char *pcszName = GuestPropFlagName(fFlag);
    107100    return RT_LIKELY(pcszName != NULL) ? strlen(pcszName) : 0;
    108101}
    … …  
    112105 * RDONLYGUEST, RDONLYHOST and RDONLY
    113106 */
    114 enum { MAX_FLAGS_LEN = sizeof("TRANSIENT, RDONLYGUEST, TRANSRESET") };
     107#define GUEST_PROP_MAX_FLAGS_LEN    sizeof("TRANSIENT, RDONLYGUEST, TRANSRESET")
    115108
    116109/**
    117110 * Parse a guest properties flags string for flag names and make sure that
    118111 * there is no junk text in the string.
     112 *
    119113 * @returns  IPRT status code
    120  * @returns  VERR_INVALID_PARAM if the flag string is not valid
     114 * @retval   VERR_INVALID_PARAMETER if the flag string is not valid
    121115 * @param    pcszFlags  the flag string to parse
    122116 * @param    pfFlags    where to store the parse result.  May not be NULL.
    … …  
    125119 *           its own library.
    126120 */
    127 DECLINLINE(int) validateFlags(const char *pcszFlags, uint32_t *pfFlags)
     121DECLINLINE(int) GuestPropValidateFlags(const char *pcszFlags, uint32_t *pfFlags)
    128122{
    129123    static const uint32_t s_aFlagList[] =
    130124    {
    131         TRANSIENT, READONLY, RDONLYGUEST, RDONLYHOST, TRANSRESET
     125        GUEST_PROP_F_TRANSIENT, GUEST_PROP_F_READONLY, GUEST_PROP_F_RDONLYGUEST, GUEST_PROP_F_RDONLYHOST, GUEST_PROP_F_TRANSRESET
    132126    };
    133127    const char *pcszNext = pcszFlags;
    … …  
    144138            unsigned i = 0;
    145139            for (; i < RT_ELEMENTS(s_aFlagList); ++i)
    146                 if (RTStrNICmp(pcszNext, flagName(s_aFlagList[i]),
    147                                flagNameLen(s_aFlagList[i])) == 0)
     140                if (RTStrNICmp(pcszNext, GuestPropFlagName(s_aFlagList[i]), GuestPropFlagNameLen(s_aFlagList[i])) == 0)
    148141                    break;
    149142            if (RT_ELEMENTS(s_aFlagList) == i)
    … …  
    152145            {
    153146                fFlags |= s_aFlagList[i];
    154                 pcszNext += flagNameLen(s_aFlagList[i]);
     147                pcszNext += GuestPropFlagNameLen(s_aFlagList[i]);
    155148                while (' ' == *pcszNext)
    156149                    ++pcszNext;
    … …  
    169162}
    170163
     164
    171165/**
    172166 * Write out flags to a string.
    … …  
    176170 *                     a buffer of size (at least) MAX_FLAGS_LEN.
    177171 */
    178 DECLINLINE(int) writeFlags(uint32_t fFlags, char *pszFlags)
     172DECLINLINE(int) GuestPropWriteFlags(uint32_t fFlags, char *pszFlags)
    179173{
    180174    /* Putting READONLY before the other RDONLY flags keeps the result short. */
    181175    static const uint32_t s_aFlagList[] =
    182176    {
    183         TRANSIENT, READONLY, RDONLYGUEST, RDONLYHOST, TRANSRESET
     177        GUEST_PROP_F_TRANSIENT, GUEST_PROP_F_READONLY, GUEST_PROP_F_RDONLYGUEST, GUEST_PROP_F_RDONLYHOST, GUEST_PROP_F_TRANSRESET
    184178    };
    185179    int rc = VINF_SUCCESS;
    186180
    187181    AssertLogRelReturn(VALID_PTR(pszFlags), VERR_INVALID_POINTER);
    188     if ((fFlags & ~ALLFLAGS) == NILFLAG)
     182    if ((fFlags & ~GUEST_PROP_F_ALLFLAGS) == GUEST_PROP_F_NILFLAG)
    189183    {
     184        char *pszNext;
     185
    190186        /* TRANSRESET implies TRANSIENT.  For compatability with old clients we
    191187           always set TRANSIENT when TRANSRESET appears. */
    192         if (fFlags & TRANSRESET)
    193             fFlags |= TRANSIENT;
    194 
    195         char *pszNext = pszFlags;
     188        if (fFlags & GUEST_PROP_F_TRANSRESET)
     189            fFlags |= GUEST_PROP_F_TRANSIENT;
     190
     191        pszNext = pszFlags;
    196192        for (unsigned i = 0; i < RT_ELEMENTS(s_aFlagList); ++i)
    197193        {
    198194            if (s_aFlagList[i] == (fFlags & s_aFlagList[i]))
    199195            {
    200                 strcpy(pszNext, flagName(s_aFlagList[i]));
    201                 pszNext += flagNameLen(s_aFlagList[i]);
     196                strcpy(pszNext, GuestPropFlagName(s_aFlagList[i]));
     197                pszNext += GuestPropFlagNameLen(s_aFlagList[i]);
    202198                fFlags &= ~s_aFlagList[i];
    203                 if (fFlags != NILFLAG)
     199                if (fFlags != GUEST_PROP_F_NILFLAG)
    204200                {
    205201                    strcpy(pszNext, ", ");
    … …  
    210206        *pszNext = '\0';
    211207
    212         Assert(fFlags == NILFLAG); /* bad s_aFlagList */
     208        Assert(fFlags == GUEST_PROP_F_NILFLAG); /* bad s_aFlagList */
    213209    }
    214210    else
    … …  
    217213}
    218214
    219 /**
    220  * The service functions which are callable by host.
    221  */
    222 enum eHostFn
    223 {
    224     /**
    225      * Set properties in a block.  The parameters are pointers to
    226      * NULL-terminated arrays containing the parameters.  These are, in order,
    227      * name, value, timestamp, flags.  Strings are stored as pointers to
    228      * mutable utf8 data.  All parameters must be supplied.
    229      */
    230     SET_PROPS_HOST = 1,
    231     /**
    232      * Get the value attached to a guest property
    233      * The parameter format matches that of GET_PROP.
    234      */
    235     GET_PROP_HOST = 2,
    236     /**
    237      * Set the value attached to a guest property
    238      * The parameter format matches that of SET_PROP.
    239      */
    240     SET_PROP_HOST = 3,
    241     /**
    242      * Set the value attached to a guest property
    243      * The parameter format matches that of SET_PROP_VALUE.
    244      */
    245     SET_PROP_VALUE_HOST = 4,
    246     /**
    247      * Remove a guest property.
    248      * The parameter format matches that of DEL_PROP.
    249      */
    250     DEL_PROP_HOST = 5,
    251     /**
    252      * Enumerate guest properties.
    253      * The parameter format matches that of ENUM_PROPS.
    254      */
    255     ENUM_PROPS_HOST = 6,
    256 
    257     /**
    258      * Set global flags for the service.  Currently RDONLYGUEST is supported.
    259      * Takes one 32-bit unsigned integer parameter for the flags.
    260      */
    261     SET_GLOBAL_FLAGS_HOST = 7,
    262 
    263     /**
    264      * Return the pointer to a debug info function enumerating all guest properties.
    265      */
    266     GET_DBGF_INFO_FN = 8
    267 };
    268 
    269 /**
    270  * The service functions which are called by guest.  The numbers may not change,
    271  * so we hardcode them.
    272  */
    273 enum eGuestFn
    274 {
    275     /** Get a guest property */
    276     GET_PROP = 1,
    277     /** Set a guest property */
    278     SET_PROP = 2,
    279     /** Set just the value of a guest property */
    280     SET_PROP_VALUE = 3,
    281     /** Delete a guest property */
    282     DEL_PROP = 4,
    283     /** Enumerate guest properties */
    284     ENUM_PROPS = 5,
    285     /** Poll for guest notifications */
    286     GET_NOTIFICATION = 6
    287 };
    288 
    289 /**
    290  * Data structure to pass to the service extension callback.  We use this to
    291  * notify the host of changes to properties.
    292  */
    293 typedef struct _HOSTCALLBACKDATA
    294 {
    295     /** Magic number to identify the structure */
    296     uint32_t u32Magic;
     215
     216/** @name The service functions which are callable by host.
     217 * @{
     218 */
     219/** Set properties in a block.
     220 * The parameters are pointers to NULL-terminated arrays containing the
     221 * parameters.  These are, in order, name, value, timestamp, flags.  Strings are
     222 * stored as pointers to mutable utf8 data.  All parameters must be supplied. */
     223#define GUEST_PROP_FN_SET_PROPS_HOST        1
     224/** Get the value attached to a guest property.
     225 * The parameter format matches that of GET_PROP. */
     226#define GUEST_PROP_FN_GET_PROP_HOST         2
     227/** Set the value attached to a guest property.
     228 * The parameter format matches that of SET_PROP. */
     229#define GUEST_PROP_FN_SET_PROP_HOST         3
     230/** Set the value attached to a guest property.
     231 * The parameter format matches that of SET_PROP_VALUE. */
     232#define GUEST_PROP_FN_SET_PROP_VALUE_HOST   4
     233/** Remove a guest property.
     234 * The parameter format matches that of DEL_PROP. */
     235#define GUEST_PROP_FN_DEL_PROP_HOST         5
     236/** Enumerate guest properties.
     237 * The parameter format matches that of ENUM_PROPS. */
     238#define GUEST_PROP_FN_ENUM_PROPS_HOST       6
     239/** Set global flags for the service.
     240 * Currently RDONLYGUEST is supported.  Takes one 32-bit unsigned integer
     241 * parameter for the flags. */
     242#define GUEST_PROP_FN_SET_GLOBAL_FLAGS_HOST 7
     243/** Return the pointer to a debug info function enumerating all guest
     244 * properties. */
     245#define GUEST_PROP_FN_GET_DBGF_INFO_FN      8
     246/** @} */
     247
     248
     249/** @name The service functions which are called by guest.
     250 *
     251 * @note The numbers may not change!
     252 * @{
     253 */
     254/** Get a guest property */
     255#define GUEST_PROP_FN_GET_PROP              1
     256/** Set a guest property */
     257#define GUEST_PROP_FN_SET_PROP              2
     258/** Set just the value of a guest property */
     259#define GUEST_PROP_FN_SET_PROP_VALUE        3
     260/** Delete a guest property */
     261#define GUEST_PROP_FN_DEL_PROP              4
     262/** Enumerate guest properties */
     263#define GUEST_PROP_FN_ENUM_PROPS            5
     264/** Poll for guest notifications */
     265#define GUEST_PROP_FN_GET_NOTIFICATION      6
     266/** @} */
     267
     268
     269/**
     270 * Data structure to pass to the service extension callback.
     271 * We use this to notify the host of changes to properties.
     272 */
     273typedef struct GUESTPROPHOSTCALLBACKDATA
     274{
     275    /** Magic number to identify the structure (GUESTPROPHOSTCALLBACKDATA_MAGIC). */
     276    uint32_t        u32Magic;
    297277    /** The name of the property that was changed */
    298     const char *pcszName;
     278    const char     *pcszName;
    299279    /** The new property value, or NULL if the property was deleted */
    300     const char *pcszValue;
     280    const char     *pcszValue;
    301281    /** The timestamp of the modification */
    302     uint64_t u64Timestamp;
     282    uint64_t       u64Timestamp;
    303283    /** The flags field of the modified property */
    304     const char *pcszFlags;
    305 } HOSTCALLBACKDATA, *PHOSTCALLBACKDATA;
    306 
    307 enum
    308 {
    309     /** Magic number for sanity checking the HOSTCALLBACKDATA structure */
    310     HOSTCALLBACKMAGIC = 0x69c87a78
    311 };
     284    const char     *pcszFlags;
     285} GUESTPROPHOSTCALLBACKDATA;
     286/** Poitner to a data structure to pass to the service extension callback. */
     287typedef GUESTPROPHOSTCALLBACKDATA *PGUESTPROPHOSTCALLBACKDATA;
     288
     289/** Magic number for sanity checking the HOSTCALLBACKDATA structure */
     290#define GUESTPROPHOSTCALLBACKDATA_MAGIC     UINT32_C(0x69c87a78)
     291
     292/** Everything defined in this file lives in this namespace. */
     293namespace guestProp {
    312294
    313295/**
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