CascadeUPnP.h

Go to the documentation of this file.

//
// CascadeUPnP.h - interface file for class CascadeUPnP
//
// Copyright (c) 2004, Roku, LLC.  All rights reserved.
//

#ifndef _ROKU_INCLUDE_CASCADE_NET_CASCADEUPNP_H
#define _ROKU_INCLUDE_CASCADE_NET_CASCADEUPNP_H

#include <cascade/util/CascadeNewArray.h>
#include <cascade/util/CascadeString.h>
#include <cascade/interthread/CascadeMutex.h>

// TODO:  (notes on original VDK API)
//
// Not currently exposed in this UPnP interface is control and subscription
// of events via the services exposed by a UPnP device.  This is currently
// a discovery-only API.
//
// FIXME: declarations currently reside in sbAllegro.cpp

// enable new cascade UPnP interface except on VDK and WIN32
#define _NEW_CASCADE_UPNP_IFACE
#ifdef WIN32
#undef _NEW_CASCADE_UPNP_IFACE
#endif
#ifdef AD_VDK_OS
#undef _NEW_CASCADE_UPNP_IFACE
#endif

// class CascadeUPnP
#ifndef _NEW_CASCADE_UPNP_IFACE
#define CascadeAppMessageSink CascadeObject
#else
#include <cascade/app/CascadeAppMessageSink.h>
#endif

class CascadeUPnP : public CascadeAppMessageSink
{
private:
    class UPnP; friend class UPnP;
public:
    CascadeUPnP();
    virtual ~CascadeUPnP();
    
public:
    // class Device is used to report discovered UPnP devices on the network
    enum DeviceStatus   { kOnline = 0, kOffline = 1 }; // could add kExpired
    class Device
    {
    public:
        CascadeString   m_deviceUUID;
            // Universally Unique Identifier for this device
            // NOTE: does NOT begin with "uuid:"
        CascadeString   m_deviceType;
            // UPnP device type, e.g., "schemas-upnp-org:device:MediaServer:1"
            // NOTE: does NOT begin with "urn:"
        DeviceStatus    m_deviceStatus;
            // Is this device online?
        CascadeString   m_deviceDescriptionURL;
            // URL to the device's XML description document
        bool            m_bRootDevice;
            // is this device a root device?
        
