RegisterActiveObject - OLE Programmer's Reference

Custom Search

RegisterActiveObject

punk, rclsid, pvreserved, pdwRegister)
IUnknown FAR* punk
REFCLSID rclsid
DWORD dwFlags
unsigned long FAR* pdwRegister

Registers an object as the active object for its class.

Parameters
punk
Pointer to the IUnknown interface of the active object.

rclsid
Pointer to the class ID of the active object.

dwFlags
Flags controlling registration of the object. Possible values are ACTIVEOBJECT_STRONG and ACTIVEOBJECT_WEAK.

pdwRegister
On return, pointer to a handle. You must pass this handle to RevokeActiveObject to end the object's status as active.

Return Value
The SCODE obtained from the returned HRESULT is one of the following:

SCODE	Meaning
S_OK	Success
Other returns	Failure

Comments
The RegisterActiveObject function registers the object to which punk points as the active object for the class denoted by rclsid. Registration causes the object to be listed in OLE's running object table, a globally accessible lookup table that keeps track of the objects that are currently running on your computer. (See the OLE 2 Programmer's Reference, Volume 1 for more information on the running object table.) The dwFlags parameter specifies the strength or weakness of the registration, which affects the way the object is shut down.

In general, OLE Automation objects should behave in the following manner:

If the object is visible, it should shut down only in response to an explicit user command (such as the Exit command from the File menu), or to the equivalent command from an OLE Automation controller (invoking the Quit or Exit method on the Application object).
If the object is not visible, it should shut down only when the last external connection to it disappears.

Strong registration performs an AddRef on the object, thereby incrementing the reference count of the object (and its associated stub) in the running object table. A strongly registered object must be explicitly revoked from the table with RevokeActiveObject. Strong registration (ACTIVEOBJECT_STRONG) is the default.

Weak registration keeps a pointer to the object in the running object table, but does not increment the reference count. Consequently, when the last external connection to a weakly registered object disappears, OLE releases the object's stub and the object itself is no longer available.

To ensure the desired behavior, you must consider not only OLE's default actions, but also the following:

Even though your code creates an invisible object, the object may become visible at some later time. Once the object is visible, it should remain visible and active until it receives an explicit command to shut down, which may occur after references from your code disappear.
Other OLE Automation controllers may be using the object. If so, your code should not force the object to shut down.

To avoid possible conflicts, OLE Automation objects should always register with ACTIVEOBJECT_WEAK, and call CoLockObjectExternal when necessary to guarantee that the object remains active. CoLockObjectExternal adds a strong lock, thereby preventing the object's reference count from reaching zero. For detailed information on this function, refer to the OLE 2 Programmer's Reference, Volume 1.

Most commonly, objects need to call CoLockObjectExternal when they become visible, so that they remain active until the user requests shutdown.

To shut down correctly, your code should follow these steps

When the object becomes visible, make the following call to add a lock on behalf of the user:

CoLockObjectExternal(punk, TRUE, TRUE)

The lock should remain in effect until the user explicitly requests shutdown, such as with a Quit or Exit command.

When the user requests shutdown, call CoLockObjectExternal again to free the lock, as follows:

CoLockObjectExternal(punk, FALSE, TRUE)

Call RevokeActiveObject to make the object inactive.
To end all connections from remote processes, call CoDisconnectObject as follows:

CoDisconnectObject(punk, 0)

This function is described in the OLE 2 Programmer's Reference, Volume 1.

Last news from Greatis Software

    Nostalgia .Net     .Net is powerful, but not all-powerful, so sometimes we need to use Win32 API for our .Net applications. It's simple enough with Platform Invoke if you have Win32 skill, but we do not always have time to dig the ancient documentation, declare the special types that are compatible with Win32, find the values of the Win32's constants and so on. Nostalgia .Net offers several simple-to-use classes, and components that will allow you to forget about the headache of Win32 and just use the power of Win32 in your application the same way as you use the native. Net classes. More »

Recommended software for developers

    Ultimate Pack     Component pack for Delphi and C++ Builder that contains runtime form designer, runtime object inspector, print suite and much more for the very special price. More »

    Form Designer .Net     Unique runtime form design solution that allows to edit any form in .Net WinForms application at runtime with full source codes for only 300 euro! More »

    Print Suite .Net     Print Suite .Net is a set of components for easy printing texts, images and grids from your WinForms applications. Full C# source codes are available More »

    Gradient Controls .Net     Gradient Controls .Net offers controls with gradient background feature. Labels, panels and so on... Full C# source codes are available More »

    Greatis iGrid     iGrid plots drawing grid right over your desktop, so you can use it everywhere, with any drawing application without any special plugins for different graphic editors. More »

All the contacts and projects

Dmitry Vasiliev (just.dmitry)

More Online Helps

Win32 Programmer's Reference
Win32 Multimedia Programmer's Reference
OLE Programmer's Reference
Microsoft Windows Pen API Programmer's Reference
Microsoft Windows Sockets 2 Reference
Microsoft Windows Telephony API (TAPI) Programmer's Reference
Unix Manual Pages

greatis just4fun network