COM
Expand Minimize

CreateBindCtx function

Returns a pointer to an implementation of IBindCtx (a bind context object). This object stores information about a particular moniker-binding operation.

Syntax


HRESULT CreateBindCtx(
  _In_   DWORD reserved,
  _Out_  LPBC *ppbc
);

Parameters

reserved [in]

This parameter is reserved and must be 0.

ppbc [out]

Address of an IBindCtx* pointer variable that receives the interface pointer to the new bind context object. When the function is successful, the caller is responsible for calling Release on the bind context. A NULL value for the bind context indicates that an error occurred.

Return value

This function can return the standard return values E_OUTOFMEMORY and S_OK.

Remarks

CreateBindCtx is most commonly used in the process of binding a moniker (locating and getting a pointer to an interface by identifying it through a moniker), as in the following steps:

  1. Get a pointer to a bind context by calling the CreateBindCtx function.
  2. Call the IMoniker::BindToObject method on the moniker, retrieving an interface pointer to the object to which the moniker refers.
  3. Release the bind context.
  4. Use the interface pointer.
  5. Release the interface pointer.

The following code fragment illustrates these steps.

// pMnk is an IMoniker * that points to a previously acquired moniker 
IInterface *pInterface; 
IBindCtx *pbc; 
 
CreateBindCtx( 0, &pbc ); 
pMnk->BindToObject( pbc, NULL, IID_IInterface, &pInterface ); 
pbc->Release(); 

// pInterface now points to the object; safe to use pInterface 
pInterface->Release(); 

Bind contexts are also used in other methods of the IMoniker interface besides IMoniker::BindToObject and in the MkParseDisplayName function.

A bind context retains references to the objects that are bound during the binding operation, causing the bound objects to remain active (keeping the object's server running) until the bind context is released. Reusing a bind context when subsequent operations bind to the same object can improve performance. You should, however, release the bind context as soon as possible, because you could be keeping the objects activated unnecessarily.

A bind context contains a BIND_OPTS structure, which contains parameters that apply to all steps in a binding operation. When you create a bind context using CreateBindCtx, the fields of the BIND_OPTS structure are initialized as follows.

cbStruct = sizeof(BIND_OPTS) 
grfFlags = 0 
grfMode = STGM_READWRITE 
dwTickCountDeadline = 0

You can call the IBindCtx::SetBindOptions method to modify these default values.

Requirements

Minimum supported client

Windows 2000 Professional [desktop apps | Windows Store apps]

Minimum supported server

Windows 2000 Server [desktop apps | Windows Store apps]

Header

Objbase.h

Library

Ole32.lib

DLL

Ole32.dll

See also

IBindCtx
IMoniker
MkParseDisplayName

 

 

Community Additions

ADD
Show:
© 2014 Microsoft