        CascadeNewArray<CascadeString>  m_serviceTypes;
            // array of strings that describe services a la Service::m_serviceType
    public:
#ifdef _NEW_CASCADE_UPNP_IFACE
        bool operator == (const Device & that) const;
            // compares this with that returning true if they are equivalent,
            // false otherwise.  Equivalency means the following:
            // m_deviceUUID == that.m_deviceUUID; same for m_deviceType, status,
            // description url and device type.
            //
            // m_servicesTypes is scanned and compared with that.m_serviceTypes
            // to determine if they both contain the same number and type of
            // services, though not necessarily in the same order in the
            // m_serviceTypes array
        Device & operator = (const Device & that);
        inline bool IsMediaServer() const { return (m_deviceType == CascadeUPnP::MediaServerDeviceType()); }
#endif
    };
    // class Service describes a service available on a device, a list of which
    // is provided in class DeviceDescription, below
    class Service
    {
    public:
        CascadeString   m_serviceType;
            // a service type string of the form:
            // "urn:<domain-name>:service:<service-type>:<v>"
            // where <domain-name> is "schemas-upnp-org" for registered services
            // and <service-type> is the service and <v> is an integer version number
        CascadeString   m_serviceId;
            // a unique identifier to id this service when communicating with the server
        CascadeString   m_scpdUrl;
            // url for retrieving the service description
            // (Service Control Protocol Definition URL)
        CascadeString   m_controlUrl;
            // url for invoking actions
        CascadeString   m_eventSubUrl;
            // url for subscribing to events
    };
    // class DeviceIcon describes an icon available on a device, a list of which
    // is provided in class DeviceDescription, below
    class DeviceIcon
    {
    public:
        CascadeString   m_mimeType;
        CascadeString   m_url;
        u16             m_nWidth;
        u16             m_nHeight;
        u16             m_nDepth;
    };
    // class DeviceDescription provides an in-depth description of a UPnP device.
    // Returned by GetDeviceDescription(), below.
    class DeviceDescription
    {
    public:
        CascadeString   m_deviceType;
            // UPnP device type.  For std devices defined by a UPnP Forum working committee,
            // must start with "urn:schemas-upnp-org:device:", followed by a device type
            // suffix, colon, and an integer device version.  (Required)
        CascadeString   m_friendlyName;
            // Short description for end user.  Should be localized.  (Required)
        CascadeString   m_manufacturer;
            // Manufacturer.  May be localized.  (Required)
        CascadeString   m_manufacturerURL;
            // Web site for manufacturer.  May be localized.  (Optional)
        CascadeString   m_modelDescription;
            // Long description for user.  Should be localized.  (Recommended)
        CascadeString   m_modelName;
            // Model name.  May be localized.  (Required)
        CascadeString   m_modelNumber;
            // Model Number.  May be localized.  (Recommended)
        CascadeString   m_modelURL;
            // Web site for model.  May be localized.  (Optional)
        CascadeString   m_serialNumber;
            // Serial number.  May be localized.  (Recommended)
        CascadeString   m_udn;
            // Unique Device Name, begins with "uuid:", is a Universally-Unique ID.  (Required)
        #ifdef _NEW_CASCADE_UPNP_IFACE
            CascadeString   m_deviceUUID;
        #endif
        CascadeString   m_upc;
            // Universal Product Code.  12-digit, all-numeric product code.  (Optional)

        CascadeNewArray<Service>        m_deviceServices;
            // list of services available on the device
        CascadeNewArray<DeviceIcon>     m_deviceIcons;
            // list of icons with which to represent the device
    };
    class AVObject
    {
    public:
        AVObject() : m_classActions(0), m_numericProperties(0), m_stringProperties(0), m_personas(0), m_resources(0) { }
    public:
        enum ObjectType
        {
            kContainer = 0,
            kItem
        };
        enum ClassActionType
        {
            kCreate = 0,
            kSearch
        };
        enum NumericPropertyType
        {
            kStorageTotal = 0,
            kStorageUsed,
            kStorageFree,
            kStorageMaxPartition,
            kDVDRegionCode,
            kOriginalTrackNumber
        };
        enum StringPropertyType
        {
            kWriteStatus = 0,
            kStorageMedium,
            kData,
            kActor,
            kAlbum,
            kArtist,
            kAuthor,
            kCreator,
            kGenre,
            kDirector,
            kProducer,
            kPublisher,
            kAlbumArtURL,
            kArtistDiscographyURI,
            kLyricsURI,
            kRelation,
            kPlaylist,
            kIconURI,
            kRegion,
            kRating,
            kRights,
            kLanguage,
            kRadioCallSign,
            kRadioStationID,
            kRadioBand,
            kChannelNumber,
            kChannelName,
            kScheduledStartTime,
            kScheduledEndTime,
            kDescription,
            kTOC,
            kUserAnnotation
        };
        enum PersonaType
        {
            kActorPersona = 0,
            kArtistPersona,
            kAuthorPersona
        };
        class ClassAction
        {
        public:
            ClassActionType     m_type;
            CascadeString       m_class;
            CascadeString       m_className;
            bool                m_bIncludeDerived;
        };
        class NumericProperty
        {
        public:
            NumericPropertyType m_type;
            s32                 m_nValue;
        };
        class StringProperty
        {
        public:
            StringPropertyType  m_type;
            CascadeString       m_value;
        };
        class Persona
        {
        public:
            PersonaType         m_type;
            CascadeString       m_name;
            CascadeString       m_role;
        };
        class Resource
        {
        public:
            CascadeString       m_protocolInfo;
            CascadeString       m_protection;
            CascadeString       m_URI;
            CascadeString       m_importURI;
            u32                 m_nSize;
            CascadeString       m_duration;
            u32                 m_nBitrate;
            u32                 m_nSampleRate;
            u32                 m_nBitsPerSample;
            u32                 m_nNumChannels;
            CascadeString       m_resolution;
            u32                 m_nColorDepth;
        };
    public:
        ObjectType                          m_type;
        CascadeString                       m_id;
        CascadeString                       m_idParent;
        CascadeString                       m_idRef;
        bool                                m_bRestricted;
        u32                                 m_nChildCount;
        bool                                m_bSearchable;
        CascadeString                       m_title;
        CascadeString                       m_class;
        CascadeString                       m_className;
        CascadeNewArray<ClassAction>        m_classActions;
        CascadeNewArray<NumericProperty>    m_numericProperties;
        CascadeNewArray<StringProperty>     m_stringProperties;
        CascadeNewArray<Persona>            m_personas;
        CascadeNewArray<Resource>           m_resources;
    };
    class AVObjectArray : private CascadeNewArray<AVObject *>
    {
    public:
        AVObjectArray() : CascadeNewArray<AVObject *>(0), m_nOwningTransactionID(0) { }
        virtual ~AVObjectArray();
    public:
        void Empty();
            // frees all elements of the array and sets the size to zero
        AVObject * TakeOwnership(u32 nIndex);
            // TakeOwnership() returns the AVObject * at index nIndex
            // and takes ownership of the AVObject *.  After calling
            // TakeOwnership() it is your responsibility to free the
            // returned AVObject *.
        u32 GetSize();
        AVObject * operator[](u32 nIndex) const;
        AVObject * GetAt(u32 nIndex) const;
        u32 GetOwningTransactionID() const;

