18 Type Libraries

Type libraries and the type description interfaces provide a way to read and bind to the descriptions of objects in a type library. These descriptions are used by COM clients when they browse, create, and manipulate COM objects.

The type description interfaces described in this chapter include:

ITypeLib() -- Retrieves information about a type library.

ITypeLib2() -- Allows ITypeLib() to cast to an ITypeLib2() in performance-sensitive cases.

ITypeInfo() -- Reads the type information within the type library.

ITypeInfo2() -- Allows ITypeInfo() to cast to an ITypeInfo2() in performance-sensitive cases.

ITypeComp() -- Creates compilers that use type information.

This chapter also describes functions for loading, registering, and querying type libraries.

18.1 Overview of Type Description Interfaces

A type library is a container for type descriptions of one or more objects, and is accessed through the ITypeLib() interface. The ITypeLib() interface provides access to information about the type description in a type library. The descriptions of individual objects are accessed through the ITypeInfo() interface.

In addition, there are two new interfaces for Automation:

ITypeInfo2::ITypeInfo()

ITypeLib2::ITypeLib()

Because they inherit from ITypeInfo() and ITypeLib, an ITypeInfo() can be cast to an ITypeInfo2() instead of using the calls QueryInterface() and Release().

By adding the new methods described in the following section, QueryInterface() can be called to ITypeInfo2() and ITypeLib2() in the same way as ITypeInfo() and ITypeLib().

The ITypeInfo() interface is typically used for reading information about objects. For example, an object browser tool can use ITypeInfo() to extract information about the characteristics and capabilities of objects from type libraries.

Table 18-1: Type Description Interface Elements

`Implemented by`	`Used by`	`Header file name`
`Oleaut32.dll` (32-bit systems) `Typelib.dll` (16-bit systems)	Tools that need to access the descriptions of objects contained in type libraries.	`Oleauto.h Dispatch.h`

Type information interfaces are intended to describe the parts of the application that can be called by outside clients, rather than those that might be used internally to build an application.

The ITypeInfo() interface provides access to the following:

The set of function descriptions associated with the type. For interfaces, this contains the set of member functions in the interface.

The set of data member descriptions associated with the type. For structures, this contains the set of fields of the type.

The general attributes of the type, such as whether it describes a structure, an interface, and so on.

The type description of an IDispatch() interface can be used to implement the interface. For more information, see the description of CreateStdDispatch() Chapter 19.

An instance of ITypeInfo() provides various information about the type of an object, and is used in different ways. A compiler can use an ITypeInfo() to compile references to members of the type. A type interface browser can use it to find information about each member of the type. An IDispatch() implementor can use it to provide automatic delegation of IDispatch() calls to an interface.

18.1.1 Type Descriptions

The information associated with an object described by ITypeInfo() can include a set of functions, a set of data members, and various type attributes. It is essentially the same as the information described by a C++ class declaration, which can be used to define both interfaces and structures, as well as any combination of functions and data members. In addition to interfaces and structure definitions, the ITypeInfo() interface is used to describe other types, including enumerations and aliases. Because the interface to a C file or library is simply a set of functions and variable declarations, ITypeInfo() can also be used to describe them.

Type information comprises individual type descriptions. Each type description must have one of the following forms:

Table 18-2: Type Description Forms

`Category`	`ODL keyword`	`Description`
alias	`typedef`	An alias for another type.
enumeration	`enum`	An enumeration.
structure	`struct`	A structure.
union	`union`	A single data item that can have one of a specified group of types.
module	`module`	Data and functions not accessed through virtual function table (VTBL) entries.
`IDispatch()` interface	`dispinterface`	`IDispatch()` properties and methods accessed through `IDispatch::Invoke()`.
COM interface	`interface`	COM member functions accessed through VTBL entries.
dual interface	`dual`	Supports either VTBL or `IDispatch()`.
component object class	`coclass`	A component object class. Specifies an implementation of one or more COM interfaces and one or more `IDispatch()` interfaces.

Note All bit flags that are not used specifically should be set to zero for future compatibility.

18.1.1.1 Alias

An alias has TypeKind = TKIND_ALIAS. An alias is an empty set of functions, an empty set of data members, and a type description (located in the TYPEATTR), which gives the actual type definition (typedef) of the alias.

18.1.1.2 Enumeration (Statement)

An enumeration (enum) has TypeKind = TKIND_ENUM. An enumeration is an empty set of functions and a set of constant data members.

18.1.1.3 Structure (Statement)

A structure (struct) description has TypeKind = TKIND_RECORD. A structure is an empty set of functions and a set of per-instance data members.

18.1.1.4 Union (Statement)

A union description has TypeKind = TKIND_UNION. A union is an empty set of functions and a set of per-instance data members, each of which has an instance offset of zero.

18.1.1.5 Module (Statement)

A module has TypeKind = TKIND_MODULE. A module is a set of static functions and a set of static data members.

18.1.1.6 V-table Interface

An interface definition has TypeKind = TKIND_INTERFACE. An interface is a set of pure virtual functions and an empty set of data members. If a type description contains any virtual functions, then the pointer to the VTBL is the first 4 bytes of the instance.

The type information fully describes the member functions in the VTBL, including parameter names and types and function return types. It may inherit from no more than one other interface.

With interfaces and dispinterfaces, all members should have different names, except the accessor functions of properties. For property functions having the same name, the documentation string and Help context should be set for only one of the functions (because they define the same property conceptually).

18.1.1.7 IDispatch Interface

These include objects (TypeKind = TKIND_DISPATCH) that support the IDispatch() interface with a specification of the dispatch data members (such as properties) and methods supported through the object's Invoke implementation. All members of the dispinterface should have different IDs, except for the accessor functions of properties.

18.1.1.8 Dual Interface

Dual interfaces (dual) have two different type descriptions for the same interface. The TKIND_INTERFACE type description describes the interface as a standard Component Object Model (COM) interface. The TKIND_DISPATCH type description describes the interface as a standard dispatch interface. The lcid and retval parameters, and the HRESULT return types are removed, and the return type of the member is specified to be the same type as the retval parameter.

By default, the TYPEKIND enumeration for a dual interface is TKIND_DISPATCH. Tools that bind to interfaces should check the type flags for TYPEFLAG_FDUAL. If this flag is set, the TKIND_INTERFACE type description is available through a call to ITypeInfo::GetRefTypeOfImplType() with an index of -1, followed by a call to ITypeInfo::GetRefTypeInfo().

18.1.1.9 Component Object Classes

These coclass objects (TypeKind = TKIND_COCLASS) support a set of implemented interfaces, which can be of either TKIND_INTERFACE or TKIND_DISPATCH.

18.2 Type Library Interface Descriptions

18.2.1 IProvideClassInfo

See IProvideClassInfo().

18.2.2 IProvideClassInfo2

See IProvideClassInfo2().

18.2.3 ITypeLib

The data that describes a set of objects is stored in a type library. A type library can be a stand-alone binary file (.tlb), a resource in a dynamic link library or executable file (.dll or .exe), or part of a compound document file.

Table 18-3: IProvideClassInfo Elements

`Implemented by`	`Used by`	`Header file name`
`Oleaut32.dll` (32-bit systems) `Typelib.dll` (16-bit systems)	Tools that need to access the descriptions of objects contained in type libraries.	`Oleauto.h Dispatch.h`

The system registry contains a list of all the installed type libraries.

The ITypeLib() interface provides methods for accessing a library of type descriptions. This interface supports the following:

Generalized containment for type information. ITypeLib() allows iteration over the type descriptions contained in the library.

Global functions and data. A type library can contain descriptions of a set of modules, each of which is the equivalent of a C or C++ source file that exports data and functions. The type library supports compiling references to the exported data and functions.

General information, including a user-readable name for the library and help for the library as a whole.

ITypeLib::FindName()

NAME

ITypeLib::FindName() - Finds occurrences of a type description in a type library. This may be used to quickly verify that a name exists in a type library.

Synopsis

#include <Oaidl.h>

HRESULT FindName( OLECHAR FAR * szNameBuf, unsigned long lHashVal, ITypeInfo FAR * FAR * ppTInfo, MEMBERID FAR * rgMemId, unsigned int FAR * pcFound );

Description

Passing *pcFound = n indicates that there is enough room in the ppTInfo and rgMemId arrays for n (ptinfo, memid) pairs. The function returns MEMBERID_NIL in rgMemId[i], if the name in szNameBuf is the name of the type information in ppTInfo[i].

Parameters

szNameBuf

The name to search for.

lHashVal

A hash value to speed up the search, computed by the LHashValOfNameSys function. If lHashVal = 0, a value is computed.

ppTInfo

On return, an array of pointers to the type descriptions that contain the name specified in szNameBuf. Cannot be NULL.

rgMemId

An array of the MEMBERIDs of the found items; rgMemId[i] is the MEMBERID that indexes into the type description specified by ppTInfo[i]. Cannot be NULL.

pcFound

On entry, indicates how many instances to look for. For example, *pcFound = 1 can be called to find the first occurrence. The search stops when one is found.

