BIND_OPTS (Compact 2013)
3/26/2014
This structure contains parameters used during a moniker-binding operation.
The BIND_OPTS2 structure can be used in its place.
A BIND_OPTS structure 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.
If you are a moniker client (that is, if you use a moniker to acquire an interface pointer to an object), you typically do not need to specify values for the members of this structure.
The CreateBindCtx function creates a bind context with the bind options set to default values that are suitable for most situations. The BindMoniker function 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_OPTS structure to the IBindCtx::SetBindOptions method.
Moniker implementers can pass a BIND_OPTS structure to the IBindCtx::GetBindOptions method to retrieve the values of these bind options.
The BIND_OPTS structure is defined in Objidl.h.
Syntax
typedef struct tagBIND_OPTS {
DWORD cbStruct;
DWORD grfFlags;
DWORD grfMode;
DWORD dwTickCountDeadline;
} BIND_OPTS, *LPBIND_OPTS;
Members
- cbStruct
Size of this structure in bytes (that is, the size of the BIND_OPTS structure).
grfFlags
Flags that control aspects of moniker binding operations.This value is a combination of bit flags in the BIND_FLAGS enumeration. New values can be defined, so moniker implementations should ignore bits in this field they do not understand.
The CreateBindCtx function initializes this field 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 STGM enumeration.
The binding operation uses these flags in the call to IPersistFile::Load when loading the file.
If the object is running, these flags are ignored by the binding operation.
The CreateBindCtx function initializes this member to STGM_READWRITE.
dwTickCountDeadline
Clock time (in milliseconds, as returned by the GetTickCount function) 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::GetTimeOfLastChange method, although it can be usefully applied to other operations as well.
The CreateBindCtx function 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 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 GetTickCount function 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 GetTickCount function.
Requirements
Header |
objidl.h |
See Also
Reference
COM Structures and Enumerations
BIND_FLAGS
STGM
BindMoniker
CreateBindCtx
IMoniker::GetTimeOfLastChange
IPersistFile::Load
BIND_OPTS2