Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

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

Syntax 

virtual DWORD Advise(
  IEventSink *
pSubscriber
) = 0;

Parameters

pSubscriber

[in] Pointer to an IEventSinkpointer that contains the IEventSink::OnStateChangedmethod 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 IEventSinkimplementation that contains the code to be executed when a state variable changes.

Services implement this method by storing the passed IEventSinkimplementation 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 Advisein 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 Adviseimplementation.

Therefore, the IEventSinkimplementation that a control point passes is not the same as the IEventSinkimplementation 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 IEventSinkimplementations, the UPnP AV Framework device proxy hides the multiple client IEventSinkimplementations and passes a single IEventSinkpointer to the service's Adviseimplementation. When the service calls OnStateChangedon the single reference, the UPnP AV Framework translates this call into event notifications for all subscribed control points.

In most cases, the Adviseimplementation should store the passed IEventSinkpointer and then immediately call OnStateChangedsome 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 IConnectionManagerImplhandles all eventing, the derived class should simply save the pointer and should not send any initial events.)

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

Requirements

Header av_upnp.h
Library Av_upnp.lib
Windows Embedded CE Windows CE 5.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also