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

   1 /*****************************************************************
   2 |
   3 |   Platinum - Service State Variable
   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 State Variable
  37  */
  38
  39 #ifndef _PLT_STATE_VARIABLE_H_
  40 #define _PLT_STATE_VARIABLE_H_
  41
  42 /*----------------------------------------------------------------------
  43 |   includes
  44 +---------------------------------------------------------------------*/
  45 #include "Neptune.h"
  46
  47 /*----------------------------------------------------------------------
  48 |   forward declarations
  49 +---------------------------------------------------------------------*/
  50 class PLT_Argument;
  51 class PLT_Service;
  52
  53 /*----------------------------------------------------------------------
  54 |   NPT_AllowedValueRange struct
  55 +---------------------------------------------------------------------*/
  56 /**
  57  The NPT_AllowedValueRange struct holds the min, max and step value allowed of
  58  a UPnP Service state variable.
  59  */
  60 typedef struct {
  61     NPT_Int32 min_value;
  62     NPT_Int32 max_value;
  63     NPT_Int32 step;
  64 } NPT_AllowedValueRange;
  65
  66 /*----------------------------------------------------------------------
  67 |   PLT_StateVariable class
  68 +---------------------------------------------------------------------*/
  69 /**
  70  The PLT_StateVariable class maintains the state of a UPnP Service state variable.
  71  It is used by a PLT_DeviceHost instance to notify subscribers of a change or by a
  72  subscriber (PLT_CtrlPoint) when a service state variable change notification
  73  has been received.
  74  */
  75 class PLT_StateVariable
  76 {
  77 public:
  78     PLT_StateVariable(PLT_Service* service);
  79     ~PLT_StateVariable();
  80
  81     /**
  82      Populate the SCPD xml document with state variable information.
  83      @param node XML Element where to insert the state variable XML Element
  84      */
  85     NPT_Result GetSCPDXML(NPT_XmlElementNode* node);
  86
  87     /**
  88      Return the PLT_Service that this state variable is associated with.
  89      @return PLT_Service pointer.
  90      */
  91     PLT_Service* GetService();
  92
  93     /**
  94      Return whether the state variable is eventable directly or indirectly. A state
  95      variable sends events indirectly when part of the "LastChange" state variable.
  96      @param indirectly Boolean to test if the state variable is sending events indirectly
  97      @return Whether the state variable sends events according to the input flag specified.
  98      */
  99     bool IsSendingEvents(bool indirectly = false);
 100
 101     /**
 102      Force the state variable to send events directly.
 103      */
 104     void DisableIndirectEventing();
 105
 106     /**
 107      Certain state variables notifications must not be sent faster than a certain
 108      rate according to the UPnP specs. This sets the rate for a given state variable.
 109      @param rate time interval to respect between notifications.
 110      */
 111     NPT_Result SetRate(NPT_TimeInterval rate);
 112
 113     /**
 114      Set the state variable value. The value is first validated to make sure
 115      it is an allowed value. Once the value is validated, it is marked for eventing by
 116      calling the PLT_Service AddChanged function.
 117      @param value new state variable value. Can be a comma separated list of values.
 118      @param clearonsend whether the statevariable should be cleared immediatly after sending
 119      */
 120     NPT_Result SetValue(const char* value, const bool clearonsend = false);
 121
 122     /**
 123      Validate the new value of the state variable.
 124      @param value new state variable value. Can be a comma separated list of values.
 125      */
 126     NPT_Result ValidateValue(const char* value);
 127
 128     /**
 129      Certain state variables require extra xml attributes when serialized.
 130      @param name the attribute name
 131      @param value the attribute value
 132      */
 133         NPT_Result SetExtraAttribute(const char* name, const char* value);
 134
 135     /**
 136      Return the state variable name.
 137      @return state variable name.
 138      */
 139     const NPT_String& GetName()     const { return m_Name;     }
 140
 141     /**
 142      Return the current state variable value.
 143      @return state variable current value.
 144      */
 145     const NPT_String& GetValue()    const { return m_Value;    }
 146
 147     /**
 148      Return the state variable data type.
 149      @return state variable data type.
 150      */
 151     const NPT_String& GetDataType() const { return m_DataType; }
 152
 153     /**
 154      Return the state variable allowed value range if any.
 155      @return state variable value range pointer or null if none.
 156      */
 157         const NPT_AllowedValueRange* GetAllowedValueRange() const { return m_AllowedValueRange; }
 158
 159     /**
 160      Helper function to return a state variable given a list of state variables
 161      and a state variable name.
 162      @param vars list of state variables
 163      @param name state variable name to look for
 164      @return PLT_StateVariable pointer.
 165      */
 166     static PLT_StateVariable* Find(NPT_List<PLT_StateVariable*>& vars,
 167                                    const char*                   name);
 168
 169 protected:
 170     /**
 171      Return whether the state variable value changed and subscribers need to
 172      be notified.
 173      */
 174     bool IsReadyToPublish();
 175
 176     /**
 177      * If this statevariable should clear after sending to all subscribers, clears the value without
 178      * eventing the change
 179      */
 180     void OnSendCompleted();
 181
 182     /**
 183      Serialize the state variable into xml.
 184      */
 185         NPT_Result Serialize(NPT_XmlElementNode& node);
 186
 187 protected:
 188     friend class PLT_Service;
 189     friend class PLT_LastChangeXMLIterator;
 190
 191     //members
 192     PLT_Service*            m_Service;
 193     NPT_AllowedValueRange*  m_AllowedValueRange;
 194     NPT_String              m_Name;
 195     NPT_String              m_DataType;
 196     NPT_String              m_DefaultValue;
 197     bool                    m_IsSendingEvents;
 198     bool                    m_IsSendingEventsIndirectly;
 199     bool                    m_ShouldClearOnSend;
 200     NPT_TimeInterval        m_Rate;
 201     NPT_TimeStamp           m_LastEvent;
 202     NPT_Array<NPT_String*>  m_AllowedValues;
 203     NPT_String              m_Value;
 204
 205         NPT_Map<NPT_String,NPT_String> m_ExtraAttributes;
 206 };
 207
 208 /*----------------------------------------------------------------------
 209 |   PLT_StateVariableNameFinder
 210 +---------------------------------------------------------------------*/
 211 /**
 212  The PLT_StateVariableNameFinder class returns the PLT_StateVariable instance
 213  given a state variable name.
 214  */
 215 class PLT_StateVariableNameFinder
 216 {
 217 public:
 218     // methods
 219     PLT_StateVariableNameFinder(const char* name) : m_Name(name) {}
 220     virtual ~PLT_StateVariableNameFinder() {}
 221
 222     bool operator()(const PLT_StateVariable* const & state_variable) const {
 223         return state_variable->GetName().Compare(m_Name, true) ? false : true;
 224     }
 225
 226 private:
 227     // members
 228     NPT_String   m_Name;
 229 };
 230
 231 #endif /* _PLT_STATE_VARIABLE_H_ */