    private:
        u32 m_nOwningTransactionID;
        CascadeMutex m_mutex;
        friend class UPnP;
        friend class CascadeUPnPMessage;
    };
public:
    #ifdef _NEW_CASCADE_UPNP_IFACE
    // We now have two versions - first the new Cascade version in which
    // all requests return cancelable transaction ids ,
    // and the existing SoundBridge version which is retained for compatibility.
    // The Cascade version is implemented in CascadeUPnP.cpp; the SB version
    // is in sbAllegro.cpp.
    // FIRST THE NEW DULCHUTES-VERSION!
        enum TransactionResult
        {
            kUnknownDevice = 0,
            kDeviceNotUPnPAVServer,
            kDeviceNotWMCServer,
            kDeviceOffline,
            kDeviceError,
            kTimeout,
            kResourceBusy,
            kDeviceDescriptionNotCached,
            kRemoteSystemElementNotResponding,
            kAllocationError,
            kDataError,
            kParameterError,
            kEnumerationAborted,
            kObjectArrayInUse,
            kReissueTransaction,
            kSuccess
        };

        // asynchronous transactions - not requiring a cached device description
        virtual u32  CatalogLocalDevices();
        virtual u32  RequestDeviceDescription(const CascadeString & deviceUUID);
        virtual u32  RequestDeviceMount(const CascadeString & deviceUUID);

        // asynchronous transactions - requiring a cached device description
        virtual u32  RequestWMCAuthorizationStatus(const CascadeString & deviceUUID);
        virtual u32  RequestAVSearchCapabilities(const CascadeString & deviceUUID);
        
        virtual u32  InitiateAVSearch(
                        const CascadeString & deviceUUID,
                        const CascadeString & containerObjectID,
                        const CascadeString & searchTerm,
                        const CascadeString & filterTerm,
                        const CascadeString & sortTerm,
                                        u32   nStartIndex,
                                        u32   nCount,
                              AVObjectArray & arrayToFill);
        
