See Also
 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. |
This method fills a caller-provided array of structures with pointers to multiple interfaces.
Calling this method is equivalent to issuing a series of separate QueryInterfacecalls except that you do not incur the overhead of a corresponding number of RPC calls.
In multithreaded applications and distributed environments, keeping RPC calls to a minimum is essential for optimal performance.
Syntax
HRESULT QueryMultipleInterfaces( ULONG cMQIs, MULTI_QI* pMQIs ); |
Parameters
- cMQIs
-
[in] Pointer to the number of elements in an array of MULTI_QIstructures, each of which contains the IID of a single interface.
- pMQIs
-
[in, out] Pointer to the first MULTI_QIstructure in the array.
Return Value
- S_OK
-
Pointers were returned to all requested interfaces.
- S_FALSE
-
Pointers were returned to some, but not all, of the requested interfaces.
- E_NOINTERFACE
-
Pointers were returned to none of the requested interfaces.
Remarks
The QueryMultipleInterfacesmethod takes as input an array of MULTI_QIstructures. Each structure specifies an interface IID and contains two additional blank members for receiving an interface pointer and return value.
This method obtains as many requested interface pointers as possible directly from the object proxy.
For each interface not implemented on the proxy, the method calls the server to obtain a pointer.
Upon receiving an interface pointer from the server, the method builds a corresponding interface proxy and returns its pointer along with pointers to the interfaces it already implements.
To determine whether the platform supports this interface, see Determining Supported COM APIs.
Notes to Callers
A caller should begin by querying the object proxy for the IMultiQIinterface. If the object proxy returns a pointer to this interface, the caller should then create a MULTI_QIstructure for each interface it wants to obtain.
Each structure should specify an interface IID and set its pItfmember to NULL. Failure to set the pItfmember to NULL will cause the object proxy to ignore the structure.
On return, QueryMultipleInterfaceswrites the requested interface pointer and a return value into each MULTI_QIstructure in the client's array. The pItfmember receives the pointer; the hrmember receives the return value.
If the value returned from a call to QueryMultipleInterfacesis S_OK, then pointers were returned for all requested interfaces.
If the return value is E_NOINTERFACE, then pointers were returned for none of the requested interfaces.
If the return value is S_FALSE, then pointers to one or more requested interfaces were not returned. In this event, the client should check the hrmember of each MULTI_QIstructure to determine which interfaces were acquired and which were not.
If a client knows ahead of time that it will be using several of an object's interfaces, it can call QueryMultipleInterfacesup front and then, later, if a QueryInterfaceis done for one of the interfaces already acquired through QueryMultipleInterfaces, no RPC call will be necessary.
On return, the caller should check the hrmember of each MULTI_QIstructure to determine which interface pointers were and were not returned.
The client is responsible for releasing each of the acquired interfaces by calling Release.
Requirements
| Header | objidl.h, objidl.idl |
| Library | ole32.lib, uuid.lib |
| Windows Embedded CE | Windows CE 3.0 and later |
| Windows Mobile | Windows Mobile Version 5.0 and later |