IBindCtx Interface

IID_IBindCtx

{0000000E-0000-0000-C000-000000000046}

The IBindCtx interface provides access to a bind context, which is an object that stores information about a particular moniker binding operation. You pass a bind context as a parameter when calling many methods of IMoniker and in certain functions related to monikers.

Anyone writing a new moniker class by implementing the IMoniker interface must call IBindCtx methods in the implementation of several IMoniker methods. Moniker providers (servers that hand out monikers to identify their objects) may also need to call IBindCtx methods from their implementations of the IOleItemContainer or IParseDisplayName interface.

Moniker clients (objects that use monikers to acquire interface pointers to other objects) typically don't call many IBindCtx methods. Instead, they simply pass a bind context as a parameter in a call to an IMoniker method. To acquire an interface pointer and activate the indicated object (called binding to an object), moniker clients typically do the following:

1. Call the CreateBindCtx function to create a bind context and get a pointer to the IBindCtx interface on the bind context object.

2. If desired (although this is rarely necessary), the moniker client can call IBindCtx::SetBindOptions to specify the bind options.

3. Pass the bind context as a parameter to the desired IMoniker method (usually IMoniker::BindToObject).

4. Call IUnknown::Release on the bind context to release it.

Although applications that act as link containers (container applications that allow their documents to contain linked objects) are moniker clients, they rarely call IMoniker methods directly. Generally, they manipulate linked objects through the system implementation (in the default handler) of the IOleLink interface. This implementation calls the appropriate IMoniker methods as needed and, in doing so, passes pointers to IBindCtx interfaces on the proper bind context objects.

Methods in VTable order

IUnknown Methods

Description

QueryInterface

Returns pointers to supported interfaces.

AddRef

Increments reference count.

Release

Decrements reference count.

IBindCtx Methods

Description

RegisterObjectBound

Registers an object with the bind context.

RevokeObjectBound

Revokes an object's registration.

ReleaseBoundObjects

Releases all registered objects.

SetBindOptions

Sets the binding options.

GetBindOptions

Retrieves the binding options.

GetRunningObjectTable

Retrieves a pointer to the Running Object Table.

RegisterObjectParam

Associates an object with a string key.

GetObjectParam

Returns the object associated with a given string key.

EnumObjectParam

Enumerates all the string keys in the table.

RevokeObjectParam

Revokes association between an object and a string key.

RegisterObjectBound

FUNCTION IBindCtx_RegisterObjectBound ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL pUnk AS DWORD _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[3] USING IBindCtx_RegisterObjectBound (pthis, pUnk) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

RevokeObjectBound

FUNCTION IBindCtx_RevokeObjectBound ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL pUnk AS DWORD _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[4] USING IBindCtx_RevokeObjectBound (pthis, pUnk) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

ReleaseBoundObjects

FUNCTION IBindCtx_ReleaseBoundObjects ( _

  BYVAL pthis AS DWORD PTR _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[5] USING IBindCtx_ReleaseBoundObjects (pthis) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

SetBindOptions

FUNCTION IBindCtx_SetBindOptions ( _

  BYVAL pthis AS DWORD PTR _

, BYREF pbindopts AS BIND_OPTS _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[6] USING IBindCtx_SetBindOptions (pthis, pbindopts) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

GetBindOptions

FUNCTION IBindCtx_GetBindOptions ( _

  BYVAL pthis AS DWORD PTR _

, BYREF pbindopts AS BIND_OPTS _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[7] USING IBindCtx_GetBindOptions (pthis, pbindopts) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

GetRunningObjectTable

FUNCTION IBindCtx_GetRunningObjectTable ( _

  BYVAL pthis AS DWORD PTR _

, BYREF pprot AS DWORD _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[8] USING IBindCtx_GetRunningObjectTable (pthis, pprot) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

Example

The following example shows the display names of all the objects currently registered in the Running Object Table (ROT).

#COMPILE EXE
#DIM ALL
#INCLUDE "Win32Api.inc"
 

FUNCTION PBMAIN

   LOCAL hr AS LONG
   LOCAL ppbc AS DWORD
   LOCAL pprot AS DWORD
   LOCAL ppenumMoniker AS DWORD
   LOCAL ppMoniker AS DWORD
   LOCAL pceltFetched AS DWORD
   LOCAL strDisplayName AS STRING

   ' Get a pointer to the Running Object Table (ROT)
   hr = CreateBindCtx(0, ppbc)
   IF hr <> %S_OK OR ppbc = %NULL THEN GOTO Terminate
   hr = IBindCtx_GetRunningObjectTable(ppbc, pprot)
   IUnknown_Release ppbc
   IF hr <> %S_OK OR pprot = %NULL THEN GOTO Terminate
 

   ' Get a pointer to the moniker enumerator
   hr = IRunningObjectTable_EnumRunning(pprot, ppenumMoniker)
   IF hr <> %S_OK OR ppenumMoniker = %NULL THEN GOTO Terminate

   ' Enumerate the monikers and retrieve the display name
   ppMoniker = 0
   DO
      hr = IEnumMoniker_Next(ppenumMoniker, 1, VARPTR(ppMoniker), pceltFetched)
      IF hr <> %S_OK OR ppMoniker = 0 OR pceltFetched = 0 THEN EXIT DO
      hr = IMoniker_GetDisplayName(ppMoniker, ppbc, %NULL, strDisplayName)
      IF ppMoniker THEN IUnknown_Release ppMoniker
      IF hr <> %S_OK THEN EXIT DO
      MSGBOX strDisplayName
   LOOP

   ' Release the enumerator
   IF ppenumMoniker THEN IUnknown_Release ppenumMoniker

Terminate:

   ' Release the Running Object Table
   IF pprot THEN IUnknown_Release pprot

END FUNCTION

RegisterObjectParam

FUNCTION IBindCtx_RegisterObjectParam ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL strKey AS STRING _

, BYVAL pUnk AS DWORD _

  ) AS LONG

  LOCAL HRESULT AS LONG

  strKey = UCODE$(strKey & $NUL)
  CALL DWORD @@pthis[9] USING IBindCtx_RegisterObjectParam (pthis, strKey, pUnk) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

GetObjectParam

FUNCTION IBindCtx_GetObjectParam ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL strKey AS STRING _

, BYREF ppunk AS DWORD _

  ) AS LONG

  LOCAL HRESULT AS LONG

  strKey = UCODE$(strKey & $NUL)
  CALL DWORD @@pthis[10] USING IBindCtx_GetObjectParam (pthis, strKey, ppunk) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

EnumObjectParam

FUNCTION IBindCtx_EnumObjectParam ( _

  BYVAL pthis AS DWORD PTR _

, BYREF ppenum AS DWORD _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[11] USING IBindCtx_EnumObjectParam (pthis, ppenum) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

RevokeObjectParam

FUNCTION IBindCtx_RevokeObjectParam ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL strKey AS STRING _

  ) AS LONG
 

  LOCAL HRESULT AS LONG
  strKey = UCODE$(strKey & $NUL)
  CALL DWORD @@pthis[12] USING IBindCtx_RevokeObjectParam (pthis, strKey) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION