/*****************************************************************
|
| Platinum - Service Action
|
| Copyright (c) 2004-2010, Plutinosoft, LLC.
| All rights reserved.
| http://www.plutinosoft.com
|
| This program is free software; you can redistribute it and/or
| modify it under the terms of the GNU General Public License
| as published by the Free Software Foundation; either version 2
| of the License, or (at your option) any later version.
|
| OEMs, ISVs, VARs and other distributors that combine and
| distribute commercially licensed software with Platinum software
| and do not wish to distribute the source code for the commercially
| licensed software under version 2, or (at your option) any later
| version, of the GNU General Public License (the "GPL") must enter
| into a commercial license agreement with Plutinosoft, LLC.
| licensing@plutinosoft.com
|
| This program is distributed in the hope that it will be useful,
| but WITHOUT ANY WARRANTY; without even the implied warranty of
| MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
| GNU General Public License for more details.
|
| You should have received a copy of the GNU General Public License
| along with this program; see the file LICENSE.txt. If not, write to
| the Free Software Foundation, Inc.,
| 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
| http://www.gnu.org/licenses/gpl-2.0.html
|
****************************************************************/
/** @file
UPnP Service Action
*/
#ifndef _PLT_ACTION_H_
#define _PLT_ACTION_H_
/*----------------------------------------------------------------------
| includes
+---------------------------------------------------------------------*/
#include "Neptune.h"
#include "PltArgument.h"
#include "PltDeviceData.h"
/*----------------------------------------------------------------------
| forward declarations
+---------------------------------------------------------------------*/
class PLT_Service;
/*----------------------------------------------------------------------
| PLT_ActionDesc
+---------------------------------------------------------------------*/
/**
The PLT_ActionDesc class provides information about a UPnP Service given action.
This description has a name, a set of arguments and is associated to a service.
*/
class PLT_ActionDesc
{
public:
/**
Constructor
@param name the action name
@param service the UPnP service the action is associated with
*/
PLT_ActionDesc(const char* name, PLT_Service* service);
~PLT_ActionDesc();
/**
Return an array of arguments
@return array of arguments
*/
NPT_Array<PLT_ArgumentDesc*>& GetArgumentDescs() {
return m_ArgumentDescs;
}
/**
Return the action name.
@return action name.
*/
const NPT_String& GetName() const { return m_Name;}
/**
Look for an argument given a name.
@param name argument name
@return PLT_ArgumentDesc pointer
*/
PLT_ArgumentDesc* GetArgumentDesc(const char* name);
/**
Serialize action information to xml into an existing xml tree
@param node the xml Element to serialize action information
*/
NPT_Result GetSCPDXML(NPT_XmlElementNode* node);
/**
Return the service the action is associated with
*/
PLT_Service* GetService();
protected:
//members
NPT_String m_Name;
PLT_Service* m_Service;
NPT_Array<PLT_ArgumentDesc*> m_ArgumentDescs;
};
/*----------------------------------------------------------------------
| PLT_Action
+---------------------------------------------------------------------*/
/**
The PLT_Action class provides a mechanism to call or verify the validity of a
specific UPNP service action.
Given a service, a UPnP Control Point would use this class to serialize a soap
request. On the other side, a UPnP Device would use this class to verify
a soap request and the validity of the action arguments.
*/
class PLT_Action
{
public:
/**
Constructor
@param action_desc the action description
If you intend to send an action, you need to use the second constructor
and pass the root device of the device you wish to control.
*/
PLT_Action(PLT_ActionDesc& action_desc);
/**
Constructor
@param action_desc the action description
@param root_device a reference to the root device of the service the action
is associated with. This insures that the device won't be deleted if it goes
away while we're waiting for a response for this action. This is important because
we only keep a reference to the PLT_ActionDesc which is own by the service operated
by the device (or embedded device).
*/
PLT_Action(PLT_ActionDesc& action_desc, PLT_DeviceDataReference& root_device);
~PLT_Action();
/**
Return the action description
@return the action description
*/
PLT_ActionDesc& GetActionDesc() { return m_ActionDesc; }
/**
Retrieve the string value of an argument given an argument name.
@param name the argument name
@param value the string value to retrieve
@return error if the argument is not found or if the type does not correspond.
*/
NPT_Result GetArgumentValue(const char* name, NPT_String& value);
/**
Retrieve the value of an argument given an argument name.
@param name the argument name
@param value the unsigned int value to retrieve
@return error if the argument is not found or if the type does not correspond.
*/
NPT_Result GetArgumentValue(const char* name, NPT_UInt32& value);
/**
Retrieve the value of an argument given an argument name.
@param name the argument name
@param value the int value to retrieve
@return error if the argument is not found or if the type does not correspond.
*/
NPT_Result GetArgumentValue(const char* name, NPT_Int32& value);
/**
Retrieve the value of an argument given an argument name.
@param name the argument name
@param value the bool value to retrieve
@return error if the argument is not found or if the type does not correspond.
*/
NPT_Result GetArgumentValue(const char* name, bool& value);
/**
Verify a value is valid for a given argument.
@param name the argument name
@param value the value to verify
*/
NPT_Result VerifyArgumentValue(const char* name, const char* value);
/**
Verify that all required arguments are set.
@param input boolean indicating whether input or output parameters
should be verified
*/
NPT_Result VerifyArguments(bool input);
/**
Set the output argument value from the associated current state variable value.
@param name the state variable name
*/
NPT_Result SetArgumentOutFromStateVariable(const char* name);
/**
Set all the output argument values associated with state variables.
*/
NPT_Result SetArgumentsOutFromStateVariable();
/**
Set an argument value
@param name the argument name
@param value the argument value
*/
NPT_Result SetArgumentValue(const char* name, const char* value);
/**
Set the error code and description in case of failure.
@param code the code for the error
@param description a short description
*/
NPT_Result SetError(unsigned int code, const char* description);
/**
Return the error description and code for the failed action.
@param code optional pointer to receive the code
@return the error short description
*/
const char* GetError(unsigned int* code = NULL);
/**
Return the error code for the failed action.
@return the error code.
*/
unsigned int GetErrorCode();
/**
Called by a control point when serializing an action.
@param stream the stream to serialize the action to
*/
NPT_Result FormatSoapRequest(NPT_OutputStream& stream);
/**
Called by a device when serializing a response to an action.
@param stream the stream to serialize the action to
*/
NPT_Result FormatSoapResponse(NPT_OutputStream& stream);
/**
Helper method for a device to serialize an action invocation error.
@param code optional pointer to receive the code
@param desc the error short description
@param stream the stream to serialize to
*/
static NPT_Result FormatSoapError(unsigned int code,
NPT_String desc,
NPT_OutputStream& stream);
private:
// methods
NPT_Result SetArgumentOutFromStateVariable(PLT_ArgumentDesc* arg_desc);
PLT_Argument* GetArgument(const char* name);
protected:
// members
PLT_ActionDesc& m_ActionDesc;
PLT_Arguments m_Arguments;
unsigned int m_ErrorCode;
NPT_String m_ErrorDescription;
// keep reference of service root device to prevent it
// from being released during action lifetime
PLT_DeviceDataReference m_RootDevice;
};
typedef NPT_Reference<PLT_Action> PLT_ActionReference;
/*----------------------------------------------------------------------
| PLT_GetSCPDXMLIterator
+---------------------------------------------------------------------*/
/**
The PLT_GetSCPDXMLIterator class provides a recursive way to serialize
an SCPD into an xml tree.
*/
template <class T>
class PLT_GetSCPDXMLIterator
{
public:
PLT_GetSCPDXMLIterator<T>(NPT_XmlElementNode* node) :
m_Node(node) {}
NPT_Result operator()(T* const & data) const {
return data->GetSCPDXML(m_Node);
}
private:
NPT_XmlElementNode* m_Node;
};
/*----------------------------------------------------------------------
| PLT_ActionDescNameFinder
+---------------------------------------------------------------------*/
/**
The PLT_ActionDescNameFinder class provides a mechanism to find a PLT_ActionDesc
given an action name.
*/
class PLT_ActionDescNameFinder
{
public:
// methods
PLT_ActionDescNameFinder(const char* name) :
m_Name(name) {}
virtual ~PLT_ActionDescNameFinder() {}
bool operator()(const PLT_ActionDesc* const & action_desc) const {
return action_desc->GetName().Compare(m_Name, true) ? false : true;
}
private:
// members
NPT_String m_Name;
};
#endif /* _PLT_ACTION_H_ */