AAF Developer Suppport Logo
 
Originally prepared by Tim Bingham, May 2001. Acknowledgement due to Josh Goldman who prepared the description of the directories, to Alexey Kharkevich who provided the description of the Unix makefile targets, Oliver Morgan who pointed out the make -> Anti-Virus workaround and to Tom Ransdell and Jeff Bedell who helped with numerous questions. Current maintainer is Simon Carter.

How do I get started with the AAF project at SourceForge ?

SourceForge is at http://sourceforge.net/ The SourceForge Project Info page for AAF is http://sourceforge.net/projects/aaf/ and the Developer Support Webpages are at http://aaf.sourceforge.net

How do I obtain and build the AAF SDK ?

The following notes describe "Anonymous CVS Access" to the AAF source code. Such access is read only. For read/write access please see How do I become an AAF developer ?. This note describes how to build the reference implementation only. Some of the AAF source files are automatically generated, the process described here uses pre-generated versions of those source files that have been checked into CVS. See How do I regenerate the generated source files ? regenerating the generated source files.

How do I obtain and build the AAF SDK on Windows NT/Windows 2000 ?

Using the WinCvs client (available from http://www.wincvs.org)
Admin -> Preferences ... -> Enter the CVSROOT -> :pserver:anonymous@aaf.cvs.sourceforge.net:/cvsroot/aaf
Admin -> Preferences ... -> Authentication -> "passwd" file on the cvs server
Admin -> Login ... -> <no password - just click OK>
Create -> Checkout module -> Enter the module name and path on the server -> AAFWinSDK
Open AAF/AAFWinSDK/AAFWinSDK.dsw with Visual Studio,
click on the FileView tab in the workspace view then right click on "Everything files" and select "Build".

How do I obtain and build the AAF SDK on Linux ?

$ export CVSROOT=:pserver:anonymous@aaf.cvs.sourceforge.net:/cvsroot/aaf
$ cvs login (Logging in to anonymous@aaf.cvs.sourceforge.net) CVS password: <no password - just hit return>
$ cvs checkout AAFLinuxSDK ...
$ cd AAF
$ make ...
$

How do I obtain and build the AAF SDK on Macintosh ?


Use the MacCvsPro client (available from maccvs.org)
Refer to the AAF web page 'Download MacOS'

OK, I've built the thing, what do I do now ?

First, try running the module test program.
This test is self validating if you see the following output then you probably have a correct build.
Tests Run: 119 Passed: 119 Failed: 0 Not Implemented: 0 Partial Success: 0The module test program is ...
Windows COMMODAAF.EXE
Macintosh COMMODAAF (PPC)
Linux ComModAAF Next, try running the example programs.
Examine the source code and project settings (GNUmakefile) for the examples.
This will show you how to get started implementing AAF in your own applications.

How do I become an AAF developer ?

Please contact Brad Gilmer or Oliver Morgan

OK, I'm a developer. How do I obtain and build the AAF SDK ?

How do I make checkins ?

What's ssh ?

SSH stands for Secure SHell. see this CERT paper
Note that you can't easily use the CVS workspace or sandbox you checked out anonymously with your developer account because all the CVS directories embedded in your checked out workspace contain a Root file specifing the original checkout parameters.
Although this can be overriden by explicitly forcing a new access method with each command
cvs -d :ext:<developer name>@aaf.cvs.sourceforge.net:/cvsroot/aaf ...
It's much more sanitary to do a new clean checkout.
Refer to the AAF web pages Using CVS/ssh on Windows or Using CVS/ssh on MacOS

How do I use CVS/ssh on Linux ?


$ export CVSROOT=:ext:<developer name>@aaf.cvs.sourceforge.net:/cvsroot/aaf
$ export CVS_RSH=ssh ...
$ cvs checkout -rRC1 AAFLinuxSDK
<developer name>@aaf.cvs.sourceforge.net's password: <enter your password>
cvs server: Updating AAF ...

$ cvs commit -m"Add new defrobnicate() member." frobber.cpp
<developer name>@aaf.cvs.sourceforge.net's password: <enter your password>
...
$ .

Help - Redhat Linux 6.1 doesn't come with ssh pre-installed !

Unlike Redhat 7.x. you have to install ssh from an RPM. Note that SSH 2.0 can be used despite notes to the contrary on SourceForge that state only SSH 1.5 is supported.

I get errors first time I use SSH access to SourceForge what's going on ?

SourceForge does not create a home directory for you until you attempt a real login to the server (as opposed to a CVS session) with name and password:
ssh -l <myname> aaf.cvs.sourceforge.net

My company's firewall is preventing me accessing sourceforge what do I need to do ?

see tha AAF web page Firewalls and SSH

What kinds of changes are allowed ?

You may add new interfaces.

What kinds of change are NOT allowed ?

You may not change existing interfaces. Here interface means interface in the COM sense. e.g. IAAFEssenceAccess as defined in AAF.idl You may not change existing interfaces as this would break binary compatibility. Binary compatibility is the ability of an existing explication (perhaps one developed with an older aafdll) to work correctly with a newer aafdll. In the newer aafdll interfaces must not have changed otherwise code in the old application will not work correctly. Newer applications can take advantage of new interfaces in in the new aafdll that will simply be ignored by older applications. Another advantage of maintaining binary compatibility is that bugs can be fixed "at run time". That is, if an older aafdll contains bugs, a newer one with the bugs fixed can only be substituted safely provided that no interfaces have been changed.

How do I add a new interface ?

You'll need to speak to "dodo" :-)

How are changes approved ?

The AAF engineering committee is responsible for defining this process.

What are the rules for interface design. I notice that there are no parameters of built-in type, such as "int" ?

What platforms are supported ?

As of RC1 (the initial sources made available on SourceForge April 17, 2001) the supported platforms are (in no particular order)
The above platforms are those on which the AAF project is known to build and run correctly.

Will the SDK compile with gcc 3.0 ?

No yet, Note gcc versions prior to 3.0 don't have support for wide streams (wostreams). I discovered this problem in gcc version 2.96. no-one has yet made any effort to fix this problem.
gcc 2.96 also has problems with basic_string<wchar_t>::c_str(). 3.0 fixes that as well. (It looks like std lib string support was completely redone in 3.0)

What's the earliest MacOS that the SDK will work on ?

MacOS 8.6 is the earliest on which we've tested RC1.

What about Macintosh OSX ?

One dependency here is on a Carbonized version of the Microsoft Structured Storage system extension. This is not yet available from Microsoft.

Does AAF build with CodeWarrior 6.0 ?

Not quite there are syill a couple of outstanding Link problems 31/7/01.

What about Windows 95, Windows 98 and Windows ME ?

For brevity, let's refer collectively to Windows 95, Windows 98 and Windows ME as consumer versions of Windows.
We have not tested building and running AAF on consumer versions Windows as we have on the "supported" platforms. However AAF does build and run on consumer versions of Windows after some minor modifications to the Visual C++ projects.
To be able to build and run AAF on a consumer version of Windows you must change the C/C++ settings in the following projects ...

./AAFWinSDK/ref-impl/aaflib/AAFLIB.dsp
./AAFWinSDK/ref-impl/Om/Om.dsp
./AAFWinSDK/DevUtils/Dump/Dump.dsp

Go to Settings -> C/C++ -> General -> Preprocessor Definitions and add -DNO_W32_WFOPEN (make sure "Settings for:" says "All Configurations")
If you wish to create a single aafdll that runs on consumer versions of Windows and on Windows Nt/2000, then different changes would be required.

What other tools will I need besides a C++ compiler ?

GNU make version 3.77
Perl version 5.002 For "Anonymous CVS Access" to the AAF project on SourceForge you need a CVS client. We suggest the following clients Operating System CVS Client Available from Windows NT/Windows 2000 WinCvs http://www.wincvs.org/ Macintosh Mac OS 8.6/9.0 MacCVS Pro http://www.maccvs.org/ Note that there are several other Macintosh CVS clients with similar sounding names. On Linux we suggest the the cvs(1) command. For brevity, let's refer collectively to Windows 95, Windows 98 and Windows ME as consumer versions of Windows. We have not tested building and running AAF on consumer versions Windows as we have the above platforms. However AAF does build and run on consumer versions of Windows after some minor source code modifications. To be able to build and run AAF on a consumer version of Windows you must make the following changes. In the following files change the implementation of wfopen() so that the non-Windows code is compiled even though you are compiling on Windows 95 or 98. This is necessary because, although _wfopen() exists and is implemented in the W32 API on Windows 95 and 98, it always fails. ./ref-impl/aaflib/aaflib.cpp ./ref-impl/src/OM/OMUtilities.cpp If you want to use the low-level file dumper on Windows 95 or 98 you'll need to make a similar change in the following file ... ./DevUtils/Dump/dump.cpp If you wish to create a single aafdll that runs on consumer versions of Windows and on Windows NT/2000, different changes would be required.

What about Red Hat Linux version 7.1 ?

As of RC1 (the initial sources made available on SourceForge April 17, 2001) AAF does not build on Red Hat Linux version 7.1. [Note to FAQ maintainer, I've since ported AAF to Red Hat Linux version 7.1 and checked the changes into SourceForge. I have notes on what I did. There are still a few warnings. I didn't bother getting the AAF/OMF converter to compile since there's no version of OMF for Linux yet. Also remaining to be done are implementations of the functions AafPos2AnsiPos() and AnsiPos2AafPos() in ref-impl/plugins/CAAFEssenceFileStream.cpp]

When I open up AAFWinSDK.dsw I get a message "Unable to connect to source code control project AAFStandardCodecs". How can I get rid of this ?

What's happening is that you have Visual Source Safe (Microsoft's source control product) installed as well as Visual Studio, Visual Source Safe is insisting on looking for a source control project even though none exists.
You can get rid of the message temporarily (the setting is saved in AAFWinSDK.opt) by answering "no" to the question "Do you wish to attempt this connection in future sessions ?" To get rid of the message permanently, change the value of the registry key HKEY_CURRENT_USER\Software\Microsoft\DevStudio\6.0\Source Control\Disabled from 0 to 1. This part of the registry contains all the settings from the Visual Studio -> Tools -> Options ... -> Source Contol dialog. Unfortunately it seems that there's no UI checkbox to disable Visual Studio/Visual Source Safe integration. For more details see http://support.microsoft.com/support/kb/articles/Q236/3/99.ASP

Where can I find out more about CVS ?

There's information to help you get started on SourceForge
Fogel CVS book One book CVS I have found useful is Karl Franz Fogel, "OpenSource Development with CVS", November 1999, The Coriolis Group, ISBN: 1576104907. Most of this is available online at http://cvsbook.red-bean.com/

There's a catalog of CVS documentation at http://www.cvshome.org/docs/ I've found the PDF version of the "the Cederqvist" - the "official" CVS manual by Per Cederqvist most useful. There's also the book by Per Cederqvist "Version Management With CVS", December 2000, iUniverse.com, ISBN: 0595149219. I'm not sure how this differs from the stuff by Cederqvist that's available online.

My line endings are messed up. What's going on ?

CVS rules for text files. - files are stored in the CVS repository with Unix line endings. - the CVS client converts the CVS repository line endings to/from the endings appropriate to your platform when you commit/checkout the file. - the conversions performed by the CVS client are dumb in that they expect the input file to have the correct line endings for their platform i.e. they convert a valid file rather than fix up an invalid one. So if the file starts out with the wrong line endings for the CVS client that is used to check it in, then the file will get mangled. e.g. checking in a file with Windows line endings using a Macintosh CVS client will probably transform "\r\n" to "\n\n", if you check this file out you'll see an extra blank line between every existing line. Adding a text file - before you add a text file make sure the file has the line endings appropriate to the platform from which you are adding the file. Fixing a file - checkout the file, convert the line ending to those appropriate to your platform (remembering that they may have been mangled) and then check it back in. CVS will do the right thing from then on. Line ending conventions Unix \n Windows \r \n Macintosh \r

My binary file is messed up. What's going on ?

Chances are the file isn't correctly tagged as binary in CVS, check the CVS/Entries file for the current directory files that were orginally added as binary have the -kb flag against them.

I get the error message "Connection refused" from Sourceforge ?

Check you have a CVS_RSH environment variable correctly set to SSH

How can I add a MacOS alias (symbolic link or shortcut) to CVS ?

Use MacCVSpro, it seems to be smart enough to figure out the special type and convert it to Apple single.

What are the pieces of the AAF project ?

The AAF project consists of the following pieces

What are the steps in the process of building an AAF SDK from the AAF project ?

These are all of the steps. Step 1 isn't necessary unless you've changed the dodo inputs files. To avoid everyone having to do step 1 the generated files are checked in to CVS. Note that regenerating the source files isn't done (by default) by the projects or makefile.

How do I regenerate the generated source files ?

To regenerate the generated files you need to "cd dodo; make". There is one caveat which only applies if you want to regenerate the generated source files, for example, if you are adding a new interface to the AAF API. Up to date generated source files as well as the files from which they are derived are checked into CVS. However, when you download them from CVS, "make" may think that the generated files need to be regenerated (since the files get modification times corresponding to the time that the working copy is created and not when the file was checked in to CVS).

Why does "cvs checkout" take so long ?

If you are using a slow (e.g. 56K or ISDN) link consider setting the CVS compression option cvs -z3 (tune the compression level for best results), compression is tradeoff between the horsepower available at each end of the link compared to the thickness of the pipe.

Make sure you are checking out the platform specific module such as AAFWinSDK rather than the default AAF module which contains the entire source tree.

For the time being if you just want the pre-built SDK for you platform you'll also get the source code needed to build it.
After the first checkout a cvs update -d command will be considerably faster since it only needs to retrieve the changed files and new directories.

Modules still need to be defined for - pre-built SDKs on Windows, Macintosh and Unix (these will also be made available as "released files").
These modules would be checked out by those wishing only to use the AAF SDK.
These users could also be satisfied by pre-built SDKs in the form of "released file packages". - everything needed to be a reference implementation developer (i.e. make a change, such as a bug fix to some existing code.)
These modules would be checked out by those wishing to enhance the AAF SDK and by those who wish to port the SDK to a new platform. - everything needed to add new interfaces to AAF. This would include the dodo tool. This would be done by those wishing to extend the set of interfaces supported by AAF.

I just want to use the AAF SDK, why do I have to build it first ?

Because CVS modules and/or "released file packages" are not yet available.

What is dodo ?

dodo is a tool used to generate some of the AAF source files. It allows multiple output files, that must be kept in sync with each other, to be generated from a single source. If you need to make a change that has an impact in more than one place you need only change the dodo input file. The original idea for dodo was that all the files it generated would eventually be maintained by hand at which point dodo could be made extinct. Hence the name "dodo". However, dodo was useful enough that it became used for code that is always generated, meaning that dodo must be kept alive.

Why does making dodo on Win2K fail with UNAME := $(shell uname) ?

The above is a GNUmake specific construct (It means run the uname command in the shell and put the output in the make symbol UNAME). You need GNUmake to use this makefile. GNUmake should be listed as one of the prerequisites for building Dodo on Windows.
Since the generated files are checked in to SourceForge you don't need to run dodo unless you are adding a new interface (you aren't allowed to change existing interfaces) or changing the generated code (in a compatible way).

