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.
- Software for developers
-
Delphi Components
.Net Components
Software for Android Developers
- More information resources
-
MegaDetailed.Net
Unix Manual Pages
Delphi Examples
- Databases for Amazon shops developers
-
Amazon Categories Database
Browse Nodes Database