IBindCtx::SetBindOptions

HRESULT IBindCtx::SetBindOptions(pbindopts)

Store in the bind context a block of parameters that will apply to later IMoniker operations using this bind context. Using block of parameters like this is just an alternative way to pass parameters to an operation. We distinguish the parameters we do for conveyance by this means because (i) they are common to most IMoniker operations, and (ii) these parameters do not change as the operation moves from piece to piece of a generic composite.

Argument	Type	Description
pbindopts	BINDOPTS*	The block of parameters to set. These can later be retrieved with IBindCtx::GetBindOptions.
return value	HRESULT	S_OK, E_OUTOFMEMORY

BINDOPTS is defined as follows:

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

The members of this structure have the following meanings:

Member	Description
grfFlags	A group of Boolean flags. Legal values that may be OR'd together are the taken from the enumeration BINDFLAGS; see below. Moniker implementations must ignore any set-bits in this field that they do not understand.
grfMode	A group of flags that indicates the intended use that the caller has towards the object that he ultimately receives from the associated moniker binding operation. Constants for this member are taken from the STGM enumeration.
	When applied to the IMoniker::BindToObject operation, by far the most significant flag values are: STGM_READ, STGM_WRITE, and STGM_READWRITE. It is possible that some binding operations might make use of the other flags, particularly STGM_DELETEONRELEASE or STGM_CREATE, but such cases are quite esoteric.
	When applied to the IMoniker::BindToStorage operation, most STGM values are potentially useful here.
	The default value for grfMode is STGM_READWRITE \| STGM_SHARE_EXCLUSIVE.
dwTickCount _Deadline	This is an indication of when the caller would like the operation to complete. Having this parameter allows the caller to approximately and heuristically bound the execution time of an operation when it is more important that the operation perform quickly than it is that it perform accurately. Most often, this capability is used with IMoniker::GetTimeOfLastChange, as was previously described, though it can be usefully applied to other operations as well.
	This 32-bit unsigned value is a time in milliseconds on the local clock maintained by the GetTickCount function. A value of zero indicates "no deadline;" callers should therefore be careful not to pass to the bind context a value of zero that was coincidentally obtained from GetTickCount. Clock wrapping is also a problem. Thus, if the value in this variable is less than the current time by more than 2 [to the 31st power] milliseconds, then it should be interpreted as indicating a time in the future of its indicated value plus 2 [to the 32nd power] milliseconds.
	Typical deadlines will allow for a few hundred milliseconds of execution. Each function should try to complete its operation by this time on the clock, or fail with the error MK_E_EXCEEDEDDEADLINE if it cannot do so in the time allotted. Functions are not required to be absolutely accurate in this regard, since it is almost impossible to predict how execution might take (thus, callers cannot rely on the operation completing by the deadline), but operations which exceeded their deadline excessively will usually cause intolerable user delays in the operation of their callers. Thus, in practice, the use of deadlines is a heuristic which callers can impose on the execution of moniker operations.
	If a moniker operation exceeds its deadline because a given object or objects that it uses are not running, and if one of these had been running, then the operation would have completed more of its execution, then the monikers of these objects should be recorded in the bind context using IBindCtx::RegisterObjectParam under the parameter names ExceededDeadline, ExceededDeadline1, ExceededDeadline2, and so forth.; use the first name in this series that is currently unused. This approach gives the caller some knowledge as to when to try the operation again

The enumeration BINDFLAGS, which contains the legal values for the bit field BINDOPTS::grfFlags, is defined as follows:

typedef enum tagBINDFLAGS {
    BINDFLAGS_MAYBOTHERUSER = 1,
    BINDFLAGS_JUSTTESTEXISTENCE = 2,
    } BINDFLAGS;

These flags have the following interpretation.

Value	Description
BINDFLAGS _MAYBOTHERUSER	If not present, then the operation to which the bind context containing this parameter is applied should not interact with the user in any way, such to ask for a password for a network volume that needs mounting. If present, then this sort of interaction is permitted. If prohibited from interacting with the user when it otherwise would like to, an operation may elect to use a different algorithm that does not require user interaction, or it may fail with the error MK_MUSTBOTHERUSER.
BINDFLAGS _JUSTTESTEXISTENCE	If present, indicates that the caller of the moniker operation to which this flag is being applied is not actually interested in having the operation carried out, but only in learning of the operation could have been carried out had this flag not been specified. For example, this flag gives the caller the ability to express that he is only interested in finding out whether an object actually exists by using this flag in a IMoniker::BindToObject call. Moniker implementations are free, however, to ignore this possible optimization and carry out the operation in full. Callers, therefore, need to be able to deal with both cases. See the individual routine descriptions for details of exactly what status is returned.