Subscribe and receive events from a service through GENA. More...

Inheritance diagram for org.fourthline.cling.controlpoint.SubscriptionCallback:

Collaboration diagram for org.fourthline.cling.controlpoint.SubscriptionCallback:

Public Member Functions
Service	getService ()

synchronized ControlPoint	getControlPoint ()

synchronized void	setControlPoint (ControlPoint controlPoint)

synchronized GENASubscription	getSubscription ()

synchronized void	setSubscription (GENASubscription subscription)

synchronized void	run ()

synchronized void	end ()

String	toString ()

Static Public Member Functions
static String	createDefaultFailureMessage (UpnpResponse responseStatus, Exception exception)

Protected Member Functions
	SubscriptionCallback (Service service)

	SubscriptionCallback (Service service, int requestedDurationSeconds)

void	failed (GENASubscription subscription, UpnpResponse responseStatus, Exception exception)

abstract void	failed (GENASubscription subscription, UpnpResponse responseStatus, Exception exception, String defaultMsg)
	Called when establishing a local or remote subscription failed.

abstract void	established (GENASubscription subscription)
	Called when a local or remote subscription was successfully established.

abstract void	ended (GENASubscription subscription, CancelReason reason, UpnpResponse responseStatus)
	Called when a local or remote subscription ended, either on user request or because of a failure.

abstract void	eventReceived (GENASubscription subscription)
	Called when an event for an established subscription has been received.

abstract void	eventsMissed (GENASubscription subscription, int numberOfMissedEvents)
	Called when a received event was out of sequence, indicating that events have been missed.

void	invalidMessage (RemoteGENASubscription remoteGENASubscription, UnsupportedDataException ex)
	Called when a received event message could not be parsed successfully.

Protected Attributes
final Service	service

final Integer	requestedDurationSeconds

Detailed Description

Subscribe and receive events from a service through GENA.

Usage example, establishing a subscription with a org.fourthline.cling.model.meta.Service:

SubscriptionCallback callback = new SubscriptionCallback(service, 600) { // Timeout in seconds

     public void established(GENASubscription sub) {
         System.out.println("Established: " + sub.getSubscriptionId());
     }

     public void failed(GENASubscription sub, UpnpResponse response, Exception ex) {
         System.err.println(
             createDefaultFailureMessage(response, ex)
         );
     }

     public void ended(GENASubscription sub, CancelReason reason, UpnpResponse response) {
         // Reason should be null, or it didn't end regularly
     }

     public void eventReceived(GENASubscription sub) {
         System.out.println("Event: " + sub.getCurrentSequence().getValue());
         Map<String, StateVariableValue> values = sub.getCurrentValues();
         StateVariableValue status = values.get("Status");
         System.out.println("Status is: " + status.toString());
     }

     public void eventsMissed(GENASubscription sub, int numberOfMissedEvents) {
         System.out.println("Missed events: " + numberOfMissedEvents);
     }
};

upnpService.getControlPoint().execute(callback);

Author: Christian Bauer

Member Function Documentation

◆ createDefaultFailureMessage()

static String org.fourthline.cling.controlpoint.SubscriptionCallback.createDefaultFailureMessage	(	UpnpResponse	responseStatus,
		Exception	exception
	)

static

Parameters

responseStatus	The (HTTP) response or `null` if there was no response.
exception	The exception or `null` if there was no exception.

Returns: A human-friendly error message.

◆ ended()

abstract void org.fourthline.cling.controlpoint.SubscriptionCallback.ended	(	GENASubscription	subscription,
		CancelReason	reason,
		UpnpResponse	responseStatus
	)

abstractprotected

Called when a local or remote subscription ended, either on user request or because of a failure.

Parameters

subscription	The ended subscription instance.
reason	If the subscription ended regularly (through `end()`), this is `null`.
responseStatus	For a remote subscription, if the cause implies a remopte response and it was received, this is it (e.g. renewal failure response).

◆ established()

abstract void org.fourthline.cling.controlpoint.SubscriptionCallback.established ( GENASubscription subscription )

abstractprotected

Called when a local or remote subscription was successfully established.

Parameters

subscription The successful subscription.

◆ eventReceived()

abstract void org.fourthline.cling.controlpoint.SubscriptionCallback.eventReceived ( GENASubscription subscription )

abstractprotected

Called when an event for an established subscription has been received.

Use the org.fourthline.cling.model.gena.GENASubscription#getCurrentValues() method to obtain the evented state variable values.

Parameters

subscription The established subscription with fresh state variable values.

◆ eventsMissed()

abstract void org.fourthline.cling.controlpoint.SubscriptionCallback.eventsMissed	(	GENASubscription	subscription,
		int	numberOfMissedEvents
	)

abstractprotected

Called when a received event was out of sequence, indicating that events have been missed.

It's up to you if you want to react to missed events or if you (can) silently ignore them.

Parameters

subscription	The established subscription.
numberOfMissedEvents	The number of missed events.

◆ failed()

abstract void org.fourthline.cling.controlpoint.SubscriptionCallback.failed	(	GENASubscription	subscription,
		UpnpResponse	responseStatus,
		Exception	exception,
		String	defaultMsg
	)

abstractprotected

Called when establishing a local or remote subscription failed.

To get a nice error message that transparently detects local or remote errors use createDefaultFailureMessage().

Parameters

subscription	The failed subscription object, not very useful at this point.
responseStatus	For a remote subscription, if a response was received at all, this is it, otherwise `null`.
exception	For a local subscription and failed creation of a remote subscription protocol (before sending the subscribe request), any exception that caused the failure, otherwise `null`.
defaultMsg	A user-friendly error message.

See also: #createDefaultFailureMessage

◆ invalidMessage()

void org.fourthline.cling.controlpoint.SubscriptionCallback.invalidMessage	(	RemoteGENASubscription	remoteGENASubscription,
		UnsupportedDataException	ex
	)

protected

Called when a received event message could not be parsed successfully.

This typically indicates a broken device which is not UPnP compliant. You can react to this failure in any way you like, for example, you could terminate the subscription or simply create an error report/log.

The default implementation will log the exception at INFO level, and the invalid XML at FINE level.

Parameters

remoteGENASubscription	The established subscription.
ex	Call `org.fourthline.cling.model.UnsupportedDataException#getData()` to access the invalid XML.

The documentation for this class was generated from the following file:

/github/workspace/yaacc/src/main/java/org/fourthline/cling/controlpoint/SubscriptionCallback.java

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Member Function Documentation

◆ createDefaultFailureMessage()

◆ ended()

◆ established()

◆ eventReceived()

◆ eventsMissed()

◆ failed()

◆ invalidMessage()