Type Information 主講人：虞台文

Content Overview The Type Library Building Type Library Type Library Deployment Loading and Using a Type Library Objects with Type Information  IProvideClassInfo

Type Information Overview

What is type information? It can be considered an owner's manual for an object, e.g., – what interfaces exist on what objects (given the CLSID)? – what member functions exist in those interfaces? and – what arguments those functions require? It can also describe custom types such as C-style data structures, unions, and enumerations, as well as noninterface functions that are exported from a DLL module. – In fact, whatever you can store in header files (H), import libraries (LIB files for linking to DLL exported functions), and indexes to help files (HLP), you can store and retrieve through type information.

Why type information? Artificial intelligence – to figure out how to get a computer to do the something as human Creating program developing tools

Example: Web Brower

Exercises 1. Design an almost-completed web browser using the ActiveX Control of Microsoft Web Browser. 2. Understanding what it is IDispatch. 3. Understanding string data type BSTR. 4. Understanding VARIANT data structure and its usages.

Type Information The Type Library

A type library is nothing more than a collection of static data structures for each element within it, and those structures contain additional nested structures to describe their contents.

OLE's Type Information Service A service for creating and manipulating information that is contained in a type library. So for the most part, the type library acts as a librarian, meaning that you, like a client or user of any library, can ask it to locate the type information for some element of interest.

Type Library Elements coclass – Describes the interfaces and dispinterfaces implemented on a particular object (identified by a CLSID). interface – Describes a vtable interface (identified by an IID): specifically, the names of member functions, the return types of those functions, and the names and types of the arguments to those functions. dispinterface – Describes a dispatch interface (identified by an IID) used by OLE Automation: specifically, the names, dispIDs, and types of the methods and properties (including return types and argument names and types for methods in the interface). module – Describes a DLL module (identified by a DLL filename), including names and ordinals for exported functions and global variables. typedef – Describes a user-defined data structure, enumeration, or union (identified by a name or an optional GUID).

Type Library and Element Attributes Name Guid (or Uuid) Version DocString HelpFileName HelpContext Lcid Flags

Object Description Language (ODL)

COM Connection Points Building Type Library

Two Ways to Build Type Library The Easy Way – Object Description Language (ODL) – MIDL(MKTYPLIB) The Hard Way – CreateTypeLib

Hello.odl // Hello.odl [ uuid(2F6CA420-C A-B826-00DD01103DE1), // LIBID_Hello helpstring("Hello 1.0 Type Library"), lcid(0x0409), version(1.0) ] library Hello { #ifdef WIN32 importlib("stdole32.tlb"); #else importlib("stdole.tlb"); #endif [ uuid(2F6CA422-C A-B826-00DD01103DE1), // IID_IHello helpstring("Hello Interface") ] interface IHello : IUnknown { [propput] void HelloMessage([in] BSTR Message); [propget] BSTR HelloMessage(void); void SayHello(void); } [ uuid(2F6CA423-C A-B826-00DD01103DE1), // IID_DHello helpstring("Hello Dispinterface") ] dispinterface DHello { interface IHello; } [ uuid(2F6CA421-C A-B826-00DD01103DE1), // CLSID_Hello helpstring("Hello Class") ] coclass Hello { dispinterface DHello; interface IHello; } // Hello.odl [ uuid(2F6CA420-C A-B826-00DD01103DE1), // LIBID_Hello helpstring("Hello 1.0 Type Library"), lcid(0x0409), version(1.0) ] library Hello { #ifdef WIN32 importlib("stdole32.tlb"); #else importlib("stdole.tlb"); #endif [ uuid(2F6CA422-C A-B826-00DD01103DE1), // IID_IHello helpstring("Hello Interface") ] interface IHello : IUnknown { [propput] void HelloMessage([in] BSTR Message); [propget] BSTR HelloMessage(void); void SayHello(void); } [ uuid(2F6CA423-C A-B826-00DD01103DE1), // IID_DHello helpstring("Hello Dispinterface") ] dispinterface DHello { interface IHello; } [ uuid(2F6CA421-C A-B826-00DD01103DE1), // CLSID_Hello helpstring("Hello Class") ] coclass Hello { dispinterface DHello; interface IHello; } }

