#include <mupnp/net/url.h>
#include <mupnp/typedef.h>
#include <mupnp/util/list.h>
#include <mupnp/util/mutex.h>
#include <mupnp/util/string.h>
#include <mupnp/util/time.h>
#include <mupnp/xml/xml.h>
#include <mupnp/action.h>
#include <mupnp/event/subscriber.h>
#include <mupnp/ssdp/ssdp_server.h>
#include <mupnp/statevariable.h>

Data Structures
struct	_mUpnpService

Macros
#define	MUPNP_SERVICE_ELEM_NAME "service"

#define	MUPNP_SERVICELIST_ELEM_NAME "serviceList"

#define	MUPNP_SERVICE_TYPE "serviceType"

#define	MUPNP_SERVICE_ID "serviceId"

#define	MUPNP_SERVICE_SCPDURL "SCPDURL"

#define	MUPNP_SERVICE_CONTROL_URL "controlURL"

#define	MUPNP_SERVICE_EVENT_SUB_URL "eventSubURL"

#define	MUPNP_SERVICE_EVENT_KEY_INVALID 0

#define	MUPNP_SERVICE_NOTIFY_WAITTIME 1000

#define	mupnp_service_next(service)

#define	mupnp_service_isservicenode(node)

#define	mupnp_service_getscpdnode(service)

#define	mupnp_service_setservicenode(service, node)

#define	mupnp_service_getservicenode(service)

#define	mupnp_service_getdevicenode(service)

#define	mupnp_service_isparsed(service)

#define	mupnp_service_setservicetype(service, value)

#define	mupnp_service_getservicetype(service)

#define	mupnp_service_setserviceid(service, value)

#define	mupnp_service_getserviceid(service)

#define	mupnp_service_setscpdurl(service, value)

#define	mupnp_service_setcontrolurl(service, value)

#define	mupnp_service_seteventsuburl(service, value)

#define	mupnp_service_hasactionbyname(service, name)

#define	mupnp_service_hasstatevariablebyname(service, name)

#define	mupnp_service_setdevice(service, dev)

#define	mupnp_service_getdevice(service)

#define	mupnp_service_getrootdevice(service)

#define	mupnp_service_getsubscribers(service)

#define	mupnp_service_getnsubscribers(service)

#define	mupnp_service_notifyallstatevariables(service)

#define	mupnp_service_lock(service)

#define	mupnp_service_unlock(service)

#define	mupnp_service_setsubscriptionsid(service, value)

#define	mupnp_service_getsubscriptionsid(service)

#define	mupnp_service_issubscribed(service)

#define	mupnp_service_clearsubscriptionsid(service)

#define	mupnp_service_setsubscriptiontimeout(service, value)

#define	mupnp_service_getsubscriptiontimeout(service)

#define	mupnp_service_setuserdata(service, value)

#define	mupnp_service_getuserdata(service)

#define	mupnp_service_seteventkey(service, value)

#define	mupnp_service_geteventkey(service)

#define	mupnp_service_setsubscriptiontimestamp(service, value)

#define	mupnp_service_getsubscriptiontimestamp(service)

#define	mupnp_service_getsubscriptionexpiration(service)

#define	mupnp_servicelist_clear(serviceList)

#define	mupnp_servicelist_size(serviceList)

#define	mupnp_servicelist_gets(serviceList)

#define	mupnp_servicelist_add(serviceList, service)

Typedefs
typedef struct _mUpnpService	mUpnpService

typedef struct _mUpnpService	mUpnpServiceList

Functions
mUpnpService *	mupnp_service_new (void)
	Create a new UPnP service instance.

void	mupnp_service_delete (mUpnpService *service)
	Destroy a UPnP service and free all associated resources.

void	mupnp_service_clear (mUpnpService *service)

bool	mupnp_service_parsedescription (mUpnpService service, const char description, size_t descriptionLen)
	Parse and populate a service from an SCPD XML document.

bool	mupnp_service_parsedescriptionurl (mUpnpService service, mUpnpNetURL url)

char *	mupnp_service_getdescription (mUpnpService service, mUpnpString descStr)

const char *	mupnp_servicetype_getidentifier (const char *serviceType)

const char *	mupnp_servicetype_geturn (const char *serviceType)

const char *	mupnp_servicetype_getservice (const char *serviceType)

const char *	mupnp_servicetype_gettype (const char *serviceType)

char *	mupnp_servicetype_getschematype (const char *serviceType)

const char *	mupnp_servicetype_getversion (const char *serviceType)

mUpnpNetURL *	mupnp_service_getscpdurl (mUpnpService *service)

bool	mupnp_service_isscpdurl (mUpnpService service, const char url)

mUpnpNetURL *	mupnp_service_getcontrolurl (mUpnpService *service)

mUpnpNetURL *	mupnp_service_geteventsuburl (mUpnpService *service)

