TAppDictionary implementation for DLLs only. More...

#include <owl/appdict.h>

Classes
struct	TEntry
	An application dictionary entry that associates a process ID (Pid) with an application (App). More...

Public Types
typedef void(*	TEntryIterator) (TEntry &)
	A dictionary iterator function pointer type that receives a reference to an entry.

Public Member Functions
	TAppDictionary ()
	Application dictionary constructor.

	~TAppDictionary ()
	Destroys the TAppDictionary object and calls DeleteCondemned to clean up the condemned applications.

TApplication *	GetApplication (uint pid=0)
	Looks up and returns the application associated with a given process ID.

void	Add (TApplication *app, uint pid=0)
	Adds an application object (app) and corresponding process ID to this dictionary.

void	Remove (TApplication *app)
	Searches for the dictionary entry using the specified application (app).

void	Remove (uint pid)
	Searches for the dictionary entry using the specified process ID (pid).

void	Condemn (TApplication *app)
	Marks an application in this dictionary as condemned by zeroing its process ID so that the application can be deleted later when DeleteCondemned is called.

bool	DeleteCondemned ()
	Deletes all condemned applications from the dictionary.

void	Iterate (TEntryIterator iter)
	Iterates through the entries in the application dictionary, calling the iter callback function for each entry.

Detailed Description

TAppDictionary implementation for DLLs only.

EXE version is all inline. Flat model must implement here, not inline, because same lib is used by DLLs

A TAppDictionary is a dictionary of associations between a process ID and an application object. A process ID identifies a process: a program (including all its affiliated code, data, and system resources) that is loaded into memory and ready to execute. A TAppDictionary object supports global application lookups using the global GetApplicationObject function or TAppDictionary's GetApplication function. If you do not define an application dictionary, ObjectWindows provides a default, global application dictionary that is exported. In fact, for .EXEs, this global application dictionary is automatically used.

TAppDictionary includes a TEntry struct, which stores a process ID and the corresponding application object associated with the ID. The public member functions add, find, and remove the entries in the application dictionary.

If you are statically linking ObjectWindows, you do not have to explicitly create an application dictionary because the default global ObjectWindows application dictionary is used. However, when writing a DLL component that is using ObjectWindows in a DLL, you do need to create your own dictionary. To make it easier to define an application dictionary, ObjectWindows includes a macro DEFINE_APP_DICTIONARY, which automatically creates or references the correct dictionary for your application.

Although this class is transparent to most users building EXEs, component DLLs need to create an instance of a TApplication class for each task that they service. This kind of application differs from an .EXE application in that it never runs a message loop. (All the other application services are available, however.)

Although a component may consist of several DLLs, each with its own TModule, the component as a whole has only one TApplication for each task. A TAppDictionary, which is used for all servers (including DLL servers) and components, lets users produce a complete, self-contained application or component. By using a TAppDictionary, these components can share application objects.

When 16-bit ObjectWindows is statically linked with an .EXE or under Win32, with per- instance data, the TAppDictionary class is implemented as a wrapper to a single application pointer. In this case, there is only one TApplication that the component ever sees.

To build a component DLL using the ObjectWindows DLL, a new TAppDictionary object must be constructed for that DLL. These are the steps an application must follow in order to associate the component DLL with the TAppDictionary, the application, and the window class hierarchy:

Use the DEFINE_APP_DICTIONARY macro to construct an instance of TAppDictionary. Typically, this will be a static global in one of the application's modules (referred to as "AppDictionary"). The DEFINE_DICTIONARY macro allows the same code to be used for EXEs and DLLs. DEFINE_APP_DICTIONARY(AppDictionary);
Construct a generic TModule and assign it to the global Module. This is the default provided in the ObjectWindows' LibMain function. LibMain(...) Module = new TModule(0, hInstance);
When each TApplication instance is constructed, pass a pointer to the TAppDictionary as the last argument to ensure that the application will insert itself into this dictionary. In addition, for 16 bit DLLs, the global module argument needs to be supplied with a placeholder value because the Module construction has already been completed at this point, as a result of the process performed in step 2 above. TApplication* app = new TMyApp(..., app, AppDictionary);
If the Doc/View model is used, supply the application pointer when constructing the TDocManager object. SetDocManager(new TDocManager(mode, this));
When a non-parented window (for example, the main window) is being constructed, pass the application as the module. SetMainWindow(new TFrameWindow(0, "", false, this));

Definition at line 30 of file appdict.h.

Member Typedef Documentation

◆ TEntryIterator

typedef void(* owl::TAppDictionary::TEntryIterator) (TEntry &)

A dictionary iterator function pointer type that receives a reference to an entry.

You can supply a function of this type to the Iterate function to iterate through the entries in the dictionary.

Definition at line 44 of file appdict.h.

Constructor & Destructor Documentation

◆ TAppDictionary()

owl::TAppDictionary::TAppDictionary ( )

Application dictionary constructor.

Definition at line 171 of file appdict.cpp.

◆ ~TAppDictionary()

owl::TAppDictionary::~TAppDictionary ( )

Destroys the TAppDictionary object and calls DeleteCondemned to clean up the condemned applications.

Definition at line 180 of file appdict.cpp.

References DeleteCondemned().

Member Function Documentation

◆ Add()

void owl::TAppDictionary::Add	(	TApplication *	app,
		uint	pid = 0 )

Adds an application object (app) and corresponding process ID to this dictionary.

The default ID is the current process's ID.

Definition at line 205 of file appdict.cpp.

◆ Condemn()

void owl::TAppDictionary::Condemn ( TApplication * app )

Marks an application in this dictionary as condemned by zeroing its process ID so that the application can be deleted later when DeleteCondemned is called.

Definition at line 247 of file appdict.cpp.

◆ DeleteCondemned()

bool owl::TAppDictionary::DeleteCondemned ( )

Deletes all condemned applications from the dictionary.

If no applications remain in the dictionary, DeleteCondemned returns true.

Definition at line 280 of file appdict.cpp.

◆ GetApplication()

TApplication * owl::TAppDictionary::GetApplication ( uint pid = 0 )

Looks up and returns the application associated with a given process ID.

The default ID is the ID of the current process. If no application is associated with the process ID, GetApplication returns 0.

Definition at line 192 of file appdict.cpp.

◆ Iterate()

void owl::TAppDictionary::Iterate ( TAppDictionary::TEntryIterator iter )

Iterates through the entries in the application dictionary, calling the iter callback function for each entry.

Definition at line 270 of file appdict.cpp.

◆ Remove() [1/2]

void owl::TAppDictionary::Remove ( TApplication * app )

Searches for the dictionary entry using the specified application (app).

Then removes a given application and process ID entry from this dictionary, but does not delete the application object.

Definition at line 218 of file appdict.cpp.

◆ Remove() [2/2]

void owl::TAppDictionary::Remove ( uint pid )

Searches for the dictionary entry using the specified process ID (pid).

Then removes a given application and its associated process ID entry from this dictionary, but does not delete the application.

Definition at line 233 of file appdict.cpp.

The documentation for this class was generated from the following files:

include/owl/appdict.h
source/owlcore/appdict.cpp

Classes

Public Types

Public Member Functions