Share via

3.1.4.1.1 Query (Opnum 7)

  • Article

The Query method is called by a client to query a collection for a collection of event classes or subscriptions.

 [id(1), helpstring("method Query")] HRESULT Query(
   [in] BSTR progID,
   [in] BSTR queryCriteria,
   [out] int* errorIndex,
   [out, retval] IUnknown** ppInterface
 );

progID: A string that identifies the type of collection. The value MUST be one of the following.

Value

Meaning

"EventSystem.EventClassCollection"

The store for event classes (as specified in section 3.1.1.1).

"EventSystem.EventSubscriptionCollection"

The store for subscriptions (as specified in section 3.1.1.2).

queryCriteria: The actual query string. The syntax for this string MUST conform to section 2.2.1.

errorIndex: The zero-based character index in the queryCriteria parameter where an error has occurred. This can occur if the syntax of the query string is incorrect, in which case errorIndex specifies the index at which the problematic syntax is present in the queryCriteria parameter.

ppInterface: If the method returns a success HRESULT, this MUST contain an interface pointer that represents the collection of the event classes or subscriptions based on the criteria specified in the queryCriteria parameter.

Return Values: An HRESULT that specifies success or failure. All success codes MUST be treated the same, and all failure codes other than EVENT_E_QUERYSYNTAX and EVENT_E_QUERYFIELD MUST be treated the same.

Return value/code

Description

0x80040203

EVENT_E_QUERYSYNTAX

A syntax error occurred while trying to evaluate a query string.

0x80040204

EVENT_E_QUERYFIELD

An invalid field name was used in a query string.

When this method is called, the server MUST use the progID parameter value to determine the store against which the query needs to be executed and validate the query. If the specified collection is not valid or if the specified query is not valid, the server MUST fail the call and return a failure HRESULT back to the client. Otherwise, the server MUST attempt to use the queryCriteria parameter to retrieve a collection of event classes or subscriptions based on the value of the progID parameter and fail the call if it cannot. Each of the objects in the collection MUST be wrapped by a DCOM object that MUST support the IEventClass and IEventClass2 interfaces and MAY<8> support the IEventClass3 interface if the object is an event class. It MUST support IEventSubscription and IEventSubscription2, and MAY<9> support IEventSubscription3 if it is a subscription object. These DCOM objects MUST be encapsulated into a collection-based DCOM object that supports the IEventObjectCollection interface. This object MUST be returned through the ppInterface parameter.