Step 5: Creating registration tables

OLE requires programs to identify themselves by registering unique identifiers and names.

OLE also needs to know what Clipboard formats a program supports. Doc/View applications also register their document file extensions and document flags. To accommodate the many new items an application might need to register, in ObjectWindows 2.5 you use macros to build structures to hold the items. Then you can pass the structure to the object that needs the information. The advantage of this method lies in the structure's flexibility. It can hold as many or as few items as you need.

Note

Previous versions of ObjectWindows passed some of the same information in parameters. Old code still works unchanged, but passing information in registration structures is the recommended method for all new applications.

A Doc/View OLE container fills one registration structure with information about the application and then creates another to describe each of its Doc/View pairs. The structure with application information is passed to the TOcRegistrar constructor. Document registration structures are passed to the document template constructor.

Here are the commands to register a typical container:

BEGIN_REGISTRATION(AppReg) // information for the TOcRegistrar constructor
 
REGDATA(clsid, "{383882A1-8ABC-101B-A23B-CE4E85D07ED2}")
 REGDATA(appname, "DrawPad Container")
END_REGISTRATION
 
BEGIN_REGISTRATION(DocReg)    // information for the document template
 REGDATA(progid, "DrawPad.Document.14")
 REGDATA(description,"Drawing Pad (Step14--Container)")
 REGDATA(extension, "p14")
 REGDATA(docfilter, "*.p14")
 REGDOCFLAGS(dtAutoOpen | dtAutoDelete | dtUpdateDir | dtCreatePrompt | dtRegisterExt)
 REGFORMAT(0, ocrEmbedSource, ocrContent, ocrIStorage, ocrGet)
 REGFORMAT(1, ocrMetafilePict, ocrContent, ocrMfPict|ocrStaticMed, ocrGet)
 REGFORMAT(2, ocrBitmap, ocrContent, ocrGDI|ocrStaticMed, ocrGet)
 REGFORMAT(3, ocrDib, ocrContent, ocrHGlobal|ocrStaticMed, ocrGet)
 REGFORMAT(4, ocrLinkSource, ocrContent, ocrIStream, ocrGet)
END_REGISTRATION

The registration macros build structures of type TRegList. Each entry in a registration structure contains a key, such as clsid or progid, and a value assigned to the key. Internally ObjectComponents finds the values by searching for the keys. The order in which the keys appear does not matter.

Insert the registration macros after your declaration of the application dictionary. Since the value of the clsid key must be a unique number identifying your application, it is recommended that you generated a new value using the GUIDGEN.EXE utility. (the ObjectWindows Reference Guide entry for clsid explains other ways to generate an identifer.) of course, modify the value of the description key to describe your container.

The example builds two structures, one named AppReg and one named DocReg. AppReg is an application registration structure and DocReg is a document registration structure. Both structures are built alike, but each contains a different set of keys and values. The keys in an application registration structure describe attributes of the application. A document registration structure describes the type of document an application can create. A document's attributes include the data formats that it can exchange with the clipboard, its file extensions, and its document type name.

The set of keys you place in a structure depends on what OLE capabilities you intend to support. The macros in the example show the minimum amount of information a container should provide.