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

   1 /*****************************************************************
   2 |
   3 |   Platinum - Device Host
   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 Device
  37  */
  38
  39 #ifndef _PLT_DEVICE_HOST_H_
  40 #define _PLT_DEVICE_HOST_H_
  41
  42 /*----------------------------------------------------------------------
  43 |   includes
  44 +---------------------------------------------------------------------*/
  45 #include "Neptune.h"
  46 #include "PltDeviceData.h"
  47 #include "PltSsdp.h"
  48 #include "PltTaskManager.h"
  49 #include "PltAction.h"
  50 #include "PltHttp.h"
  51 #include "PltHttpServer.h"
  52
  53 /*----------------------------------------------------------------------
  54 |   forward declarations
  55 +---------------------------------------------------------------------*/
  56 class PLT_SsdpDeviceAnnounceTask;
  57 class PLT_SsdpListenTask;
  58
  59 /*----------------------------------------------------------------------
  60 |   PLT_DeviceHost class
  61 +---------------------------------------------------------------------*/
  62 /**
  63  UPnP Device Host.
  64  The PLT_DeviceHost class is a base class for implementing a UPnP Device. It handles
  65  network announcements and responses to searches from ControlPoints. ControlPoint
  66  action invocations are also received and delegated to derived classes. A
  67  PLT_DeviceHost also takes care of eventing when services state variables change.
  68  */
  69 class PLT_DeviceHost : public PLT_DeviceData,
  70                        public PLT_SsdpPacketListener,
  71                        public NPT_HttpRequestHandler
  72 {
  73 public:
  74     /**
  75      Creates a new instance of UPnP Device Host.
  76      @param description_path Relative path for description url
  77      @param uuid UPnP device unique id
  78      @param device_type UPnP device type
  79      @param friendly_name Name advertised for UPnP device
  80      @param show_ip Flag to indicate if device IP should be appended to friendly name
  81      @param port local port for the device host internal HTTP server, 0 for randomly
  82      selected.
  83      @param port_rebind Flag to indicate if device host should automatically try to look
  84      for another port if failing to choose the one passed.
  85      */
  86     PLT_DeviceHost(const char*  description_path = "/",
  87                    const char*  uuid = "",
  88                    const char*  device_type = "",
  89                    const char*  friendly_name = "",
  90                    bool         show_ip = false,
  91                    NPT_UInt16   port = 0,
  92                    bool         port_rebind = false);
  93     ~PLT_DeviceHost() override;
  94
  95     virtual void SetExtraBroadcast(bool broadcast) { m_ExtraBroascast = broadcast; }
  96
  97     /**
  98      When a UPnP device comes up, the specifications require that a SSDP bye-bye
  99      sequence is sent to force the removal of the device in case it wasn't sent
 100      properly during the last shutdown.
 101      @param bye_bye_first Boolean to indicate that SSDP bye-bye sequence should
 102      be sent first or not.
 103      */
 104     virtual void SetByeByeFirst(bool bye_bye_first) { m_ByeByeFirst = bye_bye_first; }
 105
 106     /**
 107      Returns the port used by the internal HTTP server for all incoming requests.
 108      @return port
 109      */
 110     virtual NPT_UInt16 GetPort() { return m_Port; };
 111
 112     /**
 113      Sets the lease time.
 114      @param lease_time Lease Time
 115      */
 116     NPT_Result SetLeaseTime(NPT_TimeInterval lease_time) { return PLT_DeviceData::SetLeaseTime(lease_time); }
 117
 118 protected:
 119     /**
 120      NPT_HttpRequestHandler method for setting up the response of an incoming
 121      HTTP request.
 122      @param request the request received
 123      @param context the context of the request
 124      @param response the response to set up
 125      */
 126     NPT_Result SetupResponse(NPT_HttpRequest&              request,
 127                                      const NPT_HttpRequestContext& context,
 128                                      NPT_HttpResponse&             response) override;
 129
 130     /**
 131      Static method similar to Announce.
 132      @param device the device to announce
 133      @param request the SSDP pre formatted request
 134      @param socket the network socket to use to send the request
 135      @param type PLT_SsdpAnnounceType enum if the announce is a SSDP bye-bye, update or alive.
 136      */
 137     static NPT_Result Announce(PLT_DeviceData*      device,
 138                                NPT_HttpRequest&     request,
 139                                NPT_UdpSocket&       socket,
 140                                PLT_SsdpAnnounceType type);
 141     /**
 142      Called during SSDP announce. The HTTP request is already configured with
 143      the right method and host.
 144      @param request the SSDP pre formatted request
 145      @param socket the network socket to use to send the request
 146      @param type PLT_SsdpAnnounceType enum if the announce is a SSDP bye-bye, update or alive.
 147      */
 148     NPT_Result Announce(NPT_HttpRequest&     request,
 149                         NPT_UdpSocket&       socket,
 150                         PLT_SsdpAnnounceType type) {
 151         return Announce(this, request, socket, type);
 152     }
 153
 154     /**
 155      PLT_SsdpPacketListener method called when a M-SEARCH SSDP packet is received.
 156      @param request SSDP packet
 157      @param context the context of the request
 158      */
 159     NPT_Result OnSsdpPacket(const NPT_HttpRequest&        request,
 160                                     const NPT_HttpRequestContext& context) override;
 161
 162     /**
 163      Static method similar to SendSsdpSearchResponse.
 164      @param device the device to announce
 165      @param response the SSDP pre formatted response
 166      @param socket the network socket to use to send the request
 167      @param st the original request search target
 168      @param addr the remote address to send the response back to in case the socket
 169      is not already connected.
 170      */
 171     static NPT_Result SendSsdpSearchResponse(PLT_DeviceData*          device,
 172                                              NPT_HttpResponse&        response,
 173                                              NPT_UdpSocket&           socket,
 174                                              const char*              st,
 175                                              const NPT_SocketAddress* addr = NULL);
 176     /**
 177      Called by PLT_SsdpDeviceSearchResponseTask when responding to a M-SEARCH
 178      SSDP request.
 179      @param response the SSDP pre formatted response
 180      @param socket the network socket to use to send the request
 181      @param st the original request search target
 182      @param addr the remote address to send the response back to in case the socket
 183      is not already connected.
 184      */
 185     virtual NPT_Result SendSsdpSearchResponse(NPT_HttpResponse&        response,
 186                                               NPT_UdpSocket&           socket,
 187                                               const char*              st,
 188                                               const NPT_SocketAddress* addr = NULL) {
 189         return SendSsdpSearchResponse(this, response, socket, st, addr);
 190     }
 191
 192 public:
 193     /**
 194      Add UPnP icon information to serve from file system.
 195      @param icon the icon information including url path
 196      @param fileroot the file system root path
 197      @param urlroot the url root path of the icon url to match to fileroot
 198      Note: As an exemple, if the icon url path is "/images/icon1.jpg", the fileroot
 199      is "/Users/joe/www" and the urlroot is "/", when a request is made for
 200      "/images/icon1.jpg", the file is expected to be found at
 201      "/Users/joe/www/images/icon1.jpg". If the urlroot were "/images", the file
 202      would be expected to be found at "/Users/joe/www/icon1.jpg".
 203      */
 204     virtual NPT_Result AddIcon(const PLT_DeviceIcon& icon,
 205                                const char*           fileroot,
 206                                const char*           urlroot = "/");
 207
 208     /**
 209      Add UPnP icon information to serve using static image.
 210      @param icon the icon information including url path
 211      @param data the image data
 212      @param size the image data size
 213      @param copy boolean to indicate the data should be copied internally
 214      */
 215     virtual NPT_Result AddIcon(const PLT_DeviceIcon& icon,
 216                                const void*           data,
 217                                NPT_Size              size,
 218                                bool                  copy = true);
 219
 220 protected:
 221     /**
 222      Required method for setting up UPnP services of device host
 223      (and any embedded). Called when device starts.
 224      */
 225     virtual NPT_Result SetupServices() = 0;
 226
 227     /**
 228      Default implementation for registering device icon resources. Override to
 229      use different ones. Called when device starts.
 230      */
 231     virtual NPT_Result SetupIcons();
 232
 233     /**
 234      Default implementation for setting up device host. This calls SetupServices
 235      and SetupIcons when device starts.
 236      */
 237     virtual NPT_Result SetupDevice();
 238
 239     /**
 240      Called by PLT_TaskManager when the device is started.
 241      @param task the SSDP listening task to attach to for receiving
 242      SSDP M-SEARCH messages.
 243      */
 244     virtual NPT_Result Start(PLT_SsdpListenTask* task);
 245
 246     /**
 247      Called by PLT_TaskManager when the device is stoped.
 248      @param task the SSDP listening task to detach from to stop receiving
 249      SSDP M-SEARCH messages.
 250      */
 251     virtual NPT_Result Stop(PLT_SsdpListenTask* task);
 252
 253     /**
 254      This mehod is called when an action performed by a control point has been
 255      received and needs to be answered.
 256      @param action the action information to answer
 257      @param context the context information including the HTTP request and
 258      local and remote socket information (IP & port).
 259      */
 260     virtual NPT_Result OnAction(PLT_ActionReference&          action,
 261                                 const PLT_HttpRequestContext& context);
 262
 263     /**
 264      This method is called when a control point is requesting the device
 265      description.
 266      @param request the HTTP request
 267      @param context the context information including local and remote socket information.
 268      @param response the response to setup.
 269      */
 270     virtual NPT_Result ProcessGetDescription(NPT_HttpRequest&              request,
 271                                              const NPT_HttpRequestContext& context,
 272                                              NPT_HttpResponse&             response);
 273
 274     /**
 275      This method is called when a control point is requesting a service SCPD.
 276      @param service the service
 277      @param request the HTTP request
 278      @param context the context information including local and remote socket information.
 279      @param response the response to setup.
 280      */
 281     virtual NPT_Result ProcessGetSCPD(PLT_Service*                  service,
 282                                       NPT_HttpRequest&              request,
 283                                       const NPT_HttpRequestContext& context,
 284                                       NPT_HttpResponse&             response);
 285
 286     /**
 287      This method is called when a "GET" request for a resource other than the device
 288      description, SCPD, or icons has been received.
 289      @param request the HTTP request
 290      @param context the context information including local and remote socket information.
 291      @param response the response to setup.
 292      */
 293     virtual NPT_Result ProcessHttpGetRequest(NPT_HttpRequest&              request,
 294                                              const NPT_HttpRequestContext& context,
 295                                              NPT_HttpResponse&             response);
 296
 297     /**
 298      This method is called when a "POST" request has been received. This is usually
 299      an UPnP service action invocation. This will deserialize the request and call
 300      the OnAction method.
 301      @param request the HTTP request
 302      @param context the context information including local and remote socket information.
 303      @param response the response to setup.
 304      */
 305     virtual NPT_Result ProcessHttpPostRequest(NPT_HttpRequest&              request,
 306                                               const NPT_HttpRequestContext& context,
 307                                               NPT_HttpResponse&             response);
 308
 309     /**
 310      This method is called when a request from a subscriber has been received. This is
 311      for any new subscritions, existing subscrition renewal or cancellation.
 312      @param request the HTTP request
 313      @param context the context information including local and remote socket information.
 314      @param response the response to setup.
 315      */
 316     virtual NPT_Result ProcessHttpSubscriberRequest(NPT_HttpRequest&              request,
 317                                                     const NPT_HttpRequestContext& context,
 318                                                     NPT_HttpResponse&             response);
 319
 320 protected:
 321     friend class PLT_UPnP;
 322     friend class PLT_UPnP_DeviceStartIterator;
 323     friend class PLT_UPnP_DeviceStopIterator;
 324     friend class PLT_Service;
 325     friend class NPT_Reference<PLT_DeviceHost>;
 326     friend class PLT_SsdpDeviceSearchResponseInterfaceIterator;
 327     friend class PLT_SsdpDeviceSearchResponseTask;
 328     friend class PLT_SsdpAnnounceInterfaceIterator;
 329
 330     PLT_TaskManagerReference m_TaskManager;
 331     PLT_HttpServerReference  m_HttpServer;
 332     bool                     m_ExtraBroascast;
 333     NPT_UInt16               m_Port;
 334     bool                     m_PortRebind;
 335     bool                     m_ByeByeFirst;
 336     bool                     m_Started;
 337 };
 338
 339 typedef NPT_Reference<PLT_DeviceHost> PLT_DeviceHostReference;
 340
 341 #endif /* _PLT_DEVICE_HOST_H_ */