COleObjectFactory Class

 

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 COleObjectFactory Class.

Implements the OLE class factory, which creates OLE objects such as servers, automation objects, and documents.

class COleObjectFactory : public CCmdTarget  

Public Constructors

NameDescription
COleObjectFactory::COleObjectFactoryConstructs a COleObjectFactory object.

Public Methods

NameDescription
COleObjectFactory::GetClassIDReturns the OLE class ID of the objects this factory creates.
COleObjectFactory::IsLicenseValidDetermines if the license of the control is valid.
COleObjectFactory::IsRegisteredIndicates whether the object factory is registered with the OLE system DLLs.
COleObjectFactory::RegisterRegisters this object factory with the OLE system DLLs.
COleObjectFactory::RegisterAllRegisters all of the application's object factories with OLE system DLLs.
COleObjectFactory::RevokeRevokes this object factory's registration with the OLE system DLLs.
COleObjectFactory::RevokeAllRevokes an application's object factories' registrations with the OLE system DLLs.
COleObjectFactory::UnregisterAllUnregisters all of an application's object factories.
COleObjectFactory::UpdateRegistryRegisters this object factory with the OLE system registry.
COleObjectFactory::UpdateRegistryAllRegisters all of the application's object factories with the OLE system registry.

Protected Methods

NameDescription
COleObjectFactory::GetLicenseKeyRequests a unique key from the control's DLL.
COleObjectFactory::OnCreateObjectCalled by the framework to create a new object of this factory's type.
COleObjectFactory::VerifyLicenseKeyVerifies that the key embedded in the control matches the key embedded in the container.
COleObjectFactory::VerifyUserLicenseVerifies that the control is licensed for design-time use.

The COleObjectFactory class has member functions for performing the following functions:

  • Managing the registration of objects.

  • Updating the OLE system register, as well as the run-time registration that informs OLE that objects are running and ready to receive messages.

  • Enforcing licensing by limiting use of the control to licensed developers at design time and to licensed applications at run time.

  • Registering control object factories with the OLE system registry.

For more information about object creation, see the articles Data Objects and Data Sources (OLE) and Data Objects and Data Sources: Creation and Destruction. For more about registration, see the article Registration.

CObject

CCmdTarget

COleObjectFactory

Header: afxdisp.h

Constructs a COleObjectFactory object, initializes it as an unregistered object factory, and adds it to the list of factories.

COleObjectFactory(
    REFCLSID clsid,  
    CRuntimeClass* pRuntimeClass,  
    BOOL bMultiInstance,  
    LPCTSTR lpszProgID);

 
COleObjectFactory(
    REFCLSID clsid,  
    CRuntimeClass* pRuntimeClass,  
    BOOL bMultiInstance,  
    int nFlags,  
    LPCTSTR lpszProgID);

Parameters

clsid
Reference to the OLE class ID this object factory represents.

pRuntimeClass
Pointer to the run-time class of the C++ objects this factory can create.

bMultiInstance
Indicates whether a single instance of the application can support multiple instantiations. If TRUE, multiple instances of the application are launched for each request to create an object.

nFlags
Contains one or more of the following flags:

  • afxRegDefault Sets the threading model to ThreadingModel=Apartment.

  • afxRegInsertable Allows the control to appear in the Insert Object dialog box for OLE objects.

  • afxRegApartmentThreading Sets the threading model in the registry to ThreadingModel=Apartment.

  • afxRegFreeThreading Sets the threading model in the registry to ThreadingModel=Free.

    You can combine the two flags afxRegApartmentThreading and afxRegFreeThreading to set ThreadingModel=Both. See InprocServer32 in the Windows SDK for more information on threading model registration.

lpszProgID
Pointer to a string containing a verbal program identifier, such as "Microsoft Excel."

Remarks

To use the object, however, you must register it.

For more information, see CLSID Key in the Windows SDK.

Returns a reference to the OLE class ID this factory represents.

REFCLSID GetClassID() const;  

Return Value

Reference to the OLE class ID this factory represents.

Remarks

For more information, see CLSID Key in the Windows SDK.

Requests a unique license key from the control's DLL and stores it in the BSTR pointed to by pbstrKey.

virtual BOOL GetLicenseKey(
    DWORD dwReserved,  
    BSTR* pbstrKey);

Parameters

dwReserved
Reserved for future use.

pbstrKey
Pointer to a BSTR that will store the license key.

Return Value

Nonzero if the license-key string is not NULL; otherwise 0.

Remarks

The default implementation of this function returns 0 and stores nothing in the BSTR. If you use MFC ActiveX ControlWizard to create your project, ControlWizard supplies an override that retrieves the control's license key.

Determines if the license of the control is valid.

