mUPnP for C
Data Structures | Macros | Typedefs | Functions
statevariable.h File Reference
#include <mupnp/typedef.h>
#include <mupnp/util/list.h>
#include <mupnp/util/string.h>
#include <mupnp/xml/xml.h>
#include <mupnp/upnp_status.h>

Data Structures

struct  _mUpnpAllowedValuesList
 
struct  _mUpnpStateVariable
 

Macros

#define MUPNP_STATEVARIABLE_ELEM_NAME   "stateVariable"
 
#define MUPNP_SERVICESTATETALBE_ELEM_NAME   "serviceStateTable"
 
#define MUPNP_STATEVARIABLE_NAME   "name"
 
#define MUPNP_STATEVARIABLE_DATATYPE   "dataType"
 
#define MUPNP_STATEVARIABLE_SENDEVENTS   "sendEvents"
 
#define MUPNP_STATEVARIABLE_SENDEVENTS_YES   "yes"
 
#define MUPNP_STATEVARIABLE_SENDEVENTS_NO   "no"
 
#define MUPNP_STATEVARIABLE_ALLOWEDVALUELIST   "allowedValueList"
 
#define mupnp_statevariable_next(statVar)
 
#define mupnp_statevariable_isstatevariablenode(node)
 
#define mupnp_statevariable_getstatevariablenode(statVar)
 
#define mupnp_statevariable_setservice(statVar, service)
 
#define mupnp_statevariable_getservice(statVar)
 
#define mupnp_statevariable_hasallowedvaluelist(statVar)
 
#define mupnp_statevariable_getallowedvaluerange(statVar)
 
#define mupnp_statevariable_hasallowedvaluerange(statVar)
 
#define mupnp_statevariable_setname(statVar, value)
 
#define mupnp_statevariable_getname(statVar)
 
#define mupnp_statevariable_isname(statVar, name)
 
#define mupnp_statevariable_setdatatype(statVar, value)
 
#define mupnp_statevariable_getdatatype(statVar)
 
#define mupnp_statevariable_setsendevents(statVar, value)
 
#define mupnp_statevariable_getsendevents(statVar)
 
#define mupnp_statevariable_issendevents(statVar)
 
#define mupnp_statevariable_getvalue(statVar)
 
#define mupnp_statevariable_setlistener(statVar, func)
 
#define mupnp_statevariable_getlistener(statVar)
 
#define mupnp_statevariable_setstatuscode(statVar, code)
 
#define mupnp_statevariable_getstatuscode(statVar)
 
#define mupnp_statevariable_setstatusdescription(statVar, value)
 
#define mupnp_statevariable_getstatusdescription(statVar)
 
#define mupnp_statevariable_setuserdata(statVar, value)
 
#define mupnp_statevariable_getuserdata(statVar)
 
#define mupnp_servicestatetable_clear(stateTable)
 
#define mupnp_servicestatetable_size(stateTable)
 
#define mupnp_servicestatetable_gets(stateTable)
 
#define mupnp_servicestatetable_add(stateTable, statVar)
 

Typedefs

typedef struct _mUpnpAllowedValuesList mUpnpAllowedValuesList
 
typedef struct _mUpnpAllowedValuesList mUpnpAllowedValue
 
typedef struct _mUpnpStateVariable mUpnpStateVariable
 
typedef struct _mUpnpStateVariable mUpnpServiceStateTable
 
typedef bool(* MUPNP_STATEVARIABLE_LISTNER) (mUpnpStateVariable *)
 

Functions

mUpnpStateVariable * mupnp_statevariable_new (void)
 Create a new UPnP state variable.
 
void mupnp_statevariable_delete (mUpnpStateVariable *statVar)
 Destroy a UPnP state variable and free resources.
 
void mupnp_statevariable_setstatevariablenode (mUpnpStateVariable *statVar, mUpnpXmlNode *node)
 
mUpnpAllowedValuesList * mupnp_statevariable_getallowedvaluelist (mUpnpStateVariable *statVar)
 
int mupnp_statevariable_is_allowed_value (mUpnpStateVariable *statVar, const char *value)
 
mUpnpAllowedValuesList * mupnp_allowedvaluelist_new (void)
 
void mupnp_statevariable_setvalue (mUpnpStateVariable *statVar, const char *data)
 
void mupnp_statevariable_setvaluewithoutnotify (mUpnpStateVariable *statVar, const char *data)
 
mUpnpServiceStateTable * mupnp_servicestatetable_new (void)
 
