Export (0) Print
Expand All

IMultiInterfaceEventControl::GetSubscriptions method

Retrieves the collection of subscription objects associated with an event method.

Syntax


HRESULT GetSubscriptions(
  [in]           REFIID eventIID,
  [in]           BSTR bstrMethodName,
  [in]           BSTR optionalCriteria,
  [in]           int *optionalErrorIndex,
  [out, retval]  IEventObjectCollection **ppCollection
);

Parameters

eventIID [in]

The interface identifier of the firing interface.

bstrMethodName [in]

The event method associated with the subscription collection.

optionalCriteria [in]

A string specifying the query criteria. If this parameter is NULL, the default query specified by the SetDefaultQuery method is used. For details on forming a valid expression for this parameter, see the Remarks section below.

optionalErrorIndex [in]

The location, expressed as an offset, of an error in the optionalCriteria parameter. This parameter cannot be NULL.

ppCollection [out, retval]

The address of a pointer to an IEventObjectCollection interface on a collection object that enumerates the subscriptions associated with the event object.

Return value

This method can return the standard return values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and E_FAIL, as well as the following values.

Return codeDescription
S_OK

The method completed successfully.

EVENT_E_QUERYSYNTAX

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

EVENT_E_QUERYFIELD

An invalid field name was used in a query string.

EVENT_E_INTERNALEXCEPTION

An unexpected exception was raised.

EVENT_E_INTERNALERROR

An unexpected internal error was detected.

 

Remarks

This method is a more specialized form of the IEventSystem::Query method. In addition to obtaining only subscription objects, a collection obtained by calling GetSubscriptions is automatically updated whenever the subscription collection changes.

The query criteria specified by the optionalCriteria parameter can be "ALL", to specify a request for all subscription objects, or a Boolean expression denoting one or more conditions a subscription object must meet to be included in the query result. Valid expressions are of the following form: [NOT] propertynamerelationalOperatorvalue. Valid relational operators are as follows: ==, =, !=, <>, ~=. Valid values are "string", 'string', {GUID}, TRUE, FALSE, NULL.

Individual Boolean expressions can be joined with AND or OR. Expressions can be nested in parentheses to enforce a specific order of evaluation.

Following are some examples of valid query criteria:

"EventClassID == {F89859D1-6565-11D1-88C8-0080C7D771BF}"

"EventClassID == {F89859D1-6565-11D1-88C8-0080C7D771BF} AND MethodName = 'StockPriceChange'"

Requirements

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

EventSys.h

IDL

EventSys.idl

See also

IMultiInterfaceEventControl

 

 

Community Additions

ADD
Show:
© 2015 Microsoft