I get the following error from CodeWarrior when building from scratch. Error : ### Error: Out of memory ### Link Error : Link failed.

I've seen this error too but could never track it down. It seems only to happen when compiling and linking from scratch and seems also to be related to the amount of memory allocated to CodeWarrior (oddly enough allocating more memory seemed to cause it more often). The error goes away if you try again.

I get an out of memory error from CodeWarrior 6 when building ModuleTests/CAAFDictionaryTest.cpp

This test does #include files like AAFStoredObjectIDs.h, AAFTypeDefUIDs.h and AAFClassDefUIDs.h which do a lot of macro expansion via AAFMetaDictionary.h it seems to need more than 128MB for this !

When I build on Macintosh I get warnings. What's the house style guide say on the acceptability of Warnings ?

These warnings should be cleaned up, most are unused argument errors but some could indicate more serious problems. The intent is that warnings are not acceptable and that the compiler should be set to the highest level of warnings as is practicable, if possible the compiler should be set to treat all warnings as errors. For gcc this means "-Wall -Werror".

When I build on Irix I get the following error. What's going on?

"../../include/OM/OMContainerElement.h", line 36: error(1020): identifier "typename" is undefined
You are using the wrong compiler (probably "CC -o32") this compiler is so old it doesn't recognize the "typename" keyword. Use "CC -n32" or gcc instead.

