API Documentation
-
namespace UPnP
-
Enums
-
enum ErrorValues
Values:
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>
-
class Stream : public MemoryDataStream
-
class Base64
- #include <Base64.h>
-
struct SearchFilter
- #include <BaseObject.h>
-
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.
-
virtual bool formatMessage(Message &msg, MessageSpec &ms) = 0
-
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>
-
class Iterator
-
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 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
-
inline ControlPoint(size_t maxResponseSize = 2048)
-
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 –
-
inline DescriptionStream(Object &object, const String &descriptionUrl)
-
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
-
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
-
String resolvePath(const String &path) const
-
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 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 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>
-
bool configureRoot(ControlPoint &controlPoint, const String &location, XML::Node *device)
-
class DeviceHost
- #include <DeviceHost.h>
Public Functions
-
IDataSourceStream *generateDebugPage(const String &title)
Create an HTML page which applications may serve up to assist with debugging.
-
IDataSourceStream *generateDebugPage(const String &title)
-
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 EnumeratorType *clone() = 0
-
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 ContentType contentType() const
Get the current envelope content type.
-
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.
-
class Fault
- #include <Envelope.h>
-
Error load(String &&content)
-
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 ItemEnumerator *clone() override
-
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
-
virtual void search(const SearchFilter &filter) = 0
-
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.
-
using Version = uint8_t
-
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 T>
-
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.
-
using Callback = Delegate<void(SSDP::BasicMessage &message)>
-
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
-
using Callback = Delegate<bool(DeviceControl &device)>
-
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
-
using Callback = Delegate<bool(DeviceControl &device, ServiceControl &service)>
-
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.:This is usually handled by generated wrapper class templates.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;
-
virtual void search(const SearchFilter &filter) override
-
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.:This is usually handled by generated wrapper class templates.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;
-
inline const Description &description()
Get service description.
-
struct Description
- #include <ServiceControl.h>
-
inline DeviceControl &root()
-
enum ErrorValues