The registration database supports linked and embedded objects by providing a systemwide source of information about whether server applications support the OLE protocol, the names of the executable files for these applications, the verbs for classes of objects, and whether an object-handler library exists for a given class of object. For more information about this database, see Chapter 7, “Shell Library.”
When a server application is installed, it registers itself as an OLE server with the registration database. (This database is supported by the dynamic-link library SHELL.DLL.) To register itself as an OLE server, a server application records in the database that it supports one or more OLE protocols. The only protocols supported by version 1.x of the Microsoft OLE libraries are StdFileEditing and StdExecute. StdFileEditing is the current protocol for linked and embedded objects. StdExecute is used only by applications that support the OleExecute function. (A third name, Static, describes a picture than cannot be edited by using standard OLE techniques.)
When a client activates a linked or embedded object, the client library finds the command line for the server in the database, appends the /Embedding or /Embedding filename command-line option, and uses the new command line to start the server. Starting the server with either of these options differs from the user starting it directly. Either a slash (/) or a hyphen (-) can precede the word Embedding. For details about how a server reacts when it is started with these options, see Section 6.3.8, “Opening and Closing Objects.”
The entries in the registration database are used whenever an application or library needs information about an OLE server. For example, client applications that support the Insert Object command refer to the database in order to list the OLE server applications that could provide a new object. The client application also uses the registration database to retrieve the name of the server application for the Paste Special dialog box.
Applications typically add key and value pairs to the registration database by using Microsoft Windows Registration Editor (REGEDIT.EXE). Applications could also use the registration functions to add this information to the database.
The registration database stores keys and values as null-terminated strings. Keys are hierarchically structured, with the names of the components of the keys separated by backslash characters (\) . The class name and server path should be registered for every class the server supports. (This class name must be the same string as the server uses when it calls the OleRegisterServer function.) If a class has an object-handler library, it should be registered using the handler keyword. An application should also register all the verbs its class or classes support. (An application's verbs must be sequential; for example, if an object supports three verbs, the primary verb is 0 and the other verbs must be 1 and 2.)
To be available for OLE transactions, a server should register the key and value pairs shown in the following example when it is installed. This example shows the form of key and value pairs as they would be added to a database with Registration Editor. Although the text string sometimes wraps to the next line in this example, the lines should not include newline characters when they are added to the database.
HKEY_CLASSES_ROOT\class name = readable version of class name
HKEY_CLASSES_ROOT\.ext = class name
HKEY_CLASSES_ROOT\class name\protocol\StdFileEditing\server =
executable file name
HKEY_CLASSES_ROOT\class name\protocol\StdFileEditing\handler =
dll name
HKEY_CLASSES_ROOT\class name\protocol\StdFileEditing\verb\0 =
primary verb
HKEY_CLASSES_ROOT\class name\protocol\StdFileEditing\verb\1 =
secondary verb
Servers that support the OleExecute function also add the following line to the database:
HKEY_CLASSES_ROOT\class name\protocol\StdExecute\server = executable file name
An ampersand (&) can be used in the verb specification to indicate that the following character is an accelerator key. For example, if a verb is specified as &Edit, the E key is an accelerator key.
A server can register the entire path for its executable file, rather than registering only the filename and arguments. Registering only the filename fails if the application is installed in a directory that is not mentioned in the PATH environment variable. Usually, registering the path and filename is less ambiguous than registering only the filename.
Servers can register data formats that they accept on calls to the OleSetData function or that they can return when a client calls the OleRequestData function. Clients can use this information to initialize newly created objects (for example, from data selected in the client) or when using the server as an engine (for example, when sending data to a chart and getting a new picture back). Client applications should not depend on the requested data format, because the calls can be rejected by the server.
In the following example, format is the string name of the format as passed to the RegisterClipboardFormat function or is one of the system-defined clipboard formats (for example, CF_METAFILEPICT):
HKEY_CLASSES_ROOT\class name\protocol\StdFileEditing
\SetDataFormats = format[,format]
HKEY_CLASSES_ROOT\class name\protocol\StdFileEditing
\RequestDataFormats = format[,format]
For compatibility with earlier applications, the system registration service also reads and writes registration information in the [embedding] section of the WIN.INI initialization file.
In the following example, the keyword picture indicates that the server can produce metafiles for use when rendering objects:
[embedding] classname=comment,textual class name,path/arguments,picture
Server applications should store version numbers in their Native data formats. New versions of servers that are intended to replace old versions should be capable of dealing with data in Native format that was created by older versions. It is sometimes important to give the user the option of saving the data in the old format, to support an environment with a mixture of new and old versions, or to permit data to be read by other applications that can interpret only the old format.
There can be only one application at a time (on one workstation) registered as a server for a given class name. The class name (which is stored with the Native data for objects) and the server application are associated in the registration database when the server application registers during installation.
If a new version of a server application allows the user to keep the old version available, a new class name should be allocated for the new server. A good way to do this is to append a version number to the class name. This allows the user to easily differentiate between the two versions when necessary. (The OLE libraries do not check these numbers.)
When the new version of the server is installed, the user should be given the option of either mapping the old objects to the new server (registering the new server as the server for both class names) or keeping them separate. When the user keeps them separate, the user will be aware of two kinds of object (for example, Graph1 and Graph2).
The user should be able to discard the old server version at a later time by remapping the registration database, typically with the help of the server setup program. To remap the database, the old and new objects are given the same value for readable version of class name (although their class names remain distinct). The OLE client library removes duplicate names when it produces the list in the Insert Object dialog box. When a client application produces a list by enumerating the registration database, the application must do this filtering itself.