On Linux the default make at the top level doesn't descend all the branches, it only seems to build in ref-impl. Is this correct ?

Yes, this is correct for the default make file target. The default target (make with no arguments) is the reference implementation libraries. There are a number of other targets in the makefile. Here's an overview of the makefile targets.
To build AAF reference implementation libraries type: make
Now you have to install libraries and header files to create AAF SDK to use with your applications:
make install or make install AAFSDK=/home/user/New_AAF_SDK
You can do 'make install' without doing 'make' first. If 'make install' cannot find libraries to install it will build them.
With SDK created you now can build applications. To build applications distributed with the AAF SDK you can do:
make test
make examples
make utilities
make devutils
or make everything
If make cannot find installed AAF SDK it will build (if necessary) and install the SDK before building applications.
Binaries are placed in the SDK's bin directory. Do not forget that if you use install directory other than default you have to specify it:
make everything AAFSDK=/home/user/AAF_2001

How about cleaning up ?

make clean will remove: all the intermediate files (like .o for), libraries (except installed SDK libraries), and applications (tests, examples, utilities).
To remove SDK do make uninstall which removes all the installed libraries and header files. Again, don't forget that you may need to use: make clean AAFSDK=/usr/local/aaf make uninstall AAFSDK=/usr/local/aaf

What about running dodo ?