void mupnp_servicestatetable_delete (mUpnpServiceStateTable *servicestatetable)
 

Macro Definition Documentation

◆ mupnp_servicestatetable_add

#define mupnp_servicestatetable_add ( stateTable,
statVar )
Value:
mupnp_list_add((mUpnpList*)stateTable, (mUpnpList*)statVar)
mupnp_list_add
void mupnp_list_add(mUpnpList *headList, mUpnpList *list)
Add a node to the end of a list.
Definition list.c:123
_mUpnpList
The generic list interface in mUPnP.
Definition list.h:56

Add new service state table into service state table list

Parameters
stateTableService state table
statVarState variable

◆ mupnp_servicestatetable_clear

#define mupnp_servicestatetable_clear ( stateTable)
Value:
mupnp_list_clear((mUpnpList*)stateTable, (MUPNP_LIST_DESTRUCTORFUNC)mupnp_statevariable_delete)
mupnp_list_clear
void mupnp_list_clear(mUpnpList *headList, MUPNP_LIST_DESTRUCTORFUNC destructorFunc)
Definition list.c:257
MUPNP_LIST_DESTRUCTORFUNC
void(* MUPNP_LIST_DESTRUCTORFUNC)(void *)
Definition list.h:29
mupnp_statevariable_delete
void mupnp_statevariable_delete(mUpnpStateVariable *statVar)
Destroy a UPnP state variable and free resources.
Definition statevariable.c:53

Clear service state table

Parameters
stateTableService state table

◆ mupnp_servicestatetable_gets

#define mupnp_servicestatetable_gets ( stateTable)
Value:
(mUpnpStateVariable*)mupnp_list_next((mUpnpList*)stateTable)
mupnp_list_next
mUpnpList * mupnp_list_next(mUpnpList *list)
Definition list.c:234
_mUpnpStateVariable
Definition statevariable.h:86

Get next service state table from service state table list

Parameters
stateTableService state table
Returns
Service state table (node)

◆ mupnp_servicestatetable_size

#define mupnp_servicestatetable_size ( stateTable)
Value:
mupnp_list_size((mUpnpList*)stateTable)
mupnp_list_size
int mupnp_list_size(mUpnpList *headList)
Definition list.c:53

Get size of service state table

Parameters
stateTableService state table

◆ MUPNP_SERVICESTATETALBE_ELEM_NAME

#define MUPNP_SERVICESTATETALBE_ELEM_NAME   "serviceStateTable"

Definition for service state table XML element name

◆ MUPNP_STATEVARIABLE_ALLOWEDVALUELIST

#define MUPNP_STATEVARIABLE_ALLOWEDVALUELIST   "allowedValueList"

Definition for state variable allowed values list

◆ MUPNP_STATEVARIABLE_DATATYPE

#define MUPNP_STATEVARIABLE_DATATYPE   "dataType"

Definition for state variable data type element

◆ MUPNP_STATEVARIABLE_ELEM_NAME

#define MUPNP_STATEVARIABLE_ELEM_NAME   "stateVariable"

Definition for state variable XML element name

◆ mupnp_statevariable_getallowedvaluerange

#define mupnp_statevariable_getallowedvaluerange ( statVar)
Value:
(statVar->allowedValueRange)

Get allowed value range for state variable

Parameters
statVarState variable
Returns
Allowed value range

◆ mupnp_statevariable_getdatatype

#define mupnp_statevariable_getdatatype ( statVar)
Value:
mupnp_xml_node_getchildnodevalue(mupnp_statevariable_getstatevariablenode(statVar), MUPNP_STATEVARIABLE_DATATYPE)
mupnp_statevariable_getstatevariablenode
#define mupnp_statevariable_getstatevariablenode(statVar)
Definition statevariable.h:196
MUPNP_STATEVARIABLE_DATATYPE
#define MUPNP_STATEVARIABLE_DATATYPE
Definition statevariable.h:48
mupnp_xml_node_getchildnodevalue
const char * mupnp_xml_node_getchildnodevalue(mUpnpXmlNode *node, const char *name)
Definition xml_node.c:216

Get data type from state variable

Parameters
statVarState variable
Returns
Data type

◆ mupnp_statevariable_getlistener

#define mupnp_statevariable_getlistener ( statVar)
Value:
(statVar->listener)

Get lister function associated with state variable

Parameters
statVarState variable

◆ mupnp_statevariable_getname

