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:

cls – Device 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:

cls – Service 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, const 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.

Parameters:

connection –
request –
response –

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:: serviceType – ObjectClass 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:: deviceType – ObjectClass 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 &connection): 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 &connection)

Called by framework to handle an incoming HTTP request.

Parameters:

connection –
request –
response –

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.

Parameters:

connection –
request –
response –

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 &req) 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