CComClassFactory2 Class

  • Article

 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at 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

Name Description
CComClassFactory2::CreateInstance Creates an object of the specified CLSID.
CComClassFactory2::CreateInstanceLic Given a license key, creates an object of the specified CLSID.
CComClassFactory2::GetLicInfo Retrieves information describing the licensing capabilities of the class factory.
CComClassFactory2::LockServer Locks the class factory in memory.
CComClassFactory2::RequestLicKey Creates and returns a license key.

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