mUpnpActionList *	mupnp_service_getactionlist (mUpnpService *service)

mUpnpAction *	mupnp_service_getactions (mUpnpService *service)

mUpnpAction *	mupnp_service_getactionbyname (mUpnpService service, const char name)

mUpnpServiceStateTable *	mupnp_service_getservicestatetable (mUpnpService *service)

mUpnpStateVariable *	mupnp_service_getstatevariables (mUpnpService *service)

mUpnpStateVariable *	mupnp_service_getstatevariablebyname (mUpnpService service, const char name)

bool	mupnp_service_announcefrom (mUpnpService service, const char bindAddr)

bool	mupnp_service_byebyefrom (mUpnpService service, const char bindAddr)

void	mupnp_service_setactionlistener (mUpnpService *service, MUPNP_ACTION_LISTNER actionListener)

void	mupnp_service_setquerylistener (mUpnpService *service, MUPNP_STATEVARIABLE_LISTNER queryListener)

bool	mupnp_service_addsubscriber (mUpnpService service, mUpnpSubscriber sub)

bool	mupnp_service_removesubscriber (mUpnpService service, mUpnpSubscriber sub)

mUpnpSubscriber *	mupnp_service_getsubscriberbysid (mUpnpService service, const char sid)

char *	mupnp_service_getnotifyservicetypent (mUpnpService service, char buf, int bufSize)

char *	mupnp_service_getnotifyservicetypeusn (mUpnpService service, char buf, int bufSize)

bool	mupnp_service_notify (mUpnpService service, mUpnpStateVariable statVar)

bool	mupnp_service_notifyall (mUpnpService *service, bool doBracket)

void	mupnp_service_createnotifyallthread (mUpnpService *service, mUpnpTime waitTime)

mUpnpServiceList *	mupnp_servicelist_new (void)

void	mupnp_servicelist_delete (mUpnpServiceList *serviceList)

void	mupnp_service_ssdpmessagereceived (mUpnpService service, mUpnpSSDPPacket ssdpPkt)

Macro Definition Documentation

◆ mupnp_service_clearsubscriptionsid

#define mupnp_service_clearsubscriptionsid ( service )

Value:

mupnp_string_setvalue(service->subscriptionSid, "")

mupnp_string_setvalue

void mupnp_string_setvalue(mUpnpString *str, const char *value)

Definition string.c:84

Clear (i.e. empty) the service's SID (subscription ID)

Parameters

service The service in question

◆ MUPNP_SERVICE_CONTROL_URL

#define MUPNP_SERVICE_CONTROL_URL "controlURL"

◆ MUPNP_SERVICE_ELEM_NAME

#define MUPNP_SERVICE_ELEM_NAME "service"

◆ MUPNP_SERVICE_EVENT_KEY_INVALID

#define MUPNP_SERVICE_EVENT_KEY_INVALID 0

◆ MUPNP_SERVICE_EVENT_SUB_URL

#define MUPNP_SERVICE_EVENT_SUB_URL "eventSubURL"

◆ mupnp_service_getdevice

#define mupnp_service_getdevice ( service )

Value:

((mUpnpDevice*)service->parentDevice)

_mUpnpDevice

The generic UPnP device structure.

Definition device.h:122

Get the service's parent device

Parameters

service The service in question

Returns: mUpnpDevice*

◆ mupnp_service_getdevicenode

#define mupnp_service_getdevicenode ( service )

Value:

mupnp_xml_node_getparentnode(mupnp_xml_node_getparentnode(service->serviceNode))

mupnp_xml_node_getparentnode

#define mupnp_xml_node_getparentnode(node)

Definition xml.h:136

Get the parent device's XML node for the service

Parameters

service The service in question

◆ mupnp_service_geteventkey

#define mupnp_service_geteventkey ( service )

Value:

(service->eventKey)

Get the service's event key

Parameters

service The service in question

Returns: uint

◆ mupnp_service_getnsubscribers

#define mupnp_service_getnsubscribers ( service )

Value:

mupnp_subscriberlist_size(service->subscriberList)

mupnp_subscriberlist_size

#define mupnp_subscriberlist_size(subList)

Definition subscriber.h:274

Get the number of subscribers for the service

Parameters

service The service in question

Returns: int

◆ mupnp_service_getrootdevice

#define mupnp_service_getrootdevice ( service )

Value:

mupnp_device_getrootdevice((mUpnpDevice*)service->parentDevice)

mupnp_device_getrootdevice

mUpnpDevice * mupnp_device_getrootdevice(mUpnpDevice *dev)

Definition device.c:165

Get the service's top-most root device

Parameters

service The service in question

Returns: mUpnpDevice*

◆ mupnp_service_getscpdnode

#define mupnp_service_getscpdnode ( service )

Value:

mupnp_xml_nodelist_gets(service->scpdNodeList)

mupnp_xml_nodelist_gets