#define mupnp_statevariable_getname ( statVar)
Value:
mupnp_xml_node_getchildnodevalue(mupnp_statevariable_getstatevariablenode(statVar), MUPNP_STATEVARIABLE_NAME)
MUPNP_STATEVARIABLE_NAME
#define MUPNP_STATEVARIABLE_NAME
Definition statevariable.h:43

Get state variable name

Parameters
statVarState variable
Returns
State variable name

◆ mupnp_statevariable_getsendevents

#define mupnp_statevariable_getsendevents ( statVar)
Value:
mupnp_xml_node_getattributevalue(mupnp_statevariable_getstatevariablenode(statVar), MUPNP_STATEVARIABLE_SENDEVENTS)
MUPNP_STATEVARIABLE_SENDEVENTS
#define MUPNP_STATEVARIABLE_SENDEVENTS
Definition statevariable.h:53
mupnp_xml_node_getattributevalue
#define mupnp_xml_node_getattributevalue(node, name)
Definition xml.h:166

Get state variable event sending option value

Parameters
statVarState variable
Returns
Current value associated to state variable

◆ mupnp_statevariable_getservice

#define mupnp_statevariable_getservice ( statVar)
Value:
((mUpnpService*)statVar->parentService)
_mUpnpService
Definition service.h:51

Get service from state variable

Parameters
statVarState variable
Returns
UPnP service

◆ mupnp_statevariable_getstatevariablenode

#define mupnp_statevariable_getstatevariablenode ( statVar)
Value:
(statVar->stateVarNode)

Get XML node from this state variable

Parameters
statVarState variable

◆ mupnp_statevariable_getstatuscode

#define mupnp_statevariable_getstatuscode ( statVar)
Value:
mupnp_status_getcode(statVar->upnpStatus)
mupnp_status_getcode
#define mupnp_status_getcode(upnpStat)
Definition upnp_status.h:77

Get status code of this state variable

Parameters
statVarStatus variable

◆ mupnp_statevariable_getstatusdescription

#define mupnp_statevariable_getstatusdescription ( statVar)
Value:
mupnp_status_getdescription(statVar->upnpStatus)
mupnp_status_getdescription
#define mupnp_status_getdescription(upnpStat)
Definition upnp_status.h:92

Get status description from this state variable

Parameters
statVarState variable

◆ mupnp_statevariable_getuserdata

#define mupnp_statevariable_getuserdata ( statVar)
Value:
(statVar->userData)

Get user data from this state variable

Parameters
statVarState variable
Returns
User data

◆ mupnp_statevariable_getvalue

#define mupnp_statevariable_getvalue ( statVar)
Value:
mupnp_string_getvalue(statVar->value)
mupnp_string_getvalue
char * mupnp_string_getvalue(mUpnpString *str)
Definition string.c:177

Get value associated with this state variable

Parameters
statVarState variable
Returns
Value associated with this state variable

◆ mupnp_statevariable_hasallowedvaluelist

#define mupnp_statevariable_hasallowedvaluelist ( statVar)
Value:
mupnp_allowedvaluelist_size(statVar->allowedValueList)

Check if state variable has allowed value list

Parameters
statVarState variable
Returns
0 if it does not have allowed value list integer greater than zero otherwise

◆ mupnp_statevariable_hasallowedvaluerange

#define mupnp_statevariable_hasallowedvaluerange ( statVar)
Value:
((statVar->allowedValueRange != NULL) ? true : false)
true
#define true
Definition typedef.h:63

Checks if state variable has allowed variable range

Parameters
statVarState variable
Returns
True if allowed value range exists, false otherwise

◆ mupnp_statevariable_isname

#define mupnp_statevariable_isname ( statVar,
name )
Value:
mupnp_streq(mupnp_statevariable_getname(statVar), name)
mupnp_statevariable_getname
#define mupnp_statevariable_getname(statVar)
Definition statevariable.h:289
mupnp_streq
bool mupnp_streq(const char *str1, const char *str2)
Test if two strings are equal (NULL-safe)
Definition string_function.c:158

Checks if state variable has certain name

Parameters
statVarState variable
nameName to be checked
Returns
True if State variable name is same as provided, false otherwise

◆ mupnp_statevariable_issendevents

#define mupnp_statevariable_issendevents ( statVar)
Value:
(mupnp_streq(mupnp_statevariable_getsendevents(statVar), MUPNP_STATEVARIABLE_SENDEVENTS_YES))
mupnp_statevariable_getsendevents
#define mupnp_statevariable_getsendevents(statVar)
Definition statevariable.h:338
MUPNP_STATEVARIABLE_SENDEVENTS_YES
#define MUPNP_STATEVARIABLE_SENDEVENTS_YES
Definition statevariable.h:58

