nmi project AMWA

AMWA DEVELOPERS LIBRARY | Back to Dev Zone

Dodo Reference Manual

Dodo .DOD source files are simply a set of macros

These macros are expanded differently depending on the macro file used, so the same DOD file can produce both a COM API header and a COM wrapper for the related Impl function with a similar name.



Dodo diagram

In some Macro files a lot of the macros are simply null.

Macro Arguments

The arguments passed to Macros can be several lines long (espacially in the case of comments).

Occurences of ( ) parentheses and , commas in the arguments passed to macro have to be escaped with a backslash.

Some macros such as AD_METHOD1 are nested because AD_METHOD1 with 6 arguments invokes AD_XMETHOD1 with an extra argument in the base.mac file, as a result of this, escaped characters in AD_METHOD1 have to be escaped twice, an open paretheses in a comment has to be preceeded by three back slashes \\\(.

A \ (backslash) character immediately before a newline, indicates a continuation line escaped so that it will not appear in the output.

Usage: dodo -f macro_file

Expects input .dod file on standard input, writes the expanded output to standard out.

The macro files also include the base.mac file which contains common definitions.

Some of the macro files are only used once to generate an initial framework for an implementation file, for instance once you have a constructed a .dod file for your interface you can generate a empty implementation with the command:

dodo -m macros/cpp.mac < AAFMyInterface.dod

Comments

The comments for methods and interfaces follow a pretty repetitive format, since they are extracted from the IDL file by the DocJet tool to generate the COMAPI manual it is best to follow the existing style of indentation and line breaks.

The macros subdirectory contains the following different variants:

macros Depends on Used to generate
comh.mac   COM header files ref-impl/src/com-api/CAAF*.h
comc.mac   COM C++ wrapper files, boilerplate code to automatically invoke underlying Impl methods of the same name. ref-impl/src/com-api/CAFF*.cpp
comcx.mac   COM mix-in interface classes
     
h.mac - C++ API header files
cpp.mac - C++ API CPP files
comt.mac - -
cppt.mac - COM unit test implementation files
dod2iid.mac   Strips out the Interface Identifiers
exp.mac - Intermediate Export files for export to other source files
     
frefh.mac * Generates the rolled up header file that lists all the AAF Interfaces:
ref-impl/include/AAF.h
fidl.mac * Generates the IDL version of the above:
ref-impl/include/AAF.idl, AAFPrivate.idl, AAFPlugin.idl
     
idl.mac AAFPluginTypes.dod, AAFTypes.dod AAFPluginTypes.idl, AAFTypes.idl
     
implh.mac AAFRoot.dod ImplAAFRoot.h
implc.mac AAFRoot.dod ImplAAFRoot.cpp

All Dodo directives in the macro file start at the beginning of a line, and start with the '#' character.

Macro Arguments

The arguments passed to a macro are substituted in the body with the notation %n, where n is a digit starting at 1 for the first argument.

Comments

Dodo comment lines begin with #c

Directives

the #import directive will include another macro file

Macro definitions are delimited with

#startm <macro_name> <num_args>
<macro expansion specification line 1>
<macro expansion specification line 2>
...
<macro expansion specification line n>
#endm

Whenever the macro_name(<args>) is encountered in the source file, it will be replaced with the multi-line macro expansion in the output file.

Special Macros

conventionally defined at the top of each dod file

.this-module

expanded to the class or interface name such as C.this-module and Impl.this-module

.parent-module

the parent class for public inheritance at the implementation level, used to aggregate the interfaces at the COM API level by importing the methods of the parent.

Special Rules

  • Any arguments specified within a macro expansion specification using the %n syntax must have numbers that are 1 or greater, and are less than or equal to the num_args value for that macro.
  • Any macro invocation in the input file must be given precisely the number of arguments given in the num_args field of the macro's definition.