Module Class

Represents a collection of related objects.

Syntax

template<ModuleType moduleType>
class Module;

template<>
class Module<InProc> : public Details::ModuleBase;

template<>
class Module<OutOfProc> : public Module<InProc>;

Parameters

moduleType
A combination of one or more ModuleType enumeration values.

Members

Protected Classes

Name	Description
Module::GenericReleaseNotifier	Invokes an event handler when the last object in the current module is released. The event handler is specified by on a lambda, functor, or pointer-to-function.
Module::MethodReleaseNotifier	Invokes an event handler when the last object in the current module is released. The event handler is specified by an object and its pointer-to-a-method member.
Module::ReleaseNotifier	Invokes an event handler when the last object in a module is released.

Public Constructors

Name	Description
Module::~Module	Deinitializes the current instance of the Module class.

Protected Constructors

Name	Description
Module::Module	Initializes a new instance of the Module class.

Public Methods

Name	Description
Module::Create	Creates an instance of a module.
Module::DecrementObjectCount	Decrements the number of objects tracked by the module.
Module::GetActivationFactory	Gets an activation factory for the module.
Module::GetClassObject	Retrieves a cache of class factories.
Module::GetModule	Creates an instance of a module.
Module::GetObjectCount	Retrieves the number of objects managed by this module.
Module::IncrementObjectCount	Increments the number of objects tracked by the module.
Module::RegisterCOMObject	Registers one or more COM objects so other applications can connect to them.
Module::RegisterObjects	Registers COM or Windows Runtime objects so other applications can connect to them.
Module::RegisterWinRTObject	Registers one or more Windows Runtime objects so other applications can connect to them.
Module::Terminate	Causes all factories instantiated by the module to shut down.
Module::UnregisterCOMObject	Unregisters one or more COM objects, which prevents other applications from connecting to them.
Module::UnregisterObjects	Unregisters the objects in the specified module so that other applications cannot connect to them.
Module::UnregisterWinRTObject	Unregisters one or more Windows Runtime objects so that other applications cannot connect to them.

Protected Methods

Name	Description
Module::Create	Creates an instance of a module.

Protected Data Members

Name	Description
Module::objectCount_	Keeps track of how many classes have been created with the Make function.
Module::releaseNotifier_	Holds a pointer to a ReleaseNotifier object.

Macros

Name	Description
ActivatableClass	Populates an internal cache that contains a factory that can create an instance of the specified class. This macro specifies default factory and group ID parameters.
ActivatableClassWithFactory	Populates an internal cache that contains a factory that can create an instance of the specified class. This macro enables you to specify a particular factory parameter.
ActivatableClassWithFactoryEx	Populates an internal cache that contains a factory that can create an instance of the specified class. This macro enables you to specify particular factory and group ID parameters.

Inheritance Hierarchy

ModuleBase

Module

Module

Requirements

Header: module.h

Namespace: Microsoft::WRL

Module::~Module

Deinitializes the current instance of the Module class.

virtual ~Module();

Module::Create

Creates an instance of a module.

WRL_NOTHROW static Module& Create();
template<typename T>
WRL_NOTHROW static Module& Create(
   T callback
);
template<typename T>
WRL_NOTHROW static Module& Create(
   _In_ T* object,
   _In_ void (T::* method)()
);

Parameters

T
Module type.

callback
Called when the last instance object of the module is released.

object
The object and method parameters are used in combination. Points to the last instance object when the last instance object in the module is released.

method
The object and method parameters are used in combination. Points to the method of the last instance object when the last instance object in the module is released.

Return Value

Reference to the module.

Module::DecrementObjectCount

Decrements the number of objects tracked by the module.

virtual long DecrementObjectCount();

Return Value

The count before the decrement operation.

Module::GetActivationFactory

Gets an activation factory for the module.

WRL_NOTHROW HRESULT GetActivationFactory(
   _In_ HSTRING pActivatibleClassId,
   _Deref_out_ IActivationFactory **ppIFactory,
   wchar_t* serverName = nullptr
);

Parameters

pActivatibleClassId
IID of a runtime class.

ppIFactory
The IActivationFactory for the specified runtime class.

serverName
The name of a subset of class factories in the current module. Specify the server name used in the ActivatableClassWithFactoryEx macro, or specify nullptr to get the default server name.

Return Value

S_OK if successful; otherwise, the HRESULT returned by GetActivationFactory.

Module::GetClassObject

Retrieves a cache of class factories.

HRESULT GetClassObject(
   REFCLSID clsid,
   REFIID riid,
   _Deref_out_ void **ppv,
   wchar_t* serverName = nullptr
);

Parameters

clsid
Class ID.

riid
Interface ID that you request.

