# Import command

# Import command

C ++

# The import command is used to combine information from a type library. The content of this type of library is converted to C ++ class, which is mainly used to describe the COM interface.

Syntax

# Import "file name" [attribute]

# Import <File Name> [attribute]

Attribute:

Attribute 1, attribute 2 ,...

Attribute 1 Property 2...

The file name is the name of a file containing the type library information. A file can be of the following types:

* A Type Library (. TLB or. odl) file.

* An executable (. EXE) file.

* A library file (. dll) containing type library resources (such as. ocx ).

* A composite document containing the Type Library.

* Other file formats supported by loadtypelib APIs.

You can have a directory specification before the file name. The file name must be the name of an existing file. The difference between the two formats is that when the path is not fully described, the pre-processor retrieval type library files are in different order.

Action

Syntax format

The format of quotation marks allows the Preprocessor to first search for the type library files in the same directory as the files containing the # Import Statement, and then search for the files in all directories including (# include, finally, search in the following path

Angle brackets indicate that the Preprocessor searches for type library files in the following path

The compiler searches for named files in the following directory:

1. Path Environment Variable path table.

2. Lib environment variable path table.

3. Use the path specified by the/I (additional including directory) compiler option. # Import can include one or more attributes. These attributes enable the compiler to change the content of the Type Library header file. A backslash (\) can contain additional lines in a single # Import Statement, for example:

# Import "test. lib" no_namespace \

Rename ("oldname", "newname ")

# The import attributes are listed as follows:

Exclude	High_method_prefix
High_property_prefixes	Implementation_only
Include (...)	Inject_statement
Named_guids	No_auto_exclude
No_implementation	No_namespace
Raw_dispinterfaces	Raw_interfaces_only
Raw_method_prefix	Raw_native_types
Raw_property_prefixes	Rename
Rename_namespace

# The import command can create two header files in the C ++ source code that refactored the content of the Type Library. The first header file is similar to the header file generated by the Microsoft Interface Definition Language (midl) compiler, however, additional compilers generate code and data. The first header file has the same basic name as the type library, and its extension is. tlh. The second header file also has the same basic name as the type library, and its extension is. TLI. It includes the implementation of the member functions generated by the compiler and is included in the first object of (# include.

Both header files are in the output directory specified by the/fo (named object file) option. Then they are read and compiled, just as the first file is named by the # include command.

The following is the compiler optimization accompanied by # import commands:

* When the header file is created, it will be allocated the same time sign as the class library.

* Processing # during import, the compiler first tests whether the header file exists and whether it expires. If the condition is true, you do not need to create a new one.

* The Compiler delays the initialization of the OLE subsystem until the first # import command is run.

# The import command can also be used for minimum reconstruction and placed in a precompiled header file.

Basic Type Library header file

The Basic Type Library header file consists of seven parts:

1. Fixed Header body: it consists of comments, comdef. H (which defines some standard macros used in the header) # include statements, and other complicated installation information.

2. Forward reference and Type Definition: it consists of structure descriptions such as struct imyinterface and type definitions used for some tkind_alias items.

3. Sensitive pointer Description: the module class _ com_ptr_t is a sensitive pointer implementation that encapsulates interface pointers and eliminates the need to call addref, release, and QueryInterface functions. In addition, it hides the cocreateinstance call in creating a new COM object. This section uses the macro statement _ com_smartptr_typedef to create a special template for the class definition of the COM interface as the _ com_ptr_t template class. For example, the ifoo and. tlh file packages on the Interface contain:

_ Com_smartptr_typedef (ifoo, _ uuidof (ifoo ));

The compiler extends this parameter to: Type Def _ com_ptr_t <_ com_iiid <ifoo, _ uuidof (ifoo)> ifooptr;

The ifooptr type can be used in the original interface pointer ifoo. As a result, you do not need to call various iunknown member functions.

4. typeinfo Description: It mainly consists of class definition and other items. These items are described by a single information type item returned by ityptlib: gettypeinfo. In this section, each information type from the Type Library is reflected in this header in a format dependent on typekind information.

5. Select an old guid definition: the initialization process of the guid constant containing the name. These definitions are the names of clsid_coclass and iid_interface, which are similar to those generated by the midl compiler.

6. The # include statement used in the header of the second database type.