Dodo is utility to generate COM interfaces. By default all the generated files are already there and do not get touched by commands mentioned above. If you want to remove generated files along with compiled files do: make realclean 'make realclean' does 'make uninstall', 'make clean' and then removes all the generated files created by the dodo tool. Want to skip 'unistall' and 'clean'? Do: cd dodo; make realclean With generated files missing the next try to build the SDK ('make') will launch dodo to generate them. If you want just generate files without building anything do: cd dodo; make

When building on Linux I get errors because the directory "AAFi686LinuxSDK/g++/bin/debug/" does not exist. What's going on ?

Most likely you are trying to make in the examples directory before running make install at the top level to create the target directories.

What are the major components of the AAF architecture ?

What's the run time architecture ?

You link your application to a small static library aaflib which exports a small number of entry points, such as AAFFileOpenExistingRead().
At run time, code in aaflib dynamically loads aafdll, the actual guts of the AAF reference implementation, and resolves these symbols.
You must also link your application to aafiid a static library that defines the IIDs (Interface identifiers) for the AAF interfaces.

What are the libraries called and where is their code ?

The actual library files have names that vary across platforms. The platform specific names are given in the table below. To refer to a library in a platform independent way I've used names such as aaflib, aafiid and aafdll.
Library Source Description   Windows Macintosh Unix Library
aaflib ref-impl/aaflib static stub library Debug AAFD.LIB AAFLIB (Debug) libaaflib.a
Release AAF.LIB AAFLIB libaaflib.a
aafiid ref-impl/aafiid interface identifiers Debug AAFIIDD.LIB AAFIIDD.LIB libaafiid.a
Release AAFIID.LIB AAFIID.LIB libaafiid.a
aafdll ref-impl/src the AAF reference implementation Debug AAFCOAPI.DLL AAFCOAPI.DLL (PPC)Dbg libcom-api.so
Release AAFCOAPI.DLL AAFCOAPI.DLL (PPC) libcom-api.so
omf OMF/Include the OMF toolkit used by the OMF-AAF converter        
  omfToolkit.dll libOMFANSIC.a libOMFI.a

What are AAFINTP.DLL and AAFPGAPI.DLL ?

AAFINTP.DLL is an example interpolator plugin and AAFPGAPI.DLL is an example essence codec plugin (AIFC, CDCI, WAVE and JPEG codecs). The AAFPGAPI.DLL also contains the external essence container code as well as the essence data stream helper class. If future it would be a good idea to move the essence data helper class into "aafdll" (inside the AAF essence access class).

What's all that funny stuff like "@mfunc" and "@rdesc" in the comments of the source files in ref-impl/src/OM and ref-impl/include/OM ?

These are special comments recognized by AutoDuck (AutoDuck is Freeware by Eric Artzt). AutoDuck extracts the comments and produces documentation in a variety of formats. While AutoDuck is not particularly smart about C++ (e.g. it gets confused about overloaded functions) the hyperlinked html output is very useful.

Where can I get Autoduck from ?

try http://www.devstuff.com/utils.htm note there are some older versions around that don't do HTML

OK, where can I get the html ?

Run the script ref-impl/doc/OM/makedocs.ksh. Note that this script expects that you already have Autoduck (AFAIK only available for Windows) and that documentation only for the Object Manager (ref-impl/src/OM and ref-impl/include/OM) will be generated.

What do I need to port AAF to a new platform ?

Don't I need an implementation of COM ?

No.

Are you sure I don't I need an implementation of COM ?

Yes, we're sure.

How is the Microsoft COM stuff distributed for Irix & Linux - it seems to miraculously work, is there a binary lib tucked away in the Distribution ?

No it really is a miracle :-)

OK. So what C++ features does the code use and which does it avoid ?

Features we use Features we have avoided

I thought the AAF code was supposed to be portable, why does the code contain references to IStorage and IStream ? Aren't those Windows specific things ?