ppv
Pointer to returned object.

serverName
The server name that is specified in either the ActivatableClassWithFactory, ActivatableClassWithFactoryEx, or ActivatableClass macro; or nullptr to get the default server name.

Return Value

Remarks

Use this method only for COM, not the Windows Runtime. This method exposes only IClassFactory methods.

Module::GetModule

Creates an instance of a module.

static Module& GetModule();
WRL_NOTHROW static Module& GetModule();

Return Value

A reference to a module.

Module::GetObjectCount

Retrieves the number of objects managed by this module.

virtual long GetObjectCount() const;

Return Value

The current number of objects managed by this module.

Module::IncrementObjectCount

Increments the number of objects tracked by the module.

virtual long IncrementObjectCount();

Return Value

The count before the increment operation.

Module::Module

Initializes a new instance of the Module class.

Module();

Remarks

This constructor is protected and cannot be called with the new keyword. Instead, call either Module::GetModule or Module::Create.

Module::objectCount_

Keeps track of how many classes have been created with the Make function.

volatile long objectCount_;

Module::RegisterCOMObject

Registers one or more COM objects so other applications can connect to them.

WRL_NOTHROW virtual HRESULT RegisterCOMObject(
   const wchar_t* serverName,
   IID* clsids,
   IClassFactory** factories,
   DWORD* cookies,
   unsigned int count);

Parameters

serverName
Fully-qualified name of a server.

clsids
An array of CLSIDs to register.

factories
An array of IUnknown interfaces of the class objects whose availability is being published.

cookies
When the operation completes, an array of pointers to values that identify the class objects that were registered. These values are later used revoke the registration.

count
The number of CLSIDs to register.

Return Value

S_OK if successful; otherwise, an HRESULT such as CO_E_OBJISREG that indicates the reason the operation failed.

Remarks

The COM objects are registered with the CLSCTX_LOCAL_SERVER enumerator of the CLSCTX enumeration.

The type of connection to the registered objects is specified by a combination of the current comflag template parameter and the REGCLS_SUSPENDED enumerator of the REGCLS enumeration.

Module::RegisterObjects

Registers COM or Windows Runtime objects so other applications can connect to them.

HRESULT RegisterObjects(
   ModuleBase* module,
   const wchar_t* serverName);

Parameters

module
An array of COM or Windows Runtime objects.

serverName
Name of the server that created the objects.

Return Value

S_OK if successful; otherwise, an HRESULT that indicates the reason the operation failed.

Module::RegisterWinRTObject

Registers one or more Windows Runtime objects so other applications can connect to them.

HRESULT RegisterWinRTObject(const wchar_t* serverName,
   wchar_t** activatableClassIds,
   WINRT_REGISTRATION_COOKIE* cookie,
   unsigned int count)

Parameters

serverName
A name that specifies a subset of objects affected by this operation.

activatableClassIds
An array of activatable CLSIDs to register.

cookie
A value that identifies the class objects that were registered. This value is used later to revoke the registration.

count
The number of objects to register.

Return Value

S_OK if successful; otherwise, an error HRESULT such as CO_E_OBJISREG that indicates the reason the operation failed.

Module::releaseNotifier_

Holds a pointer to a ReleaseNotifier object.

ReleaseNotifier *releaseNotifier_;

Module::Terminate

Causes all factories instantiated by the module to shut down.

void Terminate();

Remarks

Releases the factories in the cache.

Module::UnregisterCOMObject

Unregisters one or more COM objects, which prevents other applications from connecting to them.

virtual HRESULT UnregisterCOMObject(
   const wchar_t* serverName,
   DWORD* cookies,
   unsigned int count

Parameters

serverName
(Unused)

cookies
An array of pointers to values that identify the class objects to be unregistered. The array was created by the RegisterCOMObject method.

count
The number of classes to unregister.

Return Value

S_OK if this operation is successful; otherwise, an error HRESULT that indicates the reason the operation failed.

Module::UnregisterObjects

Unregisters the objects in the specified module so that other applications cannot connect to them.

HRESULT UnregisterObjects(
   ModuleBase* module,
   const wchar_t* serverName);

Parameters

module
Pointer to a module.

serverName
A qualifying name that specifies a subset of objects affected by this operation.

Return Value

S_OK if this operation is successful; otherwise, an error HRESULT that indicates the reason this operation failed.

Module::UnregisterWinRTObject

Unregisters one or more Windows Runtime objects so that other applications cannot connect to them.

virtual HRESULT UnregisterWinRTObject(
   unsigned int,
   _Inout_ WINRT_REGISTRATION_COOKIE* cookie
);

Parameters

cookie
A pointer to a value that identifies the class object whose registration is to be revoked.