File : gnatcom-interface.ads


------------------------------------------------------------------------------
--                                                                          --
--      GNATCOM - Ada 95 COM/DCOM/COM+ Development Framework and Tools      --
--                                                                          --
--                    G N A T C O M . I N T E R F A C E                     --
--                                                                          --
--                                S p e c                                   --
--                                                                          --
--                            $Revision: 1.3 $
--                                                                          --
--             Copyright (C) 1999, 2000, 2001 David Botton                  --
--                                                                          --
-- This is free software;  you can  redistribute it  and/or modify it under --
-- terms of the  GNU General Public License as published  by the Free Soft- --
-- ware  Foundation;  either version 2,  or (at your option) any later ver- --
-- sion. It is distributed in the hope that it will be useful,  but WITHOUT --
-- ANY WARRANTY;  without  even the  implied warranty of MERCHANTABILITY or --
-- FITNESS FOR A PARTICULAR PURPOSE.    See the GNU General  Public License --
-- for  more details.  You should have  received  a copy of the GNU General --
-- Public License  distributed with this;  see file COPYING.  If not, write --
-- to  the Free Software Foundation,  59 Temple Place - Suite 330,  Boston, --
-- MA 02111-1307, USA.                                                      --
--                                                                          --
-- As a special exception,  if other files  instantiate  generics from this --
-- unit, or you link  this unit with other files  to produce an executable, --
-- this  unit  does not  by itself cause  the resulting  executable  to  be --
-- covered  by the  GNU  General  Public  License.  This exception does not --
-- however invalidate  any other reasons why  the executable file  might be --
-- covered by the  GNU Public License.                                      --
--                                                                          --
-- More information about GNATCOM and the most current public version can   --
-- be located on the web at http://www.adapower.com/gnatcom                 --
--                                                                          --
-- Support for GNATCOM is available from Ada Core Technologies, Inc.        --
--                                                                          --
-- 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                                               --
------------------------------------------------------------------------------

--  The Interface_Type encapsulates the functionality of IUnknown creating a
--  thick binding to COM Interfaces and Objects

--  One of the COM initialization methods must be called first before
--  using any COM Interface wrappers

with Ada.Finalization;
with Ada.Unchecked_Conversion;
with System;
with Interfaces.C;

with GNATCOM.Types;

pragma Elaborate_All (GNATCOM);