AAF is portable, however it does depend on Microsoft Structured Storage. IStorage and IStream are interfaces with implementations in Microsoft Structured Storage. Implementations of Microsoft Structured Storage for Windows and Macintosh are available directly from Microsoft and are included (headers and binaries) with AAF. On other platforms it is possible to licence the source code for the Structured Storage reference implementation from Microsoft. Header files and binaries for Linux and Irix are included.

Why does the Object Manager (ref-impl/src/OM and ref-impl/include/OM) depend on <iostream.h> ?

The release build does not. The debug build does. The default configuration for the debug build defines OM_DEBUG which enables run-time assertion checking. If an assertion fails information about the failing assertion is written to "omlog" an instance of class OMOStream. The distributed version of OMOStream is implemented using <iostream.h> (only four functions in OMOStream.cpp). If you don't have (or don't want to use) <iostream.h> you can either reimplement the four functions in OMOStream.cpp or change the body of function reportAssertionViolation() in OMAssertions.cpp to do something different.

Why does it say "This Project Has Not Released Any Files" on https://sourceforge.net/projects/aaf/, I thought that all of the source for AAF had been released ?

Here "released files" refers to the output of a project, in the form of "file packages" or "tarballs") ready for use by others. The SourceForge AAF project has not yet released any file packages these will probably be in the form of pre-built AAF SDKs for various platforms

What are the TRACE(), PRECONDITION(), POSTCONDITION() and ASSERT() calls in the Object Manager (ref-impl/src/OM and ref-impl/include/OM) ?

The macros support the use of design and programming by contract. See Bertrand Meyer, "Object-Oriented Software Construction, 2nd Edition", March, 2000, Prentice Hall, ISBN: 0136291554

What are each of the directories for ?

Here's a brief guide to the AAF Source Tree, focusing on where to find useful bits of information.

AAFWinSDK

Windows project files and default location for compiles and links (Windows platform only)

bin

Obsolete

DevUtils

Utilities useful to AAF Developers.
There's only one of these, a low-level dumper that helps diagnose file format problems.

doc

Currently obsolete, will have doc files

dodo

dodo is a tool we use to generate our header files.
This directory contains the dodo input file (*.dod). The dodo input files use macros defined in *.mac files in the macros directory. The comments in the *.dod files end up in the API reference document.

examples

Useful examples and some useful dump utilities meta Spreadsheet that defines the AAF object model, used to generate the AAFMetaDictionary.h file and the dictionary stored in the AAF file. (see ref-impl/src/impl for definitions used by the reference implementation for builtins)

omf

OMF toolkit headers and libraries for the OMF converter

ref-impl

Sources for the Com interfaces and the implementation code.

ref-impl/aafiid

ref-impl/aaflib

ref-impl/bld_cfg

ref-impl/include

Contains the .idl and .h files used by the implementation (including those exported to AAF clients). The top-level include directory has the include files that are not generated from .idl files.
AAFClassDefsUIDs.h defines the macros for defining the symbols and AUIDs for the stored classes, but does not contain the list of symbols and the AUIDs. The symbols for a class ID is in the format kAAFClassID_<class-name> However, the implementation code uses some shortened names for these symbols and AAFClassDefsUIDs.h defines symbols with the longer name. In general, the following abbreviations are used
Abbreviated form Long form
Def Definition Object
IntObj InterchangeObject
ObjRef ObjectReference
Int Integer
In addition, there are a few symbols defined for multiple spellings (UNIX and Unix, EdgeCode and Edgecode)
AAFPropertyDefs.h defines the macros for defining AUIDs for property ID and AAFPropertyIDs.h invokes the macros, but neither contains the symbol and the AUID defined for each property. The symbol for a property is in the format kAAFPropID_<class-name>_<property-name> with the added complication that the class-name used is the modified short name used in the code.

ref-impl/include/com-api

Contains the .idl files for the Com interfaces AAF.idl defines the interfaces and methods and AAFTypes.idl defines the types ref-impl/include/om Contains the header files used internally by AAF data manager for the AAF object manager

ref-impl/include/ref-api

Contains the .h files generated from the .idl files and private .h files used by the AAF data manager

ref-impl/libjpeg

Contains jpeg source code used by the JPEG codecs with the CDCI format.

ref-impl/plugins

Contains the source code used by the plugins provided with the reference implementation. These plugins are AIFC codec, JPEG codec, WAVE codec, Interpolator plugin, Plugin manager code

ref-impl/src

Contains the source code for the reference implementation

ref-impl/src/com-api

Contains the source code for the Com interfaces. The top-level directory contains the .cpp and .h file for each Com interface. CAAFAIFCDescriptor.cpp contains the source code associated with the AAFAIFCDescriptor class. In general the methods in the Com interfaces call methods of the same name in the implementation object. The .h files contain the information about which interfaces an implementation object supports. In general, for Com objects that are associated with AAF Specification classes, the implementation object will support the Com interface associated with the stored class and the Com interfaces associated with the parent class of the stored class.
This is indicated by the lines that start the class definition in the .h file.
For example, the AAFFiller stored class inherits from the AAFSegment class class CAAFFiller : public IAAFFiller, public CAAFSegment In addition, some implementation objects support additional interfaces.
For example, the implementation class associated with the AAFMasterMob class also supports the IAAFSearchSource interface.
This is shown by the following lines in the CAAFMasterMob.h file: class CAAFMasterMob : public IAAFMasterMob, public IAAFSearchSource, public CAAFMob

ref-impl/src/com-api/com-dll

Contains the code managing loading the AAF .dll and creating Com objects.

ref-impl/src/impl