Hello.odl // Hello.odl [ uuid(2F6CA420-C A-B826-00DD01103DE1), // LIBID_Hello helpstring("Hello 1.0 Type Library"), lcid(0x0409), version(1.0) ] library Hello { #ifdef WIN32 importlib("stdole32.tlb"); #else importlib("stdole.tlb"); #endif [ uuid(2F6CA422-C A-B826-00DD01103DE1), // IID_IHello helpstring("Hello Interface") ] interface IHello : IUnknown { [propput] void HelloMessage([in] BSTR Message); [propget] BSTR HelloMessage(void); void SayHello(void); } [ uuid(2F6CA423-C A-B826-00DD01103DE1), // IID_DHello helpstring("Hello Dispinterface") ] dispinterface DHello { interface IHello; } [ uuid(2F6CA421-C A-B826-00DD01103DE1), // CLSID_Hello helpstring("Hello Class") ] coclass Hello { dispinterface DHello; interface IHello; } // Hello.odl [ uuid(2F6CA420-C A-B826-00DD01103DE1), // LIBID_Hello helpstring("Hello 1.0 Type Library"), lcid(0x0409), version(1.0) ] library Hello { #ifdef WIN32 importlib("stdole32.tlb"); #else importlib("stdole.tlb"); #endif [ uuid(2F6CA422-C A-B826-00DD01103DE1), // IID_IHello helpstring("Hello Interface") ] interface IHello : IUnknown { [propput] void HelloMessage([in] BSTR Message); [propget] BSTR HelloMessage(void); void SayHello(void); } [ uuid(2F6CA423-C A-B826-00DD01103DE1), // IID_DHello helpstring("Hello Dispinterface") ] dispinterface DHello { interface IHello; } [ uuid(2F6CA421-C A-B826-00DD01103DE1), // CLSID_Hello helpstring("Hello Class") ] coclass Hello { dispinterface DHello; interface IHello; }

MIDL // Hello.odl [ uuid(2F6CA420-C A-B826-00DD01103DE1), // LIBID_Hello helpstring("Hello 1.0 Type Library"), lcid(0x0409), version(1.0) ] library Hello { #ifdef WIN32 importlib("stdole32.tlb"); #else importlib("stdole.tlb"); #endif [ uuid(2F6CA422-C A-B826-00DD01103DE1), // IID_IHello helpstring("Hello Interface") ] interface IHello : IUnknown { [propput] void HelloMessage([in] BSTR Message); [propget] BSTR HelloMessage(void); void SayHello(void); } [ uuid(2F6CA423-C A-B826-00DD01103DE1), // IID_DHello helpstring("Hello Dispinterface") ] dispinterface DHello { interface IHello; } [ uuid(2F6CA421-C A-B826-00DD01103DE1), // CLSID_Hello helpstring("Hello Class") ] coclass Hello { dispinterface DHello; interface IHello; } // Hello.odl [ uuid(2F6CA420-C A-B826-00DD01103DE1), // LIBID_Hello helpstring("Hello 1.0 Type Library"), lcid(0x0409), version(1.0) ] library Hello { #ifdef WIN32 importlib("stdole32.tlb"); #else importlib("stdole.tlb"); #endif [ uuid(2F6CA422-C A-B826-00DD01103DE1), // IID_IHello helpstring("Hello Interface") ] interface IHello : IUnknown { [propput] void HelloMessage([in] BSTR Message); [propget] BSTR HelloMessage(void); void SayHello(void); } [ uuid(2F6CA423-C A-B826-00DD01103DE1), // IID_DHello helpstring("Hello Dispinterface") ] dispinterface DHello { interface IHello; } [ uuid(2F6CA421-C A-B826-00DD01103DE1), // CLSID_Hello helpstring("Hello Class") ] coclass Hello { dispinterface DHello; interface IHello; }

OLE/COM Object Viewer  OLEVIEW.EXE

Code Generation

