[Top] [Contents] [Index] [ ? ]

GNATCOM Overview

1. Introduction to GNATCOM  
2. GNATCOM Framework Overview  
3. GNATCOM Tools Overview  
4. Sample GNATCOM Applications  Sample GNATCOM applications
5. GNATCOM Tutorial  
6. Commercial Support for GNATCOM  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1. Introduction to GNATCOM

GNATCOM comprises a framework covering binding and creation of all COM (Component Object Model) technology based objects and four powerful tools, MakeGUID, COMScope, BindCOM, and CreateCOM.

Thanks to GNATCOM the incredible wealth of technologies on the Windows 9X, NT and 2000 platforms become immediately available to Ada 95 applications. To name just a few, XML parsers, full control over Internet Explorer including integration and binding to its DHTML model, Microsoft Message Queuing, integration with Visual Basic Forms, OLEDB and ADO (Active Data Objects), MAPI, and more. GNATCOM also makes it easily possible for the many applications on these platforms to take advantage of the advanced stability and features offered by components written with GNAT.

Ada's unique combination of object-oriented, high-level real-time control and concurrency features, coupled with the fundamental distinction between interface and implementation allows building the feature-rich and highly reliable objects required by component based development.

The GNATCOM home page is located at http://www.adapower.com/gnatcom


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2. GNATCOM Framework Overview

The GNATCOM framework allows for the creation of fully compliant COM objects providing full VTBL (virtual function table) support for custom interfaces in addition to the more limited automation (dynamic dispatch support through the COM interface IDispatch) used in most ActiveX controls. Additionally, BindCOM generates bindings to both custom interfaces (VTBL based) and interfaces offering the same performance boost of C++ over other languages in using COM objects but with Ada's careful type safety features.

The GNATCOM framework provides a thick bindings to COM/DCOM/COM+ for using pre-existing components, creating new components, COM event handling, automation types, Error handling, GUID creation and conversion, and reading type libraries.

Key GNATCOM Packages


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3. GNATCOM Tools Overview


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4. Sample GNATCOM Applications

GNATCOM comes with a number of sample applications that demonstrate how to use the GNATCOM framework and bindings created by the GNATCOM tools. Many of these applications require bindings be generated for COM components first. The batch file make.bat in the bindings directory will create the needed bindings.

The res directory contains any needed files to create the Win32 resource files for the samples.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5. GNATCOM Tutorial

This tutorial assumes basic knowledge of COM/DCOM/COM+, an understanding of Ada 95 and GNAT. It would be helpful to have read the COM/DCOM/COM+ with GNAT documentation first.

