The exclude attribute

exclude("Name1"[, "Name2",...])

Name1

First item to be excluded

Name2

Second item to be excluded (if necessary)

Type libraries may include definitions of items defined in system headers or other type libraries. This attribute can be used to exclude these items from the type library header files being generated. This attribute can take any number of arguments, each being a top-level type library item to be excluded.

The high_method_prefix attribute

high_method_prefix("Prefix")

Prefix

Prefix to be used

By default, high-level error-handling properties and methods are exposed by member functions named without a prefix. The names are from the type library. The high_method_prefix attribute is used to specify a prefix to be used in naming these high-level properties and methods.

The high_property_prefixes attribute

high_property_prefixes("GetPrefix","PutPrefix","PutRefPrefix")

GetPrefix

Prefix to be used for the propget methods

PutPrefix

Prefix to be used for the propput methods

PutRefPrefix

Prefix to be used for the propputref methods

By default, high-level error-handling propget, propput, and propputref methods are exposed by member functions named with prefixes Get, Put, and PutRef respectively. The high_property_prefixes attribute is used to specify alternate prefixes for all three property methods.

The implementation_only attribute

The implementation_only attribute suppresses the generation of the .TLH header file (the primary header file). This file contains all the declarations used to expose the type-library contents. The .TLI header file, with the implementations of the wrapper member functions, will be generated and included in the compilation.

When this attribute is specified, the content of the .TLI header is in the same namespace as the one normally used in the .TLH header. In addition, the member functions are not declared as inline.

The implementation_only attribute is intended for use in conjunction with the no_implementation attribute as a way of keeping the implementations out of the precompiled header (PCH) file. An #import statement with the no_implementation attribute is placed in the source region used to create the PCH. The resulting PCH is used by a number of source files. An #import statement with the implementation_only attribute is then used outside the PCH region. You are required to use this statement only once in one of the source files. This will generate all the required wrapper member functions without additional recompilation for each source file.

Note   The implementation_only attribute in one #import statement must be use in conjunction with another #import statement, of the same type library, with the no_implementation attribute. Otherwise, compiler errors will be generated. This is because wrapper class definitions generated by the #import statement with the no_implementation attribute are required to compile the implementations generated by the implementation_only attribute.

The include(...) attribute

include(Name1[, Name2, ...])

Name1

First item to be forcibly included

Name2

Second item to be forcibly included (if necessary)

Type libraries may include definitions of items defined in system headers or other type libraries.  #import attempts to avoid multiple definition errors by automatically excluding such items.  If items have been excluded, as indicated by warning C4192, and they should not have been, this attribute can be used to disable the automatic exclusion.  This attribute can take any number of arguments, each being the name of the type-library item to be included.

The inject_statement attribute

inject_statement("source_text")

source_text

Source text to be inserted into the type library header file

The inject_statement attribute inserts its argument as source text into the type-library header. The text is placed at the beginning of the namespace declaration that wraps the type-library contents in the header file.

The named_guids attribute

The named_guids attribute tells the compiler to define and initialize GUID variables in old style, of the form LIBID_MyLib, CLSID_MyCoClass, IID_MyInterface, and DIID_MyDispInterface.

The no_implementation attribute

The no_implementation attribute suppresses the generation of the .TLI header, which contains the implementations of the wrapper member functions. If this attribute is specified, the .TLH header, with the declarations to expose type-library items, will be generated without an #include statement to include the .TLI header file.

This attribute is used in conjunction with implementation_only.

The no_auto_exclude attribute

Type libraries may include definitions of items defined in system headers or other type libraries.  #import attempts to avoid multiple definition errors by automatically excluding such items.  When this is done, warning C4192 will be issued for each item to be excluded.  You can disable this automatic exclusion by using this attribute.

The no_namespace attribute

The type-library contents in the #import header file are normally defined in a namespace. The namespace name is specified in the library statement of the original IDL file. If the no_namespace attribute is specified, this namespace is not generated by the compiler.

If you want to use a different namespace name, use the rename_namespace attribute instead.

The raw_dispinterfaces attribute

The raw_dispinterfaces attribute tells the compiler to generate low-level wrapper functions for dispinterface methods and properties that call IDispatch::Invoke and return the HRESULT error code.

If this attribute is not specified, only high-level wrappers are generated, which throw C++ exceptions in case of failure.

The raw_interfaces_only attribute

The raw_interfaces_only attribute suppresses the generation of error-handling wrapper functions and __declspec(property) declarations that use those wrapper functions.

The raw_interfaces_only attribute also causes the default prefix used in naming the non-property functions to be removed. Normally, the prefix is raw_. If this attribute is specified, the function names are directly from the type library.

This attribute allows you to expose only the low-level contents of the type library.

The raw_method_prefix attribute

raw_method_prefix("Prefix")

Prefix

The prefix to be used

Low-level properties and methods are exposed by member functions named with a default prefix of raw_ to avoid name collisions with the high-level error-handling member functions. The raw_method_prefix attribute is used to specify a different prefix.

Note   The effects of the raw_method_prefix attribute will not be changed by the presence of the raw_interfaces_only attribute. The raw_method_prefix always takes precedence over raw_interfaces_only in specifying a prefix. If both attributes are used in the same #import statement, then the prefix specified by the raw_method_prefix attribute is used.

The raw_native_types attribute

By default, the high-level error-handling methods use the COM support classes _bstr_t and _variant_t in place of the BSTR and VARIANT data types and raw COM interface pointers. These classes encapsulate the details of allocating and deallocating memory storage for these data types, and greatly simplify type casting and conversion operations. The raw_native_types attribute is used to disable the use of these COM support classes in the high-level wrapper functions, and force the use of low-level data types instead.

The raw_property_prefixes attribute

raw_property_prefixes("GetPrefix","PutPrefix","PutRefPrefix")

GetPrefix

Prefix to be used for the propget methods

PutPrefix

Prefix to be used for the propput methods

PutRefPrefix

Prefix to be used for the propputref methods

By default, low-level propget, propput, and propputref methods are exposed by member functions named with prefixes of get_, put_, and putref_ respectively. These prefixes are compatible with the names used in the header files generated by MIDL. The raw_property_prefixes attribute is used to specify alternate prefixes for all three property methods.

The rename attribute

rename("OldName","NewName")

OldName

Old name in the type library

NewName

Name to be used instead of the old name

The rename attribute is used to work around name collision problems. If this attribute is specified, the compiler replaces all occurrences of OldName in a type library with the user-supplied NewName in the resulting header files.

This attribute can be used when a name in the type library coincides with a macro definition in the system header files. If this situation is not resolved, then various syntax errors will be generated, such as C2059 and C2061.

Note   The replacement is for a name used in the type library, not for a name used in the resulting header file.

Here is an example: Suppose a property named MyParent exists in a type library, and a macro GetMyParent is defined in a header file and used before #import. Since GetMyParent is the default name of a wrapper function for the error-handling get property, a name collision will occur. To work around the problem, use the following attribute in the #import statement:

rename(“MyParent”,”MyParentX”)

which renames the name MyParent in the type library. An attempt to rename the GetMyParent wrapper name will fail:

rename(“GetMyParent”,”GetMyParentX”)

This is because the name GetMyParent only occurs in the resulting type library header file.

The rename_namespace attribute

rename_namespace("NewName")

NewName

The new name of the namespace

The rename_namespace attribute is used to rename the namespace that contains the contents of the type library. It takes a single argument, NewName, which specifies the new name for the namespace.

To remove the namespace, use the no_namespace attribute instead.

END C++ Specific