Skip to content

Latest commit

 

History

History
453 lines (301 loc) · 15.7 KB

module-class.md

File metadata and controls

453 lines (301 loc) · 15.7 KB
descriptiontitlems.datems.topicf1_keywordshelpviewer_keywordsms.assetid
Learn more about: Module Class
Module Class
10/18/2018
reference
module/Microsoft::WRL::Module
module/Microsoft::WRL::Module::Create
module/Microsoft::WRL::Module::DecrementObjectCount
module/Microsoft::WRL::Module::GetActivationFactory
module/Microsoft::WRL::Module::GetClassObject
module/Microsoft::WRL::Module::GetModule
module/Microsoft::WRL::Module::GetObjectCount
module/Microsoft::WRL::Module::IncrementObjectCount
module/Microsoft::WRL::Module::Module
module/Microsoft::WRL::Module::objectCount_Data
module/Microsoft::WRL::Module::RegisterCOMObject
module/Microsoft::WRL::Module::RegisterObjects
module/Microsoft::WRL::Module::RegisterWinRTObject
module/Microsoft::WRL::Module::releaseNotifier_
module/Microsoft::WRL::Module::Terminate
module/Microsoft::WRL::Module::~Module
module/Microsoft::WRL::Module::UnregisterCOMObject
module/Microsoft::WRL::Module::UnregisterObjects
module/Microsoft::WRL::Module::UnregisterWinRTObject
Microsoft::WRL::Module class
Microsoft::WRL::Module::Create method
Microsoft::WRL::Module::DecrementObjectCount method
Microsoft::WRL::Module::GetActivationFactory method
Microsoft::WRL::Module::GetClassObject method
Microsoft::WRL::Module::GetModule method
Microsoft::WRL::Module::GetObjectCount method
Microsoft::WRL::Module::IncrementObjectCount method
Microsoft::WRL::Module::Module, constructor
Microsoft::WRL::Module::objectCount_ data member
Microsoft::WRL::Module::RegisterCOMObject method
Microsoft::WRL::Module::RegisterObjects method
Microsoft::WRL::Module::RegisterWinRTObject method
Microsoft::WRL::Module::releaseNotifier_ data member
Microsoft::WRL::Module::Terminate method
Microsoft::WRL::Module::~Module, destructor
Microsoft::WRL::Module::UnregisterCOMObject method
Microsoft::WRL::Module::UnregisterObjects method
Microsoft::WRL::Module::UnregisterWinRTObject method
dd67e3b8-c2e1-4f53-8c0f-565a140ba649

Module Class

Represents a collection of related objects.

Syntax

template<ModuleType moduleType> classModule; template<> classModule<InProc> : public Details::ModuleBase; template<> classModule<OutOfProc> : public Module<InProc>;

Parameters

moduleType
A combination of one or more ModuleType enumeration values.

Members

Protected Classes

NameDescription
Module::GenericReleaseNotifierInvokes 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::MethodReleaseNotifierInvokes 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::ReleaseNotifierInvokes an event handler when the last object in a module is released.

Public Constructors

NameDescription
Module::~ModuleDeinitializes the current instance of the Module class.

Protected Constructors

NameDescription
Module::ModuleInitializes a new instance of the Module class.

Public Methods

NameDescription
Module::CreateCreates an instance of a module.
Module::DecrementObjectCountDecrements the number of objects tracked by the module.
Module::GetActivationFactoryGets an activation factory for the module.
Module::GetClassObjectRetrieves a cache of class factories.
Module::GetModuleCreates an instance of a module.
Module::GetObjectCountRetrieves the number of objects managed by this module.
Module::IncrementObjectCountIncrements the number of objects tracked by the module.
Module::RegisterCOMObjectRegisters one or more COM objects so other applications can connect to them.
Module::RegisterObjectsRegisters COM or Windows Runtime objects so other applications can connect to them.
Module::RegisterWinRTObjectRegisters one or more Windows Runtime objects so other applications can connect to them.
Module::TerminateCauses all factories instantiated by the module to shut down.
Module::UnregisterCOMObjectUnregisters one or more COM objects, which prevents other applications from connecting to them.
Module::UnregisterObjectsUnregisters the objects in the specified module so that other applications cannot connect to them.
Module::UnregisterWinRTObjectUnregisters one or more Windows Runtime objects so that other applications cannot connect to them.

Protected Methods

NameDescription
Module::CreateCreates an instance of a module.

Protected Data Members

NameDescription
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

NameDescription
ActivatableClassPopulates 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.
ActivatableClassWithFactoryPopulates 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.
ActivatableClassWithFactoryExPopulates 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.

virtuallongDecrementObjectCount();

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.

virtuallongGetObjectCount() const;

Return Value

The current number of objects managed by this module.

Module::IncrementObjectCount

Increments the number of objects tracked by the module.

virtuallongIncrementObjectCount();

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.

volatilelong objectCount_;

Module::RegisterCOMObject

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

WRL_NOTHROW virtual HRESULT RegisterCOMObject( constwchar_t* serverName, IID* clsids, IClassFactory** factories, DWORD* cookies, unsignedint 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, constwchar_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(constwchar_t* serverName, wchar_t** activatableClassIds, WINRT_REGISTRATION_COOKIE* cookie, unsignedint 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.

voidTerminate();

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( constwchar_t* serverName, DWORD* cookies, unsignedint 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, constwchar_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( unsignedint, _Inout_ WINRT_REGISTRATION_COOKIE* cookie );

Parameters

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

close