IEventSource::Advise (Windows Embedded CE 6.0)

1/6/2010

This method is called to provide an IEventSink pointer that the service calls to notify subscribers of state variable changes.

Syntax

virtual DWORD Advise(
  IEventSink *pSubscriber
) = 0;

Parameters

• pSubscriber
  [in] Pointer to an IEventSink pointer that contains the IEventSink::OnStateChanged method to be called when state variables change.

Return Value

Custom implementations can return appropriate error codes. If the method succeeds, it should return SUCCESS_AV. Otherwise, it should return an error code defined in WinError.h or UPnP.h, or one of the UPnP AV-specific return values specified in UPnPAVError.

Remarks

Control points and other applications call this method to provide an IEventSink implementation that contains the code to be executed when a state variable changes.

Services implement this method by storing the passed IEventSink implementation and then sending initial state variable values by calling OnStateChange.

The implementation of this method provided by the UPnP AV Framework uses UPnP event subscriptions and UPnP event notifications to connect control points and device services. Calls to Advise in a control point are handled by a control point proxy that uses UPnP eventing to notify the service of a subscription. The provided device proxy receives the UPnP event subscription and in turn calls the service's Advise implementation.

Therefore, the IEventSink implementation that a control point passes is not the same as the IEventSink implementation that the service receives. Instead, custom code interacts with proxy classes that communicate with each other.

Although multiple control points can subscribe to events from a single service, and pass multiple IEventSink implementations, the UPnP AV Framework device proxy hides the multiple client IEventSink implementations and passes a single IEventSink pointer to the service's Advise implementation. When the service calls OnStateChanged on the single reference, the UPnP AV Framework translates this call into event notifications for all subscribed control points.

In most cases, the Advise implementation should store the passed IEventSink pointer and then immediately call OnStateChanged some number of times to notify the subscriber of the current state of all variables. This meets the UPnP requirement that a new subscription result in the eventing of the current state. (The exception to this rule is in a class that derives from IConnectionManagerImpl. In this case, because IConnectionManagerImpl handles all eventing, the derived class should simply save the pointer and should not send any initial events.)

For an example implementation of Advise in a device, see the AV Renderer sample. For example control point calls to Advise, see the AV Control Point Sample.

Both examples are explained in more detail in Windows Embedded CE topic UPnP Samples.

For more information about state variables defined for each service, see UPnP AV DCP Documentation.

Requirements

See Also

Reference

IEventSource
IConnectionManagerImpl
IEventSink
IEventSink::OnStateChanged
UPnPAVError

Concepts

Eventing in the UPnP AV Framework