service.c File Reference

#include <mupnp/service.h>
#include <mupnp/device.h>
#include <mupnp/net/uri.h>
#include <mupnp/net/url.h>
#include <mupnp/ssdp/ssdp.h>
#include <mupnp/upnp.h>
#include <mupnp/upnp_function.h>
#include <mupnp/util/log.h>
#include <mupnp/util/string.h>

Functions
static void	mupnp_service_initchildnodes (mUpnpService *service)
static void	mupnp_service_initactionlist (mUpnpService *service)
static void	mupnp_service_initservicestatetable (mUpnpService *service)
static mUpnpNetURL *	mupnp_service_mangleurl (mUpnpService *service, char *type)
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_isscpdurl (mUpnpService *service, const char *url)
mUpnpNetURL *	mupnp_service_geteventsuburl (mUpnpService *service)
mUpnpNetURL *	mupnp_service_getcontrolurl (mUpnpService *service)
mUpnpNetURL *	mupnp_service_getscpdurl (mUpnpService *service)
bool	mupnp_service_parsedescription (mUpnpService *service, const char *desciption, 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)
char *	mupnp_service_getnotifyservicetypent (mUpnpService *service, char *buf, int bufSize)
char *	mupnp_service_getnotifyservicetypeusn (mUpnpService *service, char *buf, int bufSize)
bool	mupnp_service_announcefrom (mUpnpService *service, const char *bindAddr)
bool	mupnp_service_byebyefrom (mUpnpService *service, const char *bindAddr)
mUpnpAction *	mupnp_service_getactionbyname (mUpnpService *service, const char *name)
mUpnpStateVariable *	mupnp_service_getstatevariablebyname (mUpnpService *service, const char *name)
void	mupnp_service_setactionlistener (mUpnpService *service, MUPNP_ACTION_LISTNER actionListener)
void	mupnp_service_setquerylistener (mUpnpService *service, MUPNP_STATEVARIABLE_LISTNER queryListener)
mUpnpActionList *	mupnp_service_getactionlist (mUpnpService *service)
mUpnpAction *	mupnp_service_getactions (mUpnpService *service)
mUpnpServiceStateTable *	mupnp_service_getservicestatetable (mUpnpService *service)
mUpnpStateVariable *	mupnp_service_getstatevariables (mUpnpService *service)
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)
mUpnpNetURL *	mupnp_service_mangleabsoluteurl (const char *serviceURLStr, const char *baseURLStr, const char *locationURLStr)

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_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

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

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_initactionlist()

static void mupnp_service_initactionlist ( mUpnpService * service )

static

mupnp_service_initchildnodes()

static void mupnp_service_initchildnodes ( mUpnpService * service )

static

mupnp_service_initservicestatetable()

static void mupnp_service_initservicestatetable ( mUpnpService * service )

static

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_mangleabsoluteurl()

mUpnpNetURL * mupnp_service_mangleabsoluteurl	(	const char *	serviceURLStr,
		const char *	baseURLStr,
		const char *	locationURLStr )

mupnp_service_mangleurl()

static mUpnpNetURL * mupnp_service_mangleurl ( mUpnpService * service, char * type )

static

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_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_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