Contains the .cpp and .h files that define the implementation objects.
The Impl<class-name>.cpp contains the body of the code.
The Impl<lclass-name>.h files contains the header and specifies the actual datatypes used by the implementation for builtin properties.
These types should match the ones specified in the meta directory and in the metadictionary.h file. The property datatypes are specified in the end of the .h file in under the private label.
The datatypes are specified in the underlying object manager type with the typedef name of the property datatype name.
For example, ImplAAFPulldown.h specifies the following properties and types: OMStrongReferenceProperty<ImplAAFSegment> _inputSegment;
OMFixedSizeProperty<aafPulldownKind_t> _pulldownKind;
OMFixedSizeProperty<aafPulldownDir_t> _pulldownDirection;
OMFixedSizeProperty<aafPhaseFrame_t>_phaseFrame; And in ImpleAAFMobSlot.h, the following properties are listed: OMWideStringProperty _name;
OMFixedSizeProperty<aafUInt32> _trackID;
OMFixedSizeProperty<aafUInt32> _physicalTrackNum;
OMStrongReferenceProperty<ImplAAFSegment> _segment;

ref-impl/src/om

Contains the source for the AAF object manager

test

Contains the test files

test/com/ComModTestAAF

Contains the module tests. This contains the module test test bed. To run individual module tests, specify the class names as command line parameters.

test/com/ComMobTestAAF/ModuleTests

Contains the individual module tests. This contains usage code of the methods in each Com interface.
In general, the examples directory contains more useful example usage, but if a method is not used in any example, the module test provides at least a minimal usage example.

test/com/CreateSequence

Contains tests of the sequence and composition mob

test/com/EssenceAccess

Contains test of the EssenceAccess interfaces Utilities aafOMF conversion utility.

I get the following error when I try to run one of the test programs. What's wrong ?

Attempting to load the AAF dll...FAILED! RESULT = -2147024770 (0x8007007e) The specified module could not be found. The directory containing "aafdll" is not in your PATH (on Unix LD_LIBRARY_PATH).

When I run the module tests AAFEssenceAccess fails. What's wrong ?

The EssenceAccess test is looking for the file Laser.wav in the current directory. Either run the module tests from the AAFWinSDK/Test/com/ComModTestAAF directory or copy AAFWinSDK/Test/com/ComModTestAAF/Laser.wav to your current directory.

I've copied Laser.wav to my current directory and the test still fails. What's going on ?

Make sure you're not using a Macintosh version of Laser.wav on another platform. macintosh binary files are encoded for CVS.

Are there any File icons for AAF files - eg Mac BNDL and Win32 equivalent ?

No, not at present.

What is AAFPersonnelExtension.DLL ?

This dll is part of an example that shows how to extend AAF. AAF is extended using plugins. The example extension includes "personnel" meta-data, AAFPersonnelExtension.DLL is the example extension plugin.

Why doesn't the OMF to AAF converter build on Linux ?

A version of the OMF library needs to be built for Linux.

Why does it say "This project has no CVS history." for AAF. I thought that you checked in all of the RC1 files with their revision history ?

The AAF CVS repository on SourceForge does indeed contain a revision history for each file. The message is referring to the file /cvsroot/aaf/CVSROOT/history which, if present, records a history of repository activity (as opposed to activity relating to a particular file within the repository). It appears that repository history is disabled for most if not all projects on SourceForge since many display the message "This project has no CVS history."

Are the OMF libraries incorporated in to aafdll or is it an optional plugin ?

Neither, the OMFI library is only used by the AAf/OMF converter utility.

What's the absolute minumum what the user has to have in order to build/run an application that uses AAF ?

Look at the makefile and or projects for one of the example programs. I've a feeling that this question wouldn't be asked if ready-built SDKs were made available on SourceForge. To see what went onto previous SDKs look at the installers for older versions of the SDK which should still be availabel on the AAF Associatiuon ftp site.

How did you import the binary files for the Mac files to CVS with resource forks ?

How are they encoded ?

I created the entire AAF CVS tree for all platforms on Linux using files exported from our ClearCase configuration management system (the export process ran on SGI Irix). ClearCase (plus Xinet and some Avid extensions) stores, in addition to the data fork, the resource fork and finder information for Macintosh files. Macintosh CVS clients all recognize some form of encoding for binary files they check in or out of CVS. Since most Macintosh CVS clients seemed to support AppleSingle, that's the way I encodeed the files (on Unix using the karc utility from Xinet) before adding them to CVS.

Did you get MacCVS to work for SSH ?

There is a workable solution using MacCVSpro and MacSSH set for port forwarding see our CVS/SSH Mac page.

I'm having problems with text file line endings using MacCVS on OSX, what's going on ?

OSX is a Unix-like operating system and expects Unix style line endings. MacCVS is a client for MacOS and obeys the Macintosh line ending convention when checking text files out from CVS. When checking out files to OSX try the "cvs(1)" command line program.

AAF won't build on Red Hat Linux version 7.0 (gcc 2.1.92), I get errors in /usr/include/_G_config.h, what's going on ?

What versions of Linux and gcc does AAF build with ?

We have previously (for RC1) tried Red Hat Linux 6.0 and 6.1. I recently (post RC1) tried version 7.1 (gcc 2.96) There's a bug in in _G_config.h which does #include(a standard header) to get a definition of __mbstate_t (an implementation specific typedef).
Implementation specific typedefs should be obtained from implementation specific header files not from public header files like wchar.h.
Because there is ss-impl/ref/h/wchar.h the definition of __mbstate_t is not found.
I have worked around this problem by changing the makefiles and the #include directive for the structured storage reference implementation - these changes are checked in (post RC1) to CVS on SourceForge.

