module (C++)

Artigo
01/03/2018

The latest version of this topic can be found at module (C++).

Defines the library block in the .idl file.

Syntax

  
      [ module (  
   type=dll,  
   name=string,  
   version=1.0,  
   uuid=uuid,  
   lcid=integer,  
   control=boolean,  
   helpstring=string,  
   helpstringdll=string,  
   helpfile=string,  
   helpcontext=integer,  
   helpstringcontext=integer,  
   hidden=boolean,  
   restricted=boolean,  
   custom=string,  
   resource_name=string,  
) ];

Parameters

type (optional)
Can be one of the following:

dll Adds functions and classes that allow the resulting DLL to function as a in-process COM server. This is the default value.
exe Adds functions and classes that allow the resulting executable to function as a out of process COM server.
service Adds functions and classes that allow the resulting executable to function as an NT service.
unspecified Disables injection of ATL code related to the module attribute: the injection of ATL Module class, global instance _AtlModule and entry point functions. Does not disable injection of ATL code due to other attributes in the project.

name (optional)
The name of the library block.

version (optional)
The version number you want to assign to the library block. The default value is 1.0.

uuid
The unique ID for the library. If you omit this parameter, an ID will be automatically generated for the library. You may need to retrieve the uuid of your library block, which you can do by using the identifier __uuidof(libraryname).

lcid
The localization parameter. See lcid for more information.

control (optional)
Specifies that all coclasses in the library are controls.

helpstring
Specifies the type library.

helpstringdll (optional)
Sets the name of the .dll file to use to perform a document string lookup. See helpstringdll for more information.

helpfile (optional)
The name of the Help file for the type library.

helpcontext (optional)
The Help ID for this type library.

helpstringcontext (optional)
See helpstringcontext for more information.

hidden (optional)
Prevents the entire library from being displayed. This usage is intended for use with controls. Hosts need to create a new type library that wraps the control with extended properties. See the hidden MIDL attribute for more information.

restricted (optional)
Members of the library cannot be called arbitrarily. See the restricted MIDL attribute for more information.

custom (optional)
One or more attributes; this is similar to the custom attribute. The first parameter to custom is the GUID of the attribute. For example:

[module(custom={guid,1}, custom={guid1,2})]

resource_name
The string resource ID of the .rgs file used to register the APP ID of the DLL, executable, or service. When the module is of type service, this argument is also used to obtain the ID of the string containing the service name.

Note

Both the .rgs file and the string containing the service name should contain the same numerical value.

Remarks

Unless you specify the restricted parameter to emitidl, module is required in any program that uses C++ attributes.

A library block will be created if, in addition to the module attribute, source code also uses dispinterface, dual, object, or an attribute that implies coclass.

One library block is allowed in an .idl file. Multiple module entries in source code will be merged, with the most recent parameter values being implemented.

If this attribute is used within a project that uses ATL, the behavior of the attribute changes. In addition to the above behavior, the attribute also inserts a global object (called _AtlModule) of the correct type and additional support code. If the attribute is standalone, it inserts a class derived from the correct module type. If the attribute is applied to a class, it adds a base class of the correct module type. The correct type is determined by the value of the type parameter:

type = dll

CAtlDllModuleT is used as the base class and the standard DLL entry points required for a COM server. These entry points are DllMain, DllRegisterServer, DllUnRegisterServer, DllCanUnloadNow, and DllGetClassObject.
type = exe

CAtlExeModuleT is used as the base class and the standard executable entry point WinMain.
type = service

CAtlServiceModuleT is used as the base class and the standard executable entry point WinMain.
type = unspecified

Disables injection of ATL code related to the module attribute.

Example

The following code shows how to create a library block in the generated .idl file.

// cpp_attr_ref_module1.cpp  
// compile with: /LD  
[module(name="MyLibrary", version="1.2", helpfile="MyHelpFile")];

The following code shows that you can provide your own implementation of a function that would appear in the code that was injected as a result of using module. See /Fx for more information on viewing injected code. In order to override one of the functions inserted by the module attribute, make a class that will contain your implementation of the function and make the module attribute apply to that class.

// cpp_attr_ref_module2.cpp  
// compile with: /LD /link /OPT:NOREF  
#include <atlbase.h>  
#include <atlcom.h>  
#include <atlwin.h>  
#include <atltypes.h>  
#include <atlctl.h>  
#include <atlhost.h>  
#include <atlplus.h>  
  
// no semicolon after attribute block  
[module(dll, name="MyLibrary", version="1.2", helpfile="MyHelpFile")]   
// module attribute now applies to this class  
class CMyClass {  
public:  
BOOL WINAPI DllMain(DWORD dwReason, LPVOID lpReserved) {  
   // add your own code here  
   return __super::DllMain(dwReason, lpReserved);  
   }  
};

Requirements

Attribute Context

Applies to	Anywhere
Repeatable	No
Required attributes	None
Invalid attributes	None

For more information, see Attribute Contexts.

Compartilhar via