4.3 Updating a Subscription

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.

  1. The client activates the class ID CLSID_EventSystem to get the EventSystem DCOM object on the server.

  2. 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}
       );
      
      
    
  3. 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}
       );
      
    
  4. 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)  
       );
      
    
  5. 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}
       );
      
    
  6. The client calls put_Description to update the description of the item.

     HRESULT
     put_Description(
       [in] BSTR* pbstrDescription = "A custom subscription"
       );
      
    
  7. The server stores the description and returns S_OK.

  8. 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}
       );
      
    
  9. 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.