lib/libUPnP/Platinum/Source/Core/PltCtrlPoint.h

   1 /*****************************************************************
   2 |
   3 |   Platinum - Control Point
   4 |
   5 | Copyright (c) 2004-2010, Plutinosoft, LLC.
   6 | All rights reserved.
   7 | http://www.plutinosoft.com
   8 |
   9 | This program is free software; you can redistribute it and/or
  10 | modify it under the terms of the GNU General Public License
  11 | as published by the Free Software Foundation; either version 2
  12 | of the License, or (at your option) any later version.
  13 |
  14 | OEMs, ISVs, VARs and other distributors that combine and
  15 | distribute commercially licensed software with Platinum software
  16 | and do not wish to distribute the source code for the commercially
  17 | licensed software under version 2, or (at your option) any later
  18 | version, of the GNU General Public License (the "GPL") must enter
  19 | into a commercial license agreement with Plutinosoft, LLC.
  20 | licensing@plutinosoft.com
  21 |
  22 | This program is distributed in the hope that it will be useful,
  23 | but WITHOUT ANY WARRANTY; without even the implied warranty of
  24 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  25 | GNU General Public License for more details.
  26 |
  27 | You should have received a copy of the GNU General Public License
  28 | along with this program; see the file LICENSE.txt. If not, write to
  29 | the Free Software Foundation, Inc.,
  30 | 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  31 | http://www.gnu.org/licenses/gpl-2.0.html
  32 |
  33 ****************************************************************/
  34
  35 /** @file
  36  UPnP ControlPoint
  37  */
  38
  39 #ifndef _PLT_CONTROL_POINT_H_
  40 #define _PLT_CONTROL_POINT_H_
  41
  42 /*----------------------------------------------------------------------
  43 |   includes
  44 +---------------------------------------------------------------------*/
  45 #include "Neptune.h"
  46 #include "PltService.h"
  47 #include "PltSsdp.h"
  48 #include "PltDeviceData.h"
  49 #include "PltHttpServer.h"
  50
  51 /*----------------------------------------------------------------------
  52 |   forward declarations
  53 +---------------------------------------------------------------------*/
  54 class PLT_CtrlPointHouseKeepingTask;
  55 class PLT_SsdpSearchTask;
  56 class PLT_SsdpListenTask;
  57 class PLT_CtrlPointGetSCPDsTask;
  58 class PLT_CtrlPointGetSCPDRequest;
  59
  60 /*----------------------------------------------------------------------
  61 |   PLT_CtrlPointListener class
  62 +---------------------------------------------------------------------*/
  63 /**
  64  The PLT_CtrlPointListener class is an interface used to receive notifications when
  65  devices are found or removed from the network, actions responses and events
  66  are being received.
  67  */
  68 class PLT_CtrlPointListener
  69 {
  70 public:
  71     virtual ~PLT_CtrlPointListener() {}
  72
  73     virtual NPT_Result OnDeviceAdded(PLT_DeviceDataReference& device) = 0;
  74     virtual NPT_Result OnDeviceRemoved(PLT_DeviceDataReference& device) = 0;
  75     virtual NPT_Result OnActionResponse(NPT_Result res, PLT_ActionReference& action, void* userdata) = 0;
  76     virtual NPT_Result OnEventNotify(PLT_Service* service, NPT_List<PLT_StateVariable*>* vars) = 0;
  77 };
  78
  79 typedef NPT_List<PLT_CtrlPointListener*> PLT_CtrlPointListenerList;
  80
  81 /*----------------------------------------------------------------------
  82 |   PLT_CtrlPoint class
  83 +---------------------------------------------------------------------*/
  84 /**
  85  The PLT_CtrlPoint class implements the base functionality of a UPnP ControlPoint.
  86  It searches and inpects devices, invoke actions on services and subscribes to
  87  events.
  88  */
  89 class PLT_CtrlPoint : public PLT_SsdpPacketListener,
  90                       public PLT_SsdpSearchResponseListener,
  91                       public NPT_HttpRequestHandler
  92 {
  93 public:
  94     PLT_CtrlPoint(const char* search_criteria = "upnp:rootdevice"); // pass NULL to prevent repeated automatic search
  95     ~PLT_CtrlPoint() override;
  96
  97     /**
  98      Returns the port used by the internal HTTP server for all incoming event notifications.
  99      @return port
 100      */
 101     virtual NPT_Result GetPort(NPT_UInt16& port);
 102
 103     // delegation
 104     virtual NPT_Result AddListener(PLT_CtrlPointListener* listener);
 105     virtual NPT_Result RemoveListener(PLT_CtrlPointListener* listener);
 106
 107     // discovery
 108     virtual void IgnoreUUID(const char* uuid);
 109     virtual NPT_Result Search(const NPT_HttpUrl& url = NPT_HttpUrl("239.255.255.250", 1900, "*"),
 110                               const char*        target = "upnp:rootdevice",
 111                               NPT_Cardinal       mx = 5,
 112                               NPT_TimeInterval   frequency = NPT_TimeInterval(50.), // pass NPT_TimeInterval(0.) for one time only
 113                               NPT_TimeInterval   initial_delay = NPT_TimeInterval(0.));
 114     virtual NPT_Result Discover(const NPT_HttpUrl& url = NPT_HttpUrl("239.255.255.250", 1900, "*"),
 115                                 const char*        target = "ssdp:all",
 116                                 NPT_Cardinal       mx = 5,
 117                                 NPT_TimeInterval   frequency = NPT_TimeInterval(50.), // pass NPT_TimeInterval(0.) for one time only
 118                                 NPT_TimeInterval   initial_delay = NPT_TimeInterval(0.));
 119     virtual NPT_Result InspectDevice(const NPT_HttpUrl& location,
 120                                      const char*        uuid,
 121                                      NPT_TimeInterval   leasetime = *PLT_Constants::GetInstance().GetDefaultDeviceLease());
 122
 123     // actions
 124     virtual NPT_Result FindActionDesc(PLT_DeviceDataReference& device,
 125                                   const char*              service_type,
 126                                   const char*              action_name,
 127                                   PLT_ActionDesc*&         action_desc);
 128     virtual NPT_Result CreateAction(PLT_DeviceDataReference& device,
 129                                 const char*              service_type,
 130                                 const char*              action_name,
 131                                 PLT_ActionReference&     action);
 132     virtual NPT_Result InvokeAction(PLT_ActionReference& action,
 133                                     void*                userdata = NULL);
 134
 135     // events
 136     virtual NPT_Result Subscribe(PLT_Service* service,
 137                                  bool         cancel = false,
 138                                  void*        userdata = NULL);
 139
 140     // NPT_HttpRequestHandler methods
 141     NPT_Result SetupResponse(NPT_HttpRequest&              request,
 142                                      const NPT_HttpRequestContext& context,
 143                                      NPT_HttpResponse&             response) override;
 144
 145     // PLT_SsdpSearchResponseListener methods
 146     NPT_Result ProcessSsdpSearchResponse(NPT_Result                    res,
 147                                                  const NPT_HttpRequestContext& context,
 148                                                  NPT_HttpResponse*             response) override;
 149     // PLT_SsdpPacketListener method
 150     NPT_Result OnSsdpPacket(const NPT_HttpRequest&        request,
 151                                     const NPT_HttpRequestContext& context) override;
 152
 153 protected:
 154
 155     // State Variable Handling
 156     virtual NPT_Result DecomposeLastChangeVar(NPT_List<PLT_StateVariable*>& vars);
 157
 158     // methods
 159     virtual NPT_Result Start(PLT_SsdpListenTask* task);
 160     virtual NPT_Result Stop(PLT_SsdpListenTask* task);
 161
 162     // SSDP & HTTP Notifications handling
 163     virtual NPT_Result ProcessSsdpNotify(const NPT_HttpRequest&        request,
 164                                          const NPT_HttpRequestContext& context);
 165     virtual NPT_Result ProcessSsdpMessage(const NPT_HttpMessage&        message,
 166                                           const NPT_HttpRequestContext& context,
 167                                           NPT_String&                   uuid);
 168     virtual NPT_Result ProcessGetDescriptionResponse(NPT_Result                    res,
 169                                                      const NPT_HttpRequest&        request,
 170                                                      const NPT_HttpRequestContext& context,
 171                                                      NPT_HttpResponse*             response,
 172                                                      NPT_TimeInterval              leasetime,
 173                                                      NPT_String                    uuid);
 174     virtual NPT_Result ProcessGetSCPDResponse(NPT_Result                    res,
 175                                               const NPT_HttpRequest&        request,
 176                                               const NPT_HttpRequestContext& context,
 177                                               NPT_HttpResponse*             response,
 178                                               PLT_DeviceDataReference&      device);
 179     virtual NPT_Result ProcessActionResponse(NPT_Result                    res,
 180                                              const NPT_HttpRequest&        request,
 181                                              const NPT_HttpRequestContext& context,
 182                                              NPT_HttpResponse*             response,
 183                                              PLT_ActionReference&          action,
 184                                              void*                         userdata);
 185     virtual NPT_Result ProcessSubscribeResponse(NPT_Result                    res,
 186                                                 const NPT_HttpRequest&        request,
 187                                                 const NPT_HttpRequestContext& context,
 188                                                 NPT_HttpResponse*             response,
 189                                                 PLT_Service*                  service,
 190                                                 void*                         userdata);
 191     virtual NPT_Result ProcessHttpNotify(const NPT_HttpRequest&        request,
 192                                          const NPT_HttpRequestContext& context,
 193                                          NPT_HttpResponse&             response);
 194
 195     // Device management
 196     virtual NPT_Result AddDevice(PLT_DeviceDataReference& data);
 197     virtual NPT_Result RemoveDevice(PLT_DeviceDataReference& data);
 198
 199 private:
 200     // methods
 201     PLT_ThreadTask* RenewSubscriber(PLT_EventSubscriberReference subscriber);
 202
 203     NPT_Result AddPendingEventNotification(PLT_EventNotification *notification);
 204     NPT_Result ProcessPendingEventNotifications();
 205     NPT_Result ProcessEventNotification(PLT_EventSubscriberReference subscriber,
 206                                         PLT_EventNotification*       notification,
 207                                         NPT_List<PLT_StateVariable*> &vars);
 208
 209     NPT_Result DoHouseKeeping();
 210     NPT_Result FetchDeviceSCPDs(PLT_CtrlPointGetSCPDsTask* task,
 211                                 PLT_DeviceDataReference&   device,
 212                                 NPT_Cardinal               level);
 213
 214     // Device management
 215     NPT_Result FindDevice(const char* uuid, PLT_DeviceDataReference& device, bool return_root = false);
 216     NPT_Result NotifyDeviceReady(PLT_DeviceDataReference& data);
 217     NPT_Result NotifyDeviceRemoved(PLT_DeviceDataReference& data);
 218     NPT_Result CleanupDevice(PLT_DeviceDataReference& data);
 219
 220     NPT_Result ParseFault(PLT_ActionReference& action, NPT_XmlElementNode* fault);
 221     PLT_SsdpSearchTask* CreateSearchTask(const NPT_HttpUrl&   url,
 222                                          const char*          target,
 223                                          NPT_Cardinal         mx,
 224                                          NPT_TimeInterval     frequency,
 225                                          const NPT_IpAddress& address);
 226
 227 private:
 228     friend class NPT_Reference<PLT_CtrlPoint>;
 229     friend class PLT_UPnP;
 230     friend class PLT_UPnP_CtrlPointStartIterator;
 231     friend class PLT_UPnP_CtrlPointStopIterator;
 232     friend class PLT_EventSubscriberRemoverIterator;
 233     friend class PLT_CtrlPointGetDescriptionTask;
 234     friend class PLT_CtrlPointGetSCPDsTask;
 235     friend class PLT_CtrlPointInvokeActionTask;
 236     friend class PLT_CtrlPointHouseKeepingTask;
 237     friend class PLT_CtrlPointSubscribeEventTask;
 238
 239     NPT_List<NPT_String>                         m_UUIDsToIgnore;
 240     PLT_CtrlPointListenerList                    m_ListenerList;
 241     PLT_HttpServerReference                      m_EventHttpServer;
 242     PLT_TaskManagerReference                     m_TaskManager;
 243     NPT_Mutex                                    m_Lock;
 244     NPT_List<PLT_DeviceDataReference>            m_RootDevices;
 245     NPT_List<PLT_EventSubscriberReference>       m_Subscribers;
 246     NPT_String                                   m_SearchCriteria;
 247     bool                                         m_Started;
 248     NPT_List<PLT_EventNotification *>            m_PendingNotifications;
 249     NPT_List<NPT_String>                         m_PendingInspections;
 250 };
 251
 252 typedef NPT_Reference<PLT_CtrlPoint> PLT_CtrlPointReference;
 253
 254 #endif /* _PLT_CONTROL_POINT_H_ */