API Documentation

namespace UPnP

Typedefs

using Error = UPnP::Error

Enums

enum ErrorValues

Values:

enum class Error

Values:

enumerator XX
enumerator Pending
enum class ErrorCode

Values:

enumerator XX
enum class DescType

When building descriptions this qualifies what information is required.

Values:

enumerator header

Description template with main document element.

enumerator embedded

Details for embedded device or service.

enumerator content

Full details for this device or service.

Functions

ErrorCode getErrorCode(Error err)

Get corresponding error code for a given error.

Variables

DeviceHost deviceHost
class ActionRequest : public UPnP::ActionResponse
#include <ActionRequest.h>
class ActionRequestControl : public UPnP::ActionResponse
#include <ActionRequest.h>
class ActionResponse : public UPnP::LinkedItem
#include <ActionResponse.h>

Class to handle action requests and responses.

Subclassed by UPnP::ActionRequest, UPnP::ActionRequestControl

class Stream : public MemoryDataStream
#include <ActionResponse.h>

Public Functions

inline virtual bool isFinished() override

Check if all data has been read.

Return values:

bool – True on success.

inline virtual MimeType getMimeType() const override

Get MIME type for stream content.

Return values:

MimeType

class Base64
#include <Base64.h>
struct SearchFilter
#include <BaseObject.h>

Public Members

const MessageSpec &ms

Specification for message to be sent.

uint32_t delayMs

Message delay.

String targetString

Full search target value.

Callback callback

Called on a match.

class BaseObject : public UPnP::LinkedItem
#include <BaseObject.h>

Objects which hook into the SSDP message stack.

Subclassed by UPnP::ObjectTemplate< ControlPoint, BaseObject >, UPnP::Object

Public Functions

virtual bool formatMessage(Message &msg, MessageSpec &ms) = 0

Standard fields have been completed.

Note

Fields can be modified typically by adding any custom fields before sending response.

Parameters:
  • msg – The message being constructed

  • ms – Template spec. for message

Return values:

bool – Return true to send message, false to cancel

virtual void sendMessage(Message &msg, MessageSpec &ms)

Called by framework to construct then send a message.

Parameters:
  • msg – Message to send

  • ms – Template spec.

template<typename ObjectType, typename BaseObjectType>
class ObjectTemplate : public BaseObjectType
#include <BaseObject.h>

Base class template for linked items with type casting.

class Iterator
#include <BaseObject.h>
struct ClassGroup
#include <ClassGroup.h>
class ClassGroupList : public Vector<ClassGroup>
#include <ClassGroup.h>
class ControlPoint : public UPnP::ObjectTemplate<ControlPoint, BaseObject>
#include <ControlPoint.h>

Public Functions

inline ControlPoint(size_t maxResponseSize = 2048)

Constructor.

Parameters:

maxResponseSize – Limits size of stream used to receive HTTP responses

inline void reset()

Cancel any outstanding search and reset the list of known unique service names.

inline void clear()

Perform a reset and destroy all created devices.

inline bool beginSearch(const Urn &urn, SsdpSearch::Callback callback)

Searches for UPnP device or service and returns SSDP response messages.

Parameters:
  • urn – unique identifier of the service or device to find

  • callback – Invoked with SSDP response message

Return values:

bool – true on success, false if request queue is full

inline bool beginSearch(const Urn &urn, DescriptionSearch::Callback callback)

Searches for UPnP device or service and fetches its description.

Parameters:
  • urn – unique identifier of the service or device to find

  • callback – Invoked with device description document

Return values:

bool – true on success, false if request queue is full

inline bool beginSearch(const ObjectClass &cls, DeviceSearch::Callback callback)

Searches for UPnP device.

Parameters:
  • clsDevice class object

  • callback – Invoked with constructed control object

Return values:

bool – true on success, false if request queue is full

inline bool beginSearch(const ObjectClass &cls, ServiceSearch::Callback callback)

Searches for UPnP service.

Parameters:
  • clsService class object

  • callback – Invoked with constructed control object

Return values:

bool – true on success, false if request queue is full

inline bool isSearchActive() const

Determine if there’s an active search in progress.

bool cancelSearch()

Cancel any active search operation.

Todo:

Set timeout on search operation and call this automatically Need to inform application though - perhaps a generic callback on the class?

Return values:

bool – true if a search was active, false if there was no active search

virtual void onNotify(BasicMessage &msg)

Called by framework to handle an incoming SSDP message.

Parameters:

msg

virtual bool formatMessage(Message &msg, MessageSpec &ms) override

Standard fields have been completed.

Note

Fields can be modified typically by adding any custom fields before sending response.

Parameters:
  • msg – The message being constructed

  • ms – Template spec. for message

Return values:

bool – Return true to send message, false to cancel

bool sendRequest(HttpRequest *request)

Send a request.

Parameters:

request – Completed request object: leave response stream unassigned, will be set later

Return values:

bool – true on success, false if queue is full

bool requestDescription(const String &url, DescriptionSearch::Callback callback)

Send a request for description document.

Parameters:
  • request – Description URL

  • callback – To be invoked with requested document

Return values:

bool – true on success, false if queue is full

Public Static Functions

static void onSsdpMessage(BasicMessage &msg)

Called via SSDP when incoming message received.

static const ObjectClass *findClass(const Urn &objectType)

Find a registered class.

Parameters:

objectType – Urn uniquely identifying the class

Return values:

ObjectClass* – The class, or nullptr if not found

static inline void registerClasses(const FlashString &domain, ObjectClass::List &classes)

Use this method to register all device and service classes you need to control.

Class information is required in order to instantiate device or service objects in response to incoming descriptions. This information must be pre-registered with the control point.

Parameters:
  • domain

  • classes – List of classes to register

class DescriptionStream : public IDataSourceStream
#include <DescriptionStream.h>

Public Functions

inline DescriptionStream(Object &object, const String &descriptionUrl)

Construct a description stream.

Parameters:

object – The Object to enumerate

void reset()

Reset back to start.

Note

Handy if you want to re-use this stream to send it somewhere else

inline virtual bool isValid() const override

Determine if the stream object contains valid data.

Note

Where inherited classes are initialised by constructor this method indicates whether that was successful or not (e.g. FileStream)

Return values:

bool – true if valid, false if invalid

virtual uint16_t readMemoryBlock(char *data, int bufSize) override

Read a block of memory.

Todo:

Should IDataSourceStream::readMemoryBlock return same data type as its bufSize param?

Parameters:
  • data – Pointer to the data to be read

  • bufSize – Quantity of chars to read

Return values:

uint16_t – Quantity of chars read

virtual bool seek(int len) override

Move read cursor.

Parameters:

len – Relative cursor adjustment

Return values:

bool – True on success.

inline virtual bool isFinished() override

Check if all data has been read.

Return values:

bool – True on success.

inline virtual String getName() const override

Returns name of the resource.

Note

Commonly used to obtain name of file

Return values:

String

inline virtual MimeType getMimeType() const override

Get MIME type for stream content.

Return values:

MimeType

struct SpecVersion
#include <Device.h>
class Device : public UPnP::ObjectTemplate<Device, Object>
#include <Device.h>

Represents any kind of device, including a root device.

Subclassed by UPnP::DeviceControl

Public Functions

virtual String getUrl(const String &path) const

Get fully qualified URL.

virtual String getUrlBasePath() const

Get the base URL path.

String resolvePath(const String &path) const

Resolve a path (relative or absolute) into an absolute path.

virtual void search(const SearchFilter &filter) override

Called during SSDP search operation.

virtual bool formatMessage(Message &msg, MessageSpec &ms) override

Standard fields have been completed.

Note

Fields can be modified typically by adding any custom fields before sending response.

Parameters:
  • msg – The message being constructed

  • ms – Template spec. for message

Return values:

bool – Return true to send message, false to cancel

virtual bool onHttpRequest(HttpServerConnection &connection) override

Called by framework to handle an incoming HTTP request.

Return values:

bool – true if request was handled

virtual IDataSourceStream *createDescription() override

Called by framework to construct a device description response stream.

By default, the framework generates a stream constructed from the device information fields, but this method may be overridden if, for example, a fixed description is stored in an .xml file.

Return values:

IDataSourceStream* – The XML description content

class DeviceControl : public UPnP::Device
#include <DeviceControl.h>

Subclassed by Dial::Client

Public Functions

bool configureRoot(ControlPoint &controlPoint, const String &location, XML::Node *device)

Called on root device only during discovery.

inline DeviceControl &root()

Get the root device.

inline virtual String getUrl(const String &path) const override

Get fully-qualified URL given a relative path.

inline virtual String getUrlBasePath() const override

Get relative path for this device.

inline ControlPoint &controlPoint() const

Get managing control point for this device.

template<typename T>
inline ServiceControl *getService(const T &serviceType)

Find a service for this device given its class.

Template Parameters:

serviceTypeObjectClass or Urn of service to locate

Return values:

ServiceControl* – May be nullptr if not found

template<typename T>
inline DeviceControl *getDevice(const T &deviceType)

Find a child device given its class.

Template Parameters:

deviceTypeObjectClass or Urn of device to locate

Return values:

DeviceControl* – May be nullptr if not found

inline const String udn() const

Get UDN for this device.

bool configure(XML::Node *device)

Configure device using information from description document.

inline virtual void onConnected(HttpConnection&)

