4.3 Updating a Subscription
Figure 3: Updating a subscription
The previous figure shows the sequence of a client application as it updates its subscription. From before, the client knows that its SubscriptionID is B7E3D561-3BB1-46df-B47F-51DF3B307EC9 and its SubscriberCLSID is 19D10A70-1B07-4b76-87B6-99F58DEE37E7.
The client activates the class ID CLSID_EventSystem to get the EventSystem DCOM object on the server.
The client calls a Query with the subscriptions collection.
HRESULT HRESULT Query( [in] BSTR progID= "EventSystem.EventSubscriptionCollection", [in] BSTR queryCriteria = "SubscriberCLSID='{19D10A70-1B07-4b76-87B6-99F58DEE37E7}'", [out] int* errorIndex = {uninitialized}, [out, retval] IUnknown** ppInterface = {uninitialized} );
The server looks in its internal store of subscriptions for a subscription that has the SubscriberCLSID property set to "{19D10A70-1B07-4b76-87B6-99F58DEE37E7}". After the server finds the subscription that has the matching SubscriberCLSID property, it creates a DCOM object for the subscription and populates its state with the subscription properties. The DCOM object is then stored in a collection-based DCOM object that supports the IEventObjectCollection interface. The server returns S_OK with ppInterface, which contains the collection DCOM object.
HRESULT = S_OK Query( [in] BSTR progID = {unchanged}, [in] BSTR queryCriteria = {unchanged}, [out] int* errorIndex = 0, [out, retval] IUnknown** ppInterface = {DCOM object supporting IEventObjectCollection interface} );
The client calls the get_Item method to get the particular subscription for its SubscriptionID. In this example the format of the objectID is correct for a server that implements version 2 of the protocol. Because the client did not explicitly set the PartitionID and ApplicationID properties when it created the subscription, the example uses the default values for these properties.
HRESULT Item( [in] BSTR objectID = "{B7E3D561-3BB1-46df-B47F-51DF3B307EC9}-{00000000- 0000-0000-0000-000000000000}-{00000000-0000-0000-0000-000000000000}", [out,retval] VARIANT* pItem = {uninitialized) );
The server looks in the underlying collection for the subscription DCOM object that has the SubscriptionID property set to "{B7E3D561-3BB1-46df-B47F-51DF3B307EC9}". After the server successfully finds the object, it embeds it in a VARIANT in the punk field, sets the VT_TYPE on the VARIANT to VT_UNKNOWN, and returns S_OK.
HRESULT = S_OK Item( [in] BSTR objectID = {unchanged}, [out,retval] VARIANT* pItem = {vt = VT_UNKNOWN,punk = {DCOM object that supports IEventSubscrption interface} );
The client calls put_Description to update the description of the item.
HRESULT put_Description( [in] BSTR* pbstrDescription = "A custom subscription" );
The server stores the description and returns S_OK.
The client calls Store on the EventSystem DCOM object with the "EventSystem.EventSubscription" string.
HRESULT Store( [in] BSTR ProgID = "EventSystem.EventSubscription", [in] IUnknown* pInterface = {interface pointer to subscription object updated above} );
The server verifies that the description is 255 characters or less, updates the description of the subscription in its local state, and returns S_OK.
Note that the same set of operations can be performed by the client to update an event class.