Platinum UPnP SDK  1.0.5.13
PltService.h
Go to the documentation of this file.
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 
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 +---------------------------------------------------------------------*/
68 {
69 public:
70  // methods
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
91  NPT_Result InitURLs(const char* service_name);
92 
97  bool IsValid() { return (m_ActionDescs.GetItemCount() > 0); }
98 
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
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 
135  NPT_Result SetEventSubURL(const char* url) { m_EventSubURL = url; return NPT_SUCCESS; };
136 
143  NPT_String GetSCPDURL(bool absolute = false);
144 
151  NPT_String GetControlURL(bool absolute = false);
152 
159  NPT_String GetEventSubURL(bool absolute = false);
160 
165  const NPT_String& GetServiceID() const { return m_ServiceID; }
166 
171  const NPT_String& GetServiceType() const { return m_ServiceType; }
172 
177  const NPT_String& GetServiceName() const { return m_ServiceName; }
178 
183  PLT_DeviceData* GetDevice() { return m_Device; }
184 
191  NPT_Result ForceVersion(NPT_Cardinal version);
192 
197  NPT_Result GetSCPDXML(NPT_String& xml);
198 
203  NPT_Result SetSCPDXML(const char* xml);
204 
211  NPT_Result GetDescription(NPT_XmlElementNode* parent, NPT_XmlElementNode** service = NULL);
212 
220  NPT_Result SetStateVariable(const char* name, const char* value);
221 
229  NPT_Result SetStateVariableRate(const char* name, NPT_TimeInterval rate);
230 
237  NPT_Result SetStateVariableExtraAttribute(const char* name, const char* key, const char* value);
238 
243  NPT_Result IncStateVariable(const char* name);
244 
250  PLT_StateVariable* FindStateVariable(const char* name);
251 
257  NPT_Result GetStateVariableValue(const char* name, NPT_String& value);
258 
263  bool IsSubscribable();
264 
269  const NPT_List<PLT_StateVariable*>& GetStateVariables() const { return m_StateVars; }
270 
276  PLT_ActionDesc* FindActionDesc(const char* name);
277 
282  const NPT_Array<PLT_ActionDesc*>& GetActionDescs() const { return m_ActionDescs; }
283 
284 private:
291  class PLT_ServiceEventTask : public PLT_ThreadTask {
292  public:
293  PLT_ServiceEventTask(PLT_Service* service) : m_Service(service) {}
294 
295  void DoRun() {
296  while (!IsAborting(100)) m_Service->NotifyChanged();
297  }
298 
299  private:
300  PLT_Service* m_Service;
301  };
302 
303  // methods
304  void Cleanup();
305 
311  NPT_Result AddChanged(PLT_StateVariable* var);
312 
319  NPT_Result UpdateLastChange(NPT_List<PLT_StateVariable*>& vars);
320 
324  NPT_Result NotifyChanged();
325 
326  // Events
330  NPT_Result ProcessNewSubscription(
331  PLT_TaskManagerReference task_manager,
332  const NPT_SocketAddress& addr,
333  const NPT_String& callback_urls,
334  int timeout,
335  NPT_HttpResponse& response);
336 
341  NPT_Result ProcessRenewSubscription(
342  const NPT_SocketAddress& addr,
343  const NPT_String& sid,
344  int timeout,
345  NPT_HttpResponse& response);
346 
351  NPT_Result ProcessCancelSubscription(
352  const NPT_SocketAddress& addr,
353  const NPT_String& sid,
354  NPT_HttpResponse& response);
355 
356 
357 protected:
358  // friends that need to call private functions
359  friend class PLT_StateVariable; // AddChanged
360  friend class PLT_DeviceHost; // ProcessXXSubscription
361 
362  //members
363  PLT_DeviceData* m_Device;
364  NPT_String m_ServiceType;
365  NPT_String m_ServiceID;
366  NPT_String m_ServiceName;
367  NPT_String m_SCPDURL;
368  NPT_String m_ControlURL;
369  NPT_String m_EventSubURL;
370  PLT_ServiceEventTask* m_EventTask;
371  NPT_Array<PLT_ActionDesc*> m_ActionDescs;
372  NPT_List<PLT_StateVariable*> m_StateVars;
373  NPT_Mutex m_Lock;
374  NPT_List<PLT_StateVariable*> m_StateVarsChanged;
375  NPT_List<PLT_StateVariable*> m_StateVarsToPublish;
376  NPT_List<PLT_EventSubscriberReference> m_Subscribers;
377  bool m_EventingPaused;
378  NPT_String m_LastChangeNamespace;
379 };
380 
381 /*----------------------------------------------------------------------
382 | PLT_ServiceSCPDURLFinder
383 +---------------------------------------------------------------------*/
389 {
390 public:
391  // methods
392  PLT_ServiceSCPDURLFinder(const char* url) : m_URL(url) {}
393  virtual ~PLT_ServiceSCPDURLFinder() {}
394  bool operator()(PLT_Service* const & service) const;
395 
396 private:
397  // members
398  NPT_String m_URL;
399 };
400 
401 /*----------------------------------------------------------------------
402 | PLT_ServiceControlURLFinder
403 +---------------------------------------------------------------------*/
409 {
410 public:
411  // methods
412  PLT_ServiceControlURLFinder(const char* url) : m_URL(url) {}
413  virtual ~PLT_ServiceControlURLFinder() {}
414  bool operator()(PLT_Service* const & service) const;
415 
416 private:
417  // members
418  NPT_String m_URL;
419 };
420 
421 /*----------------------------------------------------------------------
422 | PLT_ServiceEventSubURLFinder
423 +---------------------------------------------------------------------*/
429 {
430 public:
431  // methods
432  PLT_ServiceEventSubURLFinder(const char* url) : m_URL(url) {}
433  virtual ~PLT_ServiceEventSubURLFinder() {}
434  bool operator()(PLT_Service* const & service) const;
435 
436 private:
437  // members
438  NPT_String m_URL;
439 };
440 
441 /*----------------------------------------------------------------------
442 | PLT_ServiceIDFinder
443 +---------------------------------------------------------------------*/
449 {
450 public:
451  // methods
452  PLT_ServiceIDFinder(const char* id) : m_Id(id) {}
453  virtual ~PLT_ServiceIDFinder() {}
454  bool operator()(PLT_Service* const & service) const;
455 
456 private:
457  // members
458  NPT_String m_Id;
459 };
460 
461 /*----------------------------------------------------------------------
462 | PLT_ServiceTypeFinder
463 +---------------------------------------------------------------------*/
469 {
470 public:
471  // methods
472  PLT_ServiceTypeFinder(const char* type) : m_Type(type) {}
473  virtual ~PLT_ServiceTypeFinder() {}
474  bool operator()(PLT_Service* const & service) const;
475 
476 private:
477  // members
478  NPT_String m_Type;
479 };
480 
481 /*----------------------------------------------------------------------
482 | PLT_ServiceNameFinder
483 +---------------------------------------------------------------------*/
489 {
490 public:
491  // methods
492  PLT_ServiceNameFinder(const char* name) : m_Name(name) {}
493  virtual ~PLT_ServiceNameFinder() {}
494  bool operator()(PLT_Service* const & service) const;
495 
496 private:
497  // members
498  NPT_String m_Name;
499 };
500 
501 /*----------------------------------------------------------------------
502 | PLT_LastChangeXMLIterator
503 +---------------------------------------------------------------------*/
509 {
510 public:
511  // methods
512  PLT_LastChangeXMLIterator(NPT_XmlElementNode* node) : m_Node(node) {}
513  virtual ~PLT_LastChangeXMLIterator() {}
514 
515  NPT_Result operator()(PLT_StateVariable* const & var) const;
516 
517 private:
518  NPT_XmlElementNode* m_Node;
519 };
520 
521 #endif /* _PLT_SERVICE_H_ */
NPT_Result GetSCPDXML(NPT_String &xml)
Return the service SCPD xml document.
PLT_ActionDesc * FindActionDesc(const char *name)
Return the PLT_ActionDesc given an action name.
NPT_Result InitURLs(const char *service_name)
When service is hosted by a PLT_DeviceHost, this setups the SCPD, control and event urls...
UPnP State Variable.
const NPT_String & GetServiceType() const
Return the service type.
Definition: PltService.h:171
The PLT_LastChangeXMLIterator class is used to serialize the LastChange variable changes into xml giv...
Definition: PltService.h:508
The PLT_ActionDesc class provides information about a UPnP Service given action.
Definition: PltAction.h:61
UPnP Service Action Argument.
The PLT_ServiceIDFinder class returns an instance of a PLT_Service given a service id...
Definition: PltService.h:448
NPT_Result ForceVersion(NPT_Cardinal version)
When a control point discover a new service with a higher version number than it can work with...
UPnP Service.
Definition: PltService.h:67
NPT_Result SetSCPDXML(const char *xml)
Set the service SCPD xml document.
NPT_Result GetStateVariableValue(const char *name, NPT_String &value)
Return the state variable value given a state variable name.
PLT_DeviceData * GetDevice()
Return the PLT_DeviceData* the service is associated with.
Definition: PltService.h:183
NPT_Result PauseEventing(bool pause=true)
When a PLT_DeviceHost needs to change more than one state variables at a time but would rather send o...
NPT_Result SetStateVariableExtraAttribute(const char *name, const char *key, const char *value)
Certain state variables require extra xml attributes when serialized.
The PLT_StateVariable class maintains the state of a UPnP Service state variable. ...
Definition: PltStateVariable.h:75
virtual bool IsAborting(NPT_Timeout timeout)
Return whether this task is in the process of stopping.
Definition: PltThreadTask.h:73
UPnP Eventing.
NPT_Result SetStateVariable(const char *name, const char *value)
Set a new value for a given state variable.
NPT_String GetEventSubURL(bool absolute=false)
Return the Event subscription url associated with this service.
The PLT_ServiceNameFinder class returns an instance of a PLT_Service given a service name...
Definition: PltService.h:488
bool IsSubscribable()
Return whether a service is capable of sending events.
const NPT_List< PLT_StateVariable * > & GetStateVariables() const
Return the list of state variables.
Definition: PltService.h:269
const NPT_String & GetServiceName() const
Return the service friendly name.
Definition: PltService.h:177
UPnP Service Action.
The PLT_DeviceData class holds information about a device being advertised or found by a control poin...
Definition: PltDeviceData.h:93
The PLT_ServiceEventSubURLFinder class returns an instance of a PLT_Service given a service event sub...
Definition: PltService.h:428
UPnP Device Host.
Definition: PltDeviceHost.h:69
The PLT_ServiceSCPDURLFinder class returns an instance of a PLT_Service given a service SCPD url...
Definition: PltService.h:388
const NPT_Array< PLT_ActionDesc * > & GetActionDescs() const
Return an array of actions descriptions PLT_ActionDesc.
Definition: PltService.h:282
NPT_Result GetDescription(NPT_XmlElementNode *parent, NPT_XmlElementNode **service=NULL)
Populate the UPnP Device description document with service information.
PLT_StateVariable * FindStateVariable(const char *name)
Return the PLT_StateVariable pointer given a state variable name.
The PLT_ServiceTypeFinder class returns an instance of a PLT_Service given a service type...
Definition: PltService.h:468
PLT_Service(PLT_DeviceData *device, const char *type, const char *id, const char *name, const char *last_change_namespace=NULL)
Create an instance of a UPnP Service either hosted or discovered.
NPT_String GetSCPDURL(bool absolute=false)
Return the SCPD url associated with this service.
The PLT_ServiceControlURLFinder class returns an instance of a PLT_Service given a service control ur...
Definition: PltService.h:408
const NPT_String & GetServiceID() const
Return the service id.
Definition: PltService.h:165
The PLT_ThreadTask class is a base class for executing a given task in a worker thread.
Definition: PltThreadTask.h:56
NPT_String GetControlURL(bool absolute=false)
Return the Control url associated with this service.
bool IsValid()
Verify the service has been properly initialized or is a valid discovered service.
Definition: PltService.h:97
NPT_Result SetSCPDURL(const char *url)
Set the SCPD url for control points to be able to fetch the SCPD xml document.
Definition: PltService.h:122
NPT_Result IncStateVariable(const char *name)
Helper function to increment a state variable representing a number.
NPT_Result SetStateVariableRate(const char *name, NPT_TimeInterval rate)
Certain state variables notifications must not be sent faster than a certain rate according to the UP...
NPT_Result SetEventSubURL(const char *url)
Set the Service Event subscription url for control points to be able to subscribe to events...
Definition: PltService.h:135