MORE INFORMATION
The
following files are available for download from the Microsoft Download
Center:
Visual C++ 6.0
For
additional information about how to download Microsoft Support files, click the
following article number to view the article in the Microsoft Knowledge Base:
119591 How to Obtain Microsoft Support Files from Online Services
Microsoft scanned this file for viruses. Microsoft used the most
current virus-detection software that was available on the date that the file
was posted. The file is stored on security-enhanced servers that help to
prevent any unauthorized changes to the file.
Visual C++ 6.0
Release Date: June 26,
2002
For additional information about how to download Microsoft
Support files, click the following article number to view the article in the
Microsoft Knowledge Base:
119591 How to Obtain Microsoft Support Files from Online Services
Microsoft scanned this file for viruses. Microsoft used the most
current virus-detection software that was available on the date that the file
was posted. The file is stored on security-enhanced servers that help to
prevent any unauthorized changes to the file.
NOTE: Use the -d option when running Regaut.exe to
decompress the file and re-create the proper directory structure.
The Regaut sample includes a Visual Basic client application called
Vbclient.exe. Vbclient.exe tries to attach to the Regaut server's document by
calling the Visual Basic GetObject API, which looks for the object in the ROT;
if that fails, it creates the object using the Visual Basic CreateObject API.
Once the first Vbclient.exe has been started, more instances of Vbclient.exe
can be started, which attach to the already running Regaut document. All
instances of Vbclient.exe share the same automation object. A C++ version of
Vbclient.exe, Vcclient.exe, is also included.
Another way to use
this sample is to start the Regaut.exe application. After Regaut is running,
start as many instances of Vbclient.exe as you want. All of these instances
attach to the already running Regaut document. Each instance of Vbclient.exe
can retrieve and change the Regaut document's data. When the Vbclient.exe
applications are done accessing the Regaut document's data, they can shut down,
leaving Regaut running with its document containing the data from the last
Vbclient.exe that changed Regaut's data.
Regaut.exe also
demonstrates the correct way to leave an automation server running if the
automation client makes the automation server's application window visible. If
during the course of automating a server, a client makes the server[ASCII 146]s
application window visible, the server should shut down only in response to an
explicit user or automation client command (such as the Exit command from the
File menu or the equivalent).
The CRegautDoc::RegisterAsActive()
function registers the Regaut document as active when a new document is created
or when an existing document is opened. It does this by registering The
CRegautDoc's IUnknown pointer in the running object table using the OLE API
RegisterActiveObject. RegisterActiveObject has the following prototype:
HRESULT RegisterActiveObject (IUnknown FAR* punk,
REFCLSID rclsid,
DWORD dwFlags,
unsigned long FAR* pdwRegister);
NOTE: punk is the IUnknown * for the object we want to register. You
get this pointer in Regaut by calling CCmdTarget::GetControllingUnknown().
The rclsid parameter is the clsid of the local server, which OLE
uses to identify this object in the ROT. Automation clients use this clsid to
search for this object in the ROT and to create this object. This clsid is
generated by Appwizard when you choose the Automation support option while
generating your application. It is created as a member variable of the CWinApp
derived class, so Regaut just uses a helper function in CRegautApp to access
this value from other classes.
The dwFlags parameter specifies how
you would like to register the active object in the running object table. You
can either register with a strong lock ACTIVEOBJECT_STRONG or a weak lock
ACTIVEOBJECT_WEAK. For automation objects, ACTIVEOBJECT_WEAK is almost always
used. Online documentation for RegisterActiveObject in Visual C++ Books online
has a detailed discussion of the differences between registering your
automation object weak versus strong. You should be familiar with this
documentation before you use RegisterActiveObject. Regaut.exe uses
ACTIVEOBJECT_WEAK.
The pdwRegister parameter is a value returned by
OLE to RegisterActiveObject that is used in calls to RevokeActiveObject to
explicitly remove an object's entry from the ROT.
When a client
application has connected to Regaut and wants to make it visible, the client
calls the ShowWindow() method. Once the Regaut window is visible, the Regaut
document makes sure the Regaut application stays running after the last client
disconnects by calling AfxSetUserControl(TRUE). This ensures that Regaut.exe
will not shut down after the last client detaches but does not ensure that the
current document will close after the last client detaches.
To
ensure that the current document does not close, CRegautDoc calls
CoLockObjectExternal(GetControllingUnknown(),TRUE,TRUE) to put an external lock
on the document. When the user does decide to shut down the CRegaut application
or otherwise close the document,
CoLockObjectExternal(GetControllingUnknown(),FALSE,TRUE) is called to remove
the external lock on the document object. The calls to AfxSetUserControl and
CoLockObjectExternal ensure that the automation server behaves correctly if the
application window becomes visible. Having the server's application window
become visible is also known as putting the user in control.
This
article demonstrates registering an object on the Running Object Table (ROT)
with the RegisterActiveObject API. RegisterActiveObject registers an object
using that objects GUID. To uniquely identify objects of the same type on the
ROT it is necessary to register the object with a moniker. Q152087 demonstrates
how to register a moniker on the ROT with IRunningObject::Register however,
please keep in mind the this is not what this sample was written to illustrate.
