service.cpp revision d8ebb1b0155a5f076e545b7a4e52df41608e1c7d
/** @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 <memory> /* for auto_ptr */
#include <iprt/cpputils.h>
/*******************************************************************************
* Internal functions *
*******************************************************************************/
/** Extract a pointer value from an HGCM parameter structure */
{
{
return VINF_SUCCESS;
}
return VERR_INVALID_PARAMETER;
}
/** Set a uint32_t value to an HGCM parameter structure */
{
}
/** Set a uint64_t value to an HGCM parameter structure */
{
}
namespace guestProp {
/**
* Class containing the shared information service functionality.
*/
{
private:
/** Type definition for use in callback functions */
/** HGCM helper functions. */
/** Pointer to our configuration values node. */
/** Pointer to our configuration timestamps node. */
/** Pointer to our configuration flags node. */
/** @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;
public:
{
RTTHREADFLAGS_WAITABLE, "GuestPropReq");
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,
{
}
/**
* @copydoc VBOXHGCMSVCHELPERS::pfnHostCall
* Wraps to the hostCall member function
*/
{
}
/**
* @copydoc VBOXHGCMSVCHELPERS::pfnRegisterExtension
* Installs a host callback for notifications of property changes.
*/
void *pvExtension)
{
// pSelf->mpfnHostCallback = pfnExtension;
return VINF_SUCCESS;
}
private:
void notifyHost(const char *pszProperty);
/**
* 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;
}
/**
* Checking that the name passed by the guest fits our criteria for a
* property name.
*
* @returns IPRT status code
* @param pszName the name passed by the guest
* @param cbName the number of bytes pszName points to, including the
* terminating '\0'
* @thread HGCM
*/
{
/*
* Validate the name, checking that it's proper UTF-8 and has
* a string terminator.
*/
return rc;
}
/**
* Check that the data passed by the guest fits our criteria for the value of
* a guest property.
*
* @returns IPRT status code
* @param pszValue the value to store in the property
* @param cbValue the number of bytes in the buffer pszValue points to
* @thread HGCM
*/
{
/*
* Validate the value, checking that it's proper UTF-8 and has
* a string terminator. Don't pass a 0 length request to the
* validator since it won't find any '\0' then.
*/
int rc = VINF_SUCCESS;
if (cbValue)
if (RT_SUCCESS(rc))
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;
LogFlowThisFunc(("\n"));
)
if (RT_SUCCESS(rc))
if (RT_SUCCESS(rc))
if (RT_SUCCESS(rc))
if (RT_SUCCESS(rc))
if (RT_SUCCESS(rc))
if (RT_SUCCESS(rc))
if (RT_SUCCESS(rc))
else if (VERR_CFGM_VALUE_NOT_FOUND == rc)
rc = VERR_NOT_FOUND;
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;
/*
* Get and validate the parameters
*/
LogFlowThisFunc(("\n"));
)
if (RT_SUCCESS(rc))
if (RT_SUCCESS(rc))
if (RT_SUCCESS(rc))
/*
* Read and set the values we will return
*/
/* Get the value size */
if (RT_SUCCESS(rc))
/* Get the flags and their size */
if (RT_SUCCESS(rc))
if (RT_SUCCESS(rc))
if (RT_SUCCESS(rc))
/* Check that the buffer is big enough */
if (RT_SUCCESS(rc))
{
}
/* Write the value */
if (RT_SUCCESS(rc))
/* Write the flags */
if (RT_SUCCESS(rc))
/* Timestamp */
uint64_t u64Timestamp = 0;
if (RT_SUCCESS(rc))
/*
* Done! Do exit logging and return.
*/
if (RT_SUCCESS(rc))
Log2(("Queried string %S, value=%.*S, timestamp=%lld, flags=%.*S\n",
else if (VERR_CFGM_VALUE_NOT_FOUND == rc)
rc = VERR_NOT_FOUND;
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
* @thread HGCM
*/
{
int rc = VINF_SUCCESS;
LogFlowThisFunc(("\n"));
/*
* First of all, make sure that we won't exceed the maximum number of properties.
*/
{
unsigned cChildren = 0;
for (PCFGMNODE pChild = CFGMR3GetFirstChild(mpValueNode); pChild != 0; pChild = CFGMR3GetNextChild(pChild))
++cChildren;
}
/*
* General parameter correctness checking.
*/
if ( RT_SUCCESS(rc)
)
)
/*
* Check the values passed in the parameters for correctness.
*/
if (RT_SUCCESS(rc))
if (RT_SUCCESS(rc))
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.
*/
if (RT_SUCCESS(rc))
{
)
}
/*
* Check whether the user supplied flags (if any) are valid.
*/
{
char *pszFlags;
if (RT_SUCCESS(rc))
}
/*
* Set the actual value
*/
if (RT_SUCCESS(rc))
{
if (RT_SUCCESS(rc))
if (RT_SUCCESS(rc))
/* If anything goes wrong, make sure that we leave a clean state
* behind. */
if (RT_FAILURE(rc))
{
}
}
/*
* Send a notification to the host and return.
*/
if (RT_SUCCESS(rc))
{
if (isGuest)
}
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
* @thread HGCM
*/
{
int rc = VINF_SUCCESS;
char *pszName;
LogFlowThisFunc(("\n"));
/*
* Check the user-supplied parameters.
*/
)
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.
*/
if (RT_SUCCESS(rc))
{
)
}
/*
* And delete the property if all is well.
*/
if (RT_SUCCESS(rc))
{
if (isGuest)
}
return rc;
}
/**
* Matches a sample name against a pattern.
*
* @returns True if matches, false if not.
* @param pszPat Pattern.
* @param pszName Name to match against the pattern.
* @todo move this into IPRT
*/
{
/* ASSUMES ASCII */
for (;;)
{
switch (chPat)
{
default:
return false;
break;
case '*':
{
/* nothing */;
for (;;)
{
&& ( !chPat
return true;
if (!ch)
return false;
}
/* won't ever get here */
break;
}
case '?':
if (!*pszName)
return false;
break;
case '\0':
return !*pszName;
}
pszName++;
pszPat++;
}
return true;
}
/* Checks to see if the given string matches against one of the patterns in
* the list. */
const char *pszString)
{
/* If the first pattern in the list is empty, treat it as "match all". */
{
&& (cchCurrent > 0)
)
{
}
else
iOffs = cchPatterns;
}
return matched;
}
/**
* 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
*/
{
/* We reallocate the temporary buffer in which we build up our array in
* increments of size BLOCK: */
enum
{
/* Calculate the increment, not yet rounded down */
/* And this is the increment after rounding */
};
int rc = VINF_SUCCESS;
/*
* Get the HGCM function arguments.
*/
LogFlowThisFunc(("\n"));
)
if (RT_SUCCESS(rc))
if (RT_SUCCESS(rc))
/*
* Start by enumerating all values in the current node into a temporary buffer.
*/
{
/* Reallocate the buffer if it has got too tight */
{
rc = VERR_NO_MEMORY;
}
/* Fetch the name into the buffer and if it matches one of the
* patterns, add its value and an empty timestamp and flags. If it
* doesn't match, we simply overwrite it in the buffer. */
if (RT_SUCCESS(rc))
/* Only increment the buffer offest if the name matches, otherwise we
* overwrite it next iteration. */
if ( RT_SUCCESS(rc)
)
{
/* Get value */
if (RT_SUCCESS(rc))
{
/* Get timestamp */
uint64_t u64Timestamp = 0;
10, 0, 0, 0) + 1;
/* Get flags */
}
}
if (RT_SUCCESS(rc))
}
if (RT_SUCCESS(rc))
{
/* The terminator. We *do* have space left for this. */
iTmpBuf += 4;
/* Copy the memory if it fits into the guest buffer */
else
}
return rc;
}
/**
* @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 HGCM service
*/
{
char szValue[MAX_VALUE_LEN];
uint64_t u64Timestamp = 0;
if (NULL == mpfnHostCallback)
return; /* Nothing to do. */
sizeof(szValue));
/*
* First case: if the property exists then send the host its current value
*/
if (rc != VERR_CFGM_VALUE_NOT_FOUND)
{
if (RT_SUCCESS(rc))
if (RT_SUCCESS(rc))
if (RT_SUCCESS(rc))
if (RT_SUCCESS(rc))
if (RT_SUCCESS(rc))
if (RT_SUCCESS(rc))
if (RT_SUCCESS(rc))
{
}
}
else
/*
* Second case: if the property does not exist then send the host an empty
* value
*/
{
if (RT_SUCCESS(rc))
}
{
}
}
/**
* 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
*/
{
sizeof(HostCallbackData)));
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;
bool fCallSync = true;
LogFlowFunc(("u32ClientID = %d, fn = %d, cParms = %d, pparms = %d\n",
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;
default:
}
if (fCallSync)
{
}
}
/**
* Service call handler for the host.
* @copydoc VBOXHGCMSVCFNTABLE::pfnHostCall
* @thread hgcm
*/
{
int rc = VINF_SUCCESS;
LogFlowFunc(("fn = %d, cParms = %d, pparms = %d\n",
switch (eFunction)
{
/* Set the root CFGM node used. This should be called when instantiating
* the service. */
/* This whole case is due to go away, so I will not clean it up. */
case SET_CFGM_NODE:
{
LogFlowFunc(("SET_CFGM_NODE\n"));
if ( (cParms != 3)
)
else
{
if (RT_SUCCESS(rc))
if (RT_SUCCESS(rc))
if (RT_SUCCESS(rc))
{
}
}
} 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;
}
return rc;
}
{
int rc;
unsigned count = 0;
mfExitThread = true;
if (RT_SUCCESS(rc))
do
{
++count;
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;
}