When I try to build AAF on Linux I get compilation errors in ref/impl/src/OM/OMUtilities.cpp saying that uuid/uuid.h can't be found. How can I fix this ?

Make sure the uuid library is installed. For rpm based distributions the uuid library is in the e2fsprogs-devel package: 
$ rpm -q e2fsprogs-devel
e2fsprogs-devel-1.27-9
For deb based ditributions such as Ubuntu: 
$ dpkg -p uuid-dev
The Object Manager uses uuid_generate() from this package to create uuids. Alternativley you can build the Object Manger to use a built-in uuid generator (define OM_USE_OM_CREATEUUID).

Was dodo written specifically for AAF or is it in-house an Avid tool ?

Specifically for AAF. It was originally intended to be thrown away, hence the name, the "dodo" is an extinct flightless bird.

How would you describe "dodo" ?

It' a macro processor.

What is/was the the intended way to EXTEND an interface using dodo ?
(and I mean that in the proper legal COM sense of course)

Before answering the dodo question let's make sure we have the terminology and rules straight.
You cannot extend individual interfaces you can however extend the API by adding new interfaces. You may not remove or change existing interfaces, this is in order to maintain compatibility of older applications with newer libraries. When a new interface is added it gets a new IID, only the new applications know that they can successfully QueryInterface() for that new IID.

Do new interfaces respond to both the new and the old UUIDs

No. It would break binary compatibility to get the new interface in response to a QI() for the old one.
Typically new interfaces are interfaces to new functionality, However, there's a common special case of adding a new interface to existing functionality.
Let's say I have (in no particular syntax)

interface foo {
method a();
method b();
.. lots of methods ...
method p();
method q();
}

But I wish there was also an r() method. I could address this by adding the following new interface

interface foo1 {
method r(); // only
}

foo1 has a different IID than foo.

However new clients would have to use both foo and foo1. Another way I could address this would be to add the following new interface
interface fooEx {
method a();
method b();
.. lots of methods ...
method p();
method q();
method r();
}

fooEx has the same methods as foo except with the addition of r(). This way new clients can ignore foo and only use fooEx. Note that, just as for foo1, fooEx has a different IID than foo. For the convenience of new clients we've repeated all the methods of foo (at least the ones we didn't want to "change") in fooEx.
Now since foo and fooEx are very similar interfaces we can (and probably should in AAF) have foo and fooEx share the same implementation. Note that this is an issue for implementors, not for clients, and is a different concept than having "the new interface respond to both the new and the old UUIDs".
For an example of how this is done in AAF see "interface IAAFTypeDefVariableArray" and "interface IAAFTypeDefVariableArrayEx".
The naming convention seems to be foo fooEx fooEx1 ...

is dodo capable of generating interfaces that share common implementation ?

You make fooEx.dod by copying foo.dod, giving it a new IID, and modifying it. If you want to share implementations, dodo knows, if you tell it, how to have an implementation support more than one interface, again see IAAFTypeDefVariableArray and IAAFTypeDefVariableArrayEx.
dodo also knows how to have the same interface supported by more that one implementation, see IAAFEndian.

Why does the AAF Toolkit leak objects ?

Given the following two code fragments - W and R.
First consider the case in which R is executed after W in the same program. The object referenced by q leaks because it is not released (R4). In this case, most leak detection tools will report a problem in the object creation code inside the AAF Toolkit, with W2 on the call stack, as this is where the leaking object was created. Without too much trouble one can trace from W2 to the cause of the leak - the Get() at R2 without a corresponding Release().
Now consider the case in which after W the objects are saved to an AAF file, the file is closed and the program exits. Some time later, most likely on a different computer, the file is then opened and the objects in it are restored by the toolkit. Then the code fragment R is executed. There's still a leak caused by the missing Release at R4, however most leak detection tools will report a problem in the object restore code inside the AAF Toolkit (this is, after all, the place at which the leaking object was created). It is not immediately obvious that the actual cause of the leak is the Get() at R2 without a corresponding Release(). 

Code W

  IAAFSomething* p = 0;            // 1

  d->CreateInstance(..., &p);      // 2

  e->Set(p);                       // 3

  p->Release();                    // 4


Code R

  IAAFSomething* q = 0;            // 1

  e->Get(&q);                      // 2

  ... Use q ...                    // 3

  // q->Release();                 // 4


The lesson here is that if your leak detection tool reports leaking objects and those objects were created in the object restore code of the AAF Toolkit then you should look for missing Release()s in your AAF Toolkit client code.
The AAF Toolkit is by no-means perfect and from time-to-time bugs are introduced. In general these are fixed promptly. Also, tools such as BoundsChecker, valgrind and the Microsoft CRT heap debugging routines are run fairly regularly on the AAF toolkit. However, in our experience, most reported AAF toolkit leaks turn out to be caused by missing Release()s in the client code.

What's the deal with Unicode and wchar_t ?

What are the portability issues ?

The ANSI/ISO C way to support Unicode is via wchar_t (from <stddef.h>), nearly all compilers support wchar_t. More problematic are the wcs functions (from <wchar.h>) since this was a late addition to ISO some compilers may not support all the wcs function or they may have them in different header files.
The AAF policy is that all strings/characters in memory and across the API are wchar_t (the size of which varies across platforms) and all strings/characters in AAF files are 2-byte unicode. Any transformation to from the in memory wchar_t to the 2-byte external form is done transparently to the API client.

What are the UNICODE and _UNICODE preprocessor symbols for ?

What's the difference ?

