Interface Definition Language (IDL)

Overview
Examples Simple Interface Declarations Derived Interfaces Interface Templates Protecting Exposed Commas

Overview

Interfaces are defined using five families of macros:

BOOST_IDL_BEGINxxx — begins an interface definition
BOOST_IDL_ENDxxx — ends an interface definition
BOOST_IDL_EXTENDS — declares a base interface
BOOST_IDL_FNz — declares a non-const member function of arity z
BOOST_IDL_CONST_FNz — declares a const member function of arity z

Examples

Example I: Simple interface declarations.

The definition of an interface name which is not a template and which does not derive from any other interface begins with BOOST_IDL_BEGIN(name) and ends with BOOST_IDL_END(name). Between the invocations of BOOST_IDL_BEGIN and BOOST_IDL_END, the macros BOOST_IDL_FNz and BOOST_IDL_CONST_FNz can be used to declare zero or more member functions.

For example, the following sequence of macro invocations

BOOST_IDL_BEGIN(IPoint)
    BOOST_IDL_CONST_FN0(x, long)
    BOOST_IDL_CONST_FN0(y, long)
    BOOST_IDL_FN1(x, void, long)
    BOOST_IDL_FN1(y, void, long)
BOOST_IDL_END(IPoint)

is equivalent to the pseudocode

interface IPoint {
    long x() const;
    long y() const;
    void x(long);
    void y(long);
}

Example II: Derived interfaces.

An interfaces may be declared to derived from an interface base using BOOST_IDL_EXTENDS(base). For example, the following sequence of macro invocations

BOOST_IDL_BEGIN(ICircle)
    BOOST_IDL_EXTENDS(IPoint)
    BOOST_IDL_CONST_FN0(diameter, long)
    BOOST_IDL_FN1(diameter, void, long)
BOOST_IDL_END(ICircle)

is equivlaent to the pseudocode

interface ICircle : IPoint {
    long diameter() const;
    void diameter(long);
}

Example III: Interface templates.

An interface template name having template arity arity may be defined using the macros BOOST_IDL_BEGIN_TEMPLATE(name, arity) and BOOST_IDL_END_TEMPLATE(name, arity), or using the convenience macros BOOST_IDL_BEGINz(name) and BOOST_IDL_ENDz(name), which have the template arity z hard-wired into the macro name. The keyword template and the template parameter list enclosed in angle brackets must precede the invocation of BOOST_IDL_BEGIN_TEMPLATE or BOOST_IDL_BEGINz.

For example, the following sequence of macro invocations

template<typename T>
BOOST_IDL_BEGIN_TEMPLATE(IStack, 1)
    BOOST_IDL_CONST_FN0(empty, bool)
    BOOST_IDL_FN1(push, void, const T&)
    BOOST_IDL_FN0(pop, void)
    BOOST_IDL_FN0(top, T&)
    BOOST_IDL_CONST_FN0(top, const T&)
BOOST_IDL_END_TEMPLATE(IStack, 1)

is equivalent to the pseudocode

template<typename T>
interface IStack {
    bool empty() const;
    void push(const T&);
    void pop();
    T& top();
    const T& top() const;
};

It could also be rendered using the convenience macros, as follows:

template<typename T>
BOOST_IDL_BEGIN1(IStack)
    BOOST_IDL_CONST_FN0(empty, bool)
    BOOST_IDL_FN1(push, void, const T&)
    BOOST_IDL_FN0(pop, void)
    BOOST_IDL_FN0(top, T&)
    BOOST_IDL_CONST_FN0(top, const T&)
BOOST_IDL_END1(IStack)

Example IV: Protecting exposed commas.

Type expressions containing unprotected commas can confuse the preprocessor; this is a particular problem when defining interface templates. In most such cases, the macro BOOST_IDL_PROTECT can be used to insert an extra set of parentheses. For example, the following pseudocode definition:

template<typename Ch, typename Tr, typename Alloc>
interface INamed {
    std::basic_string<Ch, Tr, Alloc> name() const;
};

can be rendered correctly in the IDL as follows:

template<typename Ch, typename Tr, typename Alloc>
BOOST_IDL_BEGIN3(INamed)
    BOOST_IDL_CONST_FN0(
        name, 
        BOOST_IDL_PROTECT((std::basic_string<Ch, Tr, Alloc>))
    )
BOOST_IDL_END3(INamed)

See BOOST_IDL_PROTECT for a more detailed explanation and some caveats.

Revised 13 Jan, 2005

Sha'arei Tefila, an Orthodox Shul (Synagogue) in Salt Lake City, Utah Chabad Lubavitch of Utah