Platinum UPnP SDK  1.0.5.13
Public Member Functions | Friends | List of all members
PLT_Service Class Reference

UPnP Service. More...

#include <PltService.h>

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...
 
PLT_ActionDescFindActionDesc (const char *name)
 Return the PLT_ActionDesc given an action name. More...
 
PLT_StateVariableFindStateVariable (const char *name)
 Return the PLT_StateVariable pointer given a state variable name. 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...
 
const NPT_Array
< PLT_ActionDesc * > & 
GetActionDescs () const
 Return an array of actions descriptions PLT_ActionDesc. More...
 
NPT_String GetControlURL (bool absolute=false)
 Return the Control url associated with this service. More...
 
NPT_Result GetDescription (NPT_XmlElementNode *parent, NPT_XmlElementNode **service=NULL)
 Populate the UPnP Device description document with service information. More...
 
PLT_DeviceDataGetDevice ()
 Return the PLT_DeviceData* the service is associated with. More...
 
NPT_String GetEventSubURL (bool absolute=false)
 Return the Event subscription url associated with this service. More...
 
NPT_String GetSCPDURL (bool absolute=false)
 Return the SCPD url associated with this service. More...
 
NPT_Result GetSCPDXML (NPT_String &xml)
 Return the service SCPD xml document. More...
 
const NPT_String & GetServiceID () const
 Return the service id. More...
 
const NPT_String & GetServiceName () const
 Return the service friendly name. More...
 
const NPT_String & GetServiceType () const
 Return the service type. More...
 
const NPT_List
< PLT_StateVariable * > & 
GetStateVariables () const
 Return the list of state variables. More...
 
NPT_Result GetStateVariableValue (const char *name, NPT_String &value)
 Return the state variable value given a state variable name. More...
 
NPT_Result IncStateVariable (const char *name)
 Helper function to increment a state variable representing a number. 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 IsSubscribable ()
 Return whether a service is capable of sending events. 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 SetEventSubURL (const char *url)
 Set the Service Event subscription url for control points to be able to subscribe to events. 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 SetSCPDXML (const char *xml)
 Set the service SCPD xml document. More...
 
NPT_Result SetStateVariable (const char *name, const char *value)
 Set a new value for a given state variable. 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 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...
 

Friends

class PLT_DeviceHost
 
class PLT_StateVariable
 

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_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
devicePointer to the PLT_DeviceData the service is associated to
typeString representing the UPnP service type
idString representing the UPnP service id
nameA String to create unique service SCPD, control and eventing urls
last_change_namespaceA String for the LastChange state variable namespace if any

Member Function Documentation

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

Return the PLT_ActionDesc given an action name.

Parameters
nameaction name
Returns
PLT_ActioDesc pointer
PLT_StateVariable* PLT_Service::FindStateVariable ( const char *  name)

Return the PLT_StateVariable pointer given a state variable name.

Parameters
namestate variable name
Returns
PLT_StateVariable pointer
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
versionInteger specifying the version to use
const NPT_Array<PLT_ActionDesc*>& PLT_Service::GetActionDescs ( ) const
inline

Return an array of actions descriptions PLT_ActionDesc.

Returns
array of PLT_ActionDesc pointers.
NPT_String PLT_Service::GetControlURL ( bool  absolute = false)

Return the Control url associated with this service.

Parameters
absoluteflag to indicate if absolute url including ip and port should be returned
Returns
Control url
NPT_Result PLT_Service::GetDescription ( NPT_XmlElementNode *  parent,
NPT_XmlElementNode **  service = NULL 
)

Populate the UPnP Device description document with service information.

Parameters
parentXML Element where to insert the service XML Element
servicePointer to service XML Element node newly created so it can be extended with additional non standard information.
PLT_DeviceData* PLT_Service::GetDevice ( )
inline

Return the PLT_DeviceData* the service is associated with.

Returns
PLT_DeviceData pointer
NPT_String PLT_Service::GetEventSubURL ( bool  absolute = false)

Return the Event subscription url associated with this service.

Parameters
absoluteflag to indicate if absolute url including ip and port should be returned
Returns
Event url
NPT_String PLT_Service::GetSCPDURL ( bool  absolute = false)

Return the SCPD url associated with this service.

Parameters
absoluteflag to indicate if absolute url including ip and port should be returned
Returns
SCPD url
NPT_Result PLT_Service::GetSCPDXML ( NPT_String &  xml)

Return the service SCPD xml document.

Parameters
xmlString to receive document
const NPT_String& PLT_Service::GetServiceID ( ) const
inline

Return the service id.

Returns
service id
const NPT_String& PLT_Service::GetServiceName ( ) const
inline

Return the service friendly name.

Returns
service name
const NPT_String& PLT_Service::GetServiceType ( ) const
inline

Return the service type.

Returns
service type
const NPT_List<PLT_StateVariable*>& PLT_Service::GetStateVariables ( ) const
inline

Return the list of state variables.

Returns
list of state variable pointers.
NPT_Result PLT_Service::GetStateVariableValue ( const char *  name,
NPT_String &  value 
)

Return the state variable value given a state variable name.

Parameters
namestate variable name
valuestate variable value output
NPT_Result PLT_Service::IncStateVariable ( const char *  name)

Helper function to increment a state variable representing a number.

Parameters
namestate variable name
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_namethe service name used to format unique urls
bool PLT_Service::IsSubscribable ( )

Return whether a service is capable of sending events.

Returns
true if sending events
bool PLT_Service::IsValid ( )
inline

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

Returns
true if valid.
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
pauseFlag to indicate if eventing should be paused or resumed
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
urlrelative path of even url
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
urlrelative path of SCPD url
NPT_Result PLT_Service::SetSCPDXML ( const char *  xml)

Set the service SCPD xml document.

Parameters
xmlString SCPD xml document
NPT_Result PLT_Service::SetStateVariable ( const char *  name,
const char *  value 
)

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
namestate variable name
valuenew State Variable value.
NPT_Result PLT_Service::SetStateVariableExtraAttribute ( const char *  name,
const char *  key,
const char *  value 
)

Certain state variables require extra xml attributes when serialized.

Parameters
namestate variable name
keythe attribute name
valuethe attribute value
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
namestate variable name
ratea time interval specifying the minimum interval allowed between notifications.

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