These symbols are Microsoft specific (you'll encounter them on non-Microsoft platforms because AAF uses Microsoft Structured storage on all platforms). Defining them alters the prototypes (at compile time) of functions in a couple of APIs to point to the Unicode versions of various functions. The symbol UNICODE is for the Win32 API and the symbol _UNICODE is for the the C run time API. The symbols work something like this ... Given (say in the W32) API void Foo(TCHAR* bar); with UNICODE not defined this maps to void Foo(char* bar); with UNICODE defined this maps to void FooW(wchar_t* bar); Of course this is confusing and pollutes the name space. For example try debugging ImplAAFEssenceAccess and you see that the CreateFile member ends up as CreateFileW, bah !

Is there a way to receive a more meaningful HRESULT when attempting to erroneously create an aaf file that already exists ?

If I try this, the HRESULT I get from AAFFileOpenNewModify() is AAFRESULT_ASSERTION_VIOLATION.
However the call to AAFFileOpenNewModify() resulted in a call to StgCreateDocfile() which did return a meaningful HRESULT (0x80030050, already exists) indicating that the file already exists.Unfortunately there is currently no way to receive a more meaningful HRESULT when attempting to erroneously create an .AAF file that already exists.
We planned to provide complete error handling in the Object Manager but that work has not yet been done. This work was deferred to concentrate on work items of higher priority.Currently the HRESULT returned by StgCreateDocfile() is lost. I suggest the following workaround - Use the host file system [ansi - fopen(), W32 - CreateFile() etc.] to check that the file does not already exist prior to calling AAFFileOpenNewModify()
If you have a GUI you probably want to report the error that the file already exists when the user _chooses_ the name of the file to create i.e. before calling AAFFileOpenNewModify(). Alternatively you could try calling the W32 API function GetLastError() Other workarounds involving the use of AAFCreateAAFFileOnRawStorage() [available in RC1] may be possible.
Note that the goal is for AAF to support multiple external representations. In addition to structured storage binary files, support for XML (text) and SMPTE KLV (binary) encodings is possible.
This means that calls to AFFileOpenNewModify() don't always result in a call to StgCreateDocfile(). For each external representation the function called by the Object Manager to open/create the file is different and may not even return an HRESULT [e.g. fopen()]
Any error handling scheme that is eventually implemented in the Object Manager needs to take the support for multiple external representations into account while still preserving any HRESULT that may be available.

When I try to build the AAF reference implementation on Windows 98 everything works fine until I reach the win32aafsdk.mak step. Exactly one command seems to be echoed, but doesn't get executed, then everything hangs.
After a fresh checkout out that one command is "md" to make a directory. If I make the directories by hand the command that hangs is the first "copy". If I do the first copy by hand then it hangs on the next copy command and so on. When a hang occurs I can't stop the build with the button in the tool bar. I have to kill "vcspawn" with the task manager. After doing this a couple of times the system becomes unusable and I can't shut it down cleanly. What's going wrong ?

Disable all anti-virus software. There are two different win api calls for spawning, and one of them gets intercepted by Norton Anitvirus (and I've also seen the same report for MacAfee). This problem was confirmed with Windows 98 and Norton Anti-Virus.

How do I get Visual Studio to prompt me with AAF class and interface information ?

In order to use the AAF class and interface information in Visual Studio (which is not automatically built in the project files on SourceForge).
You will need to enable the generation of .SBR files when the AAF project is built, then concatenate all these files together using the bscmake tool from a command line.

With the top level AAFWinSDK workspace open, select Project->Settings...
Select the C/C++ tab and highlight the projects you want to generate Browse info for on the left (most of the ones that start AAF...).
Then check the Generate Browse info box and hit OK.
The .SBR files during the build you can be combined with the bscmake command.
From the command line call bscmake with list of all the sbr files.In a bash shell this is something like:

cd AAF/AAFWinSDK/ref-impl
bscmake /o mydata.bsc */Debug/*.sbr

Then open the mydata.bsc file in visual studio. By highlighting a member function you will be now have the option to see it's parameters or jump to the definition.
Be careful not to check these modified project files back in to sourceforge.

I'm having problems getting CVS to work, is there any way to view individual source files ?

Yes, the CVS browse interface on SourceForge allows you to download individual files as well as viewing the differences between versions.

The C++ Standard Template Library (STL) doesn't seem to be used anywhere in the current AAF implementation.
Is this a deliberate policy? if so, why?

It is a deliberate policy. It was done for portability (i.e. portability between different implementations) and to eliminate an extra dependency. At the time we started AAF development (early 1998) the STL implementations in our first three compilers (VC++ 5.0, or was it 4.0?, CodeWarrior 3, and the SGI C++ compiler [GNU C++ was not on the list at that time]) were very inconsistent and patchy. The STL implementations have improved since then, I'm using the STL on another project where portability is less of a concern, but I still have to refer frequently to "Effective STL" by Scott Meyers. I'd recommend sticking to this policy for the AAF reference implementation.

The only appearence of <iostream> is in the Object Manager code for debug, and it's very easy to turn it off (see OMdebug above ).

I ran one of the example programs that are distributed with the AAF toolkit and created an example AAF file.
When I try to import the file into <product x> it doesn't work, why not ?

While those example programs do create AAF files they certainly do not create AAF files with the correct contents such that they can successfully be imported by <product x>. An AAF file can be thought of as a container. Having the correct container is is not sufficient, one must also have the correct contents for the file to be acceptable to the consumer. The AAF Association is aware of this issue and is working on a solution variously known as "Templates" or "Operational Patterns".

Valid HTML 4.01!