Hello.h // Machine generated IDispatch wrapper class(es) created with ClassWizard ///////////////////////////////////////////////////////////////////////////// // DHello wrapper class class DHello : public COleDispatchDriver { public: DHello() {}// Calls COleDispatchDriver default constructor DHello(LPDISPATCH pDispatch) : COleDispatchDriver(pDispatch) {} DHello(const DHello& dispatchSrc) : COleDispatchDriver(dispatchSrc) {} // Attributes public: // Operations public: CString GetHelloMessage(); void SetHelloMessage(LPCTSTR lpszNewValue); void SayHello(); }; // Machine generated IDispatch wrapper class(es) created with ClassWizard ///////////////////////////////////////////////////////////////////////////// // DHello wrapper class class DHello : public COleDispatchDriver { public: DHello() {}// Calls COleDispatchDriver default constructor DHello(LPDISPATCH pDispatch) : COleDispatchDriver(pDispatch) {} DHello(const DHello& dispatchSrc) : COleDispatchDriver(dispatchSrc) {} // Attributes public: // Operations public: CString GetHelloMessage(); void SetHelloMessage(LPCTSTR lpszNewValue); void SayHello(); };

Hello.cpp CString DHello::GetHelloMessage() { CString result; InvokeHelper(0x0, DISPATCH_PROPERTYGET, VT_BSTR, (void*)&result, NULL); return result; } void DHello::SetHelloMessage(LPCTSTR lpszNewValue) { static BYTE parms[] = VTS_BSTR; InvokeHelper(0x0, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms, lpszNewValue); } void DHello::SayHello() { InvokeHelper(0x1, DISPATCH_METHOD, VT_EMPTY, NULL, NULL); } CString DHello::GetHelloMessage() { CString result; InvokeHelper(0x0, DISPATCH_PROPERTYGET, VT_BSTR, (void*)&result, NULL); return result; } void DHello::SetHelloMessage(LPCTSTR lpszNewValue) { static BYTE parms[] = VTS_BSTR; InvokeHelper(0x0, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms, lpszNewValue); } void DHello::SayHello() { InvokeHelper(0x1, DISPATCH_METHOD, VT_EMPTY, NULL, NULL); }

Exercises 5. Define a type library using object description language (odl) for rectangle and line objects. Each coclass must include a dispinterface to handle its properties and functions. 6. Create type library by Compiling the odl you defined using MIDL. 7. Understand what extra files can be generated by MIDL. 8. Generate C++ Classes to handle coclass es for rectangle and line.

The Type Library That Jack Built This is Jack. This is the house that Jack built. This is the kitchen in the house that Jack built. This is the wall in the kitchen in the house that Jack built. This is the hole in the wall in the kitchen in the house that Jack built. This is the mouse that made the hole in the wall in the kitchen in the house that Jack built. This is Jack. This is the house that Jack built. This is the kitchen in the house that Jack built. This is the wall in the kitchen in the house that Jack built. This is the hole in the wall in the kitchen in the house that Jack built. This is the mouse that made the hole in the wall in the kitchen in the house that Jack built.

CreateTypeLib WINOLEAUTAPI CreateTypeLib( SYSKIND syskind, const OLECHAR *szFile, ICreateTypeLib **ppctlib ); WINOLEAUTAPI CreateTypeLib( SYSKIND syskind, const OLECHAR *szFile, ICreateTypeLib **ppctlib );

ICreateTypeLib Methods in VTable order IUnknown MethodsDescription QueryInterface Returns pointers to supported interfaces. AddRef Increments reference count. Release Decrements reference count. ICreateTypeLib MethodsDescription CreateTypeInfo Creates a new type description instance within the type library. SetName Sets the name of the type library. SetVersion Sets major and minor version numbers for the type library. SetGuid Sets the GUID for the type library. SetDocString Sets the documentation string for the type library. SetHelpFileName Sets the Help file name. SetHelpContext Sets the Help context ID for general information about the type library in the Help file. SetLcid Sets the locale identifier (LCID) code indicating the national language associated with the library. SetLibFlags Sets library flags, such as LIBFLAG_FRESTRICTED. SaveAllChanges Saves the ICreateTypeLib instance.

ICreateTypeLib::CreateTypeInfo HRESULT CreateTypeInfo( OLECHAR FAR* szName, TYPEKIND tkind, ICreateTypeInfo FAR* FAR* ppCTInfo ); HRESULT CreateTypeInfo( OLECHAR FAR* szName, TYPEKIND tkind, ICreateTypeInfo FAR* FAR* ppCTInfo );

