UPnP Service. More...

#include <PltService.h>

Collaboration diagram for PLT_Service:

Public Member Functions
	PLT_Service (PLT_DeviceData device, const char type, const char id, const char name, const char *last_change_namespace=NULL)
	Create an instance of a UPnP Service either hosted or discovered. More...

NPT_Result	InitURLs (const char *service_name)
	When service is hosted by a PLT_DeviceHost, this setups the SCPD, control and event urls. More...

bool	IsValid ()
	Verify the service has been properly initialized or is a valid discovered service. More...

NPT_Result	PauseEventing (bool pause=true)
	When a PLT_DeviceHost needs to change more than one state variables at a time but would rather send only one event with all state variable changes, this can be used to pause and resume the automatic eventing. More...

NPT_Result	SetSCPDURL (const char *url)
	Set the SCPD url for control points to be able to fetch the SCPD xml document. More...

NPT_Result	SetControlURL (const char *url)

NPT_Result	SetEventSubURL (const char *url)
	Set the Service Event subscription url for control points to be able to subscribe to events. More...

NPT_String	GetSCPDURL (bool absolute=false)
	Return the SCPD url associated with this service. More...

NPT_String	GetControlURL (bool absolute=false)
	Return the Control url associated with this service. More...

NPT_String	GetEventSubURL (bool absolute=false)
	Return the Event subscription url associated with this service. More...

const NPT_String &	GetServiceID () const
	Return the service id. More...

const NPT_String &	GetServiceType () const
	Return the service type. More...

const NPT_String &	GetServiceName () const
	Return the service friendly name. More...

PLT_DeviceData *	GetDevice ()
	Return the PLT_DeviceData* the service is associated with. More...

NPT_Result	ForceVersion (NPT_Cardinal version)
	When a control point discover a new service with a higher version number than it can work with, a lower version can be set to force backward compatibility. More...

NPT_Result	GetSCPDXML (NPT_String &xml)
	Return the service SCPD xml document. More...

NPT_Result	SetSCPDXML (const char *xml)
	Set the service SCPD xml document. More...

NPT_Result	GetDescription (NPT_XmlElementNode parent, NPT_XmlElementNode *service=NULL)
	Populate the UPnP Device description document with service information. More...

NPT_Result	SetStateVariable (const char name, const char value, const bool clearonsend=false)
	Set a new value for a given state variable. More...

NPT_Result	SetStateVariableRate (const char *name, NPT_TimeInterval rate)
	Certain state variables notifications must not be sent faster than a certain rate according to the UPnP specs. More...

NPT_Result	SetStateVariableExtraAttribute (const char name, const char key, const char *value)
	Certain state variables require extra xml attributes when serialized. More...

NPT_Result	IncStateVariable (const char *name)
	Helper function to increment a state variable representing a number. More...

PLT_StateVariable *	FindStateVariable (const char *name)
	Return the PLT_StateVariable pointer given a state variable name. More...

NPT_Result	GetStateVariableValue (const char *name, NPT_String &value)
	Return the state variable value given a state variable name. More...

bool	IsSubscribable ()
	Return whether a service is capable of sending events. More...

const NPT_List< PLT_StateVariable * > &	GetStateVariables () const
	Return the list of state variables. More...

PLT_ActionDesc *	FindActionDesc (const char *name)
	Return the PLT_ActionDesc given an action name. More...

const NPT_Array< PLT_ActionDesc * > &	GetActionDescs () const
	Return an array of actions descriptions PLT_ActionDesc. More...

Static Public Member Functions
static bool	IsTrue (const NPT_String &value)

Protected Attributes
PLT_DeviceData *	m_Device

NPT_String	m_ServiceType

NPT_String	m_ServiceID

NPT_String	m_ServiceName

NPT_String	m_SCPDURL

NPT_String	m_ControlURL

NPT_String	m_EventSubURL

PLT_ServiceEventTask *	m_EventTask

NPT_Array< PLT_ActionDesc * >	m_ActionDescs

NPT_List< PLT_StateVariable * >	m_StateVars

NPT_Mutex	m_Lock

NPT_List< PLT_StateVariable * >	m_StateVarsChanged