Inherited classes may override this to pull out any additional information from received response headers, etc. Invoked after description has been processed.

inline const Description &description()

Get device description.

struct Description
#include <DeviceControl.h>
class DeviceHost
#include <DeviceHost.h>

Public Functions

bool begin()

Applications must call this to initialise UPnP stack.

IDataSourceStream *generateDebugPage(const String &title)

Create an HTML page which applications may serve up to assist with debugging.

void onSearchRequest(const BasicMessage &request)

Called via SSDP when incoming message received.

template<typename ItemType, class EnumeratorType>
class Enumerator
#include <Enumerator.h>

Abstract class to enumerate items.

todo: We want a generic enumerator which returns Items, uses virtual methods so no upcasting required

Note

Returned items may only be considered valid for the duration of the current task call as they may be destroyed at any time.

Public Functions

virtual EnumeratorType *clone() = 0

Make a copy of this enumerator.

Note

Each copy maintains position independently

virtual void reset() = 0

Reset enumerator to start of list.

Note

Call to next() will return first item

virtual ItemType *current() = 0

Get the current item.

Return values:

Item* – nullptr if before start or at end of list

virtual ItemType *next() = 0

Get next item.

Return values:

Item* – nullptr if no more devices

class Envelope
#include <Envelope.h>

Class to manage a SOAP envelope for service request/response.

Unnamed Group

Error load(String &&content)

Load a SOAP document.

Parameters:

content – MUST remain valid for the lifetime of this Envelope, or until initialise() is called.

Public Functions

void clear()

Wipe the envelope contents.

inline String serialize(bool pretty)

Obtain content as XML string.

inline size_t serialize(Print &p, bool pretty)

Serialize XML content to a stream.

inline ContentType contentType() const

Get the current envelope content type.

inline String actionName() const

Get the action name.

Envelope &createRequest(const String &actionName)

Initialise the envelope as a request.

Envelope &createResponse(const String &actionName)

Initialise the envelope as a response.

inline void convertToResponse()

Set a flag that this should be converted to Response on next setArg() call.

inline void prepareResponse()

If Response is required but hasn’t been prepared yet, do it now. This wipes out the incoming request.

Fault createFault(ErrorCode error)

Initialise the envelope as a fault.

class Fault
#include <Envelope.h>
class Item
#include <Item.h>

Subclassed by Hue::Device, UPnP::LinkedItem

class ItemEnumerator : public UPnP::Enumerator<Item, ItemEnumerator>
#include <ItemEnumerator.h>

Public Functions

inline virtual ItemEnumerator *clone() override

Make a copy of this enumerator.

Note

Each copy maintains position independently

inline virtual void reset() override

Reset enumerator to start of list.

inline virtual Item *current() override

Get the current item.

Return values:

Item* – nullptr if before start or at end of list

inline virtual Item *next() override

Move to next item in list.

Return values:

Item* – the item, nullptr if at end

class LinkedItem : public UPnP::Item
#include <LinkedItem.h>

Base class template for items in a list.

Subclassed by UPnP::ActionResponse, UPnP::BaseObject

class LinkedItemList
#include <LinkedItemList.h>

Singly-linked list of items.

Note

We don’t own the items, just keep references to them

Subclassed by UPnP::ObjectList< Device >, UPnP::ObjectList< ObjectType >

class Object : public UPnP::BaseObject
#include <Object.h>

Subclassed by UPnP::ObjectTemplate< Service, Object >, UPnP::ObjectTemplate< Device, Object >

Public Functions

virtual void search(const SearchFilter &filter) = 0

Called during SSDP search operation.

inline virtual bool onHttpRequest(HttpServerConnection&)

Called by framework to handle an incoming HTTP request.

Return values:

bool – true if request was handled

inline virtual IDataSourceStream *createDescription()

Called by framework to construct a device description response stream.

By default, the framework generates a stream constructed from the device information fields, but this method may be overridden if, for example, a fixed description is stored in an .xml file.

Return values:

IDataSourceStream* – The XML description content

struct ObjectClass
#include <ObjectClass.h>

Describes device or service class.

Public Types

using Version = uint8_t

Interface version number.

using CreateObject = Object *(*)(DeviceControl *owner)

Object constructor function.

struct Device
#include <ObjectClass.h>

Device description fields.

struct Service
#include <ObjectClass.h>

Service description fields.

template<typename ObjectType>
class ObjectList : public UPnP::LinkedItemList
#include <ObjectList.h>

Class template for singly-linked list of objects.

Note

We don’t own the objects, just keep references to them

Subclassed by UPnP::OwnedObjectList< DeviceControl >, UPnP::OwnedObjectList< Service >, UPnP::OwnedObjectList< ObjectType >

Public Functions

