Step 3: Creating registration tables

Servers implement OLE objects that any container can link or embed in their own documents.

Different servers implement different types of objects. Every type of object a server can create must have a 16-byte globally unique identifier (GUID) and a unique string identifier. Every server must record this information, along with other descriptive information, in the registration database of the system where it runs. OLE reads the registry to determine what objects are available, what their capabilities are, and how to invoke the application that creates objects of each type.

A server provides registration information to ObjectComponents using macros to build registration tables: one table describing the application itself and one for each type of OLE object the server creates. Here is the application registration table from OWLOCF2.

REGISTRATION_FORMAT_BUFFER(100)
 
// application registration table
BEGIN_REGISTRATION(AppReg)
 
REGDATA(clsid, "{B6B58B70-B9C3-101B-B3FF-86C8A0834EDE}")
 REGDATA(description,"Scribble Pad Server")
END_REGISTRATION

The registration macros build a structure of items. Each item contains a key, such as clsid or description, and a value assigned to the key. The order in which the keys appear does not matter. In the example, AppReg is the name of the structure that holds the information in this table.

Servers that create several types of objects must build a document registration table for each type. (What the server creates as a document is presented through OLE as an object.) If a spreadsheet application, for example, creates spreadsheet files and graph files, and if both kinds of documents can be linked or embedded, then the application registers two document types and creates two document registration tables.

The OWLOCF2 sample program creates one type of object, a scribbling pad, so it requires one document registration table (shown here) in addition to the application registration table.

// document registration table
BEGIN_REGISTRATION(DocReg)
 REGDATA(progid, "Scribble.Document.3")
 REGDATA(description,"Scribble Pad Document")
 REGDATA(debugger, "tdw")
 
REGDATA(debugprogid,"Scribble.Document.3.D")
 REGDATA(debugdesc, "Scribble Pad Document (debug)")
 REGDATA(menuname, "Scribble")
 REGDATA(insertable, "")
 REGDATA(extension, DocExt)
 REGDATA(docfilter, "*."DocExt)
 REGDOCFLAGS(dtAutoDelete | dtUpdateDir | dtCreatePrompt | dtRegisterExt)
 
REGDATA(verb0,   "&Edit")
 
REGDATA(verb1,   "&Open")
 REGFORMAT(0, ocrEmbedSource, ocrContent, ocrIStorage, ocrGet)
 REGFORMAT(1, ocrMetafilePict, ocrContent, ocrMfPict,  ocrGet)
END_REGISTRATION

The progid key is an identifier for this document type. The string must be unique so that OLE can distinguish one object from another. The insertable key indicates that this type of document should be listed in the Insert Object dialog box. The description, menuname, and verb keys are all visible to the user during OLE operations. The description appears in the Insert Object dialog box where the user sees a list of objects available in the system. The menuname is used in the container's Edit menu when composing the string that pops up the verb menu, which is where the verb strings appear. The remaining registration items are used when the application opens a file or uses the Clipboard. For more information about particular register keys, see the ObjectWindows Reference Guide.

Place your registration structures in the source code file where you implement your TApplication-derived class. If you cut and paste registration tables from other programs, be sure to modify at least the progid and clsid because these must identify your application uniquely. (Use the GUIDGEN.EXE utility to generate new 16-byte clsid identifiers.)