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

   1 /*****************************************************************
   2 |
   3 |   Platinum - Service Action
   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 Action
  37  */
  38
  39 #ifndef _PLT_ACTION_H_
  40 #define _PLT_ACTION_H_
  41
  42 /*----------------------------------------------------------------------
  43 |   includes
  44 +---------------------------------------------------------------------*/
  45 #include "Neptune.h"
  46 #include "PltArgument.h"
  47 #include "PltDeviceData.h"
  48
  49 /*----------------------------------------------------------------------
  50 |   forward declarations
  51 +---------------------------------------------------------------------*/
  52 class PLT_Service;
  53
  54 /*----------------------------------------------------------------------
  55 |   PLT_ActionDesc
  56 +---------------------------------------------------------------------*/
  57 /**
  58  The PLT_ActionDesc class provides information about a UPnP Service given action.
  59  This description has a name, a set of arguments and is associated to a service.
  60  */
  61 class PLT_ActionDesc
  62 {
  63 public:
  64     /**
  65      Constructor
  66      @param name the action name
  67      @param service the UPnP service the action is associated with
  68      */
  69     PLT_ActionDesc(const char* name, PLT_Service* service);
  70    ~PLT_ActionDesc();
  71
  72     /**
  73      Return an array of arguments
  74      @return array of arguments
  75      */
  76     NPT_Array<PLT_ArgumentDesc*>& GetArgumentDescs() {
  77         return m_ArgumentDescs;
  78     }
  79
  80     /**
  81      Return the action name.
  82      @return action name.
  83      */
  84     const NPT_String& GetName() const { return m_Name;}
  85
  86     /**
  87      Look for an argument given a name.
  88      @param name argument name
  89      @return PLT_ArgumentDesc pointer
  90      */
  91     PLT_ArgumentDesc* GetArgumentDesc(const char* name);
  92
  93     /**
  94      Serialize action information to xml into an existing xml tree
  95      @param node the xml Element to serialize action information
  96      */
  97     NPT_Result        GetSCPDXML(NPT_XmlElementNode* node);
  98
  99     /**
 100      Return the service the action is associated with
 101      */
 102     PLT_Service*      GetService();
 103
 104 protected:
 105     //members
 106     NPT_String                   m_Name;
 107     PLT_Service*                 m_Service;
 108     NPT_Array<PLT_ArgumentDesc*> m_ArgumentDescs;
 109 };
 110
 111 /*----------------------------------------------------------------------
 112 |   PLT_Action
 113 +---------------------------------------------------------------------*/
 114 /**
 115  The PLT_Action class provides a mechanism to call or verify the validity of a
 116  specific UPNP service action.
 117  Given a service, a UPnP Control Point would use this class to serialize a soap
 118  request. On the other side, a UPnP Device would use this class to verify
 119  a soap request and the validity of the action arguments.
 120  */
 121 class PLT_Action
 122 {
 123 public:
 124     /**
 125      Constructor
 126      @param action_desc the action description
 127      If you intend to send an action, you need to use the second constructor
 128      and pass the root device of the device you wish to control.
 129      */
 130     PLT_Action(PLT_ActionDesc& action_desc);
 131
 132     /**
 133      Constructor
 134      @param action_desc the action description
 135      @param root_device a reference to the root device of the service the action
 136      is associated with. This insures that the device won't be deleted if it goes
 137      away while we're waiting for a response for this action. This is important because
 138      we only keep a reference to the PLT_ActionDesc which is own by the service operated
 139      by the device (or embedded device).
 140      */
 141     PLT_Action(PLT_ActionDesc& action_desc, PLT_DeviceDataReference& root_device);
 142     ~PLT_Action();
 143
 144     /**
 145      Return the action description
 146      @return the action description
 147      */
 148     PLT_ActionDesc& GetActionDesc() { return m_ActionDesc; }
 149
 150     /**
 151      Retrieve the string value of an argument given an argument name.
 152      @param name the argument name
 153      @param value the string value to retrieve
 154      @return error if the argument is not found or if the type does not correspond.
 155      */
 156     NPT_Result GetArgumentValue(const char* name, NPT_String& value);
 157
 158     /**
 159      Retrieve the value of an argument given an argument name.
 160      @param name the argument name
 161      @param value the unsigned int value to retrieve
 162      @return error if the argument is not found or if the type does not correspond.
 163      */
 164     NPT_Result GetArgumentValue(const char* name, NPT_UInt32& value);
 165
 166     /**
 167      Retrieve the value of an argument given an argument name.
 168      @param name the argument name
 169      @param value the int value to retrieve
 170      @return error if the argument is not found or if the type does not correspond.
 171      */
 172     NPT_Result GetArgumentValue(const char* name, NPT_Int32& value);
 173
 174     /**
 175      Retrieve the value of an argument given an argument name.
 176      @param name the argument name
 177      @param value the bool value to retrieve
 178      @return error if the argument is not found or if the type does not correspond.
 179      */
 180         NPT_Result GetArgumentValue(const char* name, bool& value);
 181
 182     /**
 183      Verify a value is valid for a given argument.
 184      @param name the argument name
 185      @param value the value to verify
 186      */
 187     NPT_Result VerifyArgumentValue(const char* name, const char* value);
 188
 189     /**
 190      Verify that all required arguments are set.
 191      @param input boolean indicating whether input or output parameters
 192      should be verified
 193      */
 194     NPT_Result VerifyArguments(bool input);
 195
 196     /**
 197      Set the output argument value from the associated current state variable value.
 198      @param name the state variable name
 199      */
 200     NPT_Result SetArgumentOutFromStateVariable(const char* name);
 201
 202     /**
 203      Set all the output argument values associated with state variables.
 204      */
 205     NPT_Result SetArgumentsOutFromStateVariable();
 206
 207     /**
 208      Set an argument value
 209      @param name the argument name
 210      @param value the argument value
 211      */
 212     NPT_Result SetArgumentValue(const char* name, const char* value);
 213
 214     /**
 215      Set the error code and description in case of failure.
 216      @param code the code for the error
 217      @param description a short description
 218      */
 219     NPT_Result SetError(unsigned int code, const char* description);
 220
 221     /**
 222      Return the error description and code for the failed action.
 223      @param code optional pointer to receive the code
 224      @return the error short description
 225      */
 226     const char* GetError(unsigned int* code = NULL);
 227
 228     /**
 229      Return the error code for the failed action.
 230      @return the error code.
 231      */
 232     unsigned int GetErrorCode();
 233
 234     /**
 235      Called by a control point when serializing an action.
 236      @param stream the stream to serialize the action to
 237      */
 238     NPT_Result    FormatSoapRequest(NPT_OutputStream& stream);
 239
 240     /**
 241      Called by a device when serializing a response to an action.
 242      @param stream the stream to serialize the action to
 243      */
 244     NPT_Result    FormatSoapResponse(NPT_OutputStream& stream);
 245
 246     /**
 247      Helper method for a device to serialize an action invocation error.
 248      @param code optional pointer to receive the code
 249      @param desc the error short description
 250      @param stream the stream to serialize to
 251      */
 252     static NPT_Result FormatSoapError(unsigned int      code,
 253                                       NPT_String        desc,
 254                                       NPT_OutputStream& stream);
 255
 256 private:
 257     // methods
 258     NPT_Result    SetArgumentOutFromStateVariable(PLT_ArgumentDesc* arg_desc);
 259     PLT_Argument* GetArgument(const char* name);
 260
 261 protected:
 262     // members
 263     PLT_ActionDesc&         m_ActionDesc;
 264     PLT_Arguments           m_Arguments;
 265     unsigned int            m_ErrorCode;
 266     NPT_String              m_ErrorDescription;
 267
 268     // keep reference of service root device to prevent it
 269     // from being released during action lifetime
 270         PLT_DeviceDataReference m_RootDevice;
 271 };
 272
 273 typedef NPT_Reference<PLT_Action> PLT_ActionReference;
 274
 275 /*----------------------------------------------------------------------
 276 |   PLT_GetSCPDXMLIterator
 277 +---------------------------------------------------------------------*/
 278 /**
 279  The PLT_GetSCPDXMLIterator class provides a recursive way to serialize
 280  an SCPD into an xml tree.
 281  */
 282 template <class T>
 283 class PLT_GetSCPDXMLIterator
 284 {
 285 public:
 286     PLT_GetSCPDXMLIterator(NPT_XmlElementNode* node) :
 287         m_Node(node) {}
 288
 289     NPT_Result operator()(T* const & data) const {
 290         return data->GetSCPDXML(m_Node);
 291     }
 292
 293 private:
 294     NPT_XmlElementNode* m_Node;
 295 };
 296
 297 /*----------------------------------------------------------------------
 298 |   PLT_ActionDescNameFinder
 299 +---------------------------------------------------------------------*/
 300 /**
 301  The PLT_ActionDescNameFinder class provides a mechanism to find a PLT_ActionDesc
 302  given an action name.
 303  */
 304 class PLT_ActionDescNameFinder
 305 {
 306 public:
 307     // methods
 308     PLT_ActionDescNameFinder(const char* name) :
 309         m_Name(name) {}
 310     virtual ~PLT_ActionDescNameFinder() {}
 311
 312     bool operator()(const PLT_ActionDesc* const & action_desc) const {
 313         return action_desc->GetName().Compare(m_Name, true) ? false : true;
 314     }
 315
 316 private:
 317     // members
 318     NPT_String   m_Name;
 319 };
 320
 321 #endif /* _PLT_ACTION_H_ */