Difference between revisions of "Ide/Creating new Project Items/Creating a COM Package"

From wiki.visual-prolog.com
Line 15: Line 15:
[[Image:Ide_How_COMPackage.png|center|frame|Creating '''New COM Package''' Dialog]]
[[Image:Ide_How_COMPackage.png|center|frame|Creating '''New COM Package''' Dialog]]


After you fill in all required COM package settings, you can press the '''Create''' button. Then the IDE creates the package subdirectory, the package header file ('''XML.ph''' for the above picture), and the package implementation file ('''XML.pack''' for the above picture). They appear in the project tree in the Project Window after the created package is compiled.
After you fill in all required COM package settings, you can press the '''Create''' button. Then the IDE creates the package subdirectory, the package header file (<vp>XML.ph</vp> for the above picture), and the package implementation file (<vp>XML.pack</vp> for the above picture). They appear in the project tree in the Project Window after the created package is compiled.


=== Options: ===
=== Options ===


'''Name:'''
'''Name:'''
:In the '''Name''' edit control you should type in the name ('''xml''' on the picture) of the COM package (wrapping package) being created.
:In the '''Name''' edit control you should type in the name (<vp>XML</vp> on the picture) of the COM package (wrapping package) being created.


'''Parent Directory'''
'''Parent Directory'''
:In the '''Parent Directory''' you should type in or select (using the '''Browse''' button) the ''parent directory'' for the package. The package will be placed into the subdirectory of this ''parent directory''. If you specify a non-existing name, then this directory will be created. By default, '''Parent Directory''' displays the directory selected in the project tree when you activate this dialog. If this directory is one of the project subdirectories, then its path is displayed relatively to the project root directory. If '''Parent Directory''' is empty, than it is equal to the project root directory.
:In the '''Parent Directory''' you should type in or select (using the '''Browse''' button) the ''parent directory'' for the package. The package will be placed into the subdirectory of this ''parent directory''. If you specify a non-existing name, then this directory will be created. By default, '''Parent Directory''' displays the directory selected in the project tree when you activate this dialog. If this directory is one of the project subdirectories, then its path is displayed relatively to the project root directory. If '''Parent Directory''' is empty, than it is equal to the project root directory.
:In the '''Parent Directory''' the IDE creates the new subdirectory with the name correspondent to the specified package name. (It is '''XML''' for the above picture.). The package will be placed into this subdirectory.
:In the '''Parent Directory''' the IDE creates the new subdirectory with the name correspondent to the specified package name. (It is <vp>XML</vp> for the above picture.). The package will be placed into this subdirectory.


'''Source''' Group Box
'''Source''' Group Box
Line 34: Line 34:
*:Press the '''Load''' button to activate the '''Load Type Library File''' dialog using which you can find and insert the name of the type library file into the edit control.
*:Press the '''Load''' button to activate the '''Load Type Library File''' dialog using which you can find and insert the name of the type library file into the edit control.
*:<br /><u>'''Attention!'''</u> Notice that you '''HAVE to''' press the '''Load''' button to enforce the IDE to load the COM information from the specified type library even if you directly type in the type library filename into the edit control.
*:<br /><u>'''Attention!'''</u> Notice that you '''HAVE to''' press the '''Load''' button to enforce the IDE to load the COM information from the specified type library even if you directly type in the type library filename into the edit control.
*:<br />If a COM client (our program importing COM server components) needs using COM server predicates, then the client application must have information about predicates in COM server components. Predicates often return values and accept parameters. The COM client requires declarations of all these predicates (and domains) in order to use them. This information can be made known in several ways. The Microsoft recommended way is to create a type library. (Remember that type libraries do not provide Prolog declarations.) Type library information can be stored in files with the following filename extensions: '''.TLB''' (type library itself), '''.OLB''' (multiple type libraries or foreign object libraries), '''.DLL''' (COM DLLs can embed type library resources), '''.EXE''' (COM EXEs can embed type library resources), '''.OCX''' (ActiveX controls).
*:<br />If a COM client (our program importing COM server components) needs using COM server predicates, then the client application must have information about predicates in COM server components. Predicates often return values and accept parameters. The COM client requires declarations of all these predicates (and domains) in order to use them. This information can be made known in several ways. The Microsoft recommended way is to create a type library. (Remember that type libraries do not provide Prolog declarations.) Type library information can be stored in files with the following filename extensions: '''.tlb''' (type library itself), '''.olb''' (multiple type libraries or foreign object libraries), '''.dll''' (COM DLLs can embed type library resources), '''.exe''' (COM EXEs can embed type library resources), '''.ocx''' (ActiveX controls).


