Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This structure contains parameters used during a moniker-binding operation.

A BIND_OPTS2structure is stored in a bind context. The same bind context is used by each component of a composite moniker during binding, allowing the same parameters to be passed to all components of a composite moniker. For more information about bind contexts, see IBindCtx.

BIND_OPTS2replaces the previously defined BIND_OPTSstructure, including the previously defined members and adding four new members.

Moniker clients (those using a moniker to acquire an interface pointer to an object) typically do not need to specify values for the members of this structure.

The CreateBindCtxfunction creates a bind context with the bind options set to default values that are suitable for most situations. The BindMonikerfunction does the same thing when creating a bind context for use in binding a moniker.

If you want to modify the values of these bind options, you can do so by passing a BIND_OPTS2structure to the IBindCtx::SetBindOptionsmethod. Moniker implementers can pass a BIND_OPTS2structure to the IBindCtx::GetBindOptionsmethod to retrieve the values of these bind options.

The BIND_OPTS2structure is defined in Objidl.h

Syntax 

typedef struct tagBIND_OPTS2 {
  DWORD 
cbStruct;
  DWORD 
grfFlags;
  DWORD 
grfMode;
  DWORD 
dwTickCountDeadline;
  DWORD 
dwTrackFlags;
  DWORD 
dwClassContext;
  LCID 
locale;
  COSERVERINFO* 
pServerInfo;
} BIND_OPTS2, *LPBIND_OPTS2;

Members

cbStruct

Size of this structure in bytes (that is, the size of the BIND_OPTS2structure).

grfFlags

Flags that control aspects of moniker binding operations.

This value is any combination of the bit flags in the BIND_FLAGSenumeration.

New values can be defined in the future, so moniker implementations should ignore bits in this member that they do not understand.

The CreateBindCtxfunction initializes this member to zero.

grfMode

Flags that should be used when opening the file that contains the object identified by the moniker.

The values are taken from the STGMenumeration.

The binding operation uses these flags in the call to IPersistFile::Loadwhen loading the file.

If the object is running, these flags are ignored by the binding operation.

The CreateBindCtxfunction initializes this field to STGM_READWRITE.

dwTickCountDeadline

Clock time (in milliseconds, as returned by the GetTickCountfunction) by which the caller wants the binding operation to be completed.

This member lets the caller limit the execution time of an operation when speed is of primary importance.

A value of zero indicates that there is no deadline.

Callers most often use this capability when calling the IMoniker::GetTimeOfLastChangemethod, although it can be usefully applied to other operations as well.

The CreateBindCtxfunction initializes this member to zero.

Typical deadlines allow for a few hundred milliseconds of execution. This deadline is a recommendation, not a requirement; however, operations that exceed their deadline by a large amount can cause delays for the user.

Each moniker implementation should try to complete its operation by the deadline or fail with the error MK_E_EXCEEDEDDEADLINE.

If a binding operation exceeds its deadline because one or more objects that it needs are not running, the moniker implementation should register the objects responsible in the bind context using the IBindCtx::RegisterObjectParam.

The objects should be registered under the parameter names "ExceededDeadline," "ExceededDeadline1," "ExceededDeadline2," and so on.

If the caller later finds the object in the Running Object Table, the caller can retry the binding operation.

The GetTickCountfunction indicates the number of milliseconds since system startup and wraps back to zero after 2^31 milliseconds. Consequently, callers should be careful not to inadvertently pass a zero value, which indicates no deadline, and moniker implementations should be aware of clock wrapping problems. For more information, see the GetTickCountfunction.

dwTrackFlags

A moniker can use this value during link tracking.

If the original persisted data that the moniker is referencing has been moved, the moniker can attempt to reestablish the link by searching for the original data though some adequate mechanism.

The dwTrackFlagsmember provides additional information on how the link should be resolved.

dwClassContext

The class context used, taken from the CLSCTXenumeration, instantiate the object.

Monikers typically pass this value to the dwClsContextparameter of CoCreateInstance.

locale

The LCID value indicating the client's preference for the locale used by the object to which they are binding.

A moniker passes this value to IClassActivator::GetClassObject.

pServerInfo

Points to a COSERVERINFOstructure.

This member allows clients calling IMoniker::BindToObjectto specify server information.

Clients can pass a BIND_OPTS2structure to the IBindCtx::SetBindOptionsmethod.

If a server name is specified in the COSERVERINFOstructure, the moniker bind is forwarded to the specified machine.

SetBindOptionsonly copies the structmembers of BIND_OPTS2, not the COSERVERINFOstructure and the pointers it contains. Callers may not free these pointers until the bind context is released.

COM's new class moniker does not honor the pServerInfoflag.

Requirements

Header objidl.h
Windows Embedded CE Windows CE 2.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also