7. Fixed ending text: currently includes # pragma pack (POP ).

In addition to the Fixed Header body and the fixed ending body, these parts are included in the namespace specified by the library statement in the original IDL file. You can use this name from the Type Library header by explicitly specifying the namespace or including the following statements.

Using namespace mylib

Immediately after the # Import Statement of the source code

Namespace can be blocked by the # no_namespace attribute of the import command. However, the blocked namespace may cause Name Conflict. The namespace can also be renamed using the rename_namespace attribute.

The compiler provides a full path to any type library that depends on the Type Library currently being processed. The path is written in the annotation format to the Type Library header (. tlh) generated by the compiler for each processed Type Library ).

If a type library contains a type reference defined for other types of libraries, the. tlh file will include the following annotations:

//

// Cross-referenced type libraries:

//

// # Import "C: \ path \ typelib0.tlb"

//

The actual file name in the # import annotation is the full path of the type library that is stored in the register for cross-reference. If you encounter an error due to omitting the type definition, check the annotation in The. tlh header to see which dependency type library needs to be input first. Compile. possible Errors in TLI files include syntax errors (for example, c2143, c2146, c2321), c2501 (instructions are missing), and c2433 ('inline' is not allowed in the data description ′).

You must determine which dependency annotations are not provided by the system header. Instead, you must provide a # import command somewhere before the # import command of the dependency Type Library to eliminate these errors.

Exclude attribute exclude ("1" [, "name 2",...])

Name 1

First excluded item

Name 2

The second exclusion item (if necessary)

The Type Library may contain the definition of items defined in the system header or other types of libraries. This attribute can be used to exclude these items from the generated Type Library header files. This attribute can contain any number of parameters, each of which is a excluded high-level library item:

High_method_prefix attribute

High_method_prefix ("prefix ")

Prefix

Prefix used

By default, a member function with no prefix is used to display the attributes and methods of advanced error handling. This name is from the Type Library. The high_method_prefix attribute specifies a prefix used to name these advanced attributes and methods.

High_property_prefixes attributes

High_property_prefixes ("getprefix," "putprefix," "putrefprefix ")

Getprefix

Prefix used for the propget Method

Putprefix

Prefix used for the propput Method

Putrefprefix

Prefix used for the propputref Method

By default, advanced error handling methods, such as propget, propput, and propputref, are described using the member functions with the names of get, put, and putref. The high_property_prefixes attribute describes the prefixes of these three attribute methods.

Implementation_only attribute