        virtual u32  InitiateAVBrowse(
                        const CascadeString & deviceUUID,
                        const CascadeString & containerObjectID,
                        const CascadeString & filterTerm,
                        const CascadeString & sortTerm,
                                        u32   nStartIndex,
                                        u32   nCount,
                              AVObjectArray & arrayToFill);
        
        virtual u32  InitiateAVObjectFetch(
                        const CascadeString & deviceUUID,
                        const CascadeString & objectID,
                        const CascadeString & filterTerm,
                                   AVObject & objectToSet);

        // cancelling asynchronous transactions
        virtual void CancelTransaction(u32 nTransactionID);

        // asynchronous transaction result notification
        virtual void OnCatalogResult(const Device & device);
        virtual void OnDeviceDescriptionResult(u32 nTransactionID, TransactionResult result, const DeviceDescription & deviceDescription);
        virtual void OnDeviceMountResult(u32 nTransactionID, TransactionResult result, bool bMounted);
        virtual void OnWMCAuthorizationStatusResult(u32 nTransactionID, TransactionResult result, bool bAuthorized);
        virtual void OnAVSearchCapabilitiesResult(u32 nTransactionID, TransactionResult result, const CascadeString & searchCapabilities);
        virtual void OnAVSearchResult(u32 nTransactionID, TransactionResult result, u32 nMatchCount, AVObjectArray & objectArray, bool bComplete);
            // OnAVSearchResult will get repeatedly called back, growing
            // objectArray until (a) your desired count is reached, (b)
            // objectArray contains nMatchCount items, or (c) an error occurs.
            // In any of these cases, bComplete will be set to true, indicating
            // that this is the last callback and that objectArray will no longer
            // be touched by CascadeUPnP - you are free to delete it.

        virtual void OnAVBrowseResult(u32 nTransactionID, TransactionResult result, u32 nMatchCount, AVObjectArray & objectArray, bool bComplete);
        virtual void OnAVObjectFetchResult(u32 nTransactionID, TransactionResult result, AVObject & object);
                
        // synchronous requests        
        virtual bool GetDeviceFromUUID(const CascadeString & deviceUUID, Device & deviceToSet);
            // GetDeviceFromUUID() will fill deviceToSet with the device structure for the device identified
            // by deviceUUID, if it is cached returning true if so, false if it is not cached.
            // This is a synchronous function provided for convenience.  The preferred method of getting
            // devices is to call CatalogLocalDevices().  This function may
            // be used on mounted devices - once a device is mounted its device is cached.

        virtual bool GetCachedDeviceDescription(const CascadeString & deviceUUID, DeviceDescription & deviceDescriptionToSet);
            // GetCachedDeviceDescription() will fill deviceDescriptionToSet with the deviceDescription for the device identified
            // by deviceUUID, if it is cached returning true if so, false if it is not cached.
            // This is a synchronous function provided for convenience.  The preferred method of getting
            // a device description is to call RequestDeviceDescription().  This function may
            // be used on mounted devices - once a device is mounted its device description is cached.

            // only works if the deviceUUID is for a device that is a media server
        virtual bool UnmountDevice(const CascadeString & deviceUUID);
        virtual bool IsDeviceMounted(const CascadeString & deviceUUID);

        virtual bool AddDeviceToPersistentMountList(const CascadeString & deviceUUID);
        virtual bool RemoveDeviceFromPersistentMountList(const CascadeString & deviceUUID);
        virtual bool RemoveAllDevicesFromPersistentMountList();
        virtual bool IsDeviceInPersistentMountList(const CascadeString & deviceUUID);

        typedef bool (MountListEnumCallback)(const CascadeString & deviceUUID, void * pClientData);
        virtual bool EnumerateMountedDevices(MountListEnumCallback * pCallback, void * pClientData);
        virtual bool EnumeratePersistentMountList(MountListEnumCallback * pCallback, void * pClientData);
        virtual bool IsDeviceOnline(const CascadeString & deviceUUID);
 
        virtual bool IsWindowsMediaConnect(const DeviceDescription & deviceDescription);
        
