CComClassFactory2 Class

This class implements the IClassFactory2 interface.

Syntax

template <class license>
class CComClassFactory2 : public IClassFactory2,
    public CComObjectRootEx<CComGlobalsThreadModel>,
    public license

Parameters

license
A class that implements the following static functions:

• static BOOL VerifyLicenseKey( BSTR bstr );

• static BOOL GetLicenseKey( DWORD dwReserved, BSTR * pBstr );

• static BOOL IsLicenseValid( );

Members

Public Methods

Remarks

CComClassFactory2 implements the IClassFactory2 interface, which is an extension of IClassFactory. IClassFactory2 controls object creation through a license. A class factory executing on a licensed machine can provide a run-time license key. This license key allows an application to instantiate objects when a full machine license does not exist.

ATL objects normally acquire a class factory by deriving from CComCoClass. This class includes the macro DECLARE_CLASSFACTORY, which declares CComClassFactory as the default class factory. To use CComClassFactory2, specify the DECLARE_CLASSFACTORY2 macro in your object's class definition. For example:

class ATL_NO_VTABLE CMyClass2 :
   public CComObjectRootEx<CComSingleThreadModel>,
   public CComCoClass<CMyClass2, &CLSID_MyClass>,
   public IDispatchImpl<IMyClass, &IID_IMyClass, &LIBID_NVC_ATL_COMLib, /*wMajor =*/ 1, /*wMinor =*/ 0>,
   public IDispatchImpl<IMyDualInterface, &__uuidof(IMyDualInterface), &LIBID_NVC_ATL_COMLib, /* wMajor = */ 1, /* wMinor = */ 0>
{
public:
   DECLARE_CLASSFACTORY2(CMyLicense)

   // Remainder of class declaration omitted

CMyLicense, the template parameter to CComClassFactory2, must implement the static functions VerifyLicenseKey, GetLicenseKey, and IsLicenseValid. The following is an example of a simple license class:

class CMyLicense
{
protected:
   static BOOL VerifyLicenseKey(BSTR bstr)
   {
      USES_CONVERSION;
      return !lstrcmp(OLE2T(bstr), _T("My run-time license key"));
   }

   static BOOL GetLicenseKey(DWORD /*dwReserved*/, BSTR* pBstr) 
   {
      USES_CONVERSION;
      *pBstr = SysAllocString( T2OLE(_T("My run-time license key"))); 
      return TRUE;
   }

   static BOOL IsLicenseValid() {  return TRUE; }
};

CComClassFactory2 derives from both CComClassFactory2Base and license. CComClassFactory2Base, in turn, derives from IClassFactory2 and CComObjectRootEx< CComGlobalsThreadModel >.

Inheritance Hierarchy

CComObjectRootBase

license

CComObjectRootEx

IClassFactory2

CComClassFactory2

Requirements

Header: atlcom.h

CComClassFactory2::CreateInstance

Creates an object of the specified CLSID and retrieves an interface pointer to this object.

STDMETHOD(CreateInstance)(LPUNKNOWN pUnkOuter, REFIID riid, void** ppvObj);

Parameters

pUnkOuter
[in] If the object is being created as part of an aggregate, then pUnkOuter must be the outer unknown. Otherwise, pUnkOuter must be NULL.

riid
[in] The IID of the requested interface. If pUnkOuter is non- NULL, riid must be IID_IUnknown.

ppvObj
[out] A pointer to the interface pointer identified by riid. If the object does not support this interface, ppvObj is set to NULL.

Return Value

A standard HRESULT value.

Remarks

Requires the machine to be fully licensed. If a full machine license does not exist, call CreateInstanceLic.

CComClassFactory2::CreateInstanceLic

Similar to CreateInstance, except that CreateInstanceLic requires a license key.

STDMETHOD(CreateInstanceLic)(
    IUnknown* pUnkOuter,
    IUnknown* /* pUnkReserved
*/,
    REFIID riid,
    BSTR bstrKey,
    void** ppvObject);

Parameters

pUnkOuter
[in] If the object is being created as part of an aggregate, then pUnkOuter must be the outer unknown. Otherwise, pUnkOuter must be NULL.

pUnkReserved
[in] Not used. Must be NULL.

riid
[in] The IID of the requested interface. If pUnkOuter is non- NULL, riid must be IID_IUnknown.

bstrKey
[in] The run-time license key previously obtained from a call to RequestLicKey. This key is required to create the object.

ppvObject
[out] A pointer to the interface pointer specified by riid. If the object does not support this interface, ppvObject is set to NULL.

Return Value

A standard HRESULT value.

Remarks

You can obtain a license key using RequestLicKey. In order to create an object on an unlicensed machine, you must call CreateInstanceLic.

CComClassFactory2::GetLicInfo

Fills a LICINFO structure with information that describes the class factory's licensing capabilities.

STDMETHOD(GetLicInfo)(LICINFO* pLicInfo);

Parameters

pLicInfo
[out] Pointer to a LICINFO structure.

Return Value

A standard HRESULT value.

Remarks

The fRuntimeKeyAvail member of this structure indicates whether, given a license key, the class factory allows objects to be created on an unlicensed machine. The fLicVerified member indicates whether a full machine license exists.

CComClassFactory2::LockServer

Increments and decrements the module lock count by calling _Module::Lock and _Module::Unlock, respectively.

STDMETHOD(LockServer)(BOOL fLock);

Parameters

fLock
[in] If TRUE, the lock count is incremented; otherwise, the lock count is decremented.

Return Value

A standard HRESULT value.

Remarks

_Module refers to the global instance of CComModule or a class derived from it.

Calling LockServer allows a client to hold onto a class factory so that multiple objects can be quickly created.

CComClassFactory2::RequestLicKey

Creates and returns a license key, provided that the fRuntimeKeyAvail member of the LICINFO structure is TRUE.

STDMETHOD(RequestLicKey)(DWORD dwReserved, BSTR* pbstrKey);

Parameters

dwReserved
[in] Not used. Must be zero.

pbstrKey
[out] Pointer to the license key.

Return Value

A standard HRESULT value.

Remarks

A license key is required for calling CreateInstanceLic to create an object on an unlicensed machine. If fRuntimeKeyAvail is FALSE, then objects can only be created on a fully licensed machine.

Call GetLicInfo to retrieve the value of fRuntimeKeyAvail.

See also

CComClassFactoryAutoThread Class
CComClassFactorySingleton Class
CComObjectRootEx Class
CComGlobalsThreadModel
Class Overview