The implementation_only attribute disables the generation of. tlh header files (basic header files. This file contains all the instructions for displaying the content of the Type Library. The implementation of the. TLI header file and the wrapper member function will be generated and included in the compilation process.

When this attribute is specified, the content of the. TLI header is placed in the same namespace as the content used to store the common. tlh header. In addition, this member function will not be used as an association description. The implementation_only attribute is generally intended to be paired with the no_implementation attribute to track implementations other than the pre-compiled header file (PCH. An # import statement with the no_implementation attribute is placed in the source region used to create PCH, and the result PCH will be used by some source files. An # import statement with the implementation_only attribute is subsequently used outside the PCH region. You only need to use this statement once in a source file. This will generate all necessary wrapper member functions that do not require additional re-compilation for each source file.

Note: The implementation_only attribute in one # import statement must be used together with the other # Import Statement in the no_implementation attribute of the same type library. Otherwise, a compilation error occurs. This is because the # Wrapper class definition generated by the import statement with the no_implementation attribute needs to compile the statement implementation generated by the implementation_only attribute.

Include (...) attributes

Include (name 1 [, name 2,...])

Name 1

The first mandatory item

Name 2

The second mandatory item (if necessary)

The Type Library may contain the definition of items defined in the system header or other type libraries. # The import command tries to use automatic exclusion to avoid multiple definition errors. If these items have been excluded, as stated in the warning c4192, and they should not be excluded, this attribute can be used to disable automatic exclusion. This attribute can contain any number of parameters. Each parameter should be the name of the included Type Library item.

Inject_statement attributes

Inject_statement ("source_text ")

Source_text

Source text inserted into the Type Library header file.

The inject_statement attribute uses its parameters as the header of the source text insertion type library. This text is placed at the beginning of the namespace description that includes the Type Library Content in the header file.

Named_guids attributes

The named_guids attribute allows the compiler to define and initialize the guid variables in the old format of the libid_mylib, clsid_mycoclass, iid_myinterface, and diid_mydispinterface templates.

No_implementation attributes

This attribute prevents the generation of. TLI header files. This file contains the implementation of wrapper member functions. If this attribute is specified, the. tlh header of the Type Library description will generate no # include statement including the. TLI header file.

This attribute is used together with the implementation_only attribute.

No_auto_exclude attribute

The Type Library may include the definition of items defined in the system header or other type libraries. # Import tries to avoid multiple definition errors by automatically rejecting these items. In this case, each excluded item generates a c4192 warning message. You can disable automatic exclusion for this attribute.

No_namespace attributes

# The Type Library Content in the import header file is generally 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, the compiler will not generate this namespace.

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

Raw_dispinterfaces attributes

The raw_dispinterfaces attribute allows the compiler to generate a low-level wrapper function. This function is used to call the idispatch: invoke and the dispinterface method and attribute that return the hresult error code. If this attribute is not specified, only the advanced wrapper is generated, and the C ++ exception is discarded when a failure occurs.

Raw_interfaces_only attribute

The raw_interfaces_only attribute prohibits the generation of wrapper functions for error handling and the use of these wrapper functions in the _ declspec (attribute) description.

The raw_interfaces_only attribute also deletes the default prefix in the non _ property function. Generally, the prefix is raw _. If this attribute is specified, the function name is directly generated from the Type Library. This attribute only displays the low-level content of the Type Library.

Raw_method_prefix attribute

Raw_method_prefix ("prefix ")

Prefix

Prefix used

Use raw _ as the default prefix to display lower-level attributes and methods of member functions, so as to avoid conflicts with the names of member functions in advanced error handling. 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 because of the existence of the raw_method_prefix attribute. When specifying a prefix, raw_method_prefix always takes precedence over raw_interfaces_only. If the two attributes are used in the same # Import Statement, the prefix specified by raw_method_prefix is used.

Raw_native_types attributes

By default, In the BSTR and variant data types and original COM interface pointers, the advanced error handling method uses com to support classes _ bctr_t and _ variant_t. These classes encapsulate the details of allocating and unassigning storage for these data types, and greatly simplify the type styling and conversion operations. The raw_native_types attribute prohibits the use of these com support classes in advanced wrapper functions and forcibly replaces the use of low-level data types.

Raw_property_prefix attribute

Raw_property_prefix ("getprefix", "putprefix", "putrefprefix ")

Getprefix

Prefix used for the propget Method

Putprefix

Prefix used for the propput Method

Putrefprefix

Prefix used for the propputref Method

By default, the low-level methods propget, propput, and propputref are displayed using the member functions with the suffix get _, put _, and putref _ respectively. These prefixes are compatible with names in header files generated by midl. The raw_property_prefixes attribute is used to describe the prefix of the three Property methods.

Rename attributes

Rename ("oldname," "newname ")

Oldname

Old name in Type Library

Newname

Used to replace the old name

The rename attribute is used to resolve name conflicts. If this attribute is specified, the compiler replaces the oldname In the result header file with the newname provided by the user in the Type Library.

This attribute is used when a name in the Type Library is duplicated with the macro definition in the system header file. If this problem is not solved, a large number of syntax errors will be generated, such as c2059 and c2061.

Note: This replacement is used for the Type Library name instead of the name in the result header file.

Here is an example: assume that the Type Library has an attribute named myparent, And the header file defines a macro getmyparent used before # import. Because getmyparent is the default name of a wrapper function used for the error processing attribute get, a name conflict occurs. To solve this problem, use the following attributes in the # Import Statement:

Rename ("myparent", "myparentx ")

This statement will rename the name myparent in the Type Library, and an error will occur if you try to rename getmyparentwrapper:

Rename ("getmyparent", "getmyparentx ")

This is because the name getmyparent only appears in the header file of the result type library.

Rename_namespace attributes

Rename_namespace ("newname ")

Newname

New namespace name

The rename_namespace attribute is used to rename the namespace that contains the content of the Type Library. It carries a parameter with the new name newname of the specified namespace.

You can use the no_namespace attribute to remove a namespace.

C ++ ends