        static const char * MediaServerDeviceType();
            // returns "schemas-upnp-org:device:MediaServer:1"

        TransactionResult GetLastTransactionResult();
        static const char * TransactionResultToString(TransactionResult result);

private:
    virtual bool OnWormholeMessage(const CascadeMessage & message);
private:
    UPnP * m_pUPnP;
#else 
public:
    virtual bool InitiateUPnPSearch(const CascadeString & searchTerm);
        // InitiateUPnPSearch() will send out a UPnP multicast search
        // request to the network using the searchTerm given.  Search
        // results will be routed asynchronously to the virtual function
        // OnSearchResult().  Clients will only see active devices in
        // their OnSearchResult() functions; to catch devices going 
        // off-line, monitor the OnStatusChange() function, below.
        // Search results will continue to be routed to the CascadeUPnP
        // object for its entire lifetime.  Returns false if search
        // could not be initiated, usually due to improperly formed
        // search term.
        //
        // The searchTerm may have one of the following forms:
        //   "ssdp:all"         - search for all UPnP devices
        //   "upnp:rootdevice"  - search for all root devices
        //   "uuid:<theUUID>"   - search for a specific device (by UUID)
        //   "urn:<theURN>"     - search for devices of a certain type
        //                        (e.g., "urn:schemas-upnp-org:device:<devType>")
        //
        // NOTE: only devices are currently searchable via the "urn:" specifier
        // currently, although the UPnP spec allows searching for services as well.
        //
        // NOTE: Each CascadeUPnP instance can only initiate one search at
        // a time.
        //
        // TODO: maybe return a search id and allow cancellation.
        
    virtual bool GetDeviceDescription(const Device & device,
            DeviceDescription & deviceDescriptionToSet, 
            u32 nTimeoutMS = 5000);
        // GetDeviceDescription() will query the device for its device
        // description XML document, parse it, and provide you with the
        // results in the DeviceDescription structure.  Returns false on
        // failure or timeout.
        //
        // Use GetDeviceDescriptionAsync() if you would prefer an asynchronous
        // version of this function.
    
    virtual bool GetDeviceDescriptionAsync(const Device & device);
        // GetDeviceDescriptionAsync() queries a device for its device
        // description XML document, parses it, and will notify you
        // when complete by calling your OnDeviceDescriptionComplete()
        // virtual function.  You may queue up as many description
        // requests as you want, but they might not execute at the
        // same time depending on network resource availibility.
        // There is a 30 second timeout for all requests once they
        // hit the network, so you are guaranteed a callback eventually.
        // Returns false if failure queing request.
        //
        // Use GetDeviceDescription() if you would prefer a synchronous
        // (blocking) version of this function.
            
public:
    virtual void OnSearchResult(const Device & device);
        // Virtual client function for processing search results after
        // initiating a search with InitiateUPnPSearch().
    
    virtual void OnStatusChange(const Device & device);
        // Virtual client function for processing of UPnP status changes
        // multicasted on the local network.  There is no filtering of
        // device types; the client should ignore updates to devices it
        // is not interested in.
        //
        // TODO: should we allow clients to register for updates only
        // about some class of devices?
        
    virtual void OnDeviceDescriptionComplete(bool bSuccess, const Device & device, const DeviceDescription & deviceDescription);
        // Virtual client function for processing results of
        // GetDeviceDescriptionAsync().
#endif
};

#endif // _ROKU_INCLUDE_CASCADE_NET_CASCADEUPNP_H

//  LOG
//  22-Sep-04   dsletten        created
//  08-Oct-04   dsletten    increased default timeout for GetDeviceDescription()
//  30-Nov-04   dsletten    added GetDeviceDescriptionAsync() and callback
//  10-Dec-04   dwoodward   added deschutes implementation
//  19-Jan-04   dwoodward   added GetCachedDeviceDescription(), GetDeviceFromUUID()

---