Check if events are sent to subscribers when this state variable changes

Parameters
statVarState variable
Returns
True if events are sent, false otherwise

◆ mupnp_statevariable_isstatevariablenode

#define mupnp_statevariable_isstatevariablenode ( node)
Value:
mupnp_xml_node_isname(node, MUPNP_STATEVARIABLE_ELEM_NAME)
MUPNP_STATEVARIABLE_ELEM_NAME
#define MUPNP_STATEVARIABLE_ELEM_NAME
Definition statevariable.h:33
mupnp_xml_node_isname
#define mupnp_xml_node_isname(node, nodename)
Definition xml.h:123

Check if XML node is state variable node

Parameters
nodeXML node

◆ MUPNP_STATEVARIABLE_NAME

#define MUPNP_STATEVARIABLE_NAME   "name"

Definition for state variable name element

◆ mupnp_statevariable_next

#define mupnp_statevariable_next ( statVar)
Value:
(mUpnpStateVariable*)mupnp_list_next((mUpnpList*)statVar)

Get next element from state variable list

Parameters
statVarstate variable list node

◆ MUPNP_STATEVARIABLE_SENDEVENTS

#define MUPNP_STATEVARIABLE_SENDEVENTS   "sendEvents"

Definition for state variable send events element name

◆ MUPNP_STATEVARIABLE_SENDEVENTS_NO

#define MUPNP_STATEVARIABLE_SENDEVENTS_NO   "no"

Definition for state variable send events element value

◆ MUPNP_STATEVARIABLE_SENDEVENTS_YES

#define MUPNP_STATEVARIABLE_SENDEVENTS_YES   "yes"

Definition for state variable send events element value

◆ mupnp_statevariable_setdatatype

#define mupnp_statevariable_setdatatype ( statVar,
value )
Value:
mupnp_xml_node_setchildnode(mupnp_statevariable_getstatevariablenode(statVar), MUPNP_STATEVARIABLE_DATATYPE, value)
mupnp_xml_node_setchildnode
void mupnp_xml_node_setchildnode(mUpnpXmlNode *node, const char *name, const char *value)
Definition xml_node.c:105

Set data type for state variable

Parameters
statVarState variable
valueData type

◆ mupnp_statevariable_setlistener

#define mupnp_statevariable_setlistener ( statVar,
func )
Value:
(statVar->listener = func)

Set listener callback for this state variable

Parameters
statVarState variable
funcListener function

◆ mupnp_statevariable_setname

#define mupnp_statevariable_setname ( statVar,
value )
Value:
mupnp_xml_node_setchildnode(mupnp_statevariable_getstatevariablenode(statVar), MUPNP_STATEVARIABLE_NAME, value)

Set state variable name

Parameters
statVarState variable
valueNew state variable name

◆ mupnp_statevariable_setsendevents

#define mupnp_statevariable_setsendevents ( statVar,
value )
Value:
mupnp_xml_node_setattribute(mupnp_statevariable_getstatevariablenode(statVar), MUPNP_STATEVARIABLE_SENDEVENTS, value)
mupnp_xml_node_setattribute
#define mupnp_xml_node_setattribute(node, name, value)
Definition xml.h:165

Set send events option for state variable, can be used to disable eventing for certain variables.

Parameters
statVarState variable
valueNew value

◆ mupnp_statevariable_setservice

#define mupnp_statevariable_setservice ( statVar,
service )
Value:
(statVar->parentService = service)

Set service for this state variable

Parameters
statVarState variable
serviceService

◆ mupnp_statevariable_setstatuscode

#define mupnp_statevariable_setstatuscode ( statVar,
code )
Value:
mupnp_status_setcode(statVar->upnpStatus, code)
mupnp_status_setcode
#define mupnp_status_setcode(upnpStat, value)
Definition upnp_status.h:70

Set status code for state variable

Parameters
statVarState variable
codeStatus code

◆ mupnp_statevariable_setstatusdescription

#define mupnp_statevariable_setstatusdescription ( statVar,
value )
Value:
mupnp_status_setdescription(statVar->upnpStatus, value)
mupnp_status_setdescription
#define mupnp_status_setdescription(upnpStat, value)
Definition upnp_status.h:85

Set status description for state variable