5.1 Creating a COM Object  
5.2 Using a COM Object  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.1 Creating a COM Object

  1. Create IDL

    The first step is to create an IDL file that conforms to OLE Automation specifications. See COM/DCOM/COM+ with GNAT documentation for more information on creating compatible IDL files for use with GNAT.

    This tutorial uses the gnatexample.idl found in the Docs/Tutorial directory containing one COM object, GNATCOMClass, that has two interfaces, IGNATMessage (a dual interface) and IGNATStat (a custom COM interface).

  2. Compile IDL to a TypeLibrary

    Compile gnatexample.idl using MIDL included with Visual Studio and the Microsoft SDK tools. This will produce the typelibrary gnatexample.tlb and a number of .h and .c files that can be erased.

  3. Generate code for COM object

    Execute the following command:

     
    CreateCOM gnatexample.tlb GNATExample
    

    This will create all the code needed to implement the COM object.

  4. With support for dual interface

    Edit the file gnatexample-gnatcomclass.ads and add a with of the package GNATCOM.Create.IDispatch.

     
    with GNATCOM.Create.IDispatch;
    

    This will include support to implement the automation (IDispatch) portion of the interface IGNATMessage for the object.

  5. Add dual interface support to object

    Add an IDispatch_Type object to the class record GNATCOMClass_Type.

     
       type GNATCOMClass_Type is
         new GNATCOM.Create.COM_Interface.CoClass_Type (GUID_Map'Access) with
          record
    
             Data : aliased GNATCOM.Create.IDispatch.IDispatch_Type
               (IID_IGNATMessage'Access,
                LIBID_GNATCOMLibrary'Access, 1, 0);
    
          end record;
    

    The options for the IDispatch_Type are the dual interface IID, the type library and the major and minor version (see the specs for the IDispatch support for more information). The IIDs and the LIBID can be found in the root package GNATExample.ads.

  6. Fill in dual interface support methods

    In function IGNATMessage_GetTypeInfoCount replace the return GNATCOM.E_NOTIMPL; with:

     
          return GNATCOM.Create.IDispatch.GetTypeInfoCount (pctinfo);
    

    In function IGNATMessage_GetTypeInfo replace the return GNATCOM.E_NOTIMPL; with:

     
          return GNATCOM.Create.IDispatch.GetTypeInfo (Object.Data'Access,
                                                       itinfo,
                                                       pptinfo);
    

    In function IGNATMessage_GetIDsOfNames replace the return GNATCOM.E_NOTIMPL; with:

     
          return GNATCOM.Create.IDispatch.GetIDsOfNames (Object.Data'Access,
                                                         rgszNames,
                                                         cNames,
                                                         rgdispid);
    

    In function IGNATMessage_Invoke replace the return GNATCOM.E_NOTIMPL; with:

     
          return GNATCOM.Create.IDispatch.Invoke (This,
                                                  Object.Data'Access,
                                                  dispidMember,
                                                  wFlags,
                                                  pdispparams,
                                                  pvarResult,
                                                  pexcepinfo,
                                                  puArgErr);
    

  7. Add data members to object

    Add members to the class record to store object instance data. In this case an integer variable is added to the record to keep count of the number of times members have been called of the IGNATMessage interface.

     
       type GNATCOMClass_Type is
         new GNATCOM.Create.COM_Interface.CoClass_Type (GUID_Map'Access) with
          record
             Data  : aliased GNATCOM.Create.IDispatch.IDispatch_Type
               (IID_IGNATMessage'Access,
                LIBID_GNATCOMLibrary'Access, 1, 0);
    
             Count : Integer := 0;
    
          end record;
    

  8. Implement remaining COM object methods

    Add with Win32.User; to the package and then fill in the lines in bold in to the IGNATMessage_Beep function removing the old return GNATCOM.E_NOTIMPL; line.

     
       function IGNATMessage_Beep
         (This : access
            GNATCOM.Create.COM_Interface.COM_Interface_Type)
         return GNATCOM.Types.HRESULT
       is
          Object   : Pointer_To_GNATCOMClass_Type :=
            Pointer_To_GNATCOMClass_Type (This.CoClass);
    
          RetValue : Win32.BOOL;
    
       begin
    
          RetValue := Win32.WinUser.MessageBeep (Win32.WinUser.MB_ICONEXCLAMATION);
          Object.Count := Object.Count + 1;
          return GNATCOM.S_OK;
    
       end IGNATMessage_Beep;
    

    Add with GNATCOM.Utility; and with GNATCOM.BSTR to the package and fill in the lines in bold in to the IGNATMessage_MessageBox function removing the old return GNATCOM.E_NOTIMPL; line. (Note that Ada exceptions should never be allowed to propagate beyond the COM object.)

     
       function IGNATMessage_MessageBox
         (This    : access
            GNATCOM.Create.COM_Interface.COM_Interface_Type;
          Message : GNATCOM.Types.BSTR)
         return GNATCOM.Types.HRESULT
       is
          Object : Pointer_To_GNATCOMClass_Type :=
            Pointer_To_GNATCOMClass_Type (This.CoClass);
       begin
    
          GNATCOM.Utility.Message_Box ("GNATCOM",
                                       GNATCOM.BSTR.To_Ada (Message, False));
          Object.Count := Object.Count + 1;
          return GNATCOM.S_OK;
       exception
          when others =>
             return GNATCOM.E_FAIL;
    
       end IGNATMessage_MessageBox;
    

    Fill in the lines in bold in to the IGNATStat_Calls function removing the old return GNATCOM.E_NOTIMPL; line.

     
       function IGNATStat_Calls
         (This          : access
            GNATCOM.Create.COM_Interface.COM_Interface_Type;
          NumberOfTimes : GNATCOM.Types.Pointer_To_int)
         return GNATCOM.Types.HRESULT
       is
          Object : Pointer_To_GNATCOMClass_Type :=
            Pointer_To_GNATCOMClass_Type (This.CoClass);
       begin
    
          NumberOfTimes.all := Interfaces.C.Int (Object.Count);
          return GNATCOM.S_OK;
    
       end IGNATStat_Calls;
    

  9. Compile and Register Object

    Compile the COM object by running the generated make.bat file. Then register either the Dll version, by typing regsvr32 gnatexample-dll.dll or the Exe version, by typing gnatexample-exe /RegServer.

    The COM object is now ready for use.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.2 Using a COM Object

  1. Create the binding

    Run BindCOM gnatexample.tlb GNATClient to create a binding to the COM object in the previous tutorial.

  2. Create main procedure

    Set up the basic client main procedure and add error handling to catch COM errors as shown in bold:

     
    with Ada.Exceptions;
    with GNAT.IO; use GNAT.IO;
    
    procedure Client is
    begin
    
    exception
       when E : others =>
          Put_Line (Ada.Exceptions.Exception_Name (E));
          Put_Line (Ada.Exceptions.Exception_Message (E));
    
    end Client;
    

  3. Initialize COM

    Before using GNATCOM, the COM environment must be initialized. This is done by calling the procedure GNATCOM.Initialize.Initialize_COM at the start of the Client procedure.

     
    procedure Client is
    begin
    
       GNATCOM.Initialize.Initialize_COM;
    
    

  4. Declare an Interface Type

    Add code to with in the bindings for the interfaces that will be used and declare objects of those types.

     
    
    with GNATClient.IGNATMessage_Interface; use GNATClient.IGNATMessage_Interface;
    with GNATClient.IGNATStat_Interface; use GNATClient.IGNATStat_Interface;
    
    procedure Client is
    
       Messages : IGNATMessage_Type;
       Stats    : IGNATStat_Type;
    
    

  5. Create Object

    Create the COM object by calling Create on one of the interfaces supported by the object.

     
       Create (Messages, GNATClient.CLSID_GNATCOMClass);
    

  6. Use object

    Once the object has been created methods can be called on the interface used to create the object, or a Query can be performed to access other interfaces of the object.

     
       Beep (Messages);
    
       MessageBox (Messages, GNATCOM.BSTR.To_BSTR ("Hello World!"));
    
       Query (Stats, Messages);
    
       Put_Line ("IGNATMessage methods called" &
                 Integer (Calls (Stats))'Img & " times.");
    

  7. Compile and run

    Compile the client code using gnatmake client and then run it. To use the object on a remote machine, first run the beep-remote.exe on the remote machine with the objects host machine name and the run the client on that machine. You may have to configure permissions on the host machine using the utility dcomcnfg.exe.

    client.adb :

     
    with Ada.Exceptions;
    with GNAT.IO; use GNAT.IO;
    
    with GNATCOM.Initialize; use GNATCOM.Initialize;
    with GNATCOM.BSTR;
    
    with GNATClient.IGNATMessage_Interface; use GNATClient.IGNATMessage_Interface;
    with GNATClient.IGNATStat_Interface; use GNATClient.IGNATStat_Interface;
    
    procedure Client is
       Messages : IGNATMessage_Type;
       Stats    : IGNATStat_Type;
    begin
       GNATCOM.Initialize.Initialize_COM;
    
       Create (Messages, GNATClient.CLSID_GNATCOMClass);
    
       Beep (Messages);
    
       MessageBox (Messages, GNATCOM.BSTR.To_BSTR ("Hello World!"));
    
       Query (Stats, Messages);
    
       Put_Line ("IGNATMessage methods called" &
                 Integer (Calls (Stats))'Img & " times.");
    exception
       when E : others =>
          Put_Line (Ada.Exceptions.Exception_Name (E));
          Put_Line (Ada.Exceptions.Exception_Message (E));
    end Client;
    


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6. Commercial Support for GNATCOM

If you are considering using GNATCOM in commercial applications, please contact the Ada Core Technologies sales offices given below for a no-cost GNATCOM evaluation package which will give you further directions on reporting feedback on this release.

 
In the U.S., contact Ada Core Technologies at:
Tel: +1 (212) 620 7300 ext 117
Fax: +1 (212) 807 0162
Email: sales@gnat.com

In Europe and elsewhere, contact ACT Europe at:
Tel: +33 1 49 70 67 16
Fax: +33 1 49 70 05 52
Email: sales@act-europe.fr


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

Index

Jump to:   A   B   C   D   E   F   G   H   I   J   M   N   P   S   T   V  

Index Entry Section

A
ActiveX4. Sample GNATCOM Applications
ActiveX Data Objects4. Sample GNATCOM Applications
ADO4. Sample GNATCOM Applications
Automation2. GNATCOM Framework Overview
Automation Types2. GNATCOM Framework Overview

B
BindCOM3. GNATCOM Tools Overview
Binding2. GNATCOM Framework Overview
BSTR2. GNATCOM Framework Overview

C
COM Types2. GNATCOM Framework Overview
COMScope3. GNATCOM Tools Overview
CreateCOM3. GNATCOM Tools Overview
Creating COM objects2. GNATCOM Framework Overview
Creating COM objects2. GNATCOM Framework Overview

D
Dual Interface2. GNATCOM Framework Overview

E
Errors2. GNATCOM Framework Overview
Events2. GNATCOM Framework Overview
Events4. Sample GNATCOM Applications
Events4. Sample GNATCOM Applications
Events4. Sample GNATCOM Applications
Examples4. Sample GNATCOM Applications
Examples5. GNATCOM Tutorial

F
Framework2. GNATCOM Framework Overview

G
Global Interface Table4. Sample GNATCOM Applications
GNATCOM2. GNATCOM Framework Overview
GNATCOM.BSTR2. GNATCOM Framework Overview
GNATCOM.Create2. GNATCOM Framework Overview
GNATCOM.Create.COM_Interface2. GNATCOM Framework Overview
GNATCOM.Dispinterface2. GNATCOM Framework Overview
GNATCOM.Errors2. GNATCOM Framework Overview
GNATCOM.Events2. GNATCOM Framework Overview
GNATCOM.Events.Event_Object2. GNATCOM Framework Overview
GNATCOM.GUID2. GNATCOM Framework Overview
GNATCOM.Initialize2. GNATCOM Framework Overview
GNATCOM.Interface2. GNATCOM Framework Overview
GNATCOM.IUnknown2. GNATCOM Framework Overview
GNATCOM.SafeArray2. GNATCOM Framework Overview
GNATCOM.VARIANT2. GNATCOM Framework Overview
GUID2. GNATCOM Framework Overview
GUID3. GNATCOM Tools Overview

H
HRESULT2. GNATCOM Framework Overview

I
IDispatch2. GNATCOM Framework Overview
Interface2. GNATCOM Framework Overview
Internet Explorer4. Sample GNATCOM Applications
Internet Explorer4. Sample GNATCOM Applications
Introduction1. Introduction to GNATCOM
IUnknown2. GNATCOM Framework Overview

J
J++4. Sample GNATCOM Applications
Java4. Sample GNATCOM Applications
JavaCall4. Sample GNATCOM Applications
JVM4. Sample GNATCOM Applications

M
MakeGUID3. GNATCOM Tools Overview
Microsoft Message Queueing4. Sample GNATCOM Applications
Moniker2. GNATCOM Framework Overview
MSMQ4. Sample GNATCOM Applications

N
NT_GNATFIND4. Sample GNATCOM Applications

P
Packages2. GNATCOM Framework Overview

S
SafeArray2. GNATCOM Framework Overview
Samples4. Sample GNATCOM Applications
Samples5. GNATCOM Tutorial
Spin4. Sample GNATCOM Applications
Support6. Commercial Support for GNATCOM

T
Tasks4. Sample GNATCOM Applications
Threads4. Sample GNATCOM Applications

V
VARIANT2. GNATCOM Framework Overview
Visual Basic4. Sample GNATCOM Applications

Jump to:   A   B   C   D   E   F   G   H   I   J   M   N   P   S   T   V  


[Top] [Contents] [Index] [ ? ]

Table of Contents


[Top] [Contents] [Index] [ ? ]

Short Table of Contents

1. Introduction to GNATCOM
2. GNATCOM Framework Overview
3. GNATCOM Tools Overview
4. Sample GNATCOM Applications
5. GNATCOM Tutorial
6. Commercial Support for GNATCOM
Index

[Top] [Contents] [Index] [ ? ]

About this document

This document was generated by Vasiliy Fofanov on February, 18 2003 using texi2html

The buttons in the navigation panels have the following meaning:

Button Name Go to From 1.2.3 go to
[ < ] Back previous section in reading order 1.2.2
[ > ] Forward next section in reading order 1.2.4
[ << ] FastBack previous or up-and-previous section 1.1
[ Up ] Up up section 1.2
[ >> ] FastForward next or up-and-next section 1.3
[Top] Top cover (top) of document  
[Contents] Contents table of contents  
[Index] Index concept index  
[ ? ] About this page  

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

This document was generated by Vasiliy Fofanov on February, 18 2003 using texi2html