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

Data Structures

struct  _mUpnpAction
 

Macros

#define MUPNP_ACTION_ELEM_NAME   "action"
 
#define MUPNP_ACTIONLIST_ELEM_NAME   "actionList"
 
#define MUPNP_ACTION_NAME   "name"
 
#define mupnp_action_next(action)
 
#define mupnp_action_isactionnode(node)
 
#define mupnp_action_getactionnode(action)
 
#define mupnp_action_setservice(action, service)
 
#define mupnp_action_getservice(action)
 
#define mupnp_action_setname(action, value)
 
#define mupnp_action_getname(action)
 
#define mupnp_action_isname(action, name)
 
#define mupnp_action_getargumentlist(action)
 
#define mupnp_action_getarguments(action)
 
#define mupnp_action_hasargumentbyname(action, name)
 
#define mupnp_action_setstatuscode(action, code)
 
#define mupnp_action_getstatuscode(action)
 
#define mupnp_action_setstatusdescription(action, value)
 
#define mupnp_action_getstatusdescription(action)
 
#define mupnp_action_setlistener(action, func)
 
#define mupnp_action_getlistener(action)
 
#define mupnp_action_setlistner   mupnp_action_setlistener
 
#define mupnp_action_getlistner   mupnp_action_getlistener
 
#define mupnp_action_setuserdata(action, value)
 
#define mupnp_action_getuserdata(action)
 
#define mupnp_actionlist_clear(actionList)
 
#define mupnp_actionlist_size(actionList)
 
#define mupnp_actionlist_gets(actionList)
 
#define mupnp_actionlist_add(actionList, action)
 

Typedefs

typedef struct _mUpnpAction mUpnpAction
 
typedef struct _mUpnpAction mUpnpActionList
 
typedef bool(* MUPNP_ACTION_LISTNER) (mUpnpAction *)
 

Functions

mUpnpAction * mupnp_action_new (void)
 Create a new UPnP action instance.
 
void mupnp_action_delete (mUpnpAction *action)
 Destroy a UPnP action and free all associated resources.
 
void mupnp_action_setactionnode (mUpnpAction *action, mUpnpXmlNode *node)
 
mUpnpArgument * mupnp_action_getargumentbyname (mUpnpAction *action, const char *name)
 
char * mupnp_action_getargumentvaluebyname (mUpnpAction *action, const char *name)
 
bool mupnp_action_setargumentvaluebyname (mUpnpAction *action, const char *name, const char *value)
 
mUpnpActionList * mupnp_actionlist_new (void)
 
void mupnp_actionlist_delete (mUpnpActionList *actionList)
 

Macro Definition Documentation

◆ MUPNP_ACTION_ELEM_NAME

#define MUPNP_ACTION_ELEM_NAME   "action"

◆ mupnp_action_getactionnode

#define mupnp_action_getactionnode ( action)
Value:
(action->actionNode)

Get the action's XML node (i.e. the XML representation of the action)

Parameters
actionThe action in question
Returns
mUpnpXmlNode*

◆ mupnp_action_getargumentlist

#define mupnp_action_getargumentlist ( action)
Value:
(action->argumentList)

Get the action's list of arguments

Parameters
actionThe action in question
Returns
mUpnpArgumentList*

◆ mupnp_action_getarguments

#define mupnp_action_getarguments ( action)
Value:
((mUpnpArgument*)mupnp_list_next((mUpnpList*)action->argumentList))
mupnp_list_next
mUpnpList * mupnp_list_next(mUpnpList *list)
Definition list.c:234
_mUpnpArgument
Definition argument.h:55
_mUpnpList
The generic list interface in mUPnP.
Definition list.h:56

Get the first argument from the action's list of arguments. Use as the starting point in iteration loops.

Parameters
actionThe action in question
Returns
mUpnpArgument*

◆ mupnp_action_getlistener

#define mupnp_action_getlistener ( action)
Value:
(action->listener)

Get the action's listener function

Parameters
actionThe action in question
Returns
bool (*MUPNP_ACTION_LISTNER)(mUpnpAction *)

◆ mupnp_action_getlistner

#define mupnp_action_getlistner   mupnp_action_getlistener
Deprecated
Compatibility macro for typo correction

◆ mupnp_action_getname

#define mupnp_action_getname ( action)
Value:
mupnp_xml_node_getchildnodevalue(mupnp_action_getactionnode(action), MUPNP_ACTION_NAME)
MUPNP_ACTION_NAME
#define MUPNP_ACTION_NAME
Definition action.h:34
mupnp_action_getactionnode
#define mupnp_action_getactionnode(action)
Definition action.h:145
mupnp_xml_node_getchildnodevalue
const char * mupnp_xml_node_getchildnodevalue(mUpnpXmlNode *node, const char *name)
Definition xml_node.c:216

Get the action's name

Parameters
actionThe action in question
Returns
char*

◆ mupnp_action_getservice

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

Get the action's parent service

Parameters
actionThe action in question
Returns
mUpnpService*

◆ mupnp_action_getstatuscode

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

Get the action's latest status code

Parameters
actionThe action in question
Returns
int

◆ mupnp_action_getstatusdescription

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

Get the action's latest status description

Parameters
actionThe action in question
Returns
char*

◆ mupnp_action_getuserdata

#define mupnp_action_getuserdata ( action)
Value:
(action->userData)

Get the action's arbitrary user data pointer

Parameters
actionThe action in question
Returns
void*

◆ mupnp_action_hasargumentbyname

#define mupnp_action_hasargumentbyname ( action,
name )
Value:
((mupnp_action_getargumentbyname(action, name) != NULL) ? true : false)
mupnp_action_getargumentbyname
mUpnpArgument * mupnp_action_getargumentbyname(mUpnpAction *action, const char *name)
Definition action.c:147
true
#define true
Definition typedef.h:63

Find out, whether the action has an argument by the given name

Parameters
actionThe action in question
nameThe name to look for
Returns
true if the action has the argument; otherwise false

◆ mupnp_action_isactionnode

#define mupnp_action_isactionnode ( node)
Value:
mupnp_xml_node_isname(node, MUPNP_ACTION_ELEM_NAME)
MUPNP_ACTION_ELEM_NAME
#define MUPNP_ACTION_ELEM_NAME
Definition action.h:31
mupnp_xml_node_isname
#define mupnp_xml_node_isname(node, nodename)
Definition xml.h:123

Check, whether the given XML node is an action node

Parameters
nodeThe mUpnpXmlNode*

◆ mupnp_action_isname

#define mupnp_action_isname ( action,
name )
Value:
mupnp_streq(mupnp_action_getname(action), name)
mupnp_action_getname
#define mupnp_action_getname(action)
Definition action.h:185
mupnp_streq
bool mupnp_streq(const char *str1, const char *str2)
Test if two strings are equal (NULL-safe)
Definition string_function.c:158

Check, whether the action's name matches the one given as parameter.

Parameters
actionThe action in question
nameThe name string to compare

◆ MUPNP_ACTION_NAME

#define MUPNP_ACTION_NAME   "name"

◆ mupnp_action_next

#define mupnp_action_next ( action)
Value:
(mUpnpAction*)mupnp_list_next((mUpnpList*)action)
_mUpnpAction
Definition action.h:40

Get the next action in a list of actions. Use as an iterator.

Parameters
actionThe current action

◆ mupnp_action_setlistener

#define mupnp_action_setlistener ( action,
func )
Value:
(action->listener = func)

Set the action's listener function

Parameters
actionThe action in question
funcThe listener function of type: bool (*MUPNP_ACTION_LISTNER)(mUpnpAction *)

◆ mupnp_action_setlistner

#define mupnp_action_setlistner   mupnp_action_setlistener
Deprecated
Compatibility macro for typo correction

◆ mupnp_action_setname

#define mupnp_action_setname ( action,
value )
Value:
mupnp_xml_node_setchildnode(mupnp_action_getactionnode(action), MUPNP_ACTION_NAME, value)
mupnp_xml_node_setchildnode
void mupnp_xml_node_setchildnode(mUpnpXmlNode *node, const char *name, const char *value)
Definition xml_node.c:105

Set the action's name

Parameters
actionThe action in question
valueThe action's name

◆ mupnp_action_setservice

#define mupnp_action_setservice ( action,
service )
Value:
(action->parentService = service)

Set the action's parent service

Parameters
actionThe action in question
serviceThe action's parent service

◆ mupnp_action_setstatuscode

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

Set the action's latest status code

Parameters
actionThe action in question
codeThe status code (int)

◆ mupnp_action_setstatusdescription

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

Set the action's latest status description

Parameters
actionThe action in question
valueThe status description string

◆ mupnp_action_setuserdata

#define mupnp_action_setuserdata ( action,
value )
Value:
(action->userData = value)

Set the action's arbitrary user data pointer

Parameters
actionThe action in question
valueThe user data pointer (void*)

◆ mupnp_actionlist_add

#define mupnp_actionlist_add ( actionList,
action )
Value:
mupnp_list_add((mUpnpList*)actionList, (mUpnpList*)action)
mupnp_list_add
void mupnp_list_add(mUpnpList *headList, mUpnpList *list)
Add a node to the end of a list.
Definition list.c:123

Add an action to a list of actions

Parameters
actionListThe list in question
actionThe action to add to the list

◆ mupnp_actionlist_clear

#define mupnp_actionlist_clear ( actionList)
Value:
mupnp_list_clear((mUpnpList*)actionList, (MUPNP_LIST_DESTRUCTORFUNC)mupnp_action_delete)
mupnp_action_delete
void mupnp_action_delete(mUpnpAction *action)
Destroy a UPnP action and free all associated resources.
Definition action.c:56
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

Clear the contents of a list of actions

Parameters
actionListThe list of actions to clear

◆ MUPNP_ACTIONLIST_ELEM_NAME

#define MUPNP_ACTIONLIST_ELEM_NAME   "actionList"

◆ mupnp_actionlist_gets

#define mupnp_actionlist_gets ( actionList)
Value:
(mUpnpAction*)mupnp_list_next((mUpnpList*)actionList)

Get the first action in a list of actions. Use as the starting point in iteration loops.

Parameters
actionListThe list in question
Returns
mUpnpAction*

◆ mupnp_actionlist_size

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

Get the number of actions in a list of actions

Parameters
actionListThe list in question
Returns
int

Typedef Documentation

◆ MUPNP_ACTION_LISTNER

typedef bool(* MUPNP_ACTION_LISTNER) (mUpnpAction *)

◆ mUpnpAction

typedef struct _mUpnpAction mUpnpAction

◆ mUpnpActionList

typedef struct _mUpnpAction mUpnpActionList

Function Documentation

◆ mupnp_action_delete()

void mupnp_action_delete ( mUpnpAction * action)

Destroy a UPnP action and free all associated resources.

Releases all resources associated with the action, including:

  • All input and output arguments
  • UPnP status object
  • XML node representation (if any)
Parameters
actionThe action to destroy. May be NULL (no-op if NULL).
Note
After calling this function, the action pointer is invalid and must not be used.
Thread-safe: Must not be called concurrently with other operations on the same action.
See also
mupnp_action_new()

◆ mupnp_action_getargumentbyname()

mUpnpArgument * mupnp_action_getargumentbyname ( mUpnpAction * action,
const char * name )

Find an argument from the action by the argument's name.

Parameters
actionThe action in question
nameThe name of the argument to look for
Returns
mUpnpArgument* if successfull; otherwise NULL

◆ mupnp_action_getargumentvaluebyname()

char * mupnp_action_getargumentvaluebyname ( mUpnpAction * action,
const char * name )

Get a value of the specified argument from the action by the argument's name directly.

Parameters
actionThe action in question
nameThe name of the argument to look for
Returns
char* if successfull; otherwise NULL

◆ mupnp_action_new()

mUpnpAction * mupnp_action_new ( void )

Create a new UPnP action instance.

Allocates and initializes a new UPnP action object. Actions represent operations that can be invoked on a UPnP service, similar to remote procedure calls. Each action has:

  • A name (action identifier)
  • Input arguments (parameters passed to the action)
  • Output arguments (return values from the action)
  • A listener callback (for device-side implementations)
  • Status information (for responses and errors)

The function initializes:

  • Argument list (empty)
  • UPnP status object for error reporting
  • Listener callback (NULL, must be set for device implementations)
Returns
A newly-created mUpnpAction on success, or NULL if memory allocation fails.
Note
The returned action must be freed with mupnp_action_delete() when no longer needed.
Thread-safe: Can be called concurrently from multiple threads.
For device implementations, set an action listener with the listener field to handle invocations from control points.
Actions are typically created during service initialization when parsing the SCPD document.
See also
mupnp_action_delete()
mupnp_action_setactionnode()
MUPNP_ACTION_LISTNER

◆ mupnp_action_setactionnode()

void mupnp_action_setactionnode ( mUpnpAction * action,
mUpnpXmlNode * node )

Set the action's XML node (i.e. the XML representation of the action)

Parameters
actionThe action in question
nodeThe mUpnpXmlNode*

◆ mupnp_action_setargumentvaluebyname()

bool mupnp_action_setargumentvaluebyname ( mUpnpAction * action,
const char * name,
const char * value )

Set a value of the specified argument from the action by the argument's name directly.

Parameters
actionThe action in question
nameThe name of the argument to look for
valueThe value to set
Returns
true if successfull; otherwise NO

◆ mupnp_actionlist_delete()

void mupnp_actionlist_delete ( mUpnpActionList * actionList)

Destroy a list of actions

Parameters
actionListThe list of actions to destroy

◆ mupnp_actionlist_new()

mUpnpActionList * mupnp_actionlist_new ( void )

Create a new list of actions

Returns
mUpnpActionList*