File : gnatcom-safearray.ads


------------------------------------------------------------------------------
--                                                                          --
--      GNATCOM - Ada 95 COM/DCOM/COM+ Development Framework and Tools      --
--                                                                          --
--                    G N A T C O M . S A F E A R R A Y                     --
--                                                                          --
--                                S p e c                                   --
--                                                                          --
--                            $Revision: 1.4 $
--                                                                          --
--             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                                               --
------------------------------------------------------------------------------

--  Binding to SAFEARRAYs, OLE Automation Arrays

with GNATCOM.Types;

package GNATCOM.SafeArray is

   type Bound is record
      Lower_Bound : Integer;
      Elements    : Natural;
   end record;

   type SafeArray_Bounds is array (Positive range <>) of Bound;

   type Index_Array is array (Positive range <>) of Integer;
   --  Indexes are passed in from right to left, ie. FORTRAN style

   function Create (VT          : GNATCOM.Types.VARTYPE;
                    Lower_Bound : Integer;
                    Elements    : Natural)
                   return GNATCOM.Types.Pointer_To_SAFEARRAY;
   --  Creates a one dimensional SAFEARRAY of range Lower_Bound ..
   --  Lower_Bound + Elements
   --  Note:
   --    VT Can not have VT_ARRAY or VT_BYREF flags set. It also may not be
   --  VT_NULL or VT_EMPTY

   function Create (VT     : GNATCOM.Types.VARTYPE;
                    Bounds : SafeArray_Bounds)
                   return GNATCOM.Types.Pointer_To_SAFEARRAY;
   --  Creates single or multi dimensional SAFEARRAYs using bounds
   --  Note:
   --    VT Can not have VT_ARRAY or VT_BYREF flags set. It also may not be
   --  VT_NULL or VT_EMPTY

   function Create
     (Lib_ID      : GNATCOM.Types.GUID;
      Ver_Maj     : Natural;
      Ver_Min     : Natural;
      Type_GUID   : GNATCOM.Types.GUID;
      Lower_Bound : Integer;
      Elements    : Natural)
     return GNATCOM.Types.Pointer_To_SAFEARRAY;
   function Create
     (Lib_ID  : GNATCOM.Types.GUID;
      Ver_Maj : Natural;
      Ver_Min : Natural;
      Type_GUID   : GNATCOM.Types.GUID;
      Bounds  : SafeArray_Bounds)
     return GNATCOM.Types.Pointer_To_SAFEARRAY;
   --  Creates a SAFEARRAY of VT_RECORDs of custom type with GUID in
   --  Type Library with Lib_ID and version Ver_Maj.Ver_Min

   function Create
     (Lib_ID      : GNATCOM.Types.GUID;
      Ver_Maj     : Natural;
      Ver_Min     : Natural;
      Index       : Natural;
      Lower_Bound : Integer;
      Elements    : Natural)
     return GNATCOM.Types.Pointer_To_SAFEARRAY;
   function Create
     (Lib_ID  : GNATCOM.Types.GUID;
      Ver_Maj : Natural;
      Ver_Min : Natural;
      Index   : Natural;
      Bounds  : SafeArray_Bounds)
     return GNATCOM.Types.Pointer_To_SAFEARRAY;
   --  Creates a SAFEARRAY of VT_RECORDs of custom type at Index in
   --  Type Library with Lib_ID and version Ver_Maj.Ver_Min

   function Create
     (Type_Info   : GNATCOM.Types.Pointer_To_ITypeInfo;
      Lower_Bound : Integer;
      Elements    : Natural)
     return GNATCOM.Types.Pointer_To_SAFEARRAY;
   function Create
     (Type_Info : GNATCOM.Types.Pointer_To_ITypeInfo;
      Bounds    : SafeArray_Bounds)
     return GNATCOM.Types.Pointer_To_SAFEARRAY;
   --  Creates a SAFEARRAY of VT_RECORDs of custom
   --  type described by Type_Info

   function Create_Custom (Size_Of_Element : Positive;
                           Lower_Bound     : Integer;
                           Elements        : Natural)
                          return GNATCOM.Types.Pointer_To_SAFEARRAY;
   --  Creates a one dimensional SAFEARRAY of range Lower_Bound ..
   --  Lower_Bound + Elements of a custom type with Size_Of_Element bytes

   function Create_Custom (Size_Of_Element : Positive;
                           Bounds          : SafeArray_Bounds)
                          return GNATCOM.Types.Pointer_To_SAFEARRAY;
   --  Creates single or multi dimensional SAFEARRAYs using bounds
   --  of a custom type with Size_Of_Element bytes

   function Copy (From : access GNATCOM.Types.SAFEARRAY)
                 return GNATCOM.Types.Pointer_To_SAFEARRAY;
   --  Duplicates a SAFEARRAY
   --  Will make new duplicates of strings and Variants and will call AddRef
   --  on COM Interfaces passed to the new copy

   procedure Free (This : access GNATCOM.Types.SAFEARRAY);
   --  Clears and Deallocates the SAFEARRAY from memory
   --  Also clears internal Variants and Strings and calls Release on
   --  COM Interfaces

   function Get_Dimensions (Of_Array : access GNATCOM.Types.SAFEARRAY)
                           return Positive;
   --  Returns number of dimensions of a SAFEARRAY

   function Get_Lower_Bound (Of_Array  : access GNATCOM.Types.SAFEARRAY;
                             Dimension : in     Positive                := 1)
                            return Integer;
   --  Returns lower bound of array dimension

   function Get_Upper_Bound (Of_Array  : access GNATCOM.Types.SAFEARRAY;
                             Dimension : in     Positive                := 1)
                            return Integer;
   --  Returns upper bound of array dimension

   generic
      type Element is private;
   function Get_Element (Of_Array : access GNATCOM.Types.SAFEARRAY;
                         Index    : in     Integer)
                        return Element;
   --  Returns a copy of the element at index in the SAFEARRAY

   generic
      type Element is private;
   function Get_Value (Of_Array : access GNATCOM.Types.SAFEARRAY;
                       Index    : in     Index_Array)
                      return Element;
   --  Returns a copy of the element at index in the multi dimensional
   --  SAFEARRAY

   generic
      type Element is private;
   procedure Put_Element (Of_Array : access GNATCOM.Types.SAFEARRAY;
                          Index    : in     Integer;
                          Value    : in     Element);
   --  Puts element in to array (Not for use with VT_DISPATCH, VT_UNKNOWN,
   --  or VT_BSTR type arrays)

   generic
      type Element is private;
   procedure Put_Value (Of_Array : access GNATCOM.Types.SAFEARRAY;
                        Index    : in     Index_Array;
                        Value    : in     Element);
   --  Puts element in to a multi dimensional  array (Not for use with
   --  VT_DISPATCH, VT_UNKNOWN or VT_BSTR type arrays)

   procedure Put_IUnknown
     (Of_Array : access GNATCOM.Types.SAFEARRAY;
      Index    : in     Integer;
      Value    : in     GNATCOM.Types.Pointer_To_IUnknown);

   procedure Put_IUnknown
     (Of_Array : access GNATCOM.Types.SAFEARRAY;
      Index    : in     Index_Array;
      Value    : in     GNATCOM.Types.Pointer_To_IUnknown);
   --  Required to place IUnknown pointers in to an array

   procedure Put_IDispatch
     (Of_Array : access GNATCOM.Types.SAFEARRAY;
      Index    : in     Integer;
      Value    : in     GNATCOM.Types.Pointer_To_IDispatch);

   procedure Put_IDispatch
     (Of_Array : access GNATCOM.Types.SAFEARRAY;
      Index    : in     Index_Array;
      Value    : in     GNATCOM.Types.Pointer_To_IDispatch);
   --  Required to place IDispatch pointers in to an array

   procedure Put_BSTR
     (Of_Array : access GNATCOM.Types.SAFEARRAY;
      Index    : in     Integer;
      Value    : in     GNATCOM.Types.BSTR;
      Clear    : in     Boolean                 := True);

   procedure Put_BSTR
     (Of_Array : access GNATCOM.Types.SAFEARRAY;
      Index    : in     Index_Array;
      Value    : in     GNATCOM.Types.BSTR;
      Clear    : in     Boolean                 := True);
   --  Required to place BSTRs in an array

   procedure Put_VARIANT
     (Of_Array : access GNATCOM.Types.SAFEARRAY;
      Index    : in     Integer;
      Value    : in     GNATCOM.Types.VARIANT;
      Clear    : in     Boolean                 := True);

   procedure Put_VARIANT
     (Of_Array : access GNATCOM.Types.SAFEARRAY;
      Index    : in     Index_Array;
      Value    : in     GNATCOM.Types.VARIANT;
      Clear    : in     Boolean                 := True);
   --  May be used to place VARIANTs in an array

   ARRAY_LOCKED_ERROR : exception;
   --  An operation is being attempted on a SAFEARRAY that has been locked

   ARRAY_CREATION_ERROR : exception;
   --  OS was unable to create array

   INVALID_INDEX_ERROR : exception;
   --  The requested index value is invalid for this array

end GNATCOM.SafeArray;