IBindCtx::RegisterObjectBound

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This method calls the IUnknown::AddRef method on the specified object to ensure that the object remains active until the bind context is released. The method stores a pointer to the object in the bind context's internal list of pointers.

The IBindCtx::RegisterObjectBound method is supported in DCOM, but it is not supported in COM.

Calling this method in COM returns a value of E_NOTIMPL.

Syntax

HRESULT RegisterObjectBound(
  IUnknown* punk
);

Parameters

• punk
  [in] Pointer to the IUnknown interface on the object that is being registered as bound.

Return Value

The following table shows the return values for this method.

Remarks

To determine whether the platform supports this interface, see Determining Supported COM APIs.

Notes to Callers

Those writing a new moniker class (through an implementation of the IMoniker interface) should call this method whenever the implementation activates an object.

This happens most often in the course of binding a moniker, but it can also happen while retrieving a moniker's display name, parsing a display name into a moniker, or retrieving the time that an object was last modified.

IBindCtx::RegisterObjectBound calls IUnknown::AddRef to create an additional reference to the object. You must, however, still release your own copy of the pointer. Calling this method twice for the same object creates two references to that object.

You can release a reference obtained through a call to this method by calling the IBindCtx::RevokeObjectBound method.

All references held by the bind context are released when the bind context itself is released.

Calling IBindCtx::RegisterObjectBound to register an object with a bind context keeps the object active until the bind context is released.

Reusing a bind context in a subsequent binding operation (either for another piece of the same composite moniker or for a different moniker) can make the subsequent binding operation more efficient because it does not have to reload that object.

This, however, improves performance only if the subsequent binding operation requires some of the same objects as the original one, so you need to balance the possible performance improvement of reusing a bind context against the costs of keeping objects activated unnecessarily.

The IBindCtx interface does not provide a method to retrieve a pointer to an object registered using IBindCtx::RegisterObjectBound.

Assuming the object has registered itself with the Running Object Table, moniker implementations can call the IRunningObjectTable::GetObject method to retrieve a pointer to the object.

Requirements

See Also

Reference

IBindCtx
IMoniker
IBindCtx::ReleaseBoundObjects
IBindCtx::RevokeObjectBound
IRunningObjectTable::GetObject
IUnknown
IUnknown::AddRef