The Structures cluster includes wrappers for data structures useful when using the COM technology.
ECOM_ARRAY is a multidimensional, resizable array. It is converted to SAFEARRAY at the COM runtime level. Most languages only support SAFEARRAYs of OLE automation types.
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 the feature
trigger (code: INTEGER)
-- Raise exception with code `code'.
-- See class ECOM_EXCEPTION_CODES for possible values.
The class also has several features that help analyzing exceptions and error codes received from the COM runtime.
-- Original HRESULT.
-- Status code.
-- Facility code.
-- Error message.
Every call to COM should be wrapped into a
rescue clause as follows:
if not retried then
-- Call to COM.
if is_developer_exception then
-- Compare `hresult' to some predefined value
-- and handle various cases,
-- or display a dialog box with an error message
retried := True
ECOM_STRUCTURE is a deferred class which inherits from WEL_STRUCTURE. All wrappers of COM structures inherit from ECOM_STRUCTURE.
ECOM_VARIANT is a wrapper of the VARIANT structure. VARIANT is the Visual Basic equivalent to Eiffel's
This wrapper exposes the feature
-- Variable type. See class ECOM_VAR_TYPE for possible values.
which specifies the actual type of the variant. The class has multiple features for typed access and setting of variables.
-- Value representing the default value of a COM optional argument.
-- Equivalent to an omitted VB argument, or C++ vtMissing, or .NET System.Reflection.Missing.
Many COM Automation servers have routines that take arguments with default values. This is very common, for example, in Microsoft Office applications such as Excel and Word. In Visual Basic, such arguments are optional and, when omitted, the server uses the default value. In languages that cannot omit arguments, a special VARIANT value representing the omitted argument must be passed. EiffelCOM applications can pass missing for this purpose.
For example, the following adds a new workbook to Excel. The default argument tells Excel to decide for itself how many worksheets to put in the new workbook:
workbook := workbooks.add (missing, 0)