IBindStatusCallback::GetBindInfo method

Provides information about how the bind operation is handled when it is called by an asynchronous moniker.

Syntax

HRESULT GetBindInfo(
  [out]     DWORD    *grfBINDF,
  [in, out] BINDINFO *pbindinfo
);

Parameters

• grfBINDF [out]
  The address of an unsigned integer value that contains a combination of values that are taken from the BINDF enumeration and indicate how the bind process is handled.

• pbindinfo [in, out]
  The address of the BINDINFO structure, which describes the client application's requirements for binding.

Return value

Returns S_OK if successful, or E_INVALIDARG if one or more parameters are invalid.

Remarks

The moniker calls this method in its implementations of the IMoniker::BindToObject method and the IMoniker::BindToStorage method to get information about the specific bind operation.

Asynchronous moniker clients should be aware that a moniker might call this method more than one time during a bind operation. A proper implementation of IBindStatusCallback::GetBindInfo prepares for this possibility. If data is returned in the pbindinfo parameter, the implementation should allocate the appropriate data (szExtraInfo or stgmedData) at the time of each call. In this way, if the callback isn't called, data isn't allocated; if the callback is called more than one time, it works correctly. The first time this callback is received by the asynchronous moniker client is prior to the call to IMoniker::BindToStorage or IMoniker::BindToObject.

Even when the value of grfBindInfoF is BINDF_ASYNCHRONOUS, it is possible that the original call to IMoniker::BindToStorage or IMoniker::BindToObject might return synchronously, instead of returning the MK_S_ASYNCHRONOUS flag. Clients of asynchronous monikers should always prepare for this possibility. Specifically, to avoid memory leaks, it is important to make sure to release the pointer that is returned by a call to either method.

One way to deal with this issue is to call your own implementation of IBindStatusCallback::OnDataAvailable or IBindStatusCallback::OnObjectAvailable to use the same code path (regardless of whether you bind synchronously or asynchronously).

If the BINDF_PULLDATA value is not set in the grfBindInfoF parameter, Urlmon.dll sets the BINDF_NEEDFILE value. If BINDF_NEEDFILE is set, the binding of resources that cannot be cached (such as an HTTPS resource) fail.

Warning  The size of the BINDINFO structure changed with the release of Microsoft Internet Explorer 4.0. Developers must write code that checks the size of the BINDINFO structure that is passed into their implementation of this method before it writes to members of the structure. For more information, see Handling BINDINFO Structures.

Requirements

See also

IBindStatusCallback

RegisterBindStatusCallback