File : gnatcom-variant.ads
------------------------------------------------------------------------------
-- --
-- GNATCOM - Ada 95 COM/DCOM/COM+ Development Framework and Tools --
-- --
-- G N A T C O M . V A R I A N T --
-- --
-- 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 --
------------------------------------------------------------------------------
-- VARIANTs are a COM type representing any one of the OLE Automation
-- Types
with Ada.Calendar;
with Interfaces.C;
with System;
with GNATCOM.Types;
package GNATCOM.VARIANT is
procedure Initialize (This : in out GNATCOM.Types.VARIANT);
-- All new VARIANTs must be initialized first before first use.
procedure Clear (This : in out GNATCOM.Types.VARIANT);
-- Clears the contents of a VARIANT and deallocates and objects it may
-- contain. Clear must be called on all VARIANTs containing BSTRs,
-- COM interfaces, or SAFEARRAYs in order to release the used resources.
procedure Free (This : in GNATCOM.Types.VARIANT);
-- Frees any BSTR, COM Interfaces, or SAFEARRAYs contained in the
-- variant, but doesn't clear out the values in the VARIANT
function Copy (From : GNATCOM.Types.VARIANT)
return GNATCOM.Types.VARIANT;
-- Creates a copy of a VARIANT
procedure Change_Type (This : in out GNATCOM.Types.VARIANT;
VT : in GNATCOM.Types.VARTYPE);
-- Converts the type and contents of the VARIANT to the type VT
function To_VARIANT (From : String)
return GNATCOM.Types.VARIANT;
function To_VARIANT_From_Wide (From : Wide_String)
return GNATCOM.Types.VARIANT;
-- Allocates a BSTR in a new VARIANT from an Ada String
function To_VARIANT_From_C (From : Interfaces.C.char_array)
return GNATCOM.Types.VARIANT;
function To_VARIANT_From_Wide_C (From : Interfaces.C.wchar_array)
return GNATCOM.Types.VARIANT;
-- Allocates a BSTR in a new VARIANT from a C String
function To_VARIANT (From : Integer;
VT : GNATCOM.Types.VARTYPE :=
GNATCOM.Types.VT_I4)
return GNATCOM.Types.VARIANT;
-- Creates a VARIANT from an Integer
function To_VARIANT (From : Float) return GNATCOM.Types.VARIANT;
-- Creates a VARIANT from a Float
function To_VARIANT (From : Boolean) return GNATCOM.Types.VARIANT;
-- Creates a VARIANT from a Boolean
function To_VARIANT (From : Ada.Calendar.Time)
return GNATCOM.Types.VARIANT;
-- Creates a VARIANT from an Ada Time type
function To_VARIANT (From : GNATCOM.Types.BSTR;
Copy : Boolean := False)
return GNATCOM.Types.VARIANT;
-- Creates a new VARIANT from a BSTR by either or attaching the BSTR
-- to the VARIANT or attaching a copy of the BSTR
function To_VARIANT (From : GNATCOM.Types.Pointer_To_IUnknown;
AddRef : Boolean := True)
return GNATCOM.Types.VARIANT;
function To_VARIANT (From : GNATCOM.Types.Pointer_To_IDispatch;
AddRef : Boolean := True)
return GNATCOM.Types.VARIANT;
-- Creates a VARIANT from COM Interfaces
function To_VARIANT (From : GNATCOM.Types.Pointer_To_SAFEARRAY;
VT : GNATCOM.Types.VARTYPE)
return GNATCOM.Types.VARIANT;
-- Creates a VARIANT from a SAFEARRAY
function To_Ada (From : GNATCOM.Types.VARIANT;
Clear : Boolean := True)
return String;
function To_Ada_Wide (From : GNATCOM.Types.VARIANT;
Clear : Boolean := True)
return Wide_String;
-- Returns an Ada string from a VARIANT and clears the BSTR in the
-- VARIANT if Clear = TRUE
-- If the contents of the Variant is a VT_NULL a "" is returned
function To_Ada (From : GNATCOM.Types.VARIANT)
return Integer;
function To_Ada (From : GNATCOM.Types.VARIANT)
return Float;
function To_Ada (From : GNATCOM.Types.VARIANT)
return Ada.Calendar.Time;
function To_Ada (From : GNATCOM.Types.VARIANT)
return Boolean;
-- Returns Ada types from VARIANTs
-- TYPE_MISMATCH_ERROR is raised if COM can not convert the contents
-- of the Variant to the requested type.
-- For example, if a variant contains -1,0,"True","False" it can be
-- converted to a boolean, but any other value will raise the
-- exception
function To_C (From : GNATCOM.Types.VARIANT;
Clear : Boolean := True)
return Interfaces.C.char_array;
function To_C_Wide (From : GNATCOM.Types.VARIANT;
Clear : Boolean := True)
return Interfaces.C.wchar_array;
-- Returns a C string from a VARIANT and clears the BSTR in
-- the VARIANT if Clear = True
function To_BSTR (From : GNATCOM.Types.VARIANT;
Copy : Boolean := False)
return GNATCOM.Types.BSTR;
-- Extracts a BSTR from a VARIANT
function To_Pointer_To_IUnknown (From : GNATCOM.Types.VARIANT;
Clear : Boolean := True)
return GNATCOM.Types.Pointer_To_IUnknown;
function To_Pointer_To_IDispatch (From : GNATCOM.Types.VARIANT;
Clear : Boolean := True)
return GNATCOM.Types.Pointer_To_IDispatch;
-- Extract COM interface pointers from a VARIANT
function To_Pointer_To_SAFEARRAY (From : GNATCOM.Types.VARIANT)
return GNATCOM.Types.Pointer_To_SAFEARRAY;
-- Extract a SAFEARRAY from a VARIANT
function To_VARIANT_BYREF (From : System.Address;
VT : GNATCOM.Types.VARTYPE)
return GNATCOM.Types.VARIANT;
function To_VARIANT_BYREF (From : access GNATCOM.Types.BSTR)
return GNATCOM.Types.VARIANT;
function To_VARIANT_BYREF (From : access GNATCOM.Types.VARIANT)
return GNATCOM.Types.VARIANT;
-- Creates a VARIANT containing a reference to an object
generic
type Element is private;
type Pointer_To_Element is access all Element;
function Get_UDT (From : GNATCOM.Types.VARIANT) return Pointer_To_Element;
-- Returns a UDT contained in a Variant
generic
type Element is private;
function Put_UDT
(UDT : access Element;
Lib_ID : in GNATCOM.Types.GUID;
Ver_Maj : in Natural;
Ver_Min : in Natural;
Type_GUID : in GNATCOM.Types.GUID)
return GNATCOM.Types.VARIANT;
-- Places a UDT in to a Variant
generic
type Element is private;
function Put_UDT_By_Index
(UDT : access Element;
Lib_ID : in GNATCOM.Types.GUID;
Ver_Maj : in Natural;
Ver_Min : in Natural;
Index : in Natural)
return GNATCOM.Types.VARIANT;
-- Places a UDT in to a Variant
generic
type Element is private;
function Put_UDT_By_Type_Info
(UDT : access Element;
Type_Info : in GNATCOM.Types.Pointer_To_ITypeInfo)
return GNATCOM.Types.VARIANT;
-- Places a UDT in to a Variant
ARRAY_LOCKED_ERROR : exception;
-- An operation is being attempt on a VARIANT containing a SAFEARRAY
-- that has been locked
INVALID_TYPE_ERROR : exception;
-- An operation is being attempted on an invalid VARIANT, perhaps
-- one that has not been initialized
OVERFLOW_ERROR : exception;
-- A type conversion created an oveflow for the new type
TYPE_MISMATCH_ERROR : exception;
-- VARIANT contents can not be converted to the requested type
end GNATCOM.VARIANT;