ON Semiconductor - READING IDL FILES

Introduction | Core Component | Communications | Additional Topics | Reference Guide




Reference Guide Reading IDL Files IDL files look similar to C++ (and to some extent C) and contain many of the same keywords and data types. When IDL files are compiled, they generate the header files needed for C++ development, and type library (.tlb) files needed by languages such as Visual Basic and Delphi. ARK DLLs have their type libraries compiled directly into them to reduce the number of files that need to be distributed. This guide assumes that the reader understands C/C++ keywords and data types and the terms that are defined in the introduction to the ARK Tutorial. An example interface IValue : IDispatch { [propget, helpstring("The name of the value")] HRESULT Name([out, retval] BSTR* rval); [propput, helpstring("The integer value")] HRESULT Value([in] int value); [propget, helpstring("The integer value")] HRESULT Value([out, retval] int* rval); }; The rest of this page describes the interesting parts of this IDL example, plus a few additional keywords and data types. interface ICore : IDispatch This line declares the interface, ICore, to be based on another interface called IDispatch. IDispatch is a standard COM interface that all interfaces derive from that support scripting. Languages such as VBScript, Matlab, VBA and to some degree Visual Basic only fully support interfaces that are based on IDispatch. All of the ARK interfaces are based on either other ARK interfaces or IDispatch, and are thus usable from most languages that support COM. HRESULT HRESULT is the return value type returned from COM properties and methods. It is typecast to a long (32-bit integer), and 0 indicates success and a non-zero value indicates that an error occurred. Visual Basic automatically interprets the HRESULT value and triggers an exception if it is non-zero. COM objects can support a standard interface called ISupportsErrorInfo that can be used to obtain more detailed information about an error. Those ARK classes that can raise exceptions support ISupportsErrorInfo. propget and propput propget and propput are attributes that identify properties. In IDL "get" operations are declared separately from "put" operations. If only a "get" operation is defined then the property is read-only. The Name property in the above example code is read-only, while Value is read/write. In C++, the propget operations are prefixed with get_, i.e. get_Name. Similarly, the propput operations are prefixed with put_. In Visual Basic, properties are used as follows: Sub ChangeValue(num as IValue) num.Value = 15 Debug.Print num.Name & " has been changed to " & num.Value & "." End Sub When passing an object to a propput operation in Visual Basic, the Set keyword is used. helpstring Help strings are encoded into the type library that is produced when an IDL file is compiled. In Visual Basic, these strings appear in the Object Browser and provide a quick description of the property or method. [in], [in, out], and [out, retval] A parameter with an [in] attribute before it is an input to the property or method. [in, out] indicates that the parameter is both an input and an output, that is, it can be changed by the property or method. [out, retval] identifies output parameters. Parameters that have the retval attribute become return values in languages such as Visual Basic (recall that in VB the HRESULT is handled implicitly). These attributes do not have an effect on how these parameters are handled in C++; it is the type that counts. [id(0)] id(0) prefixes the default method or property in an interface, if there is one. [restricted] In the actual ArkItfs.idl file, some of the interface contain [restricted] properties and methods. These properties and methods are used internally by other ARK components and are marked "restricted" so they do not clutter up the type library. They do not need to be used by ARK-based applications. BSTR BSTR is the COM string data type. In Visual Basic, this type becomes the built in String data type. In C++, special API functions must be used to manipulate BSTRs. Users of the Active Template Library (ATL) included with Visual C++ 6 have an easier time working with BSTRs with the help of the CComBSTR smart pointer. VARIANT VARIANT is another COM data type that is similar in functionality to the VB Variant data type. VARIANTs can have values of different data types assigned to them, and the type can be determined at run time. In ARK methods where a parameter can be more than one type, such as a string or an integer, a VARIANT is used. Manipulating VARIANTs in C++ requires special API functions. VARIANT_BOOL VARIANT_BOOL is the COM boolean type. This type becomes the native Boolean type in Visual Basic. In C++, the macros VARIANT_TRUE and VARIANT_FALSE define the values that should be used for true and false, respectively. SAFEARRAY SAFEARRAY is the COM array type. SAFEARRAYs appear as native arrays in Visual Basic and also require special API functions to be used in C++.