NPT_List< PLT_StateVariable * >	m_StateVarsToPublish

NPT_List< PLT_EventSubscriberReference >	m_Subscribers

bool	m_EventingPaused

NPT_String	m_LastChangeNamespace

Friends
class	PLT_StateVariable

class	PLT_DeviceHost

Detailed Description

UPnP Service.

The PLT_Service class holds information about a UPnP service of a given device. It maintains a list of actions and state variables. A PLT_DeviceData instance can own one or more PLT_Service instances. When a PLT_Service is advertised as part of a a UPnP Device (PLT_DeviceHost), it also maintains a list of subscribers to nofify when state variables change.

Constructor & Destructor Documentation

◆ PLT_Service()

PLT_Service::PLT_Service	(	PLT_DeviceData *	device,
		const char *	type,
		const char *	id,
		const char *	name,
		const char *	last_change_namespace = `NULL`
	)

Create an instance of a UPnP Service either hosted or discovered.

Parameters

device	Pointer to the PLT_DeviceData the service is associated to
type	String representing the UPnP service type
id	String representing the UPnP service id
name	A String to create unique service SCPD, control and eventing urls
last_change_namespace	A String for the LastChange state variable namespace if any

Member Function Documentation

◆ FindActionDesc()

PLT_ActionDesc * PLT_Service::FindActionDesc ( const char * name )

Return the PLT_ActionDesc given an action name.

Parameters

name	action name

Returns: PLT_ActioDesc pointer

◆ FindStateVariable()

PLT_StateVariable * PLT_Service::FindStateVariable ( const char * name )

Return the PLT_StateVariable pointer given a state variable name.

Parameters

name	state variable name

Returns: PLT_StateVariable pointer

◆ ForceVersion()

NPT_Result PLT_Service::ForceVersion ( NPT_Cardinal version )

When a control point discover a new service with a higher version number than it can work with, a lower version can be set to force backward compatibility.

Parameters

version Integer specifying the version to use

◆ GetActionDescs()

const NPT_Array<PLT_ActionDesc*>& PLT_Service::GetActionDescs ( ) const

inline

Return an array of actions descriptions PLT_ActionDesc.

Returns: array of PLT_ActionDesc pointers.

◆ GetControlURL()

NPT_String PLT_Service::GetControlURL ( bool absolute = false )

Return the Control url associated with this service.

Parameters

absolute flag to indicate if absolute url including ip and port should be returned

Returns: Control url

◆ GetDescription()

NPT_Result PLT_Service::GetDescription	(	NPT_XmlElementNode *	parent,
		NPT_XmlElementNode **	service = `NULL`
	)

Populate the UPnP Device description document with service information.

Parameters

parent	XML Element where to insert the service XML Element
service	Pointer to service XML Element node newly created so it can be extended with additional non standard information.

◆ GetDevice()

PLT_DeviceData* PLT_Service::GetDevice ( )

inline

Return the PLT_DeviceData* the service is associated with.

Returns: PLT_DeviceData pointer

◆ GetEventSubURL()

NPT_String PLT_Service::GetEventSubURL ( bool absolute = false )

Return the Event subscription url associated with this service.

Parameters

absolute flag to indicate if absolute url including ip and port should be returned

Returns: Event url

◆ GetSCPDURL()

NPT_String PLT_Service::GetSCPDURL ( bool absolute = false )

Return the SCPD url associated with this service.

Parameters

absolute flag to indicate if absolute url including ip and port should be returned

Returns: SCPD url

◆ GetSCPDXML()

NPT_Result PLT_Service::GetSCPDXML ( NPT_String & xml )

Return the service SCPD xml document.

Parameters

xml	String to receive document

◆ GetServiceID()

const NPT_String& PLT_Service::GetServiceID ( ) const

inline

Return the service id.

Returns: service id

◆ GetServiceName()

const NPT_String& PLT_Service::GetServiceName ( ) const

inline

Return the service friendly name.

Returns: service name

◆ GetServiceType()

const NPT_String& PLT_Service::GetServiceType ( ) const

inline

Return the service type.

Returns: service type

◆ GetStateVariables()

const NPT_List<PLT_StateVariable*>& PLT_Service::GetStateVariables ( ) const