Parameters
statVarState variable
valueStatus description

◆ mupnp_statevariable_setuserdata

#define mupnp_statevariable_setuserdata ( statVar,
value )
Value:
(statVar->userData = value)

Set arbitrary user data associated with this state variable

Parameters
statVarState variable
valueData

Typedef Documentation

◆ MUPNP_STATEVARIABLE_LISTNER

typedef bool(* MUPNP_STATEVARIABLE_LISTNER) (mUpnpStateVariable *)

Type definition for state variable listener function

◆ mUpnpAllowedValue

typedef struct _mUpnpAllowedValuesList mUpnpAllowedValue

◆ mUpnpAllowedValuesList

typedef struct _mUpnpAllowedValuesList mUpnpAllowedValuesList

Data type for allowed state variables allowed values table

◆ mUpnpServiceStateTable

typedef struct _mUpnpStateVariable mUpnpServiceStateTable

◆ mUpnpStateVariable

typedef struct _mUpnpStateVariable mUpnpStateVariable

Data type for state variable and state table

Function Documentation

◆ mupnp_allowedvaluelist_new()

mUpnpAllowedValuesList * mupnp_allowedvaluelist_new ( void )

Create new allowed state variable values list

◆ mupnp_servicestatetable_delete()

void mupnp_servicestatetable_delete ( mUpnpServiceStateTable * servicestatetable)

Delete service state table object

Parameters
servicestatetableService state table

◆ mupnp_servicestatetable_new()

mUpnpServiceStateTable * mupnp_servicestatetable_new ( void )

Create service state table object

◆ mupnp_statevariable_delete()

void mupnp_statevariable_delete ( mUpnpStateVariable * statVar)

Destroy a UPnP state variable and free resources.

Releases all resources associated with the state variable, including:

  • The current value string
  • Allowed values list (if any)
  • XML node references
  • UPnP status object
Parameters
statVarThe state variable to destroy. May be NULL (no-op if NULL).
Note
After calling this function, the statVar pointer is invalid.
Thread-safe: Must not be called concurrently on the same state variable.
See also
mupnp_statevariable_new()

◆ mupnp_statevariable_getallowedvaluelist()

mUpnpAllowedValuesList * mupnp_statevariable_getallowedvaluelist ( mUpnpStateVariable * statVar)

Get allowed value list

Parameters
statVarState variable
Returns
Allowed value list

◆ mupnp_statevariable_is_allowed_value()

int mupnp_statevariable_is_allowed_value ( mUpnpStateVariable * statVar,
const char * value )

Check if state variable allowes to receive value

@parap value value to be checked

Parameters
statVarState variable
Returns
0 if it does allowed to receive value

◆ mupnp_statevariable_new()

mUpnpStateVariable * mupnp_statevariable_new ( void )

Create a new UPnP state variable.

Allocates and initializes a new state variable object. State variables represent the state of a UPnP service and can be:

  • Evented (sendEvents="yes") - Changes trigger event notifications
  • Non-evented (sendEvents="no") - Query-only via action arguments

State variables have:

  • A name (identifier)
  • A data type (string, int, boolean, etc.)
  • An optional list of allowed values
  • A current value
  • Optional eventing configuration

State variables are typically created during SCPD parsing and added to the service state table.

Returns
A newly-created mUpnpStateVariable on success, or NULL if memory allocation fails.
Note
The returned state variable must be freed with mupnp_statevariable_delete() when no longer needed.
Thread-safe: Can be called concurrently from multiple threads.
For device implementations, set a query listener to handle QueryStateVariable requests.
See also
mupnp_statevariable_delete()
mupnp_statevariable_setvalue()
mupnp_statevariable_issendevents()

◆ mupnp_statevariable_setstatevariablenode()

void mupnp_statevariable_setstatevariablenode ( mUpnpStateVariable * statVar,
mUpnpXmlNode * node )

Set XML node for this state variable

Parameters
statVarState variable
nodeXML node

◆ mupnp_statevariable_setvalue()

void mupnp_statevariable_setvalue ( mUpnpStateVariable * statVar,
const char * data )

Set state variable value

Parameters
statVarState variable
dataNew value associated with this state variable, and the value is send to other devices which subscribe the service.

◆ mupnp_statevariable_setvaluewithoutnotify()

void mupnp_statevariable_setvaluewithoutnotify ( mUpnpStateVariable * statVar,
const char * data )

Set state variable value

Parameters
statVarState variable
dataNew value associated with this state variable