service.cpp revision b3456700603bc1b9e548d271b27971ad974d87ab
/** @file
*
* Guest Property Service:
* Host service entry points.
*/
/*
* Copyright (C) 2008 Sun Microsystems, Inc.
*
* This file is part of VirtualBox Open Source Edition (OSE), as
* available from http://www.virtualbox.org. This file is free software;
* General Public License (GPL) as published by the Free Software
* Foundation, in version 2 as it comes in the "COPYING" file of the
* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
* Clara, CA 95054 USA or visit http://www.sun.com if you need
* additional information or have any questions.
*/
/**
* This HGCM service allows the guest to set and query values in a property
* store on the host. The service proxies the guest requests to the service
* owner on the host using a request callback provided by the owner, and is
* notified of changes to properties made by the host. It forwards these
* notifications to clients in the guest which have expressed interest and
* are waiting for notification.
*
* The service currently consists of two threads. One of these is the main
* HGCM service thread which deals with requests from the guest and from the
* host. The second thread sends the host asynchronous notifications of
* changes made by the guest and deals with notification timeouts.
*
* Guest requests to wait for notification are added to a list of open
* notification requests and completed when a corresponding guest property
* is changed or when the request times out.
*/
#define LOG_GROUP LOG_GROUP_HGCM
/*******************************************************************************
* Header Files *
*******************************************************************************/
#include <iprt/cpputils.h>
#include <memory> /* for auto_ptr */
#include <string>
#include <list>
namespace guestProp {
/**
* Structure for holding a property
*/
struct Property
{
/** The name of the property */
/** The property value */
/** The timestamp of the property */
/** The property flags */
/** Default constructor */
/** Constructor with const char * */
/** Constructor with std::string */
/** Does the property name match one of a set of patterns? */
bool Matches(const char *pszPatterns) const
{
NULL)
);
}
/** Are two properties equal? */
{
);
}
/* Is the property nil? */
bool isNull()
{
}
};
/** The properties list type */
/**
* Structure for holding an uncompleted guest call
*/
struct GuestCall
{
/** The call handle */
/** The function that was requested */
/** The call parameters */
/** The default return value, used for passing warnings */
int mRc;
/** The standard constructor */
/** The normal contructor */
};
/** The guest call list type */
/**
* Class containing the shared information service functionality.
*/
{
private:
/** Type definition for use in callback functions */
/** HGCM helper functions. */
/** The property list */
/** The list of property changes for guest notifications */
/** The list of outstanding guest notification calls */
/** @todo we should have classes for thread and request handler thread */
/** Queue of outstanding property change notifications */
/** Thread for processing the request queue */
/** Tell the thread that it should exit */
bool mfExitThread;
/** Callback function supplied by the host for notification of updates
* to properties */
/** User data pointer to be supplied to the host callback function */
void *mpvHostData;
/**
* Get the next property change notification from the queue of saved
* notification based on the timestamp of the last notification seen.
* Notifications will only be reported if the property name matches the
* pattern given.
*
* @returns iprt status value
* @returns VWRN_NOT_FOUND if the last notification was not found in the queue
* @param pszPatterns the patterns to match the property name against
* @param u64Timestamp the timestamp of the last notification
* @param pProp where to return the property found. If none is
* found this will be set to nil.
* @thread HGCM
*/
{
/* Zero means wait for a new notification. */
#ifdef VBOX_STRICT
/*
* ENSURE that pProp is the first event in the notification queue that:
* - Appears later than u64Timestamp
* - Matches the pszPatterns
*/
else
++it; /* Next event */
if (pProp->mTimestamp != 0)
{
}
#endif /* VBOX_STRICT */
return rc;
}
public:
{
#ifndef VBOX_GUEST_PROP_TEST_NOTHREAD
if (RT_SUCCESS(rc))
"GuestPropReq");
#endif
if (RT_FAILURE(rc))
throw rc;
}
/**
* @copydoc VBOXHGCMSVCHELPERS::pfnUnload
* Simply deletes the service object
*/
{
if (RT_SUCCESS(rc))
delete pSelf;
return rc;
}
/**
* @copydoc VBOXHGCMSVCHELPERS::pfnConnect
* Stub implementation of pfnConnect and pfnDisconnect.
*/
uint32_t /* u32ClientID */,
void * /* pvClient */)
{
return VINF_SUCCESS;
}
/**
* @copydoc VBOXHGCMSVCHELPERS::pfnCall
* Wraps to the call member function
*/
void *pvClient,
{
LogFlowFunc (("pvService=%p, callHandle=%p, u32ClientID=%u, pvClient=%p, u32Function=%u, cParms=%u, paParms=%p\n", pvService, callHandle, u32ClientID, pvClient, u32Function, cParms, paParms));
LogFlowFunc (("returning\n"));
}
/**
* @copydoc VBOXHGCMSVCHELPERS::pfnHostCall
* Wraps to the hostCall member function
*/
{
LogFlowFunc (("pvService=%p, u32Function=%u, cParms=%u, paParms=%p\n", pvService, u32Function, cParms, paParms));
return rc;
}
/**
* @copydoc VBOXHGCMSVCHELPERS::pfnRegisterExtension
* Installs a host callback for notifications of property changes.
*/
void *pvExtension)
{
return VINF_SUCCESS;
}
private:
int getOldNotificationInternal(const char *pszPattern,
/**
* Empty request function for terminating the request thread.
* @returns VINF_EOF to cause the request processing function to return
* @todo return something more appropriate
*/
int uninit ();
};
/**
* Thread function for processing the request queue
* @copydoc FNRTTHREAD
*/
{
while (!pSelf->mfExitThread)
return VINF_SUCCESS;
}
/**
* Check that a string fits our criteria for a property name.
*
* @returns IPRT status code
* @param pszName the string to check, must be valid Utf8
* @param cbName the number of bytes @a pszName points to, including the
* terminating '\0'
* @thread HGCM
*/
{
int rc = VINF_SUCCESS;
return rc;
}
/**
* Check a string fits our criteria for the value of a guest property.
*
* @returns IPRT status code
* @param pszValue the string to check, must be valid Utf8
* @param cbValue the length in bytes of @a pszValue, including the
* terminator
* @thread HGCM
*/
{
int rc = VINF_SUCCESS;
if (RT_SUCCESS(rc))
return rc;
}
/**
* Set a block of properties in the property registry, checking the validity
* of the arguments passed.
*
* @returns iprt status value
* @param cParms the number of HGCM parameters supplied
* @param paParms the array of HGCM parameters
* @thread HGCM
*/
{
int rc = VINF_SUCCESS;
/*
* Get and validate the parameters
*/
if ( (cParms != 4)
)
/*
* Add the properties to the end of the list. If we succeed then we
* will remove duplicates afterwards.
*/
/* Remember the last property before we started adding, for rollback or
* cleanup. */
if (!mProperties.empty())
--itEnd;
try
{
{
)
if (RT_SUCCESS(rc))
if (RT_SUCCESS(rc))
pTimestamps[i], fFlags));
}
}
{
rc = VERR_NO_MEMORY;
}
/*
* If all went well then remove the duplicate elements.
*/
{
++itEnd;
{
bool found = false;
{
found = true;
}
}
}
/*
* If something went wrong then rollback. This is possible because we
* haven't deleted anything yet.
*/
if (RT_FAILURE(rc))
{
++itEnd;
}
return rc;
}
/**
* Retrieve a value from the property registry by name, checking the validity
* of the arguments passed. If the guest has not allocated enough buffer
* space for the value then we return VERR_OVERFLOW and set the size of the
* buffer needed in the "size" HGCM parameter. If the name was not found at
* all, we return VERR_NOT_FOUND.
*
* @returns iprt status value
* @param cParms the number of HGCM parameters supplied
* @param paParms the array of HGCM parameters
* @thread HGCM
*/
{
int rc = VINF_SUCCESS;
char *pchBuf;
char szFlags[MAX_FLAGS_LEN];
/*
* Get and validate the parameters
*/
LogFlowThisFunc(("\n"));
)
else
/*
* Read and set the values we will return
*/
/* Get the value size */
if (RT_SUCCESS(rc))
{
rc = VERR_NOT_FOUND;
{
rc = VINF_SUCCESS;
break;
}
}
if (RT_SUCCESS(rc))
if (RT_SUCCESS(rc))
{
/* Check that the buffer is big enough */
if (cchBufActual <= cchBuf)
{
/* Write the value, flags and timestamp */
/*
* Done! Do exit logging and return.
*/
Log2(("Queried string %s, value=%s, timestamp=%lld, flags=%s\n",
}
else
}
return rc;
}
/**
* Set a value in the property registry by name, checking the validity
* of the arguments passed.
*
* @returns iprt status value
* @param cParms the number of HGCM parameters supplied
* @param paParms the array of HGCM parameters
* @param isGuest is this call coming from the guest (or the host)?
* @throws std::bad_alloc if an out of memory condition occurs
* @thread HGCM
*/
{
int rc = VINF_SUCCESS;
LogFlowThisFunc(("\n"));
/*
* First of all, make sure that we won't exceed the maximum number of properties.
*/
/*
* General parameter correctness checking.
*/
if ( RT_SUCCESS(rc)
|| ( (3 == cParms)
)
)
)
/*
* Check the values passed in the parameters for correctness.
*/
if (RT_SUCCESS(rc))
if (RT_SUCCESS(rc))
/*
* If the property already exists, check its flags to see if we are allowed
* to change it.
*/
bool found = false;
if (RT_SUCCESS(rc))
{
found = true;
break;
}
)
/*
* Set the actual value
*/
if (RT_SUCCESS(rc))
{
if (found)
{
}
else /* This can throw. No problem as we have nothing to roll back. */
}
/*
* Send a notification to the host and return.
*/
if (RT_SUCCESS(rc))
{
// if (isGuest) /* Notify the host even for properties that the host
// * changed. Less efficient, but ensures consistency. */
}
return rc;
}
/**
* Remove a value in the property registry by name, checking the validity
* of the arguments passed.
*
* @returns iprt status value
* @param cParms the number of HGCM parameters supplied
* @param paParms the array of HGCM parameters
* @param isGuest is this call coming from the guest (or the host)?
* @thread HGCM
*/
{
int rc = VINF_SUCCESS;
LogFlowThisFunc(("\n"));
/*
* Check the user-supplied parameters.
*/
)
else
/*
* If the property exists, check its flags to see if we are allowed
* to change it.
*/
bool found = false;
if (RT_SUCCESS(rc))
{
found = true;
break;
}
)
/*
* And delete the property if all is well.
*/
{
// if (isGuest) /* Notify the host even for properties that the host
// * changed. Less efficient, but ensures consistency. */
}
return rc;
}
/**
* Enumerate guest properties by mask, checking the validity
* of the arguments passed.
*
* @returns iprt status value
* @param cParms the number of HGCM parameters supplied
* @param paParms the array of HGCM parameters
* @thread HGCM
*/
{
int rc = VINF_SUCCESS;
/*
* Get the HGCM function arguments.
*/
LogFlowThisFunc(("\n"));
)
/*
* First repack the patterns into the format expected by RTStrSimplePatternMatch()
*/
char pszPatterns[MAX_PATTERN_LEN];
for (unsigned i = 0; i < cchPatterns - 1; ++i)
if (pcchPatterns[i] != '\0')
pszPatterns[i] = pcchPatterns[i];
else
pszPatterns[i] = '|';
/*
* Next enumerate into a temporary buffer. This can throw, but this is
* not a problem as we have nothing to roll back.
*/
{
{
char szFlags[MAX_FLAGS_LEN];
char szTimestamp[256];
buffer += '\0';
buffer += '\0';
10, 0, 0, 0);
buffer += '\0';
if (RT_SUCCESS(rc))
buffer += '\0';
}
}
/*
* Finally write out the temporary buffer to the real one if it is not too
* small.
*/
if (RT_SUCCESS(rc))
{
/* Copy the memory if it fits into the guest buffer */
else
}
return rc;
}
/** Helper query used by getOldNotification */
{
int rc = VINF_SUCCESS;
bool warn = false;
/* We count backwards, as the guest should normally be querying the
* most recent events. */
++it) {}
/* Warn if the timestamp was not found. */
warn = true;
/* Now look for an event matching the patterns supplied. The base()
* member conveniently points to the following element. */
++base) {}
else if (RT_SUCCESS(rc))
if (warn)
rc = VWRN_NOT_FOUND;
return rc;
}
/** Helper query used by getNotification */
{
int rc = VINF_SUCCESS;
/* Format the data to write to the buffer. */
char *pchBuf;
if (RT_SUCCESS(rc))
{
char szFlags[MAX_FLAGS_LEN];
if (RT_SUCCESS(rc))
{
buffer += '\0';
buffer += '\0';
buffer += '\0';
}
}
/* Write out the data. */
if (RT_SUCCESS(rc))
{
else
}
return rc;
}
/**
* Get the next guest notification.
*
* @returns iprt status value
* @param cParms the number of HGCM parameters supplied
* @param paParms the array of HGCM parameters
* @thread HGCM
* @throws can throw std::bad_alloc
*/
{
int rc = VINF_SUCCESS;
char *pchBuf;
uint32_t cchPatterns = 0;
/*
* Get the HGCM function arguments and perform basic verification.
*/
LogFlowThisFunc(("\n"));
)
if (RT_SUCCESS(rc))
u64Timestamp));
/*
* If no timestamp was supplied or no notification was found in the queue
* of old notifications, enqueue the request in the waiting queue.
*/
{
}
/*
* Otherwise reply at once with the enqueued notification we found.
*/
else
{
if (RT_FAILURE(rc2))
}
return rc;
}
/**
* Notify the service owner and the guest that a property has been
* @param pszProperty the name of the property which has changed
* @param u64Timestamp the time at which the change took place
* @note this call allocates memory which the reqNotify request is expected to
* free again, using RTStrFree().
*
* @thread HGCM service
*/
{
int rc = VINF_SUCCESS;
/* Ensure that our timestamp is different to the last one. */
if ( !mGuestNotifications.empty()
++u64Timestamp;
/*
* Try to find the property. Create a change event if we find it and a
* delete event if we do not.
*/
/* prop is currently a delete event for pszProperty */
bool found = false;
if (RT_SUCCESS(rc))
{
found = true;
/* Make prop into a change event. */
}
/* Release waiters if applicable and add the event to the queue for
* guest notifications */
if (RT_SUCCESS(rc))
{
try
{
{
const char *pszPatterns;
{
if (RT_SUCCESS(rc2))
}
else
++it;
}
}
{
rc = VERR_NO_MEMORY;
}
}
#ifndef VBOX_GUEST_PROP_TEST_NOTHREAD
/*
* Host notifications - first case: if the property exists then send its
* current value
*/
{
char szFlags[MAX_FLAGS_LEN];
/* Send out a host notification */
if (RT_SUCCESS(rc))
if (RT_SUCCESS(rc))
if (RT_SUCCESS(rc))
if (RT_SUCCESS(rc))
{
}
}
/*
* Host notifications - second case: if the property does not exist then
* send the host an empty value
*/
{
/* Send out a host notification */
if (RT_SUCCESS(rc))
{
}
}
{
LogThisFunc (("Failed, freeing allocated strings.\n"));
}
LogFlowThisFunc (("returning\n"));
#endif /* VBOX_GUEST_PROP_TEST_NOTHREAD not defined */
}
/**
* asynchronous part.
* @param pszProperty the name of the property which has changed
* @note this call allocates memory which the reqNotify request is expected to
* free again, using RTStrFree().
*
* @thread request thread
*/
/* static */
{
LogFlowFunc (("pfnCallback=%p, pvData=%p, pszName=%p, pszValue=%p, u32TimeHigh=%u, u32TimeLow=%u, pszFlags=%p\n", pfnCallback, pvData, pszName, pszValue, u32TimeHigh, u32TimeLow, pszFlags));
/* LogFlowFunc (("pfnCallback=%p, pvData=%p, pszName=%s, pszValue=%s, u32TimeHigh=%u, u32TimeLow=%u, pszFlags=%s\n", pfnCallback, pvData, pszName, pszValue, u32TimeHigh, u32TimeLow, pszFlags)); */
sizeof(HostCallbackData));
LogFlowFunc (("Freeing strings\n"));
LogFlowFunc (("returning success\n"));
return VINF_SUCCESS;
}
/**
* Handle an HGCM service call.
* @copydoc VBOXHGCMSVCFNTABLE::pfnCall
* @note All functions which do not involve an unreasonable delay will be
* handled synchronously. If needed, we will add a request handler
* thread in future for those which do.
*
* @thread HGCM
*/
{
int rc = VINF_SUCCESS;
LogFlowFunc(("u32ClientID = %d, fn = %d, cParms = %d, pparms = %d\n",
try
{
switch (eFunction)
{
/* The guest wishes to read a property */
case GET_PROP:
LogFlowFunc(("GET_PROP\n"));
break;
/* The guest wishes to set a property */
case SET_PROP:
LogFlowFunc(("SET_PROP\n"));
break;
/* The guest wishes to set a property value */
case SET_PROP_VALUE:
LogFlowFunc(("SET_PROP_VALUE\n"));
break;
/* The guest wishes to remove a configuration value */
case DEL_PROP:
LogFlowFunc(("DEL_PROP\n"));
break;
/* The guest wishes to enumerate all properties */
case ENUM_PROPS:
LogFlowFunc(("ENUM_PROPS\n"));
break;
/* The guest wishes to get the next property notification */
case GET_NOTIFICATION:
LogFlowFunc(("GET_NOTIFICATION\n"));
break;
default:
}
}
{
rc = VERR_NO_MEMORY;
}
if (rc != VINF_HGCM_ASYNC_EXECUTE)
{
}
}
/**
* Service call handler for the host.
* @copydoc VBOXHGCMSVCFNTABLE::pfnHostCall
* @thread hgcm
*/
{
int rc = VINF_SUCCESS;
LogFlowFunc(("fn = %d, cParms = %d, pparms = %d\n",
try
{
switch (eFunction)
{
/* The host wishes to set a block of properties */
case SET_PROPS_HOST:
LogFlowFunc(("SET_PROPS_HOST\n"));
break;
/* The host wishes to read a configuration value */
case GET_PROP_HOST:
LogFlowFunc(("GET_PROP_HOST\n"));
break;
/* The host wishes to set a configuration value */
case SET_PROP_HOST:
LogFlowFunc(("SET_PROP_HOST\n"));
break;
/* The host wishes to set a configuration value */
case SET_PROP_VALUE_HOST:
LogFlowFunc(("SET_PROP_VALUE_HOST\n"));
break;
/* The host wishes to remove a configuration value */
case DEL_PROP_HOST:
LogFlowFunc(("DEL_PROP_HOST\n"));
break;
/* The host wishes to enumerate all properties */
case ENUM_PROPS_HOST:
LogFlowFunc(("ENUM_PROPS\n"));
break;
default:
break;
}
}
{
rc = VERR_NO_MEMORY;
}
return rc;
}
{
int rc = VINF_SUCCESS;
unsigned count = 0;
mfExitThread = true;
#ifndef VBOX_GUEST_PROP_TEST_NOTHREAD
if (RT_SUCCESS(rc))
do
{
++count;
#endif /* VBOX_GUEST_PROP_TEST_NOTHREAD not defined */
if (RT_SUCCESS(rc))
return rc;
}
} /* namespace guestProp */
/**
* @copydoc VBOXHGCMSVCLOAD
*/
{
int rc = VINF_SUCCESS;
{
}
else
{
LogFlowFunc(("ptable->cbSize = %d, ptable->u32Version = 0x%08X\n", ptable->cbSize, ptable->u32Version));
{
}
else
{
/* No exceptions may propogate outside. */
try {
} catch (int rcThrown) {
} catch (...) {
}
if (RT_SUCCESS(rc))
{
/* We do not maintain connections, so no client data is needed. */
/* Service specific initialization. */
}
}
}
return rc;
}