inline

Return the list of state variables.

Returns: list of state variable pointers.

◆ GetStateVariableValue()

NPT_Result PLT_Service::GetStateVariableValue	(	const char *	name,
		NPT_String &	value
	)

Return the state variable value given a state variable name.

Parameters

name	state variable name
value	state variable value output

◆ IncStateVariable()

NPT_Result PLT_Service::IncStateVariable ( const char * name )

Helper function to increment a state variable representing a number.

Parameters

name	state variable name

◆ InitURLs()

NPT_Result PLT_Service::InitURLs ( const char * service_name )

When service is hosted by a PLT_DeviceHost, this setups the SCPD, control and event urls.

Parameters

service_name the service name used to format unique urls

◆ IsSubscribable()

bool PLT_Service::IsSubscribable ( )

Return whether a service is capable of sending events.

Returns: true if sending events

◆ IsValid()

bool PLT_Service::IsValid ( )

inline

Verify the service has been properly initialized or is a valid discovered service.

Returns: true if valid.

◆ PauseEventing()

NPT_Result PLT_Service::PauseEventing ( bool pause = true )

When a PLT_DeviceHost needs to change more than one state variables at a time but would rather send only one event with all state variable changes, this can be used to pause and resume the automatic eventing.

Parameters

pause Flag to indicate if eventing should be paused or resumed

◆ SetEventSubURL()

NPT_Result PLT_Service::SetEventSubURL ( const char * url )

inline

Set the Service Event subscription url for control points to be able to subscribe to events.

Parameters

url	relative path of even url

◆ SetSCPDURL()

NPT_Result PLT_Service::SetSCPDURL ( const char * url )

inline

Set the SCPD url for control points to be able to fetch the SCPD xml document.

Parameters

url	relative path of SCPD url

◆ SetSCPDXML()

NPT_Result PLT_Service::SetSCPDXML ( const char * xml )

Set the service SCPD xml document.

Parameters

xml	String SCPD xml document

◆ SetStateVariable()

NPT_Result PLT_Service::SetStateVariable	(	const char *	name,
		const char *	value,
		const bool	clearonsend = `false`
	)

Set a new value for a given state variable.

The service keeps track of which state variables have changed and events are being triggered by a PLT_ServiceEventTask when necessary.

Parameters

name	state variable name
value	new State Variable value.
clearonsend	whether the State Variable should clear immediatly in ::OnSendingCompleted

◆ SetStateVariableExtraAttribute()

NPT_Result PLT_Service::SetStateVariableExtraAttribute	(	const char *	name,
		const char *	key,
		const char *	value
	)

Certain state variables require extra xml attributes when serialized.

Parameters

name	state variable name
key	the attribute name
value	the attribute value

◆ SetStateVariableRate()

NPT_Result PLT_Service::SetStateVariableRate	(	const char *	name,
		NPT_TimeInterval	rate
	)

Certain state variables notifications must not be sent faster than a certain rate according to the UPnP specs.

This sets the rate for a given state variable.

Parameters

name	state variable name
rate	a time interval specifying the minimum interval allowed between notifications.

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

lib/libUPnP/Platinum/Source/Core/PltService.h
lib/libUPnP/Platinum/Source/Core/PltService.cpp

Public Member Functions

Static Public Member Functions

Protected Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ PLT_Service()

Member Function Documentation

◆ FindActionDesc()

◆ FindStateVariable()

◆ ForceVersion()

◆ GetActionDescs()

◆ GetControlURL()

◆ GetDescription()

◆ GetDevice()

◆ GetEventSubURL()

◆ GetSCPDURL()

◆ GetSCPDXML()

◆ GetServiceID()

◆ GetServiceName()

◆ GetServiceType()

◆ GetStateVariables()

◆ GetStateVariableValue()

◆ IncStateVariable()

◆ InitURLs()

◆ IsSubscribable()

◆ IsValid()

◆ PauseEventing()

◆ SetEventSubURL()

◆ SetSCPDURL()

◆ SetSCPDXML()

◆ SetStateVariable()

◆ SetStateVariableExtraAttribute()

◆ SetStateVariableRate()