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

   1 /*****************************************************************
   2 |
   3 |   Platinum - Service
   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 Service
  37  */
  38
  39 #ifndef _PLT_SERVICE_H_
  40 #define _PLT_SERVICE_H_
  41
  42 /*----------------------------------------------------------------------
  43 |    includes
  44 +---------------------------------------------------------------------*/
  45 #include "Neptune.h"
  46 #include "PltEvent.h"
  47 #include "PltArgument.h"
  48 #include "PltStateVariable.h"
  49 #include "PltAction.h"
  50
  51 /*----------------------------------------------------------------------
  52 |    forward declarations
  53 +---------------------------------------------------------------------*/
  54 class PLT_DeviceData;
  55
  56 /*----------------------------------------------------------------------
  57 |    PLT_Service class
  58 +---------------------------------------------------------------------*/
  59 /**
  60  UPnP Service.
  61  The PLT_Service class holds information about a UPnP service of a given device.
  62  It maintains a list of actions and state variables. A PLT_DeviceData instance can own
  63  one or more PLT_Service instances. When a PLT_Service is advertised as part of a
  64  a UPnP Device (PLT_DeviceHost), it also maintains a list of subscribers to nofify when
  65  state variables change.
  66  */
  67 class PLT_Service
  68 {
  69 public:
  70     // methods
  71     /**
  72      Create an instance of a UPnP Service either hosted or discovered.
  73      @param device Pointer to the PLT_DeviceData the service is associated to
  74      @param type String representing the UPnP service type
  75      @param id String representing the UPnP service id
  76      @param name A String to create unique service SCPD, control and eventing urls
  77      @param last_change_namespace A String for the LastChange state variable namespace if any
  78      */
  79     PLT_Service(PLT_DeviceData* device,
  80                 const char*     type,
  81                 const char*     id,
  82                 const char*     name,
  83                 const char*     last_change_namespace = NULL);
  84     virtual ~PLT_Service();
  85
  86     // methods
  87     /**
  88      When service is hosted by a PLT_DeviceHost, this setups the SCPD, control and event urls.
  89      @param service_name the service name used to format unique urls
  90      */
  91     NPT_Result InitURLs(const char* service_name);
  92
  93     /**
  94      Verify the service has been properly initialized or is a valid discovered service.
  95      @return true if valid.
  96      */
  97     bool IsValid() {  return (m_ActionDescs.GetItemCount() > 0); }
  98
  99     /**
 100      When a PLT_DeviceHost needs to change more than one state variables at a time
 101      but would rather send only one event with all state variable changes, this can be
 102      used to pause and resume the automatic eventing.
 103      @param pause Flag to indicate if eventing should be paused or resumed
 104      */
 105     NPT_Result PauseEventing(bool pause = true);
 106
 107     // class methods
 108     static bool IsTrue(const NPT_String& value) {
 109         if (value.Compare("1", true)    &&
 110             value.Compare("true", true) &&
 111             value.Compare("yes", true)) {
 112             return false;
 113         }
 114         return true;
 115     }
 116
 117     // accessor methods
 118     /**
 119      Set the SCPD url for control points to be able to fetch the SCPD xml document.
 120      @param url relative path of SCPD url
 121      */
 122     NPT_Result SetSCPDURL(const char* url)     { m_SCPDURL = url; return NPT_SUCCESS; }
 123
 124     /*
 125      Set the Service Control url for control points to be able to invoke actions.
 126      @param url relative path of control url
 127      */
 128     NPT_Result SetControlURL(const char* url)  { m_ControlURL = url; return NPT_SUCCESS; };
 129
 130     /**
 131      Set the Service Event subscription url for control points to be able to subscribe
 132      to events.
 133      @param url relative path of even url
 134      */
 135     NPT_Result SetEventSubURL(const char* url) { m_EventSubURL = url; return NPT_SUCCESS; };
 136
 137     /**
 138      Return the SCPD url associated with this service.
 139      @param absolute flag to indicate if absolute url including ip and port should
 140      be returned
 141      @return SCPD url
 142      */
 143     NPT_String GetSCPDURL(bool absolute = false);
 144
 145     /**
 146      Return the Control url associated with this service.
 147      @param absolute flag to indicate if absolute url including ip and port should
 148      be returned
 149      @return Control url
 150      */
 151     NPT_String GetControlURL(bool absolute = false);
 152
 153     /**
 154      Return the Event subscription url associated with this service.
 155      @param absolute flag to indicate if absolute url including ip and port should
 156      be returned
 157      @return Event url
 158      */
 159     NPT_String GetEventSubURL(bool absolute = false);
 160
 161     /**
 162      Return the service id.
 163      @return service id
 164      */
 165     const NPT_String& GetServiceID() const { return m_ServiceID;   }
 166
 167     /**
 168      Return the service type.
 169      @return service type
 170      */
 171     const NPT_String& GetServiceType() const { return m_ServiceType; }
 172
 173     /**
 174      Return the service friendly name.
 175      @return service name
 176      */
 177     const NPT_String& GetServiceName() const { return m_ServiceName; }
 178
 179     /**
 180      Return the PLT_DeviceData* the service is associated with.
 181      @return PLT_DeviceData pointer
 182      */
 183     PLT_DeviceData* GetDevice() { return m_Device;      }
 184
 185     /**
 186      When a control point discover a new service with a higher version number
 187      than it can work with, a lower version can be set to force backward
 188      compatibility.
 189      @param version Integer specifying the version to use
 190      */
 191     NPT_Result ForceVersion(NPT_Cardinal version);
 192
 193     /**
 194      Return the service SCPD xml document.
 195      @param xml String to receive document
 196      */
 197     NPT_Result GetSCPDXML(NPT_String& xml);
 198
 199     /**
 200      Set the service SCPD xml document.
 201      @param xml String SCPD xml document
 202      */
 203     NPT_Result SetSCPDXML(const char* xml);
 204
 205     /**
 206      Populate the UPnP Device description document with service information.
 207      @param parent XML Element where to insert the service XML Element
 208      @param service Pointer to service XML Element node newly created so it can be
 209      extended with additional non standard information.
 210      */
 211     NPT_Result GetDescription(NPT_XmlElementNode* parent, NPT_XmlElementNode** service = NULL);
 212
 213     /**
 214      Set a new value for a given state variable. The service keeps track of which
 215      state variables have changed and events are being triggered by a PLT_ServiceEventTask
 216      when necessary.
 217      @param name state variable name
 218      @param value new State Variable value.
 219      @param clearonsend whether the State Variable should clear immediatly in ::OnSendingCompleted
 220      */
 221     NPT_Result SetStateVariable(const char* name, const char* value, const bool clearonsend = false);
 222
 223     /**
 224      Certain state variables notifications must not be sent faster than a certain
 225      rate according to the UPnP specs. This sets the rate for a given state variable.
 226      @param name state variable name
 227      @param rate a time interval specifying the minimum interval allowed between
 228      notifications.
 229      */
 230     NPT_Result SetStateVariableRate(const char* name, NPT_TimeInterval rate);
 231
 232     /**
 233      Certain state variables require extra xml attributes when serialized.
 234      @param name state variable name
 235      @param key the attribute name
 236      @param value the attribute value
 237      */
 238         NPT_Result SetStateVariableExtraAttribute(const char* name, const char* key, const char* value);
 239
 240     /**
 241      Helper function to increment a state variable representing a number.
 242      @param name state variable name
 243      */
 244     NPT_Result IncStateVariable(const char* name);
 245
 246     /**
 247      Return the PLT_StateVariable pointer given a state variable name.
 248      @param name state variable name
 249      @return PLT_StateVariable pointer
 250      */
 251     PLT_StateVariable* FindStateVariable(const char* name);
 252
 253     /**
 254      Return the state variable value given a state variable name.
 255      @param name state variable name
 256      @param value state variable value output
 257      */
 258     NPT_Result GetStateVariableValue(const char* name, NPT_String& value);
 259
 260     /**
 261      Return whether a service is capable of sending events.
 262      @return true if sending events
 263      */
 264     bool IsSubscribable();
 265
 266     /**
 267      Return the list of state variables.
 268      @return list of state variable pointers.
 269      */
 270     const NPT_List<PLT_StateVariable*>& GetStateVariables() const { return m_StateVars; }
 271
 272     /**
 273      Return the PLT_ActionDesc given an action name
 274      @param name action name
 275      @return PLT_ActioDesc pointer
 276      */
 277     PLT_ActionDesc* FindActionDesc(const char* name);
 278
 279     /**
 280      Return an array of actions descriptions PLT_ActionDesc.
 281      @return array of PLT_ActionDesc pointers.
 282      */
 283     const NPT_Array<PLT_ActionDesc*>& GetActionDescs() const { return m_ActionDescs; }
 284
 285 private:
 286     /**
 287      A task to send events.
 288      The PLT_ServiceEventTask is started when receiving a first subscription. It
 289      monitors if some state variables have changed and sends events to all
 290      subscribers if so.
 291      */
 292     class PLT_ServiceEventTask : public PLT_ThreadTask {
 293     public:
 294         PLT_ServiceEventTask(PLT_Service* service) : m_Service(service) {}
 295
 296         void DoRun() override {
 297             while (!IsAborting(100)) m_Service->NotifyChanged();
 298         }
 299
 300     private:
 301         PLT_Service* m_Service;
 302     };
 303
 304     // methods
 305     void Cleanup();
 306
 307     /**
 308      Called by a PLT_StateVariable to keep track of what events need to be
 309      sent by the PLT_ServiceEventTask task.
 310      @param var PLT_StateVariable pointer
 311      */
 312     NPT_Result AddChanged(PLT_StateVariable* var);
 313
 314     /**
 315      Certain UPnP services combine state variable changes into one single
 316      state variable called "LastChange". This function updates the LastChange
 317      state variable by looking through the list passed for state variables that
 318      are not individually evented.
 319      */
 320     NPT_Result UpdateLastChange(NPT_List<PLT_StateVariable*>& vars);
 321
 322     /**
 323      Send state variable change events to all subscribers.
 324      */
 325     NPT_Result NotifyChanged();
 326
 327     // Events
 328     /**
 329      Called by PLT_DeviceHost when it receives a request for a new subscription.
 330      */
 331     NPT_Result ProcessNewSubscription(
 332         PLT_TaskManagerReference task_manager,
 333         const NPT_SocketAddress& addr,
 334         const NPT_String&        callback_urls,
 335         int                      timeout,
 336         NPT_HttpResponse&        response);
 337
 338     /**
 339      Called by PLT_DeviceHost when it receives a request renewing an existing
 340      subscription.
 341      */
 342     NPT_Result ProcessRenewSubscription(
 343         const NPT_SocketAddress& addr,
 344         const NPT_String&        sid,
 345         int                      timeout,
 346         NPT_HttpResponse&        response);
 347
 348     /**
 349      Called by PLT_DeviceHost when it receives a request to cancel an existing
 350      subscription.
 351      */
 352     NPT_Result ProcessCancelSubscription(
 353         const NPT_SocketAddress& addr,
 354         const NPT_String&        sid,
 355         NPT_HttpResponse&        response);
 356
 357
 358 protected:
 359     // friends that need to call private functions
 360     friend class PLT_StateVariable; // AddChanged
 361     friend class PLT_DeviceHost;    // ProcessXXSubscription
 362
 363     //members
 364     PLT_DeviceData*                         m_Device;
 365     NPT_String                              m_ServiceType;
 366     NPT_String                              m_ServiceID;
 367         NPT_String                              m_ServiceName;
 368     NPT_String                              m_SCPDURL;
 369     NPT_String                              m_ControlURL;
 370     NPT_String                              m_EventSubURL;
 371     PLT_ServiceEventTask*                   m_EventTask;
 372     NPT_Array<PLT_ActionDesc*>              m_ActionDescs;
 373     NPT_List<PLT_StateVariable*>            m_StateVars;
 374     NPT_Mutex                               m_Lock;
 375     NPT_List<PLT_StateVariable*>            m_StateVarsChanged;
 376     NPT_List<PLT_StateVariable*>            m_StateVarsToPublish;
 377     NPT_List<PLT_EventSubscriberReference>  m_Subscribers;
 378     bool                                    m_EventingPaused;
 379     NPT_String                              m_LastChangeNamespace;
 380 };
 381
 382 /*----------------------------------------------------------------------
 383 |    PLT_ServiceSCPDURLFinder
 384 +---------------------------------------------------------------------*/
 385 /**
 386  The PLT_ServiceSCPDURLFinder class returns an instance of a PLT_Service given a
 387  service SCPD url.
 388  */
 389 class PLT_ServiceSCPDURLFinder
 390 {
 391 public:
 392     // methods
 393     PLT_ServiceSCPDURLFinder(const char* url) : m_URL(url) {}
 394     virtual ~PLT_ServiceSCPDURLFinder() {}
 395     bool operator()(PLT_Service* const & service) const;
 396
 397 private:
 398     // members
 399     NPT_String m_URL;
 400 };
 401
 402 /*----------------------------------------------------------------------
 403 |    PLT_ServiceControlURLFinder
 404 +---------------------------------------------------------------------*/
 405 /**
 406  The PLT_ServiceControlURLFinder class returns an instance of a PLT_Service
 407  given a service control url.
 408  */
 409 class PLT_ServiceControlURLFinder
 410 {
 411 public:
 412     // methods
 413     PLT_ServiceControlURLFinder(const char* url) : m_URL(url) {}
 414     virtual ~PLT_ServiceControlURLFinder() {}
 415     bool operator()(PLT_Service* const & service) const;
 416
 417 private:
 418     // members
 419     NPT_String m_URL;
 420 };
 421
 422 /*----------------------------------------------------------------------
 423 |    PLT_ServiceEventSubURLFinder
 424 +---------------------------------------------------------------------*/
 425 /**
 426  The PLT_ServiceEventSubURLFinder class returns an instance of a PLT_Service
 427  given a service event subscription url.
 428  */
 429 class PLT_ServiceEventSubURLFinder
 430 {
 431 public:
 432     // methods
 433     PLT_ServiceEventSubURLFinder(const char* url) : m_URL(url) {}
 434     virtual ~PLT_ServiceEventSubURLFinder() {}
 435     bool operator()(PLT_Service* const & service) const;
 436
 437 private:
 438     // members
 439     NPT_String m_URL;
 440 };
 441
 442 /*----------------------------------------------------------------------
 443 |    PLT_ServiceIDFinder
 444 +---------------------------------------------------------------------*/
 445 /**
 446  The PLT_ServiceIDFinder class returns an instance of a PLT_Service given a
 447  service id.
 448  */
 449 class PLT_ServiceIDFinder
 450 {
 451 public:
 452     // methods
 453     PLT_ServiceIDFinder(const char* id) : m_Id(id) {}
 454     virtual ~PLT_ServiceIDFinder() {}
 455     bool operator()(PLT_Service* const & service) const;
 456
 457 private:
 458     // members
 459     NPT_String m_Id;
 460 };
 461
 462 /*----------------------------------------------------------------------
 463 |    PLT_ServiceTypeFinder
 464 +---------------------------------------------------------------------*/
 465 /**
 466  The PLT_ServiceTypeFinder class returns an instance of a PLT_Service given a
 467  service type.
 468  */
 469 class PLT_ServiceTypeFinder
 470 {
 471 public:
 472     // methods
 473     PLT_ServiceTypeFinder(const char* type) : m_Type(type) {}
 474     virtual ~PLT_ServiceTypeFinder() {}
 475     bool operator()(PLT_Service* const & service) const;
 476
 477 private:
 478     // members
 479     NPT_String m_Type;
 480 };
 481
 482 /*----------------------------------------------------------------------
 483 |    PLT_ServiceNameFinder
 484 +---------------------------------------------------------------------*/
 485 /**
 486  The PLT_ServiceNameFinder class returns an instance of a PLT_Service given a
 487  service name.
 488  */
 489 class PLT_ServiceNameFinder
 490 {
 491 public:
 492     // methods
 493     PLT_ServiceNameFinder(const char* name) : m_Name(name) {}
 494     virtual ~PLT_ServiceNameFinder() {}
 495     bool operator()(PLT_Service* const & service) const;
 496
 497 private:
 498     // members
 499     NPT_String m_Name;
 500 };
 501
 502 /*----------------------------------------------------------------------
 503 |    PLT_LastChangeXMLIterator
 504 +---------------------------------------------------------------------*/
 505 /**
 506  The PLT_LastChangeXMLIterator class is used to serialize the LastChange variable
 507  changes into xml given a list of state variables.
 508  */
 509 class PLT_LastChangeXMLIterator
 510 {
 511 public:
 512     // methods
 513     PLT_LastChangeXMLIterator(NPT_XmlElementNode* node) : m_Node(node) {}
 514     virtual ~PLT_LastChangeXMLIterator() {}
 515
 516     NPT_Result operator()(PLT_StateVariable* const & var) const;
 517
 518 private:
 519     NPT_XmlElementNode* m_Node;
 520 };
 521
 522 #endif /* _PLT_SERVICE_H_ */