ICreateTypeInfo

The Type Library Creation Process Type library module typedef coclass interface dispinterface CreateTypeLib ICreateTypeLib ICreateTypeLib::Set*ICreateTypeLib::CreateTypeInfo ICreateTypeInfo ICreateTypeInfo::* ICreateTypeLib::- SaveAllChanges File (tlb)

Exercises 9. Create type library for Exercise 5 by using COM API.

COM Connection Points Type Library Deployment

Registry for Type Library

Registering a Type Library \TypeLib\{libUUID} \TypeLib\{libUUID}\major.minor = human_readable_string \TypeLib\{libUUID}\major.minor\HELPDIR = [helpfile_path] \TypeLib\{libUUID}\major.minor\Flags = typelib_flags \TypeLib\{libUUID}\major.minor\lcid\platform = localized_typelib_filename

Language Identifiers and Locales

COM Connection Points Loading and Using a Type Library

Who use the type library? Type information is a resource that both objects and clients of those objects can load directly. Objects  – load type information to give it to a client through IProvideClassInfo Clients  – main consumer of the type information – learn about the object

OLE APIs QueryPathOfRegTypeLib LoadRegTypeLib – LoadTypeLib – LoadTypeLibFromResource

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

ITypeLib NameDescription FindNameFinds occurrences of a type description in a type library. GetDocumentationRetrieves 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. GetLibAttrRetrieves the structure that contains the library's attributes. GetTypeCompEnables a client compiler to bind to a library's types, variables, constants, and global functions. GetTypeInfoRetrieves the specified type description in the library. GetTypeInfoCountReturns the number of type descriptions in the type library. GetTypeInfoOfGuidRetrieves the type description that corresponds to the specified GUID. GetTypeInfoTypeRetrieves the type of a type description. IsNameIndicates whether a passed-in string contains the name of a type or member described in the library. ReleaseTLibAttrReleases the TYPELIBATTR structure originally obtained from the GetLibAttr method.TYPELIBATTRGetLibAttr

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

Type library Interface or dispinterfaces colasses Type Library Navigation Interface or dispinterfaces ITypeLib ITypeInfo (Other colasses Interfaces, dispinterfaces)

ITypeInfo

COM Connection Points Objects with Type Information  IProvideClassInfo

IProvideClassInfo interface IProvideClassInfo : IUnknown { HRESULT GetClassInfo(ITypeInfo **ppITI); } The presence of this interface frees the client from having to load and navigate a type library itself.

Sever Code //Try loading from registry information. if (FAILED(LoadRegTypeLib(LIBID_MyTypeLibrary, 1, 0, LANG_NEUTRAL, &pITypeLib))) { //Try loading directly, fixing registry information. if (FAILED(LoadTypeLib(TEXT("MYTYPES.TLB"), &pITypeLib))) return FALSE; } //Find ITypeInfo for coclass. pITypeLib->GetTypeInfoOfGuid(CLSID_MyObject, &m_pITI); pITypeLib->Release(); //Try loading from registry information. if (FAILED(LoadRegTypeLib(LIBID_MyTypeLibrary, 1, 0, LANG_NEUTRAL, &pITypeLib))) { //Try loading directly, fixing registry information. if (FAILED(LoadTypeLib(TEXT("MYTYPES.TLB"), &pITypeLib))) return FALSE; } //Find ITypeInfo for coclass. pITypeLib->GetTypeInfoOfGuid(CLSID_MyObject, &m_pITI); pITypeLib->Release(); m_pITI

Sever Code STDMETHODIMP CMyObject::GetClassInfo(ITypeInfo **ppITI) { if (NULL==ppITI) return ResultFromScode(E_POINTER); *ppITI=m_pITI; if (NULL!=m_pITI){ m_pITI->AddRef(); return NOERROR; } return ResultFromScode(E_FAIL); } STDMETHODIMP CMyObject::GetClassInfo(ITypeInfo **ppITI) { if (NULL==ppITI) return ResultFromScode(E_POINTER); *ppITI=m_pITI; if (NULL!=m_pITI){ m_pITI->AddRef(); return NOERROR; } return ResultFromScode(E_FAIL); }