Edit

BindMoniker function (objbase.h)

  • Article

Locates an object by means of its moniker, activates the object if it is inactive, and retrieves a pointer to the specified interface on that object.

Syntax

HRESULT BindMoniker(
  [in]  LPMONIKER pmk,
  [in]  DWORD     grfOpt,
  [in]  REFIID    iidResult,
  [out] LPVOID    *ppvResult
);

Parameters

[in] pmk

A pointer to the object's moniker. See IMoniker.

[in] grfOpt

This parameter is reserved for future use and must be 0.

[in] iidResult

The interface identifier to be used to communicate with the object.

[out] ppvResult

The address of pointer variable that receives the interface pointer requested in iidResult. Upon successful return, *ppvResult contains the requested interface pointer. If an error occurs, *ppvResult is NULL. If the call is successful, the caller is responsible for releasing the pointer with a call to the object's IUnknown::Release method.

Return value

This function can return the following error codes, or any of the error values returned by the IMoniker::BindToObject method.

Return code Description
S_OK
 The object was located and activated, if necessary, and a pointer to the requested interface was returned.
MK_E_NOOBJECT
 The object that the moniker object identified could not be found.

Remarks

BindMoniker is a helper function supplied as a convenient way for a client that has the moniker of an object to obtain a pointer to one of that object's interfaces. BindMoniker packages the following calls:

CreateBindCtx(0, &pbc); 
pmk->BindToObject(pbc, NULL, riid, ppvObj);

CreateBindCtx creates a bind context object that supports the system implementation of IBindContext. The pmk parameter is actually a pointer to the IMoniker implementation on a moniker object. This implementation's BindToObject method supplies the pointer to the requested interface pointer.

If you have several monikers to bind in quick succession and if you know that those monikers will activate the same object, it may be more efficient to call the IMoniker::BindToObject method directly, which enables you to use the same bind context object for all the monikers. See the IBindCtx interface for more information.

Container applications that allow their documents to contain linked objects are a special client that generally does not make direct calls to IMoniker methods. Instead, the client manipulates the linked objects through the IOleLink interface. The default handler implements this interface and calls the appropriate IMoniker methods as needed.

Requirements

Requirement Value
Minimum supported client Windows 2000 Professional [desktop apps | UWP apps]
Minimum supported server Windows 2000 Server [desktop apps | UWP apps]
Target Platform Windows
Header objbase.h
Library Ole32.lib
DLL Ole32.dll
API set ext-ms-win-com-ole32-l1-1-5 (introduced in Windows 10, version 10.0.15063)

See also

CreateBindCtx

IMoniker::BindToObject