BOOL IsLicenseValid();

Return Value

TRUE if successul; otherwise false.

Returns a nonzero value if the factory is registered with the OLE system DLLs.

virtual BOOL IsRegistered() const;  

Return Value

Nonzero if the factory is registered; otherwise 0.

Called by the framework to create a new object.

virtual CCmdTarget* OnCreateObject();

Return Value

A pointer to the created object. It can throw a memory exception if it fails.

Remarks

Override this function to create the object from something other than the CRuntimeClass passed to the constructor.

Registers this object factory with the OLE system DLLs.

virtual BOOL Register();

Return Value

Nonzero if the factory is successfully registered; otherwise 0.

Remarks

This function is usually called by CWinApp::InitInstance when the application is launched.

Registers all of the application's object factories with the OLE system DLLs.

static BOOL PASCAL RegisterAll();

Return Value

Nonzero if the factories are successfully registered; otherwise 0.

Remarks

This function is usually called by CWinApp::InitInstance when the application is launched.

Revokes this object factory's registration with the OLE system DLLs.

void Revoke();

Remarks

The framework calls this function automatically before the application terminates. If necessary, call it from an override of CWinApp::ExitInstance.

Revokes all of the application's object factories' registrations with the OLE system DLLs.

static void PASCAL RevokeAll();

Remarks

The framework calls this function automatically before the application terminates. If necessary, call it from an override of CWinApp::ExitInstance.

Unregisters all of an application's object factories.

static BOOL PASCAL UnregisterAll();

Return Value

TRUE if successful; otherwise FALSE.

Registers all of the application's object factories with the OLE system registry.

void UpdateRegistry(LPCTSTR lpszProgID = NULL);  
virtual BOOL UpdateRegistry(BOOL bRegister);
```  
  
### Parameters  
 `lpszProgID`  
 Pointer to a string containing the human-readable program identifier, such as "Excel.Document.5."  
  
 `bRegister`  
 Determines whether the control class's object factory is to be registered.  
  
### Remarks  
 Brief discussions of the two forms for this function follow:  
  
- **UpdateRegistry(** `lpszProgID` **)** Registers this object factory with the OLE system registry. This function is usually called by [CWinApp::InitInstance](../Topic/CWinApp%20Class.md#cwinapp__initinstance) when the application is launched.  
  
- **UpdateRegistry(** `bRegister` **)** This form of the function is overridable. If `bRegister` is **TRUE**, this function registers the control class with the system registry. Otherwise, it unregisters the class.  
  
     If you use MFC ActiveX ControlWizard to create your project, ControlWizard supplies an override to this pure virtual function.  
  
##  <a name="coleobjectfactory__updateregistryall"></a>  COleObjectFactory::UpdateRegistryAll  
 Registers all of the application's object factories with the OLE system registry.  
  

static BOOL PASCAL UpdateRegistryAll(BOOL bRegister = TRUE);

  
### Parameters  
 `bRegister`  
 Determines whether the control class's object factory is to be registered.  
  
### Return Value  
 Nonzero if the factories are successfully updated; otherwise 0.  
  
### Remarks  
 This function is usually called by [CWinApp::InitInstance](../Topic/CWinApp%20Class.md#cwinapp__initinstance) when the application is launched.  
  
##  <a name="coleobjectfactory__verifylicensekey"></a>  COleObjectFactory::VerifyLicenseKey  
 Verifies that the container is licensed to use the OLE control.  
  

virtual BOOL VerifyLicenseKey(BSTR bstrKey);

  
### Parameters  
 `bstrKey`  
 A `BSTR` storing the container's version of the license string.  
  
### Return Value  
 Nonzero if the run-time license is valid; otherwise 0.  
  
### Remarks  
 The default version calls [GetLicenseKey](#coleobjectfactory__getlicensekey) to get a copy of the control's license string and compares it with the string in `bstrKey`. If the two strings match, the function returns a nonzero value; otherwise it returns 0.  
  
 You can override this function to provide customized verification of the license.  
  
 The function [VerifyUserLicense](#coleobjectfactory__verifyuserlicense) verifies the design-time license.  
  
##  <a name="coleobjectfactory__verifyuserlicense"></a>  COleObjectFactory::VerifyUserLicense  
 Verifies the design-time license for the OLE control.  
  

virtual BOOL VerifyUserLicense();

  
### Return Value  
 Nonzero if the design-time license is valid; otherwise 0.  
  
## See Also  
 [CCmdTarget Class](../Topic/CCmdTarget%20Class.md)   
 [Hierarchy Chart](../Topic/Hierarchy%20Chart.md)   
 [COleTemplateServer Class](../Topic/COleTemplateServer%20Class.md)







Show: