RegisterActiveObject

HRESULT RegisterActiveObject( 
  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 CLSID of the active object.
dwFlags: Flags controlling registration of the object. Possible values are ACTIVEOBJECT_STRONG and ACTIVEOBJECT_WEAK.
pdwRegister: On return, a pointer to a handle. This handle must be passed to RevokeActiveObject to end the object's active status.

Return Value

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning
S_OK	Success.
Other return codes	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 the running object table (ROT) of OLE, a globally accessible lookup table that keeps track of objects that are currently running on the computer. (For more information about the running object table, see the OLE Programmer's Reference.) The dwFlags parameter specifies the strength or weakness of the registration, which affects the way the object is shut down.

In general, ActiveX 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 on the File menu), or to the equivalent command from an ActiveX client (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 is gone.

Strong registration performs an AddRef on the object, 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. The default is strong registration (ACTIVEOBJECT_STRONG).

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, consider not only the default actions of OLE, but also the following:

Even though code can create 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. This can occur after references from the code disappear.
Other ActiveX clients may be using the object. If so, the code should not force the object to shut down.

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

Most commonly, objects need to call CoLockObjectExternal when they become visible, so they remain active until the user requests the object to shut down. The following procedure lists the steps your code should follow to shut down an object correctly.

To shut down an active object:

When the object becomes visible, make the following call to add a lock for the user:
```
CoLockObjectExternal(punk, TRUE, TRUE)
```
The lock remains in effect until a user explicitly requests the object to be shut down, such as with a Quit or Exit command.
When the user requests the object to be shut down, 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 more detail in the OLE Programmer's Reference.

QuickInfo

  Windows NT: Use version 3.1 and later.
  Windows: Use Windows 95 and later.
  Header: Declared in oleauto.h.
  Import Library: Link with oleaut32.lib.