Step 5: Building registration tables

Servers implement OLE objects that any container can use.

Different servers implement different types of objects. Every type of object a server creates must have a 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 which objects are available, what their capabilities are, and how to invoke the application that creates objects of each type.

ObjectComponents simplifies the task of registration. You call macros to build a table of keys with associated values. ObjectComponents receives the table and automatically performs all registration tasks.

Servers and containers use the same macros for registration, but servers must provide more information than containers. Here are the commands to build the registration tables for a typical server. This example comes from the STEP15.CPP and STEP15DV.CPP file in the EXAMPLES\OWL\TUTORIAL directory of your compiler installation.

REGISTRATION_FORMAT_BUFFER(100)    // allow space for expanding macros
 
BEGIN_REGISTRATION(AppReg)
 
REGDATA(clsid,   "{5E4BD320-8ABC-101B-A23B-CE4E85D07ED2}")
 REGDATA(description,"Drawing Pad Server")
END_REGISTRATION
 
BEGIN_REGISTRATION(DocReg)
 REGDATA(progid, "DrawPad.Document.15")
 REGDATA(description,"Drawing Pad (Step15--Server)")
 REGDATA(menuname,  "Drawing Pad 15")
 REGDATA(extension, "p15")
 REGDATA(docfilter, "*.p15")
 REGDOCFLAGS(dtAutoOpen | dtAutoDelete | dtUpdateDir | dtCreatePrompt | dtRegisterExt)
 REGDATA(insertable, "")
 
REGDATA(verb0,   "&Edit")
 
REGDATA(verb1,   "&Open")
 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 macros in the example build two structures. The first structure is named AppReg and the second is DocReg. ObjectComponents uses lowercase strings such as progid and clsid to name the standard keys to which you assign values. The values you assign are strings, and they are sensitive to case. The order of keys within the registration table doesn't matter. For information on the the full set of registration macros, see the ObjectWindows Help.

The set of keys you place in a structure depends on what OLE capabilities you intend to support and whether the structure holds application information or document information. The macros in the example show the minimum amount of information a server with one type of document should provide.

A server registers program and class ID strings (progid and clsid) for itself and for every type of document it creates. The IDs must be absolutely unique so that OLE can distinguish one application from another. The description strings appear on the Insert Object dialog box where the user sees a list of objects available in the system.

Place your registration structures in the source code files where you construct document templates and implement your TApplication-derived class. A server always creates only one application registration table (called AppReg in the example). The server might create several document registration tables, however, if it creates several different kinds of documents (for example, text objects and chart objects). Each registration table needs a unique progid value. After creating registration tables, you must pass them to the appropriate object constructors. The AppReg structure is passed to the TOcRegistrar constructor. Document registration tables are passed to the document template constructor.

DEFINE_DOC_TEMPLATE_CLASS(TMyOleDocument, TMyOleView, MyTemplate);
MyTemplate myTpl(::DocReg);

Some of the information in the document registration table is used only by the document template. The document filter and document flags have to do with documents, not with OLE. Previous versions of OWL passed the same information to the document template as a series of separate parameters. The old method is still supported for backward compatibility, but new programs, whether they use OLE or not, should use the registration macros to supply document template parameters.

Some of the registration macros expand the values passed to them. The REGISTRATION_FORMAT_BUFFER macro reserves memory needed temporarily for the expansion. To determine how much buffer space you need, allow 10 bytes for each REGFORMAT item plus the size of any string parameters you pass to the macros REGSTATUS, REGVERBOPT, REGICON, or REGFORMAT.