controlpoint_event.c File Reference

#include <mupnp/controlpoint.h>
#include <mupnp/upnp_limit.h>
#include <mupnp/util/log.h>

Functions
bool	mupnp_controlpoint_seteventlistener (mUpnpControlPoint *ctrlPoint, MUPNP_EVENT_LISTENER evlistener)
mUpnpService *	mupnp_device_getfirstexpiratedservice (mUpnpControlPoint *ctrlPoint, mUpnpDevice *dev, mUpnpTime expirationTime)
void	mupnp_controlpoint_expirationhandler (mUpnpThread *thread)
bool	mupnp_controlpoint_resubscribe (mUpnpControlPoint *ctrlPoint, mUpnpService *service, long timeout)
bool	mupnp_controlpoint_subscribe (mUpnpControlPoint *ctrlPoint, mUpnpService *service, long timeout)
	Subscribe to a UPnP service's event notifications.
bool	mupnp_controlpoint_unsubscribe (mUpnpControlPoint *ctrlPoint, mUpnpService *service)
bool	mupnp_controlpoint_subscribeall (mUpnpControlPoint *ctrlPoint, mUpnpDevice *dev, long timeout)
bool	mupnp_controlpoint_resubscribeall (mUpnpControlPoint *ctrlPoint, mUpnpDevice *dev, long timeout)
bool	mupnp_controlpoint_unsubscribeall (mUpnpControlPoint *ctrlPoint, mUpnpDevice *dev)

Function Documentation

mupnp_controlpoint_expirationhandler()

void mupnp_controlpoint_expirationhandler

(

mUpnpThread *

thread

)

Worker thread for handling expirations.

Parameters

thread

the thread in question

mupnp_controlpoint_resubscribe()

bool mupnp_controlpoint_resubscribe	(	mUpnpControlPoint *	ctrlPoint,
		mUpnpService *	service,
		long	timeout )

Re-subscribe to a service's events (i.e. renew subscription)

Parameters

ctrlPoint	The control point in use
service	The service to subscribe to
timeout	Timeout for subscription expiration/renewal

Returns

true if successful; otherwise false

mupnp_controlpoint_resubscribeall()

bool mupnp_controlpoint_resubscribeall	(	mUpnpControlPoint *	ctrlPoint,
		mUpnpDevice *	dev,
		long	timeout )

Re-subscribe to all of the device's services' events (i.e. renew subscription)

Parameters

ctrlPoint	The control point in use
dev	The device to subscribe to
timeout	Timeout for subscription expiration/renewal

Returns

true if successful; otherwise false

mupnp_controlpoint_seteventlistener()

bool mupnp_controlpoint_seteventlistener	(	mUpnpControlPoint *	ctrlPoint,
		MUPNP_EVENT_LISTENER	evlistener )

Set a single event listener for the control point. Use this function to get event notifications to user-space applications if you need only one listener.

Parameters

ctrlPoint	The control point in question
evlistener	The callback function to set, that is of type MUPNP_EVENT_LISTENER, or NULL

mupnp_controlpoint_subscribe()

bool mupnp_controlpoint_subscribe	(	mUpnpControlPoint *	ctrlPoint,
		mUpnpService *	service,
		long	timeout )

Subscribe to a UPnP service's event notifications.

Sends a SUBSCRIBE request to the service's event subscription URL to receive notifications when the service's state variables change. The service will send an initial event message with current values, followed by updates whenever evented state variables change.

The subscription is identified by a Subscription ID (SID) returned by the service and stored in the service object. Event notifications are received on the control point's HTTP event server and dispatched to registered event listeners.

Subscriptions must be renewed before they expire using mupnp_controlpoint_resubscribe() or they will be automatically cancelled by the service.

Parameters

ctrlPoint	The control point to use. Must not be NULL and must be running.
service	The service to subscribe to. Must not be NULL and must have a valid event subscription URL.
timeout	The requested subscription duration in seconds. Use 0 or negative value for infinite duration (if supported by the service). Typical values: 300-1800 seconds. The service may grant a different duration than requested.

Return values

true	Subscription successful. Check service's SID for subscription ID.
false	Subscription failed due to: NULL parameters Control point not running Network error Service doesn't support eventing Service rejected subscription (e.g., too many subscribers)

Note

Thread-safe: Can be called from any thread, but the control point should be locked if accessing device/service pointers.

Side effect: Updates the service's subscriptionSid and subscriptionTimeout fields on success.

Event notifications are delivered asynchronously via event listener callbacks. Set listeners with mupnp_controlpoint_addeventlistener().

The initial event notification (containing all evented state variables) should arrive shortly after subscription.

Warning

Always unsubscribe before destroying the control point to avoid orphaned subscriptions on the service side.

See also

mupnp_controlpoint_resubscribe()

mupnp_controlpoint_unsubscribe()

mupnp_controlpoint_addeventlistener()

mupnp_service_getsubscriptionsid()

// Example: Subscribe to a service's events
mupnp_controlpoint_lock(ctrlPoint);
mUpnpDevice* dev = mupnp_controlpoint_getdevicebytype(ctrlPoint, "...:MediaServer");
if (dev) {
    mUpnpService* service = mupnp_device_getservicebytype(dev, "ContentDirectory");
    if (service) {
        // Subscribe for 30 minutes
        if (mupnp_controlpoint_subscribe(ctrlPoint, service, 1800)) {
            printf("Subscribed with SID: %s\n", 
                   mupnp_service_getsubscriptionsid(service));
        }
    }
}
mupnp_controlpoint_unlock(ctrlPoint);

mupnp_controlpoint_subscribeall()

bool mupnp_controlpoint_subscribeall	(	mUpnpControlPoint *	ctrlPoint,
		mUpnpDevice *	dev,
		long	timeout )

Subscribe to all of the device's services' events

Parameters

ctrlPoint	The control point in use
dev	The device to subscribe to
timeout	Timeout for subscription expiration/renewal

Returns

true if successful; otherwise false

mupnp_controlpoint_unsubscribe()

bool mupnp_controlpoint_unsubscribe	(	mUpnpControlPoint *	ctrlPoint,
		mUpnpService *	service )

Unsubscribe to a service's events (i.e. cancel subscription)

Parameters

ctrlPoint	The control point in use
service	The service to unsubscribe to

Returns

true if successful; otherwise false

mupnp_controlpoint_unsubscribeall()

bool mupnp_controlpoint_unsubscribeall	(	mUpnpControlPoint *	ctrlPoint,
		mUpnpDevice *	dev )

Unsubscribe to all of the device's services' events (i.e. cancel subscription)

Parameters

ctrlPoint	The control point in use
dev	The device to unsubscribe to

Returns

true if successful; otherwise false

mupnp_device_getfirstexpiratedservice()

mUpnpService * mupnp_device_getfirstexpiratedservice	(	mUpnpControlPoint *	ctrlPoint,
		mUpnpDevice *	dev,
		mUpnpTime	expirationTime )