共用方式為

3.1.4.1.3 Remove (Opnum 9)

  • 發行項

The Remove method is called by a client to remove a collection of event classes or subscriptions by criteria represented by a query string in the queryCriteria parameter.

 [id(3), helpstring("method Remove")] HRESULT Remove(
   [in] BSTR progID,
   [in] BSTR queryCriteria,
   [out] int* errorIndex
 );

progID: A string that uniquely 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 the errorIndex specifies the index at which the problematic syntax is present in the queryCriteria parameter.

Return Values: An HRESULT specifying success or failure. All success codes MUST be treated the same, and all failure codes other than EVENT_E_QUERYSYNTAX, EVENT_E_QUERYFIELD, and EVENT_E_NOT_ALL_REMOVED 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.

0x8004020B

EVENT_E_NOT_ALL_REMOVED

Not all of the requested objects could be removed.

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 the specified query is not valid, the server MUST fail the call, returning a failure HRESULT to the client.

Otherwise, if they are valid, the server MUST use the queryCriteria parameter to determine the event classes or subscriptions that need to be removed. If none of the entries in the internal store matched the query criteria, the server MUST fail the call.

Otherwise, the server will validate the entries in the query according to the following verification cases:

  • Protocol version is 1; CatalogMode is TRUE

    If the query includes anything other than subscriptions with the SubscriberInterface property set (transient subscriptions), the server MAY fail the call, returning a failure HRESULT to the client. If the server does not fail the call, the server behavior is undefined.

  • Protocol version is 1; CatalogMode is FALSE

    No additional verification.

  • Protocol version is 2; CatalogMode is TRUE

    If the query includes anything other than subscriptions with the PartitionID property not equal to GUID_NULL and with the SubscriberInterface property set (transient subscriptions), the server MAY fail the call, returning a failure HRESULT to the client. If the server does not fail the call, the server behavior is undefined.

  • Protocol version is 2; CatalogMode is FALSE

    If the query includes anything other than event classes and subscriptions with the PartitionID property equal to GUID_NULL, the server SHOULD fail the call, returning a failure HRESULT to the client.

If the verification succeeds, the server MUST attempt to remove the event classes or subscriptions from its internal collection and fail the call if it cannot.