vboxweb.h revision 15e9181ff43bf09ce40eaab73cee8c8492f99878
/*
* vboxweb.h:
* header file for "real" web server code.
*
* Copyright (C) 2006-2010 Oracle Corporation
*
* 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.
*/
/****************************************************************************
*
* debug macro
*
****************************************************************************/
#ifdef DEBUG
#define LOG_GROUP LOG_GROUP_WEBSERVICE
#endif
#include <string>
/****************************************************************************
*
* typedefs
*
****************************************************************************/
// type used by gSOAP-generated code
/****************************************************************************
*
* global variables
*
****************************************************************************/
extern bool g_fVerbose;
extern const WSDLT_ID g_EmptyWSDLID;
/****************************************************************************
*
* SOAP exceptions
*
****************************************************************************/
void RaiseSoapRuntimeFault2(struct soap *soap, HRESULT apirc, IUnknown *pObj, const com::Guid &iid);
/**
* Template function called everywhere from methodmaps.cpp which calls
* RaiseSoapRuntimeFault2() with the correct COM interface ID.
* @param soap
* @param apirc
* @param pObj
*/
{
}
/****************************************************************************
*
* conversion helpers
*
****************************************************************************/
/****************************************************************************
*
* managed object reference classes
*
****************************************************************************/
/**
* An instance of this gets created for every client that logs onto the
* webservice (via the special IWebsessionManager::logon() SOAP API) and
* maintains the managed object references for that session.
*/
{
bool _fDestructing;
// hide the copy constructor because we're not copyable
int authenticate(const char *pcszUsername,
const char *pcszPassword);
{
return _uSessionID;
}
const WSDLT_ID& getSessionWSDLID() const;
void touch();
time_t getLastObjectLookup() const
{
return _tLastObjectLookup;
}
void DumpRefs();
};
/**
* ManagedObjectRef is used to map COM pointers to object IDs
* within a session. Such object IDs are 64-bit integers.
*
* When a webservice method call is invoked on an object, it
* has an opaque string called a "managed object reference". Such
* a string consists of a session ID combined with an object ID.
*
*/
{
// owning session:
void *_pobjInterface; // pointer to COM interface represented by _guidInterface, for which this MOR
// was created; this may be an IUnknown or something more specific
const char *_pcszInterface; // string representation of that interface (e.g. "IMachine")
// keys:
// long ID as string
void *pobjInterface,
const char *pcszInterface);
~ManagedObjectRef();
{
return _id;
}
/**
* Returns the contained COM pointer and the UUID of the COM interface
* which it supports.
* @param
* @return
*/
{
return _guidInterface;
}
/**
* Returns the ID of this managed object reference to string
* form, for returning with SOAP data or similar.
*
* @return The ID in string form.
*/
{
return _strID;
}
const char* getInterfaceName() const
{
return _pcszInterface;
}
bool fNullAllowed);
};
/**
* Template function that resolves a managed object reference to a COM pointer
* of the template class T.
*
* This gets called only from tons of generated code in methodmaps.cpp to
* resolve objects in *input* parameters to COM methods (i.e. translate
* MOR strings to COM objects which should exist already).
*
* This is a template function so that we can support ComPtr's for arbitrary
* interfaces and automatically verify that the managed object reference on
* the internal stack actually is of the expected interface. We also now avoid
* calling QueryInterface for the case that the interface desired by the caller
* is the same as the interface for which the MOR was originally created. In
* that case, the lookup is very fast.
*
* @param soap
* @param id in: integer managed object reference, as passed in by web service client
* @param pComPtr out: reference to COM pointer object that receives the com pointer,
* if SOAP_OK is returned
* @param fNullAllowed in: if true, then this func returns a NULL COM pointer if an
* empty MOR is passed in (i.e. NULL pointers are allowed). If false,
* then this fails; this will be false when called for the "this"
* argument of method calls, which really shouldn't be NULL.
* @return error code or SOAP_OK if no error
*/
bool fNullAllowed)
{
// findRefFromId requires thelock
int rc;
// error:
else
{
{
return 0;
}
// pRef->getPtr returns both a void* for its specific interface pointer as well as a generic IUnknown*
void *pobjInterface;
if (guidInterface == guidCaller)
{
// same interface: then no QueryInterface needed
WEBDEBUG((" %s(): returning original %s*=0x%lX (IUnknown*=0x%lX)\n", __FUNCTION__, pRef->getInterfaceName(), pobjInterface, pobjUnknown));
return 0;
}
// QueryInterface tests whether p actually supports the templated T interface desired by caller
T *pT;
if (pT)
{
// assign to caller's ComPtr<T>; use asOutParam() to avoid adding another reference, QueryInterface() already added one
WEBDEBUG((" %s(): returning pointer 0x%lX for queried interface %RTuuid (IUnknown*=0x%lX)\n", __FUNCTION__, pT, guidCaller.raw(), pobjUnknown));
return 0;
}
WEBDEBUG((" Interface not supported for object reference %s, which is of class %s\n", id.c_str(), pRef->getInterfaceName()));
}
return rc;
}
/**
* Creates a new managed object for the given COM pointer. If a reference already exists
* for the given pointer, then that reference's ID is returned instead.
*
* This gets called from tons of generated code in methodmaps.cpp to
* resolve objects *returned* from COM methods (i.e. create MOR strings from COM objects
* which might have been newly created).
*
* @param idParent managed object reference of calling object; used to extract session ID
* @param pc COM object for which to create a reference
* @return existing or new managed object reference
*/
const char *pcszInterface,
{
// NULL comptr should return NULL MOR
{
WEBDEBUG((" createOrFindRefFromComPtr(): returning empty MOR for NULL COM pointer\n"));
return g_EmptyWSDLID;
}
{
// we need an IUnknown pointer for the MOR
pobjUnknown, // IUnknown *pobjUnknown
pc, // void *pobjInterface
COM_IIDOF(T),
)
}
// session has expired, return an empty MOR instead of allocating a
// new reference which couldn't be used anyway.
return g_EmptyWSDLID;
}