template<typename T>
inline ObjectType *find(const T &objectType)

Search list for matching entry.

Template Parameters:

Urn – or String

Return values:

ObjectType* – Located definition or nullptr if not found

inline ObjectType *find(const ObjectClass &objectClass)

Search list for matching entry given its class @objectClass Class information for object.

Return values:

ObjectType* – Located definition or nullptr if not found

template<typename ObjectType>
class OwnedObjectList : public UPnP::ObjectList<ObjectType>
#include <ObjectList.h>

Class template for singly-linked list of objects.

Note

We own the objects so are responsible for destroying them when removed

struct Search
#include <Search.h>

This is a helper class used by ControlPoint to manage different search types.

Subclassed by UPnP::DescriptionSearch, UPnP::DeviceSearch, UPnP::ServiceSearch, UPnP::SsdpSearch

struct SsdpSearch : public UPnP::Search
#include <Search.h>

Public Types

using Callback = Delegate<void(SSDP::BasicMessage &message)>

Callback invoked for every matching SSDP message.

struct DescriptionSearch : public UPnP::Search
#include <Search.h>

Public Types

using Callback = Delegate<void(HttpConnection &connection, XML::Document *description)>

Callback invoked when description received If HTTP request fails, description will be null.

struct DeviceSearch : public UPnP::Search
#include <Search.h>

Public Types

using Callback = Delegate<bool(DeviceControl &device)>

Callback invoked when device has been located.

Note

If callback sends out action requests then must return true

Param device:

A newly constructed instance matching the search criteria

Retval bool:

Return true to keep the device, false to destroy it

struct ServiceSearch : public UPnP::Search
#include <Search.h>

Public Types

using Callback = Delegate<bool(DeviceControl &device, ServiceControl &service)>

Callback invoked when service has been located.

Note

If callback sends out action requests then must return true

Param device:

A newly constructed instance matching the search criteria

Param service:

Requested service interface

Retval bool:

Return true to keep the device, false to destroy it

class Service : public UPnP::ObjectTemplate<Service, Object>
#include <Service.h>

Represents any kind of device, including a root device.

Subclassed by UPnP::ServiceControl

Public Functions

virtual void search(const SearchFilter &filter) override

Called during SSDP search operation.

virtual bool formatMessage(Message &msg, MessageSpec &ms) override

Standard fields have been completed.

Note

Fields can be modified typically by adding any custom fields before sending response.

Parameters:
  • msg – The message being constructed

  • ms – Template spec. for message

Return values:

bool – Return true to send message, false to cancel

virtual bool onHttpRequest(HttpServerConnection &connection) override

Called by framework to handle an incoming HTTP request.

Return values:

bool – true if request was handled

virtual IDataSourceStream *createDescription() override

Called by framework to construct a device description response stream.

By default, the framework generates a stream constructed from the device information fields, but this method may be overridden if, for example, a fixed description is stored in an .xml file.

Return values:

IDataSourceStream* – The XML description content

inline virtual bool sendRequest(HttpRequest *request) const

Implemented in ServiceControl.

virtual Error handleAction(ActionRequest &req) = 0

An action request has been received.

Parameters:

env – Contains the action request

Return values:

ErrorCode – Implementation should place response into env after reading parameters, e.g.:

if(env.actionName() == "MyAction") {
        String arg1;
        int arg2;
        env.getArg("arg1", arg1);
        env.getArg("arg2", arg2);
        auto& response = env.createResponse();
        // Process command here
        int arg3 = processMyAction(arg1, arg2);
        response.setArg("arg3", arg3);
        return ErrorCode::Success;
    }

    return ErrorCode::InvalidAction;
This is usually handled by generated wrapper class templates.

class ServiceControl : public UPnP::Service
#include <ServiceControl.h>

Public Functions

inline DeviceControl &root()

Get the root device.

virtual bool sendRequest(HttpRequest *request) const override

Implemented in ServiceControl.

inline virtual Error handleAction(ActionRequest&) override

An action request has been received.

Parameters:

env – Contains the action request

Return values:

ErrorCode – Implementation should place response into env after reading parameters, e.g.:

if(env.actionName() == "MyAction") {
        String arg1;
        int arg2;
        env.getArg("arg1", arg1);
        env.getArg("arg2", arg2);
        auto& response = env.createResponse();
        // Process command here
        int arg3 = processMyAction(arg1, arg2);
        response.setArg("arg3", arg3);
        return ErrorCode::Success;
    }

    return ErrorCode::InvalidAction;
This is usually handled by generated wrapper class templates.

bool configure(const XML::Node *service)

Called during initialisation to configure this object.

inline const Description &description()

Get service description.

struct Description
#include <ServiceControl.h>
namespace schemas_upnp_org
namespace device