3.1.4.1.2 Store (Opnum 8)

  • Article

The Store method is called by a client to store either an event class or a subscription.

 [id(2), helpstring("method Store")] HRESULT Store(
   [in] BSTR ProgID,
   [in] IUnknown* pInterface
 );

ProgID: A string that uniquely identifies the kind of object that the client is trying to store. It MUST be one of the following values.

Value

Meaning

"EventSystem.EventClass"

The store for event classes, as specified in section 3.1.1.1.

"EventSystem.EventSubscription"

The store for subscriptions, as specified in section 3.1.1.2.

pInterface: An interface pointer to a DCOM object that was created by performing DCOM activation on the server by the client by using either the CLSID_EventClass (as specified in section 1.9), which represents the CLSID for event class, or CLSID_Subscription (as specified in section 1.9), which represents the subscriber.

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_INVALID_PER_USER_SID MUST be treated the same.

Return value/code

Description

0x80040207

EVENT_E_INVALID_PER_USER_SID

The owner SID, as defined in [MS-DTYP] section 2.4.2, on a per-user subscription does not exist.

When this method is called, the server MUST verify that all the required properties of the event class or of the subscription (properties of the DCOM object that is passed in as part of the pInterface parameter) are specified and are correct.

If this DCOM object is an event class, the server MUST set the EventClassID property to an internally generated value if it has not already been set, it MUST verify that the EventClassName property is set, and it MUST verify that either the Typelib or the FiringInterfaceID property is set. If these verifications fail, the server MUST fail the call and return an HRESULT to the client.

If this DCOM object is a subscription, the server MUST set the SubscriptionID property to an internally generated value if it has not already been set; it MUST verify that the SubscriptionName property is set; it MUST verify that either the EventClassID, the PublisherID, or the InterfaceID property is set; and it MUST verify that the subscription is either transient or persistent. A transient subscription has the SubscriberInterface property set but neither the SubscriberCLSID nor the SubscriberMoniker property set. A persistent subscription has one or both of the SubscriberCLSID and SubscriberMoniker properties set, but the SubscriberInterface property is not set. If these verifications fail, the server MUST fail the call and return an HRESULT to the client.

Otherwise, it MUST take the individual properties of the event class or the subscription, based on the type of store requested, MUST attempt to store these properties in its internal store and MUST fail the call if it cannot. If an entry already exists in the store for the particular object that is represented by the DCOM object instance, the server MUST update its internal store entry with the new values of the subscription or the event class, as specified in the DCOM object instance. If the RetainSubKeys state variable is TRUE, any PublisherProperties or SubscriberProperties within the existing entry that do not exist within the new object instance MUST NOT be deleted by the server. If the RetainSubKeys state variable is FALSE, all PublisherProperties or SubscriberProperties in the existing entry MUST be deleted and replaced by the values in the new object instance. The RetainSubKeys state variable MUST have no effect on entries that do not already exist in the store.

Additional verifications might be required depending on the protocol version and the state of the CatalogMode variable. See the individual cases below for details.

  • Protocol version is 1; CatalogMode is TRUE

    The DCOM object MUST be a transient subscription, meaning that it has the SubscriberInterface property set and neither the SubscriberCLSID nor the SubscriberMoniker property set. If not, 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

    The DCOM object MUST be a transient subscription, meaning that it has the SubscriberInterface property set and neither the SubscriberCLSID nor the SubscriberMoniker property set. If not, 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.

    If the PartitionID property of the object is equal to GUID_NULL or has not been set, the server MUST treat the PartitionID property as if it were set to the default partition identifier value {41E90F3E-56C1-4633-81C3-6E8BAC8BDD70}.

  • Protocol version is 2; CatalogMode is FALSE

    The DCOM object MUST have a PartitionID property equal to GUID_NULL. If not, the server SHOULD fail the call, returning a failure HRESULT to the client.