*'''TypeLib ID'''
*'''TypeLib ID'''
*:When this option is checked ON, then in the edit control you should specify the '''TypeLib ID''' of the ''type library'' for the COM component that you wish to import. The '''TypeLib ID''' is a universally unique identifier (UUID) under which the type library is registered in the Windows system registry. (See {{ide|Creating new Project Items#CLSID|CLSID}} for more information.) The '''TypeLib ID''' should be specified as a string of hexadecimal numbers with the following format:
*:When this option is checked ON, then in the edit control you should specify the '''TypeLib ID''' of the ''type library'' for the COM component that you wish to import. The '''TypeLib ID''' is a universally unique identifier (UUID) under which the type library is registered in the Windows system registry. (See '''CLSID''' for more information.) The '''TypeLib ID''' should be specified as a string of hexadecimal numbers with the following format:
*: <vipbnf>{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}</vipbnf>
*: <vipbnf>{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}</vipbnf>
*:Then you '''MUST''' press the '''Load''' button to enforce the IDE to load COM information from the type library registered with this '''TypeLib ID'''.
*:Then you '''MUST''' press the '''Load''' button to enforce the IDE to load COM information from the type library registered with this '''TypeLib ID'''.
Line 47: Line 47:
*:<vipbnf>{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}</vipbnf>
*:<vipbnf>{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}</vipbnf>
*:Then you '''MUST''' press the '''Load''' button to enforce the IDE to load COM information from the COM module that embeds the COM component with the specified '''CLSID'''.
*:Then you '''MUST''' press the '''Load''' button to enforce the IDE to load COM information from the COM module that embeds the COM component with the specified '''CLSID'''.
*:<br />'''Note.''' Really a COM module can embed several COM components. If you wish to import one of these COM components, then you can specify a CLSID registered to any COM component in this COM module. (Later you will be able to specify the required COM component (or interface) in the list box in the [#Import_Group_Box '''Import'''] group box.)
*:<br />'''Note.''' Really a COM module can embed several COM components. If you wish to import one of these COM components, then you can specify a CLSID registered to any COM component in this COM module. (Later you will be able to specify the required COM component (or interface) in the list box in the '''Import''' group box.)
*:<br />In MSDN terminology, '''CLSID''' is a class identifier. In the Visual Prolog PFC terminology (see the COM package description in the PFC) '''CLSID''' is a COM component identifier.
*:<br />In MSDN terminology, '''CLSID''' is a class identifier. In the Visual Prolog PFC terminology (see the COM package description in the PFC) '''CLSID''' is a COM component identifier.
*:'''CLSID''' is a universally unique identifier (UUID) that identifies the type of a COM component. Each COM component has its '''CLSID''' in the Windows system registry database so that it can be loaded and used by other applications. For example, a spreadsheet can create worksheet components, chart components, and macrosheet components. Each of these components has its own '''CLSID''' that uniquely identifies this component to the system. That is, if your COM module (COM server or COM container) allows linking to its embedded components, then you need to register the special '''CLSID''' for each COM component embedded into the COM module.
*:'''CLSID''' is a universally unique identifier (UUID) that identifies the type of a COM component. Each COM component has its '''CLSID''' in the Windows system registry database so that it can be loaded and used by other applications. For example, a spreadsheet can create worksheet components, chart components, and macrosheet components. Each of these components has its own '''CLSID''' that uniquely identifies this component to the system. That is, if your COM module (COM server or COM container) allows linking to its embedded components, then you need to register the special '''CLSID''' for each COM component embedded into the COM module.
Line 59: Line 59:
*:When you find a '''CLSID''' you can find the associated '''PROGID''' under the following registry sub-key:
*:When you find a '''CLSID''' you can find the associated '''PROGID''' under the following registry sub-key:
*:'''<vipbnf>HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID\{CLSID}\ProgID = <programatic identifier></vipbnf>'''
*:'''<vipbnf>HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID\{CLSID}\ProgID = <programatic identifier></vipbnf>'''
*:See the '''{{ide|Creating new Project Items#PROGID|PROGID}}''' options description below.
*:See the '''PROGID''' options description below.
*:<br />'''Universally unique identifier (UUID)'''
*:<br />'''Universally unique identifier (UUID)'''
*:<br />The universally unique identifier (UUID) is also known as the globally unique identifier (GUID). The UUID, or GUID, is a unique, 128-bit value used to identify objects. Objects can be OLE servers, interfaces, client objects, etc. Beginning from this moment objects will be identified with UUIDs.
*:<br />The universally unique identifier (UUID) is also known as the globally unique identifier (GUID). The UUID, or GUID, is a unique, 128-bit value used to identify objects. Objects can be OLE servers, interfaces, client objects, etc. Beginning from this moment objects will be identified with UUIDs.
Line 68: Line 68:
*:<br />Words are separated by dots as in <vp>Word.Document.6</vp>. (Blank spaces cannot be used.)
*:<br />Words are separated by dots as in <vp>Word.Document.6</vp>. (Blank spaces cannot be used.)
*:Then you '''MUST''' press the '''Load''' button to enforce the IDE to load COM information from the COM module registered with this '''PROGID'''.
*:Then you '''MUST''' press the '''Load''' button to enforce the IDE to load COM information from the COM module registered with this '''PROGID'''.
*:'''PROGID'''s are versioned programmatic identifiers. '''PROGID'''s present human-readable versions of class identifiers ({{ide|Creating new Project Items#CLSID|CLSID}}) used to identify COM components. '''PROGID''' is a registry entry that can be associated with {{ide|Creating new Project Items#CLSID|CLSID}}. Like {{ide|Creating new Project Items#CLSID|CLSID}}, '''PROGID''' identifies a COM component but with less precision because it is not guaranteed to be globally unique. The ''<vp>Version</vp>'' portion is optional but strongly recommended. Using ''<vp>Version</vp>'', even if there is only one version of the '''PROGID''', helps to avoid conflicts. It enables different versions of a component coexist without overwriting '''PROGID'''s. If you do not specify a version for a '''PROGID''', the default ''<vp>Version</vp>'' <vp>= 1</vp>.
*:'''PROGID'''s are versioned programmatic identifiers. '''PROGID'''s present human-readable versions of class identifiers ('''CLSID''') used to identify COM components. '''PROGID''' is a registry entry that can be associated with '''CLSID'''. Like '''CLSID''', '''PROGID''' identifies a COM component but with less precision because it is not guaranteed to be globally unique. The ''<vp>Version</vp>'' portion is optional but strongly recommended. Using ''<vp>Version</vp>'', even if there is only one version of the '''PROGID''', helps to avoid conflicts. It enables different versions of a component coexist without overwriting '''PROGID'''s. If you do not specify a version for a '''PROGID''', the default ''<vp>Version</vp>'' <vp>= 1</vp>.
*:How to find '''PROGID''' entries in the registry is described in the {{ide|Creating new Project Items#CLSID|CLSID}}.
*:How to find '''PROGID''' entries in the registry is described in the '''CLSID'''.


*'''IID'''
*'''IID'''
Line 76: Line 76:
*:<vipbnf>{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}</vipbnf>
*:<vipbnf>{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}</vipbnf>
*:Then you '''MUST''' press the '''Load''' button to enforce the IDE to load COM information from the COM module that embeds the interface with the specified '''IID'''.
*:Then you '''MUST''' press the '''Load''' button to enforce the IDE to load COM information from the COM module that embeds the interface with the specified '''IID'''.
*:Really you can specify an '''IID''' registered to any interface embedded into the same COM module that embeds the interface you wish to import. (Later you will be able to specify the required COM component (or interface) in the list box in the [#Import_Group_Box '''Import'''] group box.)
*:Really you can specify an '''IID''' registered to any interface embedded into the same COM module that embeds the interface you wish to import. (Later you will be able to specify the required COM component (or interface) in the list box in the '''Import''' group box.)
*:In the system registry database you can find all registered '''IID'''s under:
*:In the system registry database you can find all registered '''IID'''s under:
*:'''<vipbnf>HKEY_LOCAL_MACHINE\SOFTWARE\Classes\Interface</vipbnf>'''
*:'''<vipbnf>HKEY_LOCAL_MACHINE\SOFTWARE\Classes\Interface</vipbnf>'''

Revision as of 08:23, 18 April 2013

How to Import an Existing COM Component

Terminology Used in COM

The Component Object Model (COM) is a way for software components to communicate with each other. It is a binary standard that allows any two components to communicate regardless of what machine they are running on (as long as the machines are connected), what operating systems the machines are running (as long as they support COM), and what language the components are written in. COM provides location transparency: it does not matter whether components are in DLLs or in EXEs. COM components are binary units of code that include packaging and registration code and that create COM objects. Each COM component, in the COM programming model, is a programming structure encapsulating both data and functionality. It is defined and allocated as a single unit and the only public access to the COM data and functionality is through the programming interfaces.

Each COM is simply a program module: a DLL or an EXE file. It can contain one or more COM components. (In Microsoft MSDN terminology components are coclasses.) Each component knows about several interfaces. (In MSDN terminology - each component can support several interfaces.) Each component supports the default interface iUnknown. Using the iUnknown::queryInterface/2-> predicate from the iUnknown interface, one can retrieve references to all interfaces known to a component. Each interface can provide several predicates (methods).

The main aim of importing a COM component into your project is using predicates defined in this COM component. Therefore, the COM package generated for an imported COM component has to provide some wrapper (glue code) to methods implemented in the COM component. That is, the generated COM package must provide declarations of correspondent interfaces, predicates, and domains.

How to Create a New COM Package

To create a COM package providing the interface (wrapper) to some COM component, you should activate the File | New IDE command. Then in the left pane of the opened Create Project Item dialog you should select COM Package. Then the dialog accepts the following shape:

Creating New COM Package Dialog

After you fill in all required COM package settings, you can press the Create button. Then the IDE creates the package subdirectory, the package header file (XML.ph for the above picture), and the package implementation file (XML.pack for the above picture). They appear in the project tree in the Project Window after the created package is compiled.

Options

Name:

In the Name edit control you should type in the name (XML on the picture) of the COM package (wrapping package) being created.

Parent Directory

In the Parent Directory you should type in or select (using the Browse button) the parent directory for the package. The package will be placed into the subdirectory of this parent directory. If you specify a non-existing name, then this directory will be created. By default, Parent Directory displays the directory selected in the project tree when you activate this dialog. If this directory is one of the project subdirectories, then its path is displayed relatively to the project root directory. If Parent Directory is empty, than it is equal to the project root directory.
In the Parent Directory the IDE creates the new subdirectory with the name correspondent to the specified package name. (It is XML for the above picture.). The package will be placed into this subdirectory.

Source Group Box

Controls in this group box are used to specify a COM module (DLL or EXE) from which a component should be imported. It contains the following controls:

  • Type Library
    When this option is checked ON, then in the edit control you should specify a file that contains the type library describing the COM component.
    Press the Load button to activate the Load Type Library File dialog using which you can find and insert the name of the type library file into the edit control.

    Attention! Notice that you HAVE to press the Load button to enforce the IDE to load the COM information from the specified type library even if you directly type in the type library filename into the edit control.

    If a COM client (our program importing COM server components) needs using COM server predicates, then the client application must have information about predicates in COM server components. Predicates often return values and accept parameters. The COM client requires declarations of all these predicates (and domains) in order to use them. This information can be made known in several ways. The Microsoft recommended way is to create a type library. (Remember that type libraries do not provide Prolog declarations.) Type library information can be stored in files with the following filename extensions: .tlb (type library itself), .olb (multiple type libraries or foreign object libraries), .dll (COM DLLs can embed type library resources), .exe (COM EXEs can embed type library resources), .ocx (ActiveX controls).
  • TypeLib ID
    When this option is checked ON, then in the edit control you should specify the TypeLib ID of the type library for the COM component that you wish to import. The TypeLib ID is a universally unique identifier (UUID) under which the type library is registered in the Windows system registry. (See CLSID for more information.) The TypeLib ID should be specified as a string of hexadecimal numbers with the following format:
    {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}
    Then you MUST press the Load button to enforce the IDE to load COM information from the type library registered with this TypeLib ID.
    In the system registry database you can find all registered TypeLib IDs under:
    HKEY_CLASSES_ROOT\TypeLib = {TypeLib ID}
  • CLSID
    When this option is checked ON, then in the edit control you should specify the CLSID of the COM component that you wish to import. The CLSID should be specified as a string of hexadecimal numbers with the following format:
    {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}
    Then you MUST press the Load button to enforce the IDE to load COM information from the COM module that embeds the COM component with the specified CLSID.

    Note. Really a COM module can embed several COM components. If you wish to import one of these COM components, then you can specify a CLSID registered to any COM component in this COM module. (Later you will be able to specify the required COM component (or interface) in the list box in the Import group box.)

    In MSDN terminology, CLSID is a class identifier. In the Visual Prolog PFC terminology (see the COM package description in the PFC) CLSID is a COM component identifier.
    CLSID is a universally unique identifier (UUID) that identifies the type of a COM component. Each COM component has its CLSID in the Windows system registry database so that it can be loaded and used by other applications. For example, a spreadsheet can create worksheet components, chart components, and macrosheet components. Each of these components has its own CLSID that uniquely identifies this component to the system. That is, if your COM module (COM server or COM container) allows linking to its embedded components, then you need to register the special CLSID for each COM component embedded into the COM module.
    The CLSID is stored in the Windows registry database under the following registry key:
    HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID = {CLSID}
    The CLSID is a 128-bit number (in the hexadecimal format) within a pair of curly braces. Typically, CLSIDs (and other UUID values) are represented as strings of hexadecimal numbers with the following format:
    {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}
    For example,
    {4208fb66-e22a-11d1-a7d7-00a0c982c00d}
    You can use the UUIDGEN.exe tool to create a new UUID.
    When you find a CLSID you can find the associated PROGID under the following registry sub-key:
    HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID\{CLSID}\ProgID = <programatic identifier>
    See the PROGID options description below.

    Universally unique identifier (UUID)

    The universally unique identifier (UUID) is also known as the globally unique identifier (GUID). The UUID, or GUID, is a unique, 128-bit value used to identify objects. Objects can be OLE servers, interfaces, client objects, etc. Beginning from this moment objects will be identified with UUIDs.
  • PROGID
    When this option is checked ON. In the edit control you should specify the PROGID of the COM module from which you wish to import the COM component. The PROGID should be specified as a string of the following format:
    <Program>.<Component>.<Version>

    Words are separated by dots as in Word.Document.6. (Blank spaces cannot be used.)
    Then you MUST press the Load button to enforce the IDE to load COM information from the COM module registered with this PROGID.
    PROGIDs are versioned programmatic identifiers. PROGIDs present human-readable versions of class identifiers (CLSID) used to identify COM components. PROGID is a registry entry that can be associated with CLSID. Like CLSID, PROGID identifies a COM component but with less precision because it is not guaranteed to be globally unique. The Version portion is optional but strongly recommended. Using Version, even if there is only one version of the PROGID, helps to avoid conflicts. It enables different versions of a component coexist without overwriting PROGIDs. If you do not specify a version for a PROGID, the default Version = 1.
    How to find PROGID entries in the registry is described in the CLSID.
  • IID
    When this option is checked ON, then in the edit control you should specify the IID of the COM component interface that you wish to import.
    IID is a universally unique identifier (UUID) that uniquely identifies a particular COM interface. IID should be specified as a string of hexadecimal numbers with the following format:
    {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}
    Then you MUST press the Load button to enforce the IDE to load COM information from the COM module that embeds the interface with the specified IID.
    Really you can specify an IID registered to any interface embedded into the same COM module that embeds the interface you wish to import. (Later you will be able to specify the required COM component (or interface) in the list box in the Import group box.)
    In the system registry database you can find all registered IIDs under:
    HKEY_LOCAL_MACHINE\SOFTWARE\Classes\Interface