#define mupnp_xml_nodelist_gets(nodeList)

Definition xml.h:103

Get the service's SCPD node

Parameters

service The service in question

◆ mupnp_service_getserviceid

#define mupnp_service_getserviceid ( service )

Value:

mupnp_xml_node_getchildnodevalue(mupnp_service_getservicenode(service), MUPNP_SERVICE_ID)

MUPNP_SERVICE_ID

#define MUPNP_SERVICE_ID

Definition service.h:40

mupnp_service_getservicenode

#define mupnp_service_getservicenode(service)

Definition service.h:176

mupnp_xml_node_getchildnodevalue

const char * mupnp_xml_node_getchildnodevalue(mUpnpXmlNode *node, const char *name)

Definition xml_node.c:216

Get the service's service ID

Parameters

service The service in question

Returns: char*

◆ mupnp_service_getservicenode

#define mupnp_service_getservicenode ( service )

Value:

(service->serviceNode)

Get the root XML node for the service

Parameters

service The service in question

◆ mupnp_service_getservicetype

#define mupnp_service_getservicetype ( service )

Value:

mupnp_xml_node_getchildnodevalue(mupnp_service_getservicenode(service), MUPNP_SERVICE_TYPE)

MUPNP_SERVICE_TYPE

#define MUPNP_SERVICE_TYPE

Definition service.h:39

Get the service's complete type string (ex. "urn:schemas-upnp-org:service:FooService:1")

Parameters

service The service in question

Returns: char*

◆ mupnp_service_getsubscribers

#define mupnp_service_getsubscribers ( service )

Value:

mupnp_subscriberlist_gets(service->subscriberList)

mupnp_subscriberlist_gets

#define mupnp_subscriberlist_gets(subList)

Definition subscriber.h:281

Get the first node in the service's list of event subscribers. Use as the starting point in iteration loops.

Parameters

service The service in question

◆ mupnp_service_getsubscriptionexpiration

#define mupnp_service_getsubscriptionexpiration ( service )

Value:

(service->subscriptionTimestamp + service->subscriptionTimeout - MUPNP_SUBSCRIPTION_DELAY)

MUPNP_SUBSCRIPTION_DELAY

#define MUPNP_SUBSCRIPTION_DELAY

Definition event.h:80

Get the service's subscription expiration time

Parameters

service The service in question

Returns: mUpnpTime

◆ mupnp_service_getsubscriptionsid

#define mupnp_service_getsubscriptionsid ( service )

Value:

mupnp_string_getvalue(service->subscriptionSid)

mupnp_string_getvalue

char * mupnp_string_getvalue(mUpnpString *str)

Definition string.c:177

Get the service's SID (subscription ID)

Parameters

service The service in question

Returns: char*

◆ mupnp_service_getsubscriptiontimeout

#define mupnp_service_getsubscriptiontimeout ( service )

Value:

(service->subscriptionTimeout)

Get the service's subscription timeout (expiration) value

Parameters

service The service in question

Returns: long

◆ mupnp_service_getsubscriptiontimestamp

#define mupnp_service_getsubscriptiontimestamp ( service )

Value:

(service->subscriptionTimestamp)

Get the service's subscription time stamp

Parameters

service The service in question

Returns: mUpnpTime

◆ mupnp_service_getuserdata

#define mupnp_service_getuserdata ( service )

Value:

(service->userData)

Get the service's arbitrary user data pointer

Parameters

service The service in question

Returns: void*

◆ mupnp_service_hasactionbyname

#define mupnp_service_hasactionbyname	(		service,
			name )

Value:

((mupnp_service_getactionbyname(service, name) != NULL) ? true : false)

mupnp_service_getactionbyname

mUpnpAction * mupnp_service_getactionbyname(mUpnpService *service, const char *name)

Definition service.c:843

true

#define true

Definition typedef.h:63

Check, whether a service has an action by the given name

Parameters

service	The service in question
name	The name of the action

◆ mupnp_service_hasstatevariablebyname

#define mupnp_service_hasstatevariablebyname	(		service,
			name )

Value:

((mupnp_service_getstatevariablebyname(service, name) != NULL) ? true : false)

mupnp_service_getstatevariablebyname

mUpnpStateVariable * mupnp_service_getstatevariablebyname(mUpnpService *service, const char *name)

Definition service.c:915

Check, whether the service has the given state variable

Parameters

service	The service in question
name	The name of the state variable

Returns: true if found; otherwise false

◆ MUPNP_SERVICE_ID

#define MUPNP_SERVICE_ID "serviceId"

◆ mupnp_service_isparsed

#define mupnp_service_isparsed ( service )

Value:

(service->parsed)

Get the service's parsing status (i.e. whether the service has been completely constructed). Useful mainly in optimized control point mode.

Parameters

service The service in question

◆ mupnp_service_isservicenode

#define mupnp_service_isservicenode ( node )

Value:

