define dual-interface

Definition macro

Summary

Creates a new dual COM interface.

Macro call

define [ class-adjectives ] dual-interface interface-name  (superclass)
  [ client-class vtable-client-class-name
  [ :: client-superclass-name ] ; ]
  { typelib-clause 
  | property 
  | function }*
end [dual-interface] [interface-name]

Arguments

class-adjectives

Any Dylan class definition adjective.

interface-name

name_bnf

vtable-client-class-name

name_bnf

typelib-clause

  { uuid uuid; 
  | name name; 
  | documentation documentation;
  | help-file help-file; 
  | help-context help-context; 
  | major-version major-version; 
  | minor-version minor-version; 
  | locale locale;
  }

property

  { [ virtual ] property property-name :: property-type 
          { , option }* ;
  | constant property property-name :: property-type 
           [ = property-value ] { , option }* ;
  }

function

function member-name 
  ( { argument-name :: argument-type, }* )
       => ( [ result-name :: result-type ] )
  { , option }* ;

option

  { name: name 
  | disp-id: disp-id 
  | documentation: documentation 
  | help-context:  help-context 
  }

Library

OLE-Automation

Module

OLE

Description

Used to create a dual interface, with the members being accessible either through a v-table or through IDispatch/Invoke. This macro combines the functionality of define vtable-interface and define dispatch-interface. Typically it is used to define a class that just specifies the interface, with implementations of the interface being defined by subclasses.

The superclass list specifies the class to inherit from. It should be either <simple-dispatch> or another server class defined with define dual-interface or define dispatch-interface.

If another server class is included, the type information for this class inherits the type information from the superclass.

An instance of <dual-type-info> (a subclass of
<vtable-type-info>) is created which is an ITypeInfo interface describing the dual interface.

This value can be fetched by applying the function
type-information to the class or to an instance of the class.

Call function dispatch-type-information to obtain the instance of <disp-type-info> instead.

The clauses of the definition have the same meaning as documented for the define vtable-interface and define dispatch-interface macros. However, compared to define vtable-interface, dispatch interfaces impose several restrictions:

• The vtable-member clause cannot be used. (All member functions will implicitly return a status code.)
• No more than one result value can be returned in addition to the implicit status code.
• The data types for properties, parameters, and return values are restricted to those supported by OLE Automation. (Refer to section 4.8 of the OLE, COM, ActiveX and DBMS library reference.)

  Compared to define dispatch-interface, dual interfaces impose the following restrictions:

• The uuid clause is required.
• The slot clause cannot be used; slots should be defined in a separate implementation subclass.
• Properties should be declared as virtual in an interface class that will use a separate implementation subclass.
• Property types and function parameter and result lists must be explicitly declared instead of defaulting from the function definition. (This implementation limitation is because the types are needed for compile-time generation of v-table functions, not just for the run-time creation of type info data.)
• Do not call exit-invoke or abort in the implementation method for a dual interface member function or property because there will be no condition handler when it is invoked through the v-table.

Example

define dual-interface <IDual> (<simple-dispatch>)
  client-class <C-IDual>;
  uuid "{DC86922A-16C3-11D2-9A67-006097C90313}";
  virtual property foo :: <integer>;
  function bar (a :: <integer>) 
    => (b :: <string>);
end dual-interface <IDual>;

define COM-interface <my-dual> (<IDual>)
  slot foo :: <integer>;
end COM-interface <my-dual>;

define method bar (this :: <my-dual>, a :: <integer>)
               => (result :: <SCODE>, b :: <string>)
  ...
  values($S-OK, ...)
end method bar;

The above defines a class <IDual> which specifies a dual interface, and a subclass <my-dual> which implements a server for it. It also defines a class <C-IDual> for v-table client access, and creates type information describing the interface.

---

OLE, COM, ActiveX and DBMS Reference - 31 MAR 2000