Factory Template classes

The factory template classes create callback code for both automated and non automated Doc/View and non-Doc/view ObjectWindows applications. Use these factory template classes to make objects for embedding and linking. (That is, when an application object needs to be embedded within another container, the callback function is responsible for creating the embedded object.) Depending on the template arguments passed to the factory class, you obtain different kinds of factories designed to create the object you need. All the templetized classes, however, assume that the application is using a global AppDictionary (the application's dictionary), and a global Registrar (the TOcRegistrar pointer that manages registering the application in the database).

ObjectWindows includes several factory template classes, divided into two main categories: those designed for Doc/View applications and those designed for non-Doc/View applications. Although all these classes contain the same functions, they are designed to create different types of objects.

The factory class hierarchy chart illustrates the inheritance relationship among these classes. Each class takes three arguments: the application class, the automation class, and the Doc/View class. The arguments indicate whether or not the application is a Doc/View application and whether or not the application is automated. The factory classes and their definitions include the following four classes.

 TOleDocViewFactory class for Doc/View, non-automated, OLE components
 template <class T> class TOleDocViewFactory
 : public TOleFactoryBase<T, TOleFactoryDocView<T, TOleFactoryNoAuto<T>>>{ };
 
 TOleDocViewAutoFactory class for Doc/View, automated OLE components
 template <class T> class TOleDocViewAutoFactory
 : public TOleFactoryBase<T, TOleFactoryDocView<T, TOleFactoryAuto<T>>>{ };
 TOleFactory class for non-Doc/View, non-automated, OLE components
 template <class T> class TOleFactory
 : public TOleFactoryBase<T, TOleFactoryNoDocView<T, TOleFactoryNoAuto<T>>>{ };
 TOleAutoFactory class for non-Doc/View, automated OLE components
 template <class T> class TOleAutoFactory
 : public TOleFactoryBase<T, TOleFactoryNoDocView<T, TOleFactoryAuto<T>>>{ };

For either a Doc/View or a non-Doc/View application, you need to register your application in your OwlMain function. The argument to TOcRegistrar (in this case, TOleFactory<TDrawApp>) constructs an object and converts it to a TComponentFactory type, using the operator TComponentFactory to create a function pointer. In reality, the object is never created because all the factory class's functions are static.

Pass your application object derived from TApplication as the parameter to TOleFactory, as the following code from STEP15.CPP illustrates:

 int
 OwlMain(int /*argc*/, char* /*argv*/ [])
 { 
   try { 
     Registrar = new TOcRegistrar(AppReg, TOleFactory<TDrawApp>(),
                                  TApplication::GetCmdLine());
     if (Registrar->IsOptionSet(TOcCmdLine::AnyRegOption))
       return 0;
 //If this is a normal exe server, run the application now; otherwise,
 // wait until the factory is called.
     return Registrar->Run();
 }

In general, the following steps, illustrated in the Factory Class Callback Flowchart, show the steps each factory class follows in the default callback code:

1. The factory gets the application. This is the application object derived from TApplication. For a DLL server, there can be several instances of the object. Using TAppDictionary::GetApplication, the factory verifies whether or not there is an entry in the application dictionary for an application object for the current process.
2. If the application does not exist, the factory creates the application object and tests to see if the application was created successfully before creating its corresponding TOcApp object. If the shutdown option flag is set, it then exits. (If the application has already been destroyed, the shutdown flag is set.)
3. If the factory is passed a shutdown option flag (one of the TOcAppMode enum values), it then shuts down the application and calls the factory's DestroyApp function to destroy the application.
4. If the application is automated, the factory creates a corresponding automation object.
5. If the object ID is not zero, the factory creates the object and gets the OLE interface. Otherwise, it gets the application's OLE interface. At this point, the Doc/View and non-Doc/View processes differ because they need to create different types of objects. If the application is automated, the factory creates an automated helper object.
6. The factory checks to see if the option flag amRun (one of the TOcAppMode enum values) is set, and, if so, it runs the application. This occurs if the application either was built as an .EXE or is a DLL running as an .EXE. If the amRun flag is not set and the application is an in-proc DLL server and should not be running, the factory just starts the application.
7. The factory returns either the OLE interface for the object or 0 if no interface was requested or if an error occurred.

The factory can be called back to walk through this process several times:

1. On the first callback, the factory creates the application, and if the amRun flag is set, it enters a message loop.
2. On the second callback, OLE calls the factory to automate or embed or link an object. In the case of an embedded and/or linked object, this pass can occur one or more times. (In the case of an automation object, however, this second pass occurs only once because any subsequent requests pass through the automated application itself.)
3. On the final callback, the factory shuts down the application.