File : gnatcom-create-com_interface.ads
------------------------------------------------------------------------------
-- --
-- GNATCOM - Ada 95 COM/DCOM/COM+ Development Framework and Tools --
-- --
-- G N A T C O M . C R E A T E . 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 --
------------------------------------------------------------------------------
-- COM_Interface provides an implementation of IUnknown for COM objects
-- and provides the C++ style virtual function tables that comprise
-- the COM binary standard for interfaces
with GNATCOM.Types;
with System;
package GNATCOM.Create.COM_Interface is
type GUID_Record is
record
IID : aliased GNATCOM.Types.GUID;
Vtbl : System.Address;
end record;
-- Map for IIDs to virtual function tables
type GUID_Record_Array is array (Natural range <>) of GUID_Record;
type Pointer_To_GUID_Record_Array is access all GUID_Record_Array;
-- The GUID_Record_Array is used by QueryInterface to find
-- which interfaces are implemented and retrieve their virtual
-- function tables.
type COM_Interface_Type;
type Pointer_To_COM_Interface_Type is access all COM_Interface_Type;
type CoClass_Type (IID_Map : Pointer_To_GUID_Record_Array) is tagged
record
Ref_Count : aliased Interfaces.C.long := 1;
IUnknown : Pointer_To_COM_Interface_Type := null;
end record;
-- New COM objects extend CoClass_Type with their own implementation
-- data IID_Map contains a map of each implemented interface,
-- Ref_Count keeps a class wide reference count and pIUnknown contains
-- a pointer to the "official" IUnknown. COM specs state that every
-- QueryInterface for IUnknown must return the same pointer to IUnknown
-- Other interfaces need not always return the same pointer and in
-- GNATCOM they frequently are not the same.
type Pointer_To_CoClass is access all CoClass_Type'Class;
-- Base type for CoClasses used with COM_Interface_Type
function QueryInterface
(Dispatch : in CoClass_Type;
This : access COM_Interface_Type;
riid : in GNATCOM.Types.Pointer_To_GUID;
ppvObject : access GNATCOM.Types.Pointer_To_Void)
return GNATCOM.Types.HRESULT;
-- QueryInterface extension
-- Dispatched if no matching interface is found in the classes IID_Map
-- by the internal QueryInterface implementation.
-- The default implementation returns E_NOINTERFACE as should any
-- version of QueryInterface that does not handle interface riid
-- Function specs for IUnknown
--
-- The QueryInterface, Addref and Release are the first three functions
-- in every interface since every interface is a child of IUnknown. This
-- allows every interface to be treated polymorphically as
-- IUnknown. Then QueryInterface can be used to query the object for
-- support of an interface and retrieve a pointer to the COM object's
-- interface that conforms to the requested interface. In essence
-- QueryInterface is used to do a typesafe "cast" from one interface of
-- a COM object to another.
type Af_QueryInterface is access
function (This : access COM_Interface_Type;
riid : in GNATCOM.Types.Pointer_To_GUID;
ppvObject : access GNATCOM.Types.Pointer_To_Void)
return GNATCOM.Types.HRESULT;
pragma Convention (Stdcall, Af_QueryInterface);
type Af_AddRef is access function (This : access COM_Interface_Type)
return Interfaces.C.unsigned_long;
pragma Convention (Stdcall, Af_AddRef);
type Af_Release is access function (This : access COM_Interface_Type)
return Interfaces.C.unsigned_long;
pragma Convention (Stdcall, Af_Release);
function QueryInterface
(This : access COM_Interface_Type;
riid : in GNATCOM.Types.Pointer_To_GUID;
ppvObject : access GNATCOM.Types.Pointer_To_Void)
return GNATCOM.Types.HRESULT;
pragma Convention (Stdcall, QueryInterface);
-- Query COM object for the interface riid and return a pointer to it
-- if possible. QueryInterface will call AddRef on the interface before
-- returning it in ppvObject
-- If riid is not found it dispatches to the CoClass version of
-- QueryInterface
function AddRef (This : access COM_Interface_Type)
return Interfaces.C.unsigned_long;
pragma Convention (Stdcall, AddRef);
-- Add a reference count to the object
function Release (This : access COM_Interface_Type)
return Interfaces.C.unsigned_long;
pragma Convention (Stdcall, Release);
-- Reduce reference count. If 0 free object from memory
procedure Release (This : access COM_Interface_Type);
-- This procedure can be used to release user created objects
-- such as those created by GNATCOM.Events.Event_Object.Create
type IUnknown_Vtbl_Record is
record
QueryInterface : GNATCOM.Create.COM_Interface.Af_QueryInterface :=
GNATCOM.Create.COM_Interface.QueryInterface'Access;
AddRef : GNATCOM.Create.COM_Interface.Af_AddRef :=
GNATCOM.Create.COM_Interface.AddRef'Access;
Release : GNATCOM.Create.COM_Interface.Af_Release :=
GNATCOM.Create.COM_Interface.Release'Access;
end record;
pragma Convention (C_PASS_BY_COPY, IUnknown_Vtbl_Record);
type Pointer_To_IUnknown_Vtbl is access all IUnknown_Vtbl_Record;
-- IUknown virtual function table
IUnknown_Vtbl : aliased IUnknown_Vtbl_Record;
type COM_Interface_Type is
record
Vtbl : System.Address := IUnknown_Vtbl'Address;
CoClass : Pointer_To_CoClass;
Ref_Count : aliased Interfaces.C.long := 1;
end record;
pragma Convention (C_PASS_BY_COPY, COM_Interface_Type);
-- The COM_Interface_Type is constructed so that the first element
-- in the record is a pointer to the table of functions and
-- additional members are private data elements of the
-- COM_Interface_Type unavailable to clients of the COM object. The
-- CoClass element holds a pointer to the object wide data elements
-- of the COM object.
function Create_Object (Class_Object : Pointer_To_CoClass) return
Pointer_To_COM_Interface_Type;
-- Creates the working COM object and returns the COM_Interface_Type
-- for the IUnknown interface to the object
end GNATCOM.Create.COM_Interface;