package GNATCOM.Interface is

   type Interface_Type is new Ada.Finalization.Controlled with private;

   procedure Create
     (This        : in out Interface_Type;
      From        : in     GNATCOM.Types.GUID;
      Server_Type : in     GNATCOM.Types.CLSCTX := GNATCOM.Types.CLSCTX_ALL);
   --  Creates new COM object using a CLSID

   procedure Create
     (This        : in out Interface_Type;
      From        : in     String;
      Server_Type : in     GNATCOM.Types.CLSCTX := GNATCOM.Types.CLSCTX_ALL);
   --  Creates new COM object using the COM PROGID

   procedure Create
     (This        : in out Interface_Type;
      From        : in     GNATCOM.Types.GUID;
      Key         : in     GNATCOM.Types.BSTR;
      Free_Key    : in     Boolean              := True;
      Server_Type : in     GNATCOM.Types.CLSCTX := GNATCOM.Types.CLSCTX_ALL);
   --  Creates new COM object using a CLSID and a License Key
   --  If Free_Key is true, the BSTR Key is deallocated

   function Get_Key (Object : in GNATCOM.Types.GUID) return GNATCOM.Types.BSTR;
   --  Gets a licese key if available for the object

   procedure CreateFromMoniker
     (This : in out Interface_Type;
      From : in     String);
   --  Creates a new COM object using a the DisplayName of a Moniker

   procedure CreateRemote
     (This   : in out Interface_Type;
      From   : in     GNATCOM.Types.GUID;
      Server : in     String);
   --  Creates the COM object on a remote machine using a CLSID

   procedure CreateRemote
     (This   : in out Interface_Type;
      From   : in     String;
      Server : in     String);
   --  Creates the COM object on a remote machine using a COM PROGID

   procedure Query
     (This : in out Interface_Type;
      From : in     Interface_Type'class);
   --  Queries and object through any of its interfaces to return and
   --  interface of the IID type set in the Interface_Type

   procedure Query
     (This    : in out Interface_Type;
      From    : in     Interface_Type'Class;
      Success : in out Boolean);
   --  Queries and object through any of its interfaces to return and
   --  interface of the IID type set in the Interface_Type

   procedure Set_IID
     (This : in out Interface_Type;
      IID  : in     GNATCOM.Types.GUID);
   --  Sets the IID to be used when for querying new interfaces

   function IID (This : Interface_Type) return GNATCOM.Types.GUID;
   --  Returns the currently set IID to use when querying new interface

   function Is_Attached (This : Interface_Type) return Boolean;
   --  Returns true if this is attached to a COM Interface

   procedure Attach
     (This : in out Interface_Type;
      From : in     System.Address);
   --  Attaches a COM interface to an Interface_Type.
   --  No Query is performed.

   procedure Attach
     (This : in out Interface_Type;
      From : in     GNATCOM.Types.Pointer_To_IUnknown);
   --  Attaches a COM interface to an Interface_Type.
   --  Performs a Query on the IUnknown to convert it to the curretly set IID

   procedure Attach
     (This : in out Interface_Type;
      From : in     GNATCOM.Types.VARIANT);
   --  Attaches an IUnknown COM interface contained in a VARIANT to an
   --  Interface_Type. Performs a Query on the IUnknown to convert it to
   --  the currently set IID

   function Pointer (This : Interface_Type)
     return GNATCOM.Types.Pointer_To_IUnknown;
   --  Returns the internal interface pointer

   function Address (This : Interface_Type) return System.Address;
   --  Returns the address of the interface pointer

   procedure Free (This : in out Interface_Type);
   --  Calls Release on the attached interface and clears internal
   --  pointers.

   function IsEqual (Left  : in Interface_Type;
                     Right : in Interface_Type'Class)
                    return Boolean;
   --  Compares two Interfaces to see if they are from the same object
   --  this is done by querying each object for IUnknown and then comparing
   --  the interface pointers returned to see if they pointer to the same
   --  address. According to the COM specification all QueryInterfaces for
   --  IUnknown must return the same pointer value.

   type GIT_Cookie is new Interfaces.C.unsigned_long;
   --  Used for holding a reference value to an interface placed in the
   --  Global Interface Table

   function Put_In_GIT (This : Interface_Type) return GIT_Cookie;
   --  Place Interface in Global Interface Table.
   --
   --  Each process that uses COM has an associated table where
   --  interface pointers can be stored. Pointer stored in this table
   --  can be retrieved from any thread regardless of its thread model,
   --  ie. it automaticly marshalls interface pointers accross apartment
   --  boundries.

   procedure Remove_From_GIT (Cookie : in GIT_Cookie);
   --  Remove interface from Global Interface Table

   procedure Attach_From_GIT (This   : in out Interface_Type;
                              Cookie : in     GIT_Cookie);
   --  Attach an interface in the GIT to this type

   procedure Free (This : in GNATCOM.Types.BSTR);
   procedure Free (This : in GNATCOM.Types.VARIANT);
   --  Helper functions for freeing contents of BSTRs and VARIANTs in
   --  thick bindings

   CLASS_NOT_REGISTERED_ERROR : exception;
   --  Raised when an attempt to create a COM object has been performed and
   --  the object has not been registered on the system

   CLASS_NOT_LICENSED_ERROR : exception;
   --  Raised when unable to create object do to license violation or
   --  lack of license key
   --  A valid license key needs to be passed to the create function

   CLASS_NOT_AVAILABLE_ERROR : exception;
   --  Raised when object uncreatable

   INVALID_PROGID_ERROR : exception;
   --  Raised when a request to create a COM object with an invalid PROGID

   SERVER_FILE_NOT_FOUND_ERROR : exception;
   --  An attempt was made to load the COM server specified in the registry,
   --  but the file was not found

   SERVER_ERROR : exception;
   --  There is something wrong with the COM server either the file has an
   --  invalid image, or it did not properly establish itself as a COM server
   --  with the OS

   --  Wrappers directly to Interface_Type's IUnknown

   procedure Finalize (This : in out Interface_Type);
   procedure Adjust (This : in out Interface_Type);
   --  These procedures insure proper reference counting for IUknown

   procedure AddRef (This : in Interface_Type);
   --  Wrapper for IUknown::AddRef

   procedure Release (This : in Interface_Type);
   --  Wrapper for IUknown::Release
   --  Releases a reference count to the interface, COM objects free
   --  themselves from memory when all outstanding interfaces have had
   --  their reference counts reduced to zero

   function QueryInterface
     (This               : in     Interface_Type;
      IID                : in     GNATCOM.Types.GUID;
      Pointer_To_Pointer : access GNATCOM.Types.Pointer_To_Void)
     return GNATCOM.Types.HRESULT;
   --  Wrapper for IUknown::QueryInterface

   function To_Pointer_To_IUnknown is
     new Ada.Unchecked_Conversion
     (System.Address, GNATCOM.Types.Pointer_To_IUnknown);

   function To_VARIANT_From_Interface (From : in Interface_Type)
     return GNATCOM.Types.VARIANT;
   --  Create a VARIANT containing a pointer to the From interface
   --  Calls Addref. VARIANT should be destroyed when no longer needed.

private

   type Interface_Type is new Ada.Finalization.Controlled with
      record
         Interface_Address : aliased System.Address := System.Null_Address;
         IID               : aliased GNATCOM.Types.GUID :=
           GNATCOM.Types.IID_IUnknown;
      end record;

end GNATCOM.Interface;