Structures

A Structures cluster includes wrappers for COM structures and additional data structures.

ECOM_ARRAY

ECOM_ARRAY is multidimensional, resizable array.  It is converted to SAFEARRAY at the COM runtime level.  Most languages support only SAFEARRAYs of OLE automation types.

ECOM_EXCEPTION

ECOM_EXCEPTION provides support for triggering and catching exceptions.  According to the COM specification, every feature of a COM interface should return a status code of type HRESULT.  HRESULT is a 32 bit integer.  The COM specification defines possible exception codes and corresponding human-readable descriptions.  

The status code is mapped by the EiffelCOM runtime to Eiffel exceptions.  To raise COM-specific exceptions, the class ECOM_EXCEPTION provides feature trigger:

trigger (code: INTEGER)
      -- Raise exception with code `code'.
      -- See class ECOM_EXCEPTION_CODES for possible values.

The class also has several features that help to interpret exceptions and error codes received from the COM runtime.  

hresult: INTEGER 
       -- Original HRESULT.
   require
       applicable: is_developer_exception

hresult_code: INTEGER 
       -- Status code.
   require
       applicable: is_developer_exception

hresult_facility: INTEGER
       -- Facility code.
   require
       applicable: is_developer_exception

hresult_message: STRING
       -- Error message.
   require
       applicable: is_developer_exception

 Every call to the COM layer should be wrapped into the rescue-clause as following:

some_feature is
   local
      retried: BOOLEAN
      ...
   do
        if not retried then
            -- Call to COM.
        end
   rescue
        if is_developer_exception then
            -- Compare `hresult' to some predefined value
            -- and handle various cases,
            -- or display a dialog box with an error message
            -- `hresult_message'.
        end
        retried := True
        retry
   end

 ECOM_STRUCTURE

ECOM_STRUCTURE is a deferred class, which inherit from WEL_STRUCTURE. All wrappers of COM structures inherit from ECOM_STRUCTURE.  

ECOM_VARIANT

ECOM_VARIANT is a wrapper of the VARIANT structure.  VARIANT is Visual Basic equivalent of ANY.  In Visual Basic variable of any type conforms to VARIANT.  Since semantics and binary layout of Visual Basic is different from those of Eiffel, there is no simple way to map VARIANT to ANY. Instead, we created a simple wrapper of the VARIANT structure.

It has the feature 

   variable_type: INTEGER
         -- Variable type. See class ECOM_VAR_TYPE for possible values.

 which specifies the type of the wrapped variable. The class has multiple feature for typed access and setting of variables.