On exit, indicates the number of instances that were found. If the in and out values of *pcFound are identical, there may be more type descriptions that contain the name.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
E_OUTOFMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.
TYPE_E_IOERROR: The function could not write to the file.
TYPE_E_INVDATAREAD: The function could not read from the file.
TYPE_E_UNSUPFORMAT: The type library has an older format.
TYPE_E_INVALIDSTATE: The type library could not be opened.
TYPE_E_CANTLOADLIBRARY: The library or .dll file could not be loaded.
TYPE_E_ELEMENTNOTFOUND: The element was not found.

ITypeLib::GetDocumentation()

NAME

ITypeLib::GetDocumentation() - Retrieves the library's documentation string, the complete Help file name and path, and the context identifier for the library Help topic in the Help file.

Synopsis

#include <Oaidl.h>

HRESULT GetDocumentation( int index, BSTR FAR * pBstrName, BSTR FAR * pBstrDocString, unsigned long FAR * pdwHelpContext, BSTR FAR * pBstrHelpFile );

Description

The caller should free the BSTR parameters pBstrName, pBstrDocString, and pBstrHelpFile.

Parameters

index: Index of the type description whose documentation is to be returned. I If index is -1, then the documentation for the library itself is returned.
pBstrName: Returns a BSTR that contains the name of the specified item. If the caller does not need the item name, then pBstrName can be NULL.
pBstrDocString: Returns a BSTR that contains the documentation string for the specified item. If the caller does not need the documentation string, then pBstrDocString can be NULL.
pdwHelpContext: Returns the Help context identifier (ID) associated with the specified item. If the caller does not need the Help context ID, then pdwHelpContext can be NULL.
pBstrHelpFile: Returns a BSTR that contains the fully qualified name of the Help file. If the caller does not need the Help file name, then pBstrHelpFile can be NULL.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
STG_E_INSUFFICIENTMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.
TYPE_E_IOERROR: The function could not write to the file.
TYPE_E_INVDATAREAD: The function could not read from the file.
TYPE_E_UNSUPFORMAT: The type library has an older format.
TYPE_E_INVALIDSTATE: The type library could not be opened.
TYPE_E_ELEMENTNOTFOUND: The element was not found.

Examples

for (i = 0; i < utypeinfoCount; i++)
{
	CHECKRESULT(ptlib->GetDocumentation(i, &bstrName, NULL, NULL, NULL));
.
.
.
	SysFreeString(bstrName);
}

ITypeLib::GetLibAttr()

NAME

ITypeLib::GetLibAttr() - Retrieves the structure that contains the library's attributes.

Synopsis

#include <Oaidl.h>

HRESULT GetLibAttr( TLIBATTR FAR * FAR * ppTLibAttrr );

Description

Use ITypeLib::ReleaseTLibAttr() to free the memory occupied by the TLIBATTR structure.

Parameters

ppTLibAttrr: Pointer to a structure that contains the library's attributes.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
E_OUTOFMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.
TYPE_E_IOERROR: The function could not write to the file.
TYPE_E_INVDATAREAD: The function could not read from the file.
TYPE_E_UNSUPFORMAT: The type library has an unsupported format.
TYPE_E_INVALIDSTATE: The type library could not be opened.

ITypeLib::GetTypeComp()

NAME

ITypeLib::GetTypeComp() - Enables a client compiler to bind to a library's types, variables, constants, and global functions.

Synopsis

HRESULT GetTypeComp( ITypeComp FAR * FAR * ppTComp );

Description

The Bind function of the returned TypeComp binds to global functions, variables, constants, enumerated values, and coclass members. The Bind function also binds the names of the TYPEKIND enumerations of TKIND_MODULE, TKIND_ENUM, and TKIND_COCLASS. These names shadow any global names defined within the type information. The members of TKIND_ENUM, TKIND_MODULE, and TKIND_COCLASS types marked as Application objects can be directly bound to from ITypeComp() without specifying the name of the module.

ITypeComp::Bind() and ITypeComp::BindType() accept only unqualified names. ITypeLib::GetTypeComp() returns a pointer to the ITypeComp() interface, which is then used to bind to global elements in the library. The names of some types (TKIND_ENUM, TKIND_MODULE, and TKIND_COCLASS) share the name space with variables, functions, constants, and enumerators.

If a member requires qualification to differentiate it from other items in the name space, GetTypeComp can be called successively for each qualifier in order to bind to the desired member. This allows programming language compilers to access members of modules, enumerations, and coclasses, even though the member can't be bound to with a qualified name.

Parameters

ppTComp: Points to a pointer to the ITypeComp() instance for this ITypeLib. A client compiler uses the methods in the ITypeComp() interface to bind to types in ITypeLib, as well as to the global functions, variables, and constants defined in ITypeLib().

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
E_OUTOFMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.
TYPE_E_IOERROR: The function could not read from the file.
TYPE_E_INVDATAREAD: Invalid data.
TYPE_E_UNSUPFORMAT: The type library has an older format.
TYPE_E_INVALIDSTATE: The type library could not be opened.
TYPE_E_WRONGTYPEKIND: Type mismatch.

ITypeLib::GetTypeInfo()

NAME

ITypeLib::GetTypeInfo() - Retrieves the specified type description in the library.

Synopsis

#include <Oaidl.h>

HRESULT GetTypeInfo( unsigned int index, ITypeInfo FAR * FAR * ppTInfo );

Description

For dual interfaces, ITypeLib::GetTypeInfo() returns only the TKIND_DISPATCH type information. To get the TKIND_INTERFACE type information, ITypeInfo::GetRefTypeOfImplType() can be called on the TKIND_DISPATCH type information, passing an index of -1. Then, the returned type information handle can be passed to ITypeInfo::GetRefTypeInfo().

Parameters

index: Index of the ITypeInfo() interface to be returned.
ppTInfo: If successful, returns a pointer to the pointer to the ITypeInfo() interface.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
TYPE_E_ELEMENTNOTFOUND: The index parameter is outside the range of 0 to GetTypeInfoCount() -1.
E_OUTOFMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.
TYPE_E_IOERROR: The function could not read from the file.
TYPE_E_INVDATAREAD: Invalid data.
TYPE_E_UNSUPFORMAT: The type library has an older format.
TYPE_E_REGISTRYACCESS: There was an error accessing the system registration database.
TYPE_E_INVALIDSTATE: The type library could not be opened.

Examples

The following example gets the TKIND_INTERFACE type information for a dual interface.

ptlib->GetTypeInfo((unsigned int) dwIndex, &ptypeinfoDisp);
ptypeinfoDisp->GetRefTypeOfImplType(-1, &phreftype);
ptypeinfoDisp->GetRefTypeInfo(phreftype, &ptypeinfoInt);

ITypeLib::GetTypeInfoCount()

NAME

ITypeLib::GetTypeInfoCount() -

Synopsis

HRESULT GetTypeInfoCount( );

Description

Returns the number of type descriptions in the type library.

Parameters

none

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
E_NOTIMPL: Failure.

ITypeLib::GetTypeInfoOfGuid()

NAME

ITypeLib::GetTypeInfoOfGuid() - Retrieves the type description that corresponds to the specified GUID.

Synopsis

#include <Oaidl.h>

HRESULT GetTypeInfoOfGuid( REFGUID guid, ITypeInfo FAR * FAR * ppTinfo );

Parameters

guid: Pointer to the GUID of the type description.
ppTinfo: Pointer to a pointer to the ITypeInfo() interface.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
TYPE_E_ELEMENTNOTFOUND: No type description was found in the library with the specified GUID.
E_OUTOFMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.
TYPE_E_IOERROR: The function could not write to the file.
TYPE_E_INVDATAREAD: The function could not read from the file.
TYPE_E_UNSUPFORMAT: The type library has an older format.
TYPE_E_REGISTRYACCESS: There was an error accessing the system registration database.
TYPE_E_INVALIDSTATE: The type library could not be opened.

ITypeLib::GetTypeInfoType()

NAME

ITypeLib::GetTypeInfoType() - Retrieves the type of a type description.

Synopsis

#include <Oaidl.h>

HRESULT GetTypeInfoType( unsigned int index, TYPEKIND FAR * pTKind );

Parameters

index: The index of the type description within the type library.
pTKind: A pointer to the TYPEKIND enumeration for the type description.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
TYPE_E_ELEMENTNOTFOUND: Index is outside the range of 0 to GetTypeInfoCount() -1.

ITypeLib::IsName()

NAME

ITypeLib::IsName() - Indicates whether a passed-in string contains the name of a type or member described in the library.

Synopsis

#include <Oaidl.h>

HRESULT IsName( OLECHAR FAR * szNameBuf, unsigned long lHashVal, BOOL pfName );

Parameters

szNameBuf: The string to test. If IsName() is successful, szNameBuf is modified to match the case (capitalization) found in the type library.
lHashVal: The hash value of szNameBuf.
pfName: On return, set to True if szNameBuf was found in the type library; otherwise False.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
E_OUTOFMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.
TYPE_E_IOERROR: The function could not read from the file.
TYPE_E_INVDATAREAD: Invalid data.
TYPE_E_UNSUPFORMAT: The type library has an older format.
TYPE_E_INVALIDSTATE: The type library could not be opened.

ITypeLib::ReleaseTLibAttr()

NAME

ITypeLib::ReleaseTLibAttr() - Releases the TLIBATTR originally obtained from ITypeLib::GetLibAttr().

Synopsis

#include <Oaidl.h>

HRESULT ReleaseTLibAttr( TLIBATTR FAR * pTLibAttr );

Description

Releases the specified TLIBATTR. This TLIBATTR was previously obtained with a call to GetTypeLib::GetLibAttr.

Parameters

pTLibAttr: Pointer to the TLIBATTR to be freed.

18.2.4 ITypeLib2

The ITypeLib2() interface inherits from the ITypeLib() interface. This allows ITypeLib() to cast to an ITypeLib2() in performance-sensitive cases, rather than perform extra QueryInterface() and Release() calls.

DECLARE_INTERFACE_(ITypeLib2(), ITypeLib())
{

ITypeLib2::GetCustData()

NAME

ITypeLib2::GetCustData() - Gets the custom data.

Synopsis

#include <Oaidl.h>

HRESULT GetCustData( REFGUID guid, VARIANT * pVarVal );

Parameters

guid: GUID used to identify the data.
pVarVal: Where to put the retrieved data.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
E_OUTOFMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.

ITypeLib2::GetDocumentation2()

NAME

ITypeLib2::GetDocumentation2() - Retrieves the library's documentation string, the complete Help file name and path, the localization context to use, and the context ID for the library Help topic in the Help file.

Synopsis

#include <Oaidl.h>

HRESULT GetDocumentation2( [in] int index, [in] LCID lcid, [out] BSTR FAR * pbstrHelpString, [out] unsigned long FAR * pdwHelpStringContext, BSTR FAR * pbstrHelpStringDll );

Description

Gets information at the type library level. The caller should free the BSTR parameters.

This function will call _DLLGetDocumentation in the specified DLL to retrieve the desired Help string, if there is a Help string context for this item. If no Help string context exists or an error occurs, then it will defer to the GetDocumentation method and return the associated documentation string.

Parameters

index: Index of the type description whose documentation is to be returned; if index is -1, then the documentation for the library is returned.
lcid: Locale identifier.
pbstrHelpString: Returns a BSTR that contains the name of the specified item. If the caller does not need the item name, then pbstrHelpString can be NULL.
pdwHelpStringContext: Returns the Help localization context. If the caller does not need the Help context, then it can be NULL.
pbstrHelpStringDll: Returns a BSTR that contains the fully qualified name of the file containing the DLL used for Help file. If the caller does not need the file name, then it can be NULL.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
STG_E_INSUFFICIENTMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.
TYPE_E_IOERROR: The function could not write to the file.
TYPE_E_INVDATAREAD: The function could not read from the file.
TYPE_E_UNSUPFORMAT: The type library has an older format.
TYPE_E_INVALIDSTATE: The type library could not be opened.
TYPE_E_ELEMENTNOTFOUND: The element was not found.

ITypeLib2::GetLibStatistics()

NAME

ITypeLib2::GetLibStatistics() - Returns statistics about a type library that are required for efficient sizing of hash tables.

Synopsis

#include <Oaidl.h>

HRESULT GetLibStatistics( unsigned long * pcUniqueNames, unsigned long * pcchUniqueNames );

Parameters

pcUniqueNames: Returns a pointer to a count of unique names. If the caller does not need this information, set to NULL.
pcchUniqueNames: Returns a pointer to a change in the count of unique names.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
E_OUTOFMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.

Examples

ITypeLib2::GetLibStatistics(DWORD *pcUniqueNames, DWORD * pcchUniqueNames)

ITypeLib2::GetAllCustData()

NAME

ITypeLib2::GetAllCustData() - Gets all custom data items for the library.

Synopsis

#include <Oaidl.h>

HRESULT GetAllCustData( CUSTDATA * pCustData );

Description

After the call, the caller needs to release memory used to hold the custom data item by calling ClearCustData().

Parameters

pCustData

Returns a pointer to CUSTDATA (which holds all custom data items).

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
E_OUTOFMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.

18.2.5 ITypeInfo

ITypeInfo::AddressOfMember()

NAME

ITypeInfo::AddressOfMember() - Retrieves the addresses of static functions or variables, such as those defined in a DLL.

Synopsis

#include <Oaidl.h>

HRESULT AddressOfMember( MEMBERID memid, INVOKEKIND invKind, VOID FAR * FAR * ppv );

Description

The addresses are valid until the caller releases its reference to the type description. The invKind parameter can be ignored unless the address of a property function is being requested.

If the type description inherits from another type description, this function is recursive to the base type description, if necessary, to find the item with the requested member ID.

Parameters

memid: Member ID of the static member whose address is to be retrieved. The member ID is defined by the DISPID.
invKind: Specifies whether the member is a property, and if so, what kind.
ppv: On return, points to a pointer to the static member.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
E_OUTOFMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.
TYPE_E_IOERROR: The function could not read from the file.
TYPE_E_WRONGTYPEKIND: Type mismatch.
TYPE_E_INVDATAREAD: The function could not read from the file.
TYPE_E_UNSUPFORMAT: The type library has an older format.
TYPE_E_INVALIDSTATE: The type library could not be opened.
TYPE_E_ELEMENTNOTFOUND: The element was not found.
TYPE_E_DLLFUNCTIONNOTFOUND: The function could not be found in the DLL.
TYPE_E_CANTLOADLIBRARY: The type library or DLL could not be loaded.

ITypeInfo::CreateInstance()

NAME

ITypeInfo::CreateInstance() - Creates a new instance of a type that describes a component object class (coclass).

Synopsis

#include <Oaidl.h>

HRESULT CreateInstance( IUnknown FAR * pUnkOuter, REFIID riid, VOID FAR * FAR * ppvObj );

Description

For types that describe a component object class (coclass), CreateInstance creates a new instance of the class. Normally, CreateInstance calls CoCreateInstance() with the type description's GUID. For an Application object, it first calls GetActiveObject(). If the application is active, GetActiveObject() returns the active object; otherwise, if GetActiveObject() fails, CreateInstance calls CoCreateInstance().

Parameters

pUnkOuter: A pointer to the controlling IUnknown(). If NULL, then a stand-alone instance is created. If valid, then an aggregate object is created.
riid: An ID for the interface that the caller will use to communicate with the resulting object.
ppvObj: On return, points to a pointer to an instance of the created object.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
E_OUTOFMEMORY: Out of memory.
TYPE_E_WRONGTYPEKIND: Type mismatch.
E_INVALIDARG: One or more of the arguments is invalid.
E_NOINTERFACE: COM could not find an implementation of one or more required interfaces.
TYPE_E_UNSUPFORMAT: The type library has an older format.
TYPE_E_INVALIDSTATE: The type library could not be opened.
Other return codes: Additional errors may be returned from GetActiveObject() or CoCreateInstance().

ITypeInfo::GetContainingTypeLib()

NAME

ITypeInfo::GetContainingTypeLib() - Retrieves the containing type library and the index of the type description within that type library.

Synopsis

#include <Oaidl.h>

HRESULT GetContainingTypeLib( ITypeLib FAR * FAR * ppTLib, unsigned int FAR * pIndex );

Parameters

ppTLib: On return, points to the containing type library.
pIndex: On return, points to the index of the type description within the containing type library.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
E_OUTOFMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.
E_NOINTERFACE: COM could not find an implementation of one or more required interfaces.
TYPE_E_IOERROR: The function could not write to the file.
TYPE_E_INVDATAREAD: The function could not read from the file.
TYPE_E_UNSUPFORMAT: The type library has an older format.
TYPE_E_INVALIDSTATE: The type library could not be opened.

ITypeInfo::GetDllEntry()

NAME

ITypeInfo::GetDllEntry() - Retrieves a description or specification of an entry point for a function in a DLL.

Synopsis

#include <Oaidl.h>

HRESULT GetDllEntry( MEMBERID memid, INVOKEKIND invKind, BSTR FAR * pBstrDllName, BSTR FAR * pBstrName, unsigned short FAR * pwOrdinal );

Description

The caller passes in a member ID, which represents the member function whose entry description is desired. If the function has a DLL entry point, the name of the DLL that contains the function, as well as its name or ordinal identifier, are placed in the passed-in pointers allocated by the caller. If there is no DLL entry point for the function, an error is returned.

If the type description inherits from another type description, this function is recursive to the base type description, if necessary, to find the item with the requested member ID.

The caller should use SysFreeString() to free the BSTRs referenced by pBstrName and pBstrDllName.

Parameters

memid: ID of the member function whose DLL entry description is to be returned.
invKind: Specifies the kind of member identified by memid. This is important for properties, because one memid can identify up to three separate functions.
pBstrDllName: If not NULL, the function sets pBstrDllName to a BSTR that contains the name of the DLL.
pBstrName: If not NULL, the function sets lpbstrName to a BSTR that contains the name of the entry point. If the entry point is specified by an ordinal, *lpbstrName is set to NULL.
pwOrdinal: If not NULL, and if the function is defined by an ordinal, then lpwOrdinal is set to point to the ordinal.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
E_OUTOFMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.
E_NOINTERFACE: COM could not find an implementation of one or more required interfaces.
TYPE_E_ELEMENTNOTFOUND: The element was not found.
TYPE_E_IOERROR: The function could not read from the file.
TYPE_E_INVDATAREAD: Invalid data.
TYPE_E_UNSUPFORMAT: The type library has an older format.
TYPE_E_INVALIDSTATE: The type library could not be opened.
TYPE_E_WRONGTYPEKIND: Type mismatch.

ITypeInfo::GetDocumentation()

NAME

ITypeInfo::GetDocumentation() - Retrieves the documentation string, the complete Help file name and path, and the context ID for the Help topic for a specified type description.

Synopsis

#include <Oaidl.h>

HRESULT GetDocumentation( MEMBERID memid, BSTR FAR * pBstrName, BSTR FAR * pBstrDocString, unsigned long FAR * pdwHelpContext, BSTR FAR * pBstrHelpFile );

Description

The function GetDocumentation provides access to the documentation for the member specified by the memid parameter. If the passed-in memid is MEMBERID_NIL, then the documentation for the type description is returned.

If the type description inherits from another type description, this function is recursive to the base type description, if necessary, to find the item with the requested member ID.

The caller should use SysFreeString() to free the BSTRs referenced by pBstrName, pBstrDocString, and pBstrHelpFile.

Parameters

memid: ID of the member whose documentation is to be returned.
pBstrName: Pointer to a BSTR allocated by the callee into which the name of the specified item is placed. If the caller does not need the item name, pBstrName can be NULL.
pBstrDocString: Pointer to a BSTR into which the documentation string for the specified item is placed. If the caller does not need the documentation string, pBstrDocString can be NULL.
pdwHelpContext: Pointer to the Help context associated with the specified item. If the caller does not need the Help context, the pdwHelpContext can be NULL.
pBstrHelpFile: Pointer to a BSTR into which the fully qualified name of the Help file is placed. If the caller does not need the Help file name, pBstrHelpFile can be NULL.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
E_OUTOFMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.
TYPE_E_IOERROR: The function could not read from the file.
TYPE_E_ELEMENTNOTFOUND: The element was not found.
TYPE_E_INVDATAREAD: Invalid data.
TYPE_E_UNSUPFORMAT: The type library has an older format.
TYPE_E_INVALIDSTATE: The type library could not be opened.
TYPE_E_ELEMENTNOTFOUND: The element was not found.

Examples

CHECKRESULT(ptypeinfo->GetDocumentation(idMember, &bstrName, NULL, NULL, 
	NULL));
.
.
.
SysFreeString (bstrName);

ITypeInfo::GetFuncDesc()

NAME

ITypeInfo::GetFuncDesc() - Retrieves the FUNCDESC structure that contains information about a specified function.

Synopsis

#include <Oaidl.h>

HRESULT GetFuncDesc( unsigned int index, FUNCDESC FAR * FAR * ppFuncDesc );

Description

The function GetFuncDesc provides access to a FUNCDESC structure that describes the function with the specified index. The FUNCDESC should be freed with ITypeInfo::ReleaseFuncDesc(). The number of functions in the type is one of the attributes contained in the TYPEATTR structure.

Parameters

index: Index of the function whose description is to be returned. The index should be in the range of 0 to 1 less than the number of functions in this type.
ppFuncDesc: On return, points to a pointer to a FUNCDESC that describes the specified function.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
E_OUTOFMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.
TYPE_E_IOERROR: The function could not read from the file.
TYPE_E_INVDATAREAD: Invalid data.
TYPE_E_UNSUPFORMAT: The type library has an older format.
TYPE_E_INVALIDSTATE: The type library could not be opened.

Examples

CHECKRESULT(ptypeinfo->GetFuncDesc(i, &pfuncdesc));
idMember = pfuncdesc->elemdescFunc.ID;
CHECKRESULT(ptypeinfo->GetDocumentation(idMember, &bstrName, NULL, NULL, NULL));
ptypeinfo->ReleaseFuncDesc(pfuncdesc);

ITypeInfo::GetIDsOfNames()

NAME

ITypeInfo::GetIDsOfNames() - Maps between member names and member IDs, and parameter names and parameter IDs.

Synopsis

#include <Oaidl.h>

HRESULT GetIDsOfNames( OLECHAR FAR * FAR * rgszNames, unsigned int cNames, MEMBERID FAR * pMemId );

Description

The function GetIDsOfNames maps the name of a member (rgszNames[0]) and its parameters (rgszNames[1] ...rgszNames[cNames - 1]) to the ID of the member (rgid[0]), and to the IDs of the specified parameters (rgid[1] ... rgid[cNames - 1]). The IDs of parameters are 0 for the first parameter in the member function's argument list, 1 for the second, and so on.

If the type description inherits from another type description, this function is recursive to the base type description, if necessary, to find the item with the requested member ID.

Parameters

rgszNames: Passed-in pointer to an array of names to be mapped.
cNames: Count of the names to be mapped.
pMemId: Caller-allocated array in which name mappings are placed.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
STG_E_INSUFFICIENTMEMORY: Out of memory.
E_OUTOFMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.
DISP_E_UNKNOWNNAME: One or more of the names could not be found.
DISP_E_UNKNOWNLCID: The locale identifier (LCID) could not be found in the COM DLLs.
TYPE_E_IOERROR: The function could not write to the file.
TYPE_E_INVDATAREAD: The function could not read from the file.
TYPE_E_UNSUPFORMAT: The type library has an older format.
TYPE_E_INVALIDSTATE: The type library could not be opened.
TYPE_E_WRONGTYPEKIND: Type mismatch.

ITypeInfo::GetImplTypeFlags()

NAME

ITypeInfo::GetImplTypeFlags() - Retrieves the IMPLTYPEFLAGS enumeration for one implemented interface or base interface in a type description.

Synopsis

#include <Oaidl.h>

HRESULT GetImplTypeFlags( unsigned int index, int * pImplTypeFlags );

Description

The flags are associated with the act of inheritance, and not with the inherited interface.

Parameters

index: Index of the implemented interface or base interface for which to get the flags.
pImplTypeFlags: On return, pointer to the IMPLTYPEFLAGS enumeration.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
E_OUTOFMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.
TYPE_E_INVDATAREAD: The function could not read from the file.
TYPE_E_UNSUPFORMAT: The type library has an older format.
TYPE_E_INVALIDSTATE: The type library could not be opened.
TYPE_E_WRONGTYPEKIND: Type mismatch.

ITypeInfo::GetMops()

NAME

ITypeInfo::GetMops() - Retrieves marshaling information.

Synopsis

#include <Oaidl.h>

HRESULT GetMops( MEMBERID memid, BSTR FAR * pBstrMops );

Description

If the passed-in member ID is MEMBERID_NIL, the function returns the opcode string for marshaling the fields of the structure described by the type description. Otherwise, it returns the opcode string for marshaling the function specified by the index.

If the type description inherits from another type description, this function recurses on the base type description, if necessary, to find the item with the requested member ID.

Parameters

memid: The member ID that indicates which marshaling information is needed.
pBstrMops: On return, contains a pointer to the opcode string used in marshaling the fields of the structure described by the referenced type description, or returns NULL if there is no information to return.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
E_OUTOFMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.
TYPE_E_IOERROR: The function could not read from the file.
TYPE_E_UNSUPFORMAT: The type library has an older format.
TYPE_E_INVALIDSTATE: The type library could not be opened.
TYPE_E_ELEMENTNOTFOUND: The element was not found.
TYPE_E_WRONGTYPEKIND: Type mismatch.

ITypeInfo::GetNames()

NAME

ITypeInfo::GetNames() - Retrieves the variable with the specified member ID (or the name of the property or method and its parameters) that correspond to the specified function ID.

Synopsis

#include <Oaidl.h>

HRESULT GetNames( MEMBERID memid, BSTR FAR * rgBstrNames, unsigned int cMaxNames, unsigned int FAR * pcNames );

Description

The caller must release the returned BSTR (Basic string) array.

If the member ID identifies a property that is implemented with property functions, the property name is returned.

For property get functions, the names of the function and its parameters are always returned.

For property put and put reference functions, the right side of the assignment is unnamed. If cMaxNames is less than is required to return all of the names of the parameters of a function, then only the names of the first cMaxNames - 1 parameters are returned. The names of the parameters are returned in the array in the same order that they appear elsewhere in the interface (for example, the same order in the parameter array associated with the FUNCDESC enumeration).

If the type description inherits from another type description, this function is recursive to the base type description, if necessary, to find the item with the requested member ID.

Parameters

memid: The ID of the member whose name (or names) is to be returned.
rgBstrNames: Pointer to the caller-allocated array. On return, each of these lpcName elements is filled in to point to a BSTR that contains the name (or names) associated with the member.
cMaxNames: Length of the passed-in rgBstrNames array.
pcNames: On return, points to the number that represents the number of names in rgBstrNames array.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
E_OUTOFMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.
TYPE_E_IOERROR: The function could not read from the file.
TYPE_E_INVDATAREAD: Invalid data.
TYPE_E_UNSUPFORMAT: The type library has an older format.
TYPE_E_INVALIDSTATE: The type library could not be opened.
TYPE_E_WRONGTYPEKIND: Type mismatch.
TYPE_E_ELEMENTNOTFOUND: The element was not found.

ITypeInfo::GetRefTypeInfo()

NAME

ITypeInfo::GetRefTypeInfo() - If a type description references other type descriptions, it retrieves the referenced type descriptions.

Synopsis

#include <Oaidl.h>

HRESULT GetRefTypeInfo( HREFTYPE hRefType, ITypeInfo FAR * FAR * ppTInfo );

Description

On return, the second parameter contains a pointer to a pointer to a type description that is referenced by this type description. A type description must have a reference to each type description that occurs as the type of any of its variables, function parameters, or function return types. For example, if the type of a data member is a record type, the type description for that data member contains the hRefTypeof a referenced type description. To get a pointer to the type description, the reference is passed to GetRefTypeInfo.

Parameters

hRefType: Handle to the referenced type description to be returned.
ppTInfo: Points a pointer to a pointer to the referenced type description.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
E_OUTOFMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.
TYPE_E_IOERROR: The function could not read from the file.
TYPE_E_INVDATAREAD: Invalid data.
TYPE_E_UNSUPFORMAT: The type library has an older format.
TYPE_E_INVALIDSTATE: The type library could not be opened.
TYPE_E_WRONGTYPEKIND: Type mismatch.
TYPE_E_ELEMENTNOTFOUND: The element was not found.
TYPE_E_REGISTRYACCESS: There was an error accessing the system registration database.
TYPE_E_LIBNOTREGISTERED: The type library was not found in the system registration database.

ITypeInfo::GetRefTypeOfImplType()

NAME

ITypeInfo::GetRefTypeOfImplType() - If a type description describes a COM class, it retrieves the type description of the implemented interface types. For an interface, GetRefTypeOfImplType returns the type information for inherited interfaces, if any exist.

Synopsis

#include <Oaidl.h>

HRESULT GetRefTypeOfImplType( unsigned int index, HREFTYPE FAR * pRefType );

Description

If the TKIND_DISPATCH type description is for a dual interface, the TKIND_INTERFACE type description can be obtained by calling GetRefTypeOfImplType with an index of -1, and by passing the returned pRefType handle to GetRefTypeInfo to retrieve the type information.

Parameters

index: Index of the implemented type whose handle is returned. The valid range is 0 to the cImplTypes field in the TYPEATTR structure.
pRefType: On return, points to a handle for the implemented interface (if any). This handle can be passed to ITypeInfo::GetRefTypeInfo() to get the type description.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
TYPE_E_ELEMENTNOTFOUND: Passed index is outside the range 0 to 1 less than the number of function descriptions.
E_INVALIDARG: One or more of the arguments is invalid.
TYPE_E_IOERROR: The function could not read from the file.
TYPE_E_INVDATAREAD: Invalid data.
TYPE_E_UNSUPFORMAT: The type library has an older format.
TYPE_E_INVALIDSTATE: The type library could not be opened.

ITypeInfo::GetTypeAttr()

NAME

ITypeInfo::GetTypeAttr() - Retrieves a TYPEATTR structure that contains the attributes of the type description.

Synopsis

#include <Oaidl.h>

HRESULT GetTypeAttr( TYPEATTR FAR * FAR * ppTypeAttr );

Description

To free the TYPEATTR structure, use ITypeInfo::ReleaseTypeAttr().

Parameters

ppTypeAttr: On return, points to a pointer to a structure that contains the attributes of this type description.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
E_OUTOFMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.
TYPE_E_IOERROR: The function could not write to the file.
TYPE_E_INVDATAREAD: The function could not read from the file.
TYPE_E_UNSUPFORMAT: The type library has an older format.
TYPE_E_INVALIDSTATE: The type library could not be opened.

Examples

CHECKRESULT(ptypeinfoCur->GetTypeAttr(&ptypeattrCur));
.
.
.
ptypeinfoCur->ReleaseTypeAttr(ptypeattrCur);

ITypeInfo::GetTypeComp()

NAME

ITypeInfo::GetTypeComp() - Retrieves the ITypeComp() interface for the type description, which enables a client compiler to bind to the type description's members.

Synopsis

#include <Oaidl.h>

HRESULT GetTypeComp( ITypeComp FAR * FAR * ppTComp );

Description

A client compiler can use the ITypeComp() interface to bind to members of the type.

Parameters

ppTComp: On return, points to a pointer to the ITypeComp() of the containing type library.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
E_OUTOFMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.
TYPE_E_IOERROR: The function could not read from the file.
TYPE_E_INVDATAREAD: Invalid data.
TYPE_E_UNSUPFORMAT: The type library has an older format.
TYPE_E_INVALIDSTATE: The type library could not be opened.
TYPE_E_WRONGTYPEKIND: Type mismatch.

ITypeInfo::GetVarDesc()

NAME

ITypeInfo::GetVarDesc() - Retrieves a VARDESC structure that describes the specified variable.

Synopsis

#include <Oaidl.h>

HRESULT GetVarDesc( unsigned int index, VARDESC FAR * FAR * ppVarDesc );

Description

To free the VARDESC structure, use ReleaseVarDesc.

Parameters

index: Index of the variable whose description is to be returned. The index should be in the range of 0 to 1 less than the number of variables in this type.
ppVarDesc: On return, points to a pointer to a VARDESC that describes the specified variable.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
E_OUTOFMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.
TYPE_E_IOERROR: The function could not read from the file.
TYPE_E_INVDATAREAD: Invalid data.
TYPE_E_UNSUPFORMAT: The type library has an older format.
TYPE_E_INVALIDSTATE: The type library could not be opened.

Examples

CHECKRESULT(ptypeinfo->GetVarDesc(i, &pvardesc));
idMember = pvardesc->memid;
CHECKRESULT(ptypeinfo->GetDocumentation(idMember, &bstrName, NULL, NULL, 
		NULL));
ptypeinfo->ReleaseVarDesc(pvardesc);

ITypeInfo::Invoke()

NAME

ITypeInfo::Invoke() - Invokes a method, or accesses a property of an object, that implements the interface described by the type description.

Synopsis

#include <Oaidl.h>

HRESULT Invoke( VOID FAR * pvInstance, MEMBERID memid, unsigned short wFlags, DISPPARAMS FAR * pDispParams, VARIANT FAR * pVarResult, EXCEPINFO FAR * pExcepInfo, unsigned int FAR * puArgErr );

Description

Use the function ITypeInfo::Invoke() to access a member of an object or invoke a method that implements the interface described by this type description. For objects that support the IDispatch() interface, you can use Invoke to implement IDispatch::Invoke().

ITypeInfo::Invoke() takes a pointer to an instance of the class. Otherwise, its parameters are the same as IDispatch::Invoke, except that ITypeInfo::Invoke() omits the refiid and lcid parameters. When called, ITypeInfo::Invoke() performs the actions described by the IDispatch::Invoke() parameters on the specified instance.

For VTBL interface members, ITypeInfo::Invoke() passes the LCID of the type information into parameters tagged with the lcid attribute, and the returned value into the retval attribute.

If the type description inherits from another type description, this function recurses on the base type description to find the item with the requested member ID.

Parameters

pvInstance: Pointer to an instance of the interface described by this type description.
memid: Identifies the interface member.
wFlags: Flags describing the context of the invoke call, as follows:

1. ITypeInfo::Invoke Invocation Flags

`Value`	`Description`
`DISPATCH_METHOD`	The member is accessed as a method. If there is ambiguity, both this and the `DISPATCH_PROPERTYGET` flag can be set.
`DISPATCH_PROPERTYGET`	The member is retrieved as a property or data member.
`DISPATCH_PROPERTYPUT`	The member is changed as a property or data member.
`DISPATCH_PROPERTYPUTREF`	The member is changed by using a reference assignment, rather than a value assignment. This value is only valid when the property accepts a reference to an object.

pDispParams

Points to a structure that contains an array of arguments, an array of DISPIDs for named arguments, and counts of the number of elements in each array.

pVarResult

Should be NULL if the caller does not expect any result. Otherwise, it should be a pointer to the location at which the result is to be stored. If wFlags specifies DISPATCH_PROPERTYPUT or DISPATCH_PROPERTYPUTREF, pVarResultis ignored.

pExcepInfo

Points to an exception information structure, which is filled in only if DISP_E_EXCEPTION is returned. If pExcepInfois NULL on input, only an HRESULT error will be returned.

puArgErr

If Invoke returns DISP_E_TYPEMISMATCH, puArgErr indicates the index (within rgvarg) of the argument with incorrect type. If more than one argument returns an error, puArgErr indicates only the first argument with an error. Arguments in pDispParams->rgvarg appear in reverse order, so the first argument is the one having the highest index in the array. Cannot be NULL.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
E_INVALIDARG: One or more of the arguments is invalid.
DISP_E_EXCEPTION: The member being invoked has returned an error HRESULT. If the member implements IErrorInfo(), details are available in the error object. Otherwise, the pExcepInfo parameter contains details.
TYPE_E_IOERROR: The function could not read from the file.
TYPE_E_INVDATAREAD: Invalid data.
TYPE_E_UNSUPFORMAT: The type library has an older format.
TYPE_E_REGISTRYACCESS: There was an error accessing the system registration database.
TYPE_E_LIBNOTREGISTERED: The type library was not found in the system registration database.
TYPE_E_INVALIDSTATE: The type library could not be opened.
TYPE_E_WRONGTYPEKIND: Type mismatch.
TYPE_E_ELEMENTNOTFOUND: The element was not found.
TYPE_E_BADMODULEKIND: The module does not support Invoke.
Other return codes: Any of the IDispatch::Invoke() errors may also be returned.

ITypeInfo::ReleaseFuncDesc()

NAME

ITypeInfo::ReleaseFuncDesc() - Releases a FUNCDESC previously returned by GetFuncDesc.

Synopsis

#include <Oaidl.h>

HRESULT ReleaseFuncDesc( FUNCDESC FAR * pFuncDesc );

Description

The function ReleaseFuncDesc releases a FUNCDESC that was returned through ITypeInfo::GetFuncDesc().

Parameters

pFuncDesc: Pointer to the FUNCDESC to be freed.

Examples

ptypeinfoCur->ReleaseFuncDesc(pfuncdesc);

ITypeInfo::ReleaseTypeAttr()

NAME

ITypeInfo::ReleaseTypeAttr() - Releases a TYPEATTR previously returned by GetTypeAttr.

Synopsis

#include <Oaidl.h>

HRESULT ReleaseTypeAttr( TYPEATTR FAR * pTypeAttr );

Description

The function ReleaseTypeAttr releases a TYPEATTR that was returned through ITypeInfo::GetTypeAttr().

Parameters

pTypeAttr: Pointer to the TYPEATTR to be freed.

ITypeInfo::ReleaseVarDesc()

NAME

ITypeInfo::ReleaseVarDesc() - Releases a VARDESC previously returned by GetVarDesc.

Synopsis

#include <Oaidl.h>

HRESULT ReleaseVarDesc( VARDESC FAR * pVarDesc );

Description

ReleaseVarDesc releases a VARDESC that was returned through ITypeInfo::GetVarDesc().

Parameters

pVarDesc: Pointer to the VARDESC to be freed.

Examples

VARDESC		FAR *pVarDesc;
CHECKRESULT(ptypeinfo->GetVarDesc(i, &pvardesc));
idMember = pvardesc->memid;
CHECKRESULT(ptypeinfo->GetDocumentation(idMember, &bstrName, NULL, NULL, 	NULL));
ptypeinfo->ReleaseVarDesc(pvardesc);

18.2.6 ITypeInfo2

An ITypeInfo() can be cast to an ITypeInfo2() instead of using the calls QueryInterface() and Release().

ITypeInfo2::GetTypeKind()

NAME

ITypeInfo2::GetTypeKind() - Returns the TYPEKIND enumeration quickly, without doing any allocations.

Synopsis

#include <Oaidl.h>

HRESULT GetTypeKind( TYPEKIND * pTypeKind );

Parameters

pTypeKind: Reference to a TYPEKIND enumeration.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
E_OUTOFMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.

Examples

HRESULT ITypeInfo2::GetTypeKind(TYPEKIND * ptypekind)

ITypeInfo2::GetTypeFlags()

NAME

ITypeInfo2::GetTypeFlags() - Returns the type flags without any allocations. This returns a DWORD type flag, which expands the type flags without enlarging the TYPEATTR (type attribute).

Synopsis

#include <Oaidl.h>

HRESULT GetTypeFlags( unsigned long * pTypeFlags );

Parameters

pTypeFlags: The DWORD reference to a TYPEFLAG.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
E_OUTOFMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.

Examples

HRESULT ITypeInfo2::GetTypeFlags(DWORD * pTypeFlags)

ITypeInfo2::GetFuncIndexOfMemId()

NAME

ITypeInfo2::GetFuncIndexOfMemId() - Binds to a specific member based on a known DISPID, where the member name is not known (for example, when binding to a default member).

Synopsis

#include <Oaidl.h>

HRESULT GetFuncIndexOfMemId( MEMBERID memid, INVOKEKIND invKind, unsigned int * pFuncIndex );

Parameters

memid: Member identifier.
invKind: Invoke kind.
pFuncIndex: Returns an index into the function.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
E_OUTOFMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.

Examples

ITypeInfo2::GetFuncIndexOfMemId(
MEMID memid, 
INVOKEKIND invKind, 
UINT * pfuncIndex)

ITypeInfo2::GetVarIndexOfMemId()

NAME

ITypeInfo2::GetVarIndexOfMemId() - Binds to a specific member based on a known DISPID, where the member name is not known (for example, when binding to a default member).

Synopsis

#include <Oaidl.h>

HRESULT GetVarIndexOfMemId( MEMBERID memid, unsigned int * pVarIndex );

Parameters

memid: Member identifier.
pVarIndex: Returns the index.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
E_OUTOFMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.

Examples

ITypeInfo2::GetVarIndexOfMemId(MEMID memid, UINT * pvarIndex)

ITypeInfo2::GetCustData()

NAME

ITypeInfo2::GetCustData() - Gets the custom data.

Synopsis

#include <Oaidl.h>

HRESULT GetCustData( REFGUID guid, VARIANT * pVarVal );

Parameters

guid: GUID used to identify the data.
pVarVal: Where to put the retrieved data.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
E_OUTOFMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.

ITypeInfo2::GetAllCustData()

NAME

ITypeInfo2::GetAllCustData() - Gets all custom data items for the library.

Synopsis

#include <Oaidl.h>

HRESULT GetAllCustData( CUSTDATA * pCustData );

Description

After the call, the caller needs to release memory used to hold the custom data item by calling ClearCustData().

Parameters

pCustData: Returns a pointer to CUSTDATA (which holds all custom data items).

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
E_OUTOFMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.

ITypeInfo2::GetAllFuncCustData()

NAME

ITypeInfo2::GetAllFuncCustData() - Gets all custom data from the specified function.

Synopsis

#include <Oaidl.h>

HRESULT GetAllFuncCustData( unsigned int index, CUSTDATA * pCustData );

Description

After the call, the caller needs to release memory used to hold the custom data item by calling ClearCustData().

Parameters

index: The index of the function for which to get the custom data.
pCustData: Returns a pointer to CUSTDATA (which holds all custom data items).

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
E_OUTOFMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.

ITypeInfo2::GetAllImplTypeCustData()

NAME

ITypeInfo2::GetAllImplTypeCustData() - Gets all custom data for the specified implementation type.

Synopsis

#include <Oaidl.h>

HRESULT GetAllImplTypeCustData( unsigned int index, CUSTDATA * pCustData );

Parameters

index: Index of the implementation type for the custom data.
pCustData: Returns a pointer to CUSTDATA (which holds all custom data items).

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
E_OUTOFMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.

ITypeInfo2::GetAllParamCustData()

NAME

ITypeInfo2::GetAllParamCustData() - Gets all of the custom data for the specified function parameter.

Synopsis

#include <Oaidl.h>

HRESULT GetAllParamCustData( unsigned int indexFunc, unsigned int indexParam, CUSTDATA * pCustData );

Parameters

indexFunc: Index of the function for which to get the custom data.
IndexParam: Index of the parameter of this function for which to get the custom data.
pCustData: Returns a pointer to CUSTDATA (which holds all custom data items).

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
E_OUTOFMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.

ITypeInfo2::GetAllVarCustData()

NAME

ITypeInfo2::GetAllVarCustData() - Gets the variable for the custom data.

Synopsis

#include <Oaidl.h>

HRESULT GetAllVarCustData( unsigned int index, CUSTDATA * pCustData );

Parameters

index: Index of the variable for which to get the custom data.
pCustData: Returns a pointer to CUSTDATA (which holds all custom data items).

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
E_OUTOFMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.

ITypeInfo2::GetFuncCustData()

NAME

ITypeInfo2::GetFuncCustData() - Gets the custom data from the specified function.

Synopsis

#include <Oaidl.h>

HRESULT GetFuncCustData( unsigned int index, REFGUID guid, VARIANT * pVarVal );

Parameters

index: The index of the function for which to get the custom data.
guid: The GUID used to identify the data.
pVarVal: Where to put the data.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
E_OUTOFMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.

ITypeInfo2::GetParamCustData()

NAME

ITypeInfo2::GetParamCustData() - Gets the specified custom data parameter.

Synopsis

#include <Oaidl.h>

HRESULT GetParamCustData( unsigned int indexFunc, unsigned int indexParam, REFGUID guid, VARIANT * pVarVal );

Parameters

indexFunc: Index of the function for which to get the custom data.
IndexParam: Index of the parameter of this function for which to get the custom data.
guid: GUID used to identify the data.
pVarVal: Where to put the retrieved data.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
E_OUTOFMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.

ITypeInfo2::GetVarCustData()

NAME

ITypeInfo2::GetVarCustData() - Gets the variable for the custom data.

Synopsis

#include <Oaidl.h>

HRESULT GetVarCustData( unsigned int index, REFGUID guid, VARIANT * pVarVal );

Parameters

index: Index of the variable for which to get the custom data.
guid: GUID used to identify the data.
PVarVal: Where to put the retrieved data.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
E_OUTOFMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.

ITypeInfo2::GetImplTypeCustData()

NAME

ITypeInfo2::GetImplTypeCustData() - Gets the implementation type of the custom data.

Synopsis

#include <Oaidl.h>

HRESULT GetImplTypeCustData( unsigned int index, REFGUID guid, VARIANT * pVarVal );

Parameters

index: Index of the implementation type for the custom data.
guid: GUID used to identify the data.
pVarVal: Where to put the retrieved data.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
E_OUTOFMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.

ITypeInfo2::GetDocumentation2()

NAME

ITypeInfo2::GetDocumentation2() - Retrieves the documentation string, the complete Help file name and path, the localization context to use, and the context ID for the library Help topic in the Help file.

Synopsis

#include <Oaidl.h>

HRESULT GetDocumentation2( [in] MEMID memid, [in] LCID lcid, [out] BSTR FAR * pbstrHelpString, [out] unsigned long FAR * pdwHelpStringContext, BSTR FAR * pbstrHelpStringDll );

Description

Gets information at the type information level (about the type information and its members). The caller should free the BSTR parameters.

Parameters

memid: Member identifier for the type description.
lcid: Locale identifier (LCID).
pbstrHelpString: Returns a BSTR that contains the name of the specified item. If the caller does not need the item name, then pbstrHelpString can be NULL.
pdwHelpStringContext: Returns the Help localization context. If the caller does not need the Help context, it can be NULL.
pbstrHelpStringDll: Returns a BSTR that contains the fully qualified name of the file containing the DLL used for Help file. If the caller does not need the file name, it can be NULL.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
STG_E_INSUFFICIENTMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.
TYPE_E_IOERROR: The function could not write to the file.
TYPE_E_INVDATAREAD: The function could not read from the file.
TYPE_E_UNSUPFORMAT: The type library has an older format.
TYPE_E_INVALIDSTATE: The type library could not be opened.
TYPE_E_ELEMENTNOTFOUND: The element was not found.

18.2.7 ITypeComp

The ITypeComp() interface provides a fast way to access information that compilers need when binding to and instantiating structures and interfaces. Binding is the process of mapping names to types and type members.

Description

Table 18-4: ITypeComp Elements

`Implemented by`	`Used by`	`Header file name`
`Oleaut32.dll` (32-bit systems) `Typelib.dll` (16-bit systems)	Tools that need to access the descriptions of objects contained in type libraries.	`Oleauto.h Dispatch.h`

ITypeComp::Bind()

NAME

ITypeComp::Bind() - Maps a name to a member of a type, or binds global variables and functions contained in a type library.

Synopsis

#include <Oaidl.h>

HRESULT Bind( OLECHAR FAR * szName, unsigned long lHashVal, unsigned short wFlags, ITypeInfo FAR * FAR * ppTInfo, DESCKIND FAR * pDescKind, BINDPTR FAR * pBindPtr );

Description

Use Bind for binding to the variables and methods of a type, or for binding to the global variables and methods in a type library. The returned DESCKIND pointer pDescKind indicates whether the name was bound to a VARDESC, a FUNCDESC, or to an ITypeComp() instance. The returned pBindPtr points to the VARDESC, FUNCDESC, or ITypeComp().

If a data member or method is bound to, then ppTInfo points to the type description that contains the method or data member.

If Bind binds the name to a nested binding context, it returns a pointer to an ITypeComp() instance in pBindPtr and a NULL type description pointer in ppTInfo. For example, if the name of a type description is passed for a module (TKIND_MODULE), enumeration (TKIND_ENUM), or coclass (TKIND_COCLASS), Bind returns the ITypeComp() instance of the type description for the module, enumeration, or coclass. This feature supports languages such as Visual Basic that allow references to members of a type description to be qualified by the name of the type description. For example, a function in a module can be referenced by modulename.functionname.

The members of TKIND_ENUM, TKIND_MODULE, and TKIND_COCLASS types marked as Application objects can be bound to directly from ITypeComp, without specifying the name of the module. The ITypeComp() of a coclass defers to the ITypeComp() of its default interface.

As with other methods of ITypeComp(), ITypeInfo(), and ITypeLib(), the calling code is responsible for releasing the returned object instances or structures. If a VARDESC or FUNCDESC is returned, the caller is responsible for deleting it with the returned type description and releasing the type description instance itself. Otherwise, if an ITypeComp() instance is returned, the caller must release it.

Special rules apply if you call a type library's Bind method, passing it the name of a member of an Application object class (a class that has the TYPEFLAG_FAPPOBJECT flag set). In this case, Bind returns DESCKIND_IMPLICITAPPOBJ in pDescKind, a VARDESC that describes the Application object in pBindPtr, and the ITypeInfo() of the Application object class in ppTInfo. To bind to the object, ITypeInfo::GetTypeComp() must make a call to get the ITypeComp() of the Application object class, and then reinvoke its Bind method with the name initially passed to the type library's ITypeComp().

The caller should use the returned ITypeInfo() pointer (ppTInfo) to get the address of the member.

The wflags parameter is the same as the wflags parameter in IDispatch::Invoke().

Parameters

szName: Name to be bound.
lHashVal: Hash value for the name computed by LHashValOfNameSys.
wFlags: Flags word containing one or more of the Invoke flags defined in the INVOKEKIND enumeration. Specifies whether the name was referenced as a method or a property. When binding to a variable, specify the flag INVOKE_PROPERTYGET. Specify zero to bind to any type of member.
ppTInfo: If a FUNCDESC or VARDESC was returned, then ppTInfo points to a pointer to the type description that contains the item to which it is bound.
pDescKind: Pointer to a DESCKIND enumerator that indicates whether the name bound to is a VARDESC, FUNCDESC, or TYPECOMP. If there was no match, points to DESCKIND_NONE.
pBindPtr: On return, contains a pointer to the bound-to VARDESC, FUNCDESC, or ITypeComp() interface.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
E_OUTOFMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.
TYPE_E_IOERROR: The function could not read from the file.
TYPE_E_INVDATAREAD: Invalid data.
TYPE_E_UNSUPFORMAT: The type library has an older format.
TYPE_E_INVALIDSTATE: The type library could not be opened.
TYPE_E_AMBIGUOUSNAME: More than one instance of this name occurs in the type library.

ITypeComp::BindType()

NAME

ITypeComp::BindType() - Binds to the type descriptions contained within a type library.

Synopsis

#include <Oaidl.h>

HRESULT BindType( OLECHAR FAR * szName, unsigned long lHashVal, ITypeInfo FAR * FAR * ppTInfo, ITypeComp FAR * FAR * ppTComp );

Description

Use the function BindType for binding a type name to the ITypeInfo() that describes the type. This function is invoked on the ITypeComp() that is returned by ITypeLib::GetTypeComp() to bind to types defined within that library. It can also be used in the future for binding to nested types.

Parameters

szName: Name to be bound.
lHashVal: Hash value for the name computed by LHashValOfName().
ppTInfo: On return, contains a pointer to a pointer to an ITypeInfo() of the type to which the name was bound.
ppTComp: Passes a valid pointer, such as the address of an ITypeComp* variable.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
E_OUTOFMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.
TYPE_E_IOERROR: The function could not read from the file.
TYPE_E_INVDATAREAD: Invalid data.
TYPE_E_UNSUPFORMAT: The type library has an older format.
TYPE_E_INVALIDSTATE: The type library could not be opened.
TYPE_E_AMBIGUOUSNAME: More than one instance of this name occurs in the type library.

Examples

TypeComp * ptcomp;
	ptemp -> BindType(szName, lhashval, &ptinfo, &ptemp)

18.3 Type Library API Descriptions

CreateTypeLib()

NAME

CreateTypeLib() - Provides access to a new object instance that supports the ICreateTypeLib interface.

Synopsis

#include <oleauto.h>

HRESULT CreateTypeLib(( SYSKIND syskind, OLECHAR FAR* szFile, ICreateTypeLib FAR* FAR* lplpctlib );

Description

CreateTypeLib() sets its output parameter (lplpctlib) to point to a newly created object that supports the ICreateTypeLib interface.

Parameters

syskind: The target operating system for which to create a type library.
szFile: The name of the file to create.
lplpctlib: Pointer to an instance supporting the ICreateTypeLib interface.

Return Values

The return value of the returned HRESULT is one of the following:

S_OK: Success.
E_OUTOFMEMORY: Out of memory.
STG_E_INSUFFICIENTMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.
TYPE_E_IOERROR: The efunction could not create the file.
Other return codes: All FACILITY_STORAGE errors.

LHashValOfName()

NAME

LHashValOfName() - Computes a hash value for a name that can then be passed to ITypeComp::Bind(), ITypeComp::BindType(), ITypeLib::FindName(), or ITypeLib::IsName().

Synopsis

HRESULT LHashValOfName(( LCID lcid, OLECHAR FAR * szName );

Description

This function is equivalent to LHashValOfNameSys. The header file Oleauto.h contains macros that define LHashValOfName() as LHashValOfNameSys, with the target operating system (syskind) based on the build preprocessor flags.

LHashValOfName() computes a 32-bit hash value for a name that can be passed to ITypeComp::Bind, ITypeComp::BindType, ITypeLib::FindName, or ITypeLib::IsName(). The returned hash value is independent of the case of the characters in szName, as long as the language of the name is one of the languages supported by the COM National Language Specification API. Any two strings that match when a case-insensitive comparison is done using any language produce the same hash value.

Parameters

lcid: The LCID for the string.
szName: String whose hash value is to be computed.

Return Values

A 32-bit hash value that represents the passed-in name.

LHashValOfNameSys()

NAME

LHashValOfNameSys() - Computes a hash value for a name that can then be passed to ITypeComp::Bind(), ITypeComp::BindType(), ITypeLib::FindName(), or ITypeLib::IsName().

Synopsis

#include <oleauto.h>

HRESULT LHashValOfNameSys( SYSKIND syskind, LCID lcid, OLECHAR FAR * szName );

Description

Computes a hash value for a name that can then be passed to ITypeComp::Bind(),ITypeComp::BindType,ITypeLib::FindName, orITypeLib::IsName.

Parameters

syskind: The SYSKIND of the target operating system.
lcid: The LCID for the string.
szName: String whose hash value is to be computed.

Return Values

A 32-bit hash value that represents the passed-in name.

LoadTypeLibEx()

NAME

LoadTypeLibEx() - Loads and optionally registers a type library.

Synopsis

HRESULT LoadTypeLibEx(( OLECHAR FAR * szFile, REGKIND regkind, ITypeLib FAR * FAR * pptlib );

Description

The function LoadTypeLibEx() loads a type library (usually created with MIDL) that is stored in the specified file. If szFile specifies only a file name without any path, LoadTypeLibEx() searches for the file and proceeds as follows:

If the file is a stand-alone type library (usually with a .TLB extension), the type library is loaded directly.

If the file is a DLL or an executable file, it is loaded. By default, the type library is extracted from the first resource of type ITypeLib(). To load a different type of library resource, append an integer index to szFile. For example:
```
LoadTypeLib(<``><''>C:\MONTANA\EXE\MFA.EXE\3<``><''>,
pptlib)
```
This statement loads the type library resource 3 from the file Mfa.exe file.

If the file is none of the above, the file name is parsed into a moniker (an object that represents a file-based link source) using MkParseDisplayName(), and then the moniker is bound to IID_ITypeLib. This approach allows LoadTypeLibEx() to be used on foreign type libraries, including in-memory type libraries. Foreign type libraries cannot reside in a DLL or an executable file.

If the type library is already loaded, LoadTypeLibEx() increments the type library's reference count and returns a pointer to the type library.

The regKind parameter enables programmers to specify whether or not the type library should be registered in the system registry (for future loading via LoadRegTypeLib()). When REGKIND_NONE is specified, the library is not registered in the system registry. When REGKIND_DEFAULT is specified, LoadTypeLibEx() will register the type library if the path is not specified in the szFile parameter, otherwise LoadTypeLibEx() will not register the type library. When REGKIND_REGISTER is specified, LoadTypeLibEx() will always register the type library in the system registry.

It is recommended that RegisterTypeLib() be used to register a type library.

Parameters

szFile: Contains the name of the file from whichLoadTypeLib should attempt to load a type library.
regkind: Identifies the kind of registration to perform for the type library (REGKIND_DEFAULT, REGKIND_REGISTER, or REGKIND_NONE).
pptlib: On return, contains a pointer to a pointer to the loaded type library.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
E_OUTOFMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.
TYPE_E_IOERROR: The function could not write to the file.
TYPE_E_INVALIDSTATE: The type library could not be opened.
TYPE_E_INVDATAREAD: The function could not read from the file.
TYPE_E_UNSUPFORMAT: The type library has an older format.
TYPE_E_UNKNOWNLCID: The LCID could not be found in the COM-supported DLLs.
TYPE_E_CANTLOADLIBRARY: The type library or DLL could not be loaded.
TYPE_E_REGISTRYACCESS: The system registration database could not be opened.
Other return codes: All FACILITY_STORAGE errors can be returned.

LoadRegTypeLib()

NAME

LoadRegTypeLib() - Uses registry information to load a type library.

Synopsis

#include <oleauto.h>

HRESULT LoadRegTypeLib(( REFGUID rguid, Unsigned short wVerMajor, Unsigned short wVerMinor, LCID lcid, ITypeLib FAR * FAR * pptlib );

Description

The function LoadRegTypeLib() defers to LoadTypeLibEx() to load the file.

LoadRegTypeLib() compares the requested version numbers against those found in the system registry, and takes one of the following actions:

If one of the registered libraries exactly matches both the requested major and minor version numbers, then that type library is loaded.

If one or more registered type libraries exactly match the requested major version number, and has a greater minor version number than that requested, the one with the greatest minor version number is loaded.

If none of the registered type libraries exactly match the requested major version number (or if none of those that do exactly match the major version number also have a minor version number greater than or equal to the requested minor version number), then LoadRegTypeLib() returns an error.

Parameters

rguid: The GUID of the library being loaded.
wVerMajor: Major version number of the library being loaded.
wVerMinor: Minor version number of the library being loaded.
lcid: National language code of the library being loaded.
pptlib: On return, points to a pointer to the loaded type library.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
E_OUTOFMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.
TYPE_E_IOERROR: The function could not read from the file.
TYPE_E_INVALIDSTATE: The type library could not be opened.
TYPE_E_INVDATAREAD: The function could not read from the file.
TYPE_E_UNSUPFORMAT: The type library has an older format.
TYPE_E_UNKNOWNLCID: The passed in LCID could not be found in the COM-supported DLLs.
TYPE_E_CANTLOADLIBRARY: The type library or DLL could not be loaded.
Other return codes: All FACILITY_STORAGE and system registry errors can also be returned.

RegisterTypeLib()

NAME

RegisterTypeLib() - Adds information about a type library to the system registry.

Synopsis

#include <oleauto.h>

HRESULT RegisterTypeLib(( ITypeLib FAR * ptlib, OLECHAR FAR * szFullPath, OLECHAR FAR * szHelpDir );

Description

The function RegisterTypeLib() can be used during application initialization to register the application's type library correctly.

In addition to filling in a complete registry entry under the type library key, RegisterTypeLib() adds entries for each of the dispinterfaces and Automation-compatible interfaces, including dual interfaces. This information is required to create instances of these interfaces. Coclasses are not registered (that is, RegisterTypeLib() does not write any values to the CLSID key of the coclass).

Parameters

ptlib: Pointer to the type library being registered.
szFullPath: Fully qualified path specification for the type library being registered.
szHelpDir: Directory in which the Help file for the library being registered can be found. Can be NULL.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
E_OUTOFMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.
TYPE_E_IOERROR: The function could not write to the file.
TYPE_E_REGISTRYACCESS: The system registration database could not be opened.
TYPE_E_INVALIDSTATE: The type library could not be opened.

UnRegisterTypeLib()

NAME

UnRegisterTypeLib() - Removes type library information from the system registry. Use this API to allow applications to properly uninstall themselves. In-process objects typically call this API from DllUnregisterServer().

Synopsis

HRESULT UnRegisterTypeLib(( REFGUID libID, unsigned short wVerMajor, unsigned short wVerMinor, LCID lcid, SYSKIND syskind );

Description

In-process objects typically call this API from DllUnregisterServer().

Parameters

libID: Globally unique identifier.
wVerMajor: Major version number of the type library being removed.
wVerMinor: Minor version number of the type library being removed.
lcid: Locale identifier.
syskind: The target operating system (SYSKIND).

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.
E_OUTOFMEMORY: Out of memory.
E_INVALIDARG: One or more of the arguments is invalid.
TYPE_E_IOERROR: The function could not write to the file.
TYPE_E_REGISTRYACCESS: The system registration database could not be opened.
TYPE_E_INVALIDSTATE: The type library could not be opened.

QueryPathOfRegTypeLib()

NAME

QueryPathOfRegTypeLib() - Retrieves the path of a registered type library.

Synopsis

#include <oleauto.h>

HRESULT QueryPathOfRegTypeLib(( REFGUID guid, unsigned short wVerMajor, unsigned short wVerMinor, LCID lcid, LPBSTR lpbstrPathName );

Description

Returns the fully qualified file name that is specified for the type library in the registry. The caller allocates the BSTR that is passed in, and must free it after use.

Parameters

guid: GUID of the library whose path is to be queried.
wVerMajor: Major version number of the library whose path is to be queried.
wVerMinor: Minor version number of the library whose path is to be queried.
lcid: National language code for the library whose path is to be queried.
lpbstrPathName: Caller-allocated BSTR in which the type library name is returned.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK: Success.