mupnp_xml_node_isname(node, MUPNP_SERVICE_ELEM_NAME)

MUPNP_SERVICE_ELEM_NAME

#define MUPNP_SERVICE_ELEM_NAME

Definition service.h:36

mupnp_xml_node_isname

#define mupnp_xml_node_isname(node, nodename)

Definition xml.h:123

Check, whether the given XML node is a service root node

Parameters

node	mUpnpXmlNode*

Returns: true if the node is a service root node; otherwise false

◆ mupnp_service_issubscribed

#define mupnp_service_issubscribed ( service )

Value:

((0 < mupnp_string_length(service->subscriptionSid)) ? true : false)

mupnp_string_length

size_t mupnp_string_length(mUpnpString *str)

Definition string.c:206

Check, whether the service has any subscribers

Parameters

service The service in question

Returns: true if at least one subscriber is found; otherwise false

◆ mupnp_service_lock

#define mupnp_service_lock ( service )

Value:

mupnp_mutex_lock(service->mutex)

mupnp_mutex_lock

bool mupnp_mutex_lock(mUpnpMutex *mutex)

Acquire a mutex lock (blocking)

Definition mutex.c:264

Lock the service's mutex

Parameters

service The service in question

◆ mupnp_service_next

#define mupnp_service_next ( service )

Value:

(mUpnpService*)mupnp_list_next((mUpnpList*)service)

mupnp_list_next

mUpnpList * mupnp_list_next(mUpnpList *list)

Definition list.c:234

_mUpnpList

The generic list interface in mUPnP.

Definition list.h:56

_mUpnpService

Definition service.h:51

Get the next service in a service list. Use as an iterator.

Parameters

service Current service

◆ MUPNP_SERVICE_NOTIFY_WAITTIME

#define MUPNP_SERVICE_NOTIFY_WAITTIME 1000

◆ mupnp_service_notifyallstatevariables

#define mupnp_service_notifyallstatevariables ( service )

Value:

mupnp_service_notifyall(service, false);

mupnp_service_notifyall

bool mupnp_service_notifyall(mUpnpService *service, bool doBracket)

Definition service_notify.c:123

Send a notification message to all of the service's subscribers

Parameters

service The service in question

Deprecated: Use mupnp_service_notifyall().

◆ MUPNP_SERVICE_SCPDURL

#define MUPNP_SERVICE_SCPDURL "SCPDURL"

◆ mupnp_service_setcontrolurl

#define mupnp_service_setcontrolurl	(		service,
			value )

Value:

mupnp_xml_node_setchildnode(mupnp_service_getservicenode(service), MUPNP_SERVICE_CONTROL_URL, value)

MUPNP_SERVICE_CONTROL_URL

#define MUPNP_SERVICE_CONTROL_URL

Definition service.h:42

mupnp_xml_node_setchildnode

void mupnp_xml_node_setchildnode(mUpnpXmlNode *node, const char *name, const char *value)

Definition xml_node.c:105

Set the service's control URL

Parameters

service	The service in question
value	The control URL string

◆ mupnp_service_setdevice

#define mupnp_service_setdevice	(		service,
			dev )

Value:

(service->parentDevice = dev)

Set the service's parent device

Parameters

service	The service in question
dev	The parent device

◆ mupnp_service_seteventkey

#define mupnp_service_seteventkey	(		service,
			value )

Value:

(service->eventKey = value)

Set the service's event key (i.e. the sequential number used in events)

Parameters

service	The service in question
value	The event key value (uint)

◆ mupnp_service_seteventsuburl

#define mupnp_service_seteventsuburl	(		service,
			value )

Value:

mupnp_xml_node_setchildnode(mupnp_service_getservicenode(service), MUPNP_SERVICE_EVENT_SUB_URL, value)

MUPNP_SERVICE_EVENT_SUB_URL

#define MUPNP_SERVICE_EVENT_SUB_URL

Definition service.h:43

Get the service's event subscription URL

Parameters

service	The service in question
value	The event subscription URL string

◆ mupnp_service_setscpdurl

#define mupnp_service_setscpdurl	(		service,
			value )

Value:

mupnp_xml_node_setchildnode(mupnp_service_getservicenode(service), MUPNP_SERVICE_SCPDURL, value)

MUPNP_SERVICE_SCPDURL

#define MUPNP_SERVICE_SCPDURL

Definition service.h:41

Set the service's SCPD (service description) URL

Parameters

service	The service in question
value	The SCPD URL string

◆ mupnp_service_setserviceid

#define mupnp_service_setserviceid	(		service,
			value )

Value:

mupnp_xml_node_setchildnode(mupnp_service_getservicenode(service), MUPNP_SERVICE_ID, value)

Set the service's service ID

Parameters

service	The service in question
value	Service ID string

◆ mupnp_service_setservicenode

#define mupnp_service_setservicenode	(		service,
			node )

Value:

(service->serviceNode = node)

Set the root XML node for the service

Parameters

service	The service in question
node	The node to set

◆ mupnp_service_setservicetype

#define mupnp_service_setservicetype	(		service,
			value )

Value:

mupnp_xml_node_setchildnode(mupnp_service_getservicenode(service), MUPNP_SERVICE_TYPE, value)

Set the service's complete type string (ex. "urn:schemas-upnp-org:service:FooService:1")

Parameters

service	The service in question
value	The type string

◆ mupnp_service_setsubscriptionsid

#define mupnp_service_setsubscriptionsid	(		service,
			value )

Value:

mupnp_string_setvalue(service->subscriptionSid, value)

Set the service's subscription's SID (subscription ID)

Parameters

service	The service in question
value	The SID

◆ mupnp_service_setsubscriptiontimeout

#define mupnp_service_setsubscriptiontimeout	(		service,
			value )

Value:

(service->subscriptionTimeout = value)

Set the service's subscription timeout (expiration) value

Parameters

service	The service in question
value	The timeout value

◆ mupnp_service_setsubscriptiontimestamp

#define mupnp_service_setsubscriptiontimestamp	(		service,
			value )

Value:

(service->subscriptionTimestamp = value)

Set the service's subscription time stamp

Parameters

service	The service in question
value	The time stamp

◆ mupnp_service_setuserdata

#define mupnp_service_setuserdata	(		service,
			value )

Value:

(service->userData = value)

Set the service's arbitrary user data pointer

Parameters

service	The service in question
value	The user data pointer

◆ MUPNP_SERVICE_TYPE

#define MUPNP_SERVICE_TYPE "serviceType"

◆ mupnp_service_unlock

#define mupnp_service_unlock ( service )

Value:

mupnp_mutex_unlock(service->mutex)

mupnp_mutex_unlock

bool mupnp_mutex_unlock(mUpnpMutex *mutex)

Release a previously acquired mutex lock.

Definition mutex.c:294

Unlock the service's mutex

Parameters

service The service in question

◆ mupnp_servicelist_add

#define mupnp_servicelist_add	(		serviceList,
			service )

Value:

mupnp_list_add((mUpnpList*)serviceList, (mUpnpList*)service)

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 a service to a list of services

Parameters

serviceList	The list to add the service to
service	The service to add to the list

◆ mupnp_servicelist_clear

#define mupnp_servicelist_clear ( serviceList )

Value:

mupnp_list_clear((mUpnpList*)serviceList, (MUPNP_LIST_DESTRUCTORFUNC)mupnp_service_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_service_delete

void mupnp_service_delete(mUpnpService *service)

Destroy a UPnP service and free all associated resources.

Definition service.c:87

Clear the contents of a list of services

Parameters

serviceList The list of services to clear

◆ MUPNP_SERVICELIST_ELEM_NAME

#define MUPNP_SERVICELIST_ELEM_NAME "serviceList"

◆ mupnp_servicelist_gets

#define mupnp_servicelist_gets ( serviceList )

Value:

(mUpnpService*)mupnp_list_next((mUpnpList*)serviceList)

Get the first service in a list of services. Use as the starting point in iteration loops.

Parameters

serviceList The service list

◆ mupnp_servicelist_size

#define mupnp_servicelist_size ( serviceList )

Value:

mupnp_list_size((mUpnpList*)serviceList)

mupnp_list_size

int mupnp_list_size(mUpnpList *headList)

Definition list.c:53

Get the number of services in a list of services

Parameters

serviceList The list of services

Returns: int

Typedef Documentation

◆ mUpnpService

typedef struct _mUpnpService mUpnpService

◆ mUpnpServiceList

typedef struct _mUpnpService mUpnpServiceList

Function Documentation

◆ mupnp_service_addsubscriber()

bool mupnp_service_addsubscriber	(	mUpnpService *	service,
		mUpnpSubscriber *	sub )

Add a subscriber to the service

Parameters

service	The service in question
sub	The subscriber

◆ mupnp_service_announcefrom()

bool mupnp_service_announcefrom	(	mUpnpService *	service,
		const char *	bindAddr )

Send a service announcement (advertisement) from the given address

Parameters

service	The service to advertise
bindAddr	The address to attach to the announcement

◆ mupnp_service_byebyefrom()

bool mupnp_service_byebyefrom	(	mUpnpService *	service,
		const char *	bindAddr )

Send a byebye announcement (i.e. a cancelling advertisement) from the given address

Parameters

service	The service to announce from
bindAddr	The address to attach to the announcement

◆ mupnp_service_clear()

void mupnp_service_clear ( mUpnpService * service )

Clear the contents of a UPnP service

Parameters

service The service to clear

◆ mupnp_service_createnotifyallthread()

void mupnp_service_createnotifyallthread	(	mUpnpService *	service,
		mUpnpTime	waitTime )

Create a new thread to send a notification message to all of the service's subscribers

Parameters

service	The service in question
waitTime	The wait time to send

◆ mupnp_service_delete()

void mupnp_service_delete ( mUpnpService * service )

Destroy a UPnP service and free all associated resources.

Releases all resources associated with the service, including:

All actions and their argument lists
State variable table and all state variables
SCPD XML description nodes
Subscriber list (if eventing enabled)
Internal mutexes

Parameters

service The service to destroy. May be NULL (no-op if NULL).

Note: After calling this function, the service pointer is invalid and must not be used.; Thread-safe: Must not be called concurrently with other operations on the same service.; Active event subscriptions are not automatically cancelled on the control point side. Subscribers will eventually time out.

See also: mupnp_service_new()

◆ mupnp_service_getactionbyname()

mUpnpAction * mupnp_service_getactionbyname	(	mUpnpService *	service,
		const char *	name )

Get an action from the service by the action's name

Parameters

service	The service in question
name	The name of the action to look for

Returns: mUpnpAction* or NULL

◆ mupnp_service_getactionlist()

mUpnpActionList * mupnp_service_getactionlist ( mUpnpService * service )

Get the service's list of actions (head of list)

Parameters

service The service in question

◆ mupnp_service_getactions()

mUpnpAction * mupnp_service_getactions ( mUpnpService * service )

Get the first action in the service's list of actions. Use as the starting point in iteration loops.

Parameters

service The service in question

◆ mupnp_service_getcontrolurl()

mUpnpNetURL * mupnp_service_getcontrolurl ( mUpnpService * service )

Get the service's control URL

Parameters

service The service in question

Returns: mUpnpNetURL Pointer to URL/URI structure

Get the service's control URL

Parameters

service The service in question

Returns: char*

◆ mupnp_service_getdescription()

char * mupnp_service_getdescription	(	mUpnpService *	service,
		mUpnpString *	descStr )

Get the service's description XML nodes as a string

Parameters

service	The service in question
descStr	The description string

◆ mupnp_service_geteventsuburl()

mUpnpNetURL * mupnp_service_geteventsuburl ( mUpnpService * service )

Get the service's event subscription URL

Parameters

service The service in question

Returns: mUpnpNetURL Pointer to URL/URI structure

Get the service's event subscription URL

Parameters

service The service in question

Returns: char*

◆ mupnp_service_getnotifyservicetypent()

char * mupnp_service_getnotifyservicetypent	(	mUpnpService *	service,
		char *	buf,
		int	bufSize )

◆ mupnp_service_getnotifyservicetypeusn()

char * mupnp_service_getnotifyservicetypeusn	(	mUpnpService *	service,
		char *	buf,
		int	bufSize )

◆ mupnp_service_getscpdurl()

mUpnpNetURL * mupnp_service_getscpdurl ( mUpnpService * service )

Get the service's SCPD (service description) URL

Parameters

service The service in question

Returns: mUpnpNetURL Pointer to URL/URI structure

◆ mupnp_service_getservicestatetable()

mUpnpServiceStateTable * mupnp_service_getservicestatetable ( mUpnpService * service )

Get the service's state table

Parameters

service The service in question

◆ mupnp_service_getstatevariablebyname()

mUpnpStateVariable * mupnp_service_getstatevariablebyname	(	mUpnpService *	service,
		const char *	name )

Get a state variable from the service's state table by the variable's name

Parameters

service	The service in question
name	the name of the variable

Returns: mUpnpStateVariable* or NULL

◆ mupnp_service_getstatevariables()

mUpnpStateVariable * mupnp_service_getstatevariables ( mUpnpService * service )

Get the first state variable in the service's state table. Use as the starting point in iteration loops.

Parameters

service The service in question

◆ mupnp_service_getsubscriberbysid()

mUpnpSubscriber * mupnp_service_getsubscriberbysid	(	mUpnpService *	service,
		const char *	sid )

Find a subscriber from the service's list of subscribers by its SID (Subscription ID)

Parameters

service	The service in question
sid	The SID

◆ mupnp_service_isscpdurl()

bool mupnp_service_isscpdurl	(	mUpnpService *	service,
		const char *	url )

Compare the service's SCPD URL and the given location

Parameters

service	The service in question
url	The URL (location) to compare

Returns: true if location is found from URL; otherwise false

◆ mupnp_service_new()

mUpnpService * mupnp_service_new ( void )

Create a new UPnP service instance.

Allocates and initializes a new UPnP service object. Services represent the functional units within a UPnP device, providing actions and state variables that can be controlled and queried by control points.

The function initializes:

Action list (empty)
State variable table (empty)
Subscriber list for event notifications (if eventing enabled)
Internal mutex for thread safety
SCPD (Service Control Protocol Description) node list

After creation, the service should be populated either by:

Parsing an SCPD document with mupnp_service_parsedescription()
Manual configuration with setter functions

Returns: A newly-created mUpnpService on success, or NULL if memory allocation fails.

Note: The returned service must be freed with mupnp_service_delete() when no longer needed.; Thread-safe: Can be called concurrently from multiple threads.; Services are typically created as part of device initialization and are managed by the parent device's service list.

See also: mupnp_service_delete(); mupnp_service_parsedescription()

◆ mupnp_service_notify()

bool mupnp_service_notify	(	mUpnpService *	service,
		mUpnpStateVariable *	statVar )

Send a notification of a service's changed state variable

Parameters

service	The service in question
statVar	The changed state variable

◆ mupnp_service_notifyall()

bool mupnp_service_notifyall	(	mUpnpService *	service,
		bool	doBracket )

Send a notification message to all of the service's subscribers

Parameters

service The service in question

◆ mupnp_service_parsedescription()

bool mupnp_service_parsedescription	(	mUpnpService *	service,
		const char *	description,
		size_t	descriptionLen )

Parse and populate a service from an SCPD XML document.

Parses the Service Control Protocol Definition (SCPD) XML document and populates the service with:

Actions and their input/output arguments
State variables with types, allowed values, and eventing properties

The SCPD document must conform to the UPnP Device Architecture specification. Any existing actions and state variables are cleared before parsing.

Example SCPD structure:

<scpd xmlns="urn:schemas-upnp-org:service-1-0">
  <specVersion><major>1</major><minor>0</minor></specVersion>
  <actionList>
    <action>
      <name>GetStatus</name>
      <argumentList>
        <argument>
          <name>Status</name>
          <direction>out</direction>
          <relatedStateVariable>Status</relatedStateVariable>
        </argument>
      </argumentList>
    </action>
  </actionList>
  <serviceStateTable>
    <stateVariable sendEvents="yes">
      <name>Status</name>
      <dataType>string</dataType>
    </stateVariable>
  </serviceStateTable>
</scpd>

Parameters

service	The service to populate. Must not be NULL.
description	The SCPD XML document as a string. Must not be NULL.
descriptionLen	The length of the XML document in bytes.

Return values

true	Successfully parsed the SCPD document
false	Parsing failed due to: NULL parameters Malformed XML XML doesn't conform to SCPD schema Memory allocation failure

Note: Thread-safe: Can be called from any thread.; Side effect: Clears any existing actions and state variables before parsing the new description.; The service's parsed flag is set to true on successful parsing.

See also: mupnp_service_parsedescriptionurl(); mupnp_service_isparsed()

◆ mupnp_service_parsedescriptionurl()

bool mupnp_service_parsedescriptionurl	(	mUpnpService *	service,
		mUpnpNetURL *	url )

Create the service's contents from the given URL. Gets the XML document from the URL and passes it again to mupnp_service_parsedescription

Parameters

service	The service to create
url	The URL of the document to parse

◆ mupnp_service_removesubscriber()

bool mupnp_service_removesubscriber	(	mUpnpService *	service,
		mUpnpSubscriber *	sub )

Remove a subscriber from the service

Parameters

service	The service in question
sub	The subscriber to remove

◆ mupnp_service_setactionlistener()

void mupnp_service_setactionlistener	(	mUpnpService *	service,
		MUPNP_ACTION_LISTNER	actionListener )

Set an action listener to the service

Parameters

service	The service in question
actionListener	A callback function of type MUPNP_ACTION_LISTNER

◆ mupnp_service_setquerylistener()

void mupnp_service_setquerylistener	(	mUpnpService *	service,
		MUPNP_STATEVARIABLE_LISTNER	queryListener )

Set a query listener to the service

Parameters

service	The service in question
queryListener	A callback function of type MUPNP_STATEVARIABLE_LISTNER

◆ mupnp_service_ssdpmessagereceived()

void mupnp_service_ssdpmessagereceived	(	mUpnpService *	service,
		mUpnpSSDPPacket *	ssdpPkt )

The service's handler function that deals with received SSDP messages.

Parameters

service	The service in question
ssdpPkt	The received SSDP packet

◆ mupnp_servicelist_delete()

void mupnp_servicelist_delete ( mUpnpServiceList * serviceList )

Destroy a list of services

Parameters

serviceList The list of services to destroy

◆ mupnp_servicelist_new()

mUpnpServiceList * mupnp_servicelist_new ( void )

Create a new list of services

◆ mupnp_servicetype_getidentifier()

const char * mupnp_servicetype_getidentifier ( const char * serviceType )

Get the identifier-part of a service type string (usually "urn")

Parameters

serviceType A service type string (usually the result from mupnp_service_getservicetype)

Returns: A newly-created char* if successful; otherwise NULL

◆ mupnp_servicetype_getschematype()

char * mupnp_servicetype_getschematype ( const char * serviceType )

Get the schema type part of a service type string (without last colon) (ex. "urn:schemas-upnp-org:service:ContentDirectory")

Parameters

serviceType A service type string (usually the result from mupnp_service_getservicetype)

Returns: A newly-created char* if successful; otherwise NULL

◆ mupnp_servicetype_getservice()

const char * mupnp_servicetype_getservice ( const char * serviceType )

Get the service part of a service type string (usually just "service")

Parameters

serviceType A service type string (usually the result from mupnp_service_getservicetype)

Returns: A newly-created char* if successful; otherwise NULL

◆ mupnp_servicetype_gettype()

const char * mupnp_servicetype_gettype ( const char * serviceType )

Get the type part of a service type string (ex. "ContentDirectory")

Parameters

serviceType A service type string (usually the result from mupnp_service_getservicetype)

Returns: A newly-created char* if successful; otherwise NULL

◆ mupnp_servicetype_geturn()

const char * mupnp_servicetype_geturn ( const char * serviceType )

Get the URN part of a service type string (usually "schemas-upnp-org")

Parameters

serviceType A service type string (usually the result from mupnp_service_getservicetype)

Returns: A newly-created char* if successful; otherwise NULL

◆ mupnp_servicetype_getversion()

const char * mupnp_servicetype_getversion ( const char * serviceType )

Get the version part of a service type string (ex. "1")

Parameters

serviceType A service type string (usually the result from mupnp_service_getservicetype)

Returns: A newly-created char* if successful; otherwise NULL

Data Structures

Macros

Typedefs

Functions

Macro Definition Documentation

◆ mupnp_service_clearsubscriptionsid

◆ MUPNP_SERVICE_CONTROL_URL

◆ MUPNP_SERVICE_ELEM_NAME

◆ MUPNP_SERVICE_EVENT_KEY_INVALID

◆ MUPNP_SERVICE_EVENT_SUB_URL

◆ mupnp_service_getdevice

◆ mupnp_service_getdevicenode

◆ mupnp_service_geteventkey

◆ mupnp_service_getnsubscribers

◆ mupnp_service_getrootdevice

◆ mupnp_service_getscpdnode

◆ mupnp_service_getserviceid

◆ mupnp_service_getservicenode

◆ mupnp_service_getservicetype

◆ mupnp_service_getsubscribers

◆ mupnp_service_getsubscriptionexpiration

◆ mupnp_service_getsubscriptionsid

◆ mupnp_service_getsubscriptiontimeout

◆ mupnp_service_getsubscriptiontimestamp

◆ mupnp_service_getuserdata

◆ mupnp_service_hasactionbyname

◆ mupnp_service_hasstatevariablebyname

◆ MUPNP_SERVICE_ID

◆ mupnp_service_isparsed

◆ mupnp_service_isservicenode

◆ mupnp_service_issubscribed

◆ mupnp_service_lock

◆ mupnp_service_next

◆ MUPNP_SERVICE_NOTIFY_WAITTIME

◆ mupnp_service_notifyallstatevariables

◆ MUPNP_SERVICE_SCPDURL

◆ mupnp_service_setcontrolurl

◆ mupnp_service_setdevice

◆ mupnp_service_seteventkey

◆ mupnp_service_seteventsuburl

◆ mupnp_service_setscpdurl

◆ mupnp_service_setserviceid

◆ mupnp_service_setservicenode

◆ mupnp_service_setservicetype

◆ mupnp_service_setsubscriptionsid

◆ mupnp_service_setsubscriptiontimeout

◆ mupnp_service_setsubscriptiontimestamp

◆ mupnp_service_setuserdata

◆ MUPNP_SERVICE_TYPE

◆ mupnp_service_unlock

◆ mupnp_servicelist_add

◆ mupnp_servicelist_clear

◆ MUPNP_SERVICELIST_ELEM_NAME

◆ mupnp_servicelist_gets

◆ mupnp_servicelist_size

Typedef Documentation

◆ mUpnpService

◆ mUpnpServiceList

Function Documentation

◆ mupnp_service_addsubscriber()

◆ mupnp_service_announcefrom()

◆ mupnp_service_byebyefrom()

◆ mupnp_service_clear()

◆ mupnp_service_createnotifyallthread()

◆ mupnp_service_delete()

◆ mupnp_service_getactionbyname()

◆ mupnp_service_getactionlist()

◆ mupnp_service_getactions()

◆ mupnp_service_getcontrolurl()

◆ mupnp_service_getdescription()

◆ mupnp_service_geteventsuburl()

◆ mupnp_service_getnotifyservicetypent()

◆ mupnp_service_getnotifyservicetypeusn()

◆ mupnp_service_getscpdurl()

◆ mupnp_service_getservicestatetable()

◆ mupnp_service_getstatevariablebyname()

◆ mupnp_service_getstatevariables()

◆ mupnp_service_getsubscriberbysid()

◆ mupnp_service_isscpdurl()

◆ mupnp_service_new()