IBindCtx Interface

The bind context parameter passed to many of the IMoniker operations serves a few purposes.

Its primary purpose is to accumulate the set of objects that get bound during an operation but which should be released when the operation is complete. This is particularly useful in generic composites: using the bind context in this way avoids binding an object, releasing it, only to have it bound again when the operation moves on to another piece of the composite.

Another purpose of the bind context is to pass a group of parameters which do not change as an operation moves from one piece of a generic composite to another. These are the binding options, and are described below. Some of these binding options have a related return value in certain error conditions; the bind context provides the means by which they can be returned.

The bind context is also the only means through which moniker operations should access contextual information about their environment. There should be no direct calls in moniker implementations to API functions that query or set state in the environment; all such calls should instead funnel through the bind context. Doing this allows for future enhancements which can dynamically modify binding behavior.

The predefined piece of contextual information that moniker operations need to access is the Running Object Table; monikers should always access this table indirectly though IBindCtx::GetRunningObjectTable, rather than using the global function GetRunningObjectTable. IBindCtx interface allows for future extensions to the passed-in contextual information in the form the ability to maintain a string-keyed table of objects. See IBindCtx::RegisterObjectParam and related functions.

interface IBindCtx : IUnknown { 
    virtual    HRESULT    RegisterObjectBound(punk);
    virtual    HRESULT    RevokeObjectBound(punk);
    virtual    HRESULT    ReleaseBoundObjects();
    virtual    HRESULT    SetBindOptions(pbindopts);
    virtual    HRESULT    GetBindOptions(pbindopts);
    virtual    HRESULT    GetRunningObjectTable(pprot);
    virtual    HRESULT    RegisterObjectParam(lpszKey, punk);
    virtual    HRESULT    GetObjectParam(lpszKey, ppunk);
    virtual    HRESULT    EnumObjectParam(ppenum);
    virtual    HRESULT    RevokeObjectParam(lpszKey);
    };

typedef struct {
    DWORD    cbStruct;                // the size in bytes of this structure. ie: sizeof(BINDOPTS).
    DWORD    grfFlags;
    DWORD    grfMode;
    DWORD    dwTickCountDeadline;
    } BINDOPTS;

HRESULT CreateBindCtx(reserved, ppbc);