2
* Copyright (C) 2010, 2011 Tuomo Penttinen, all rights reserved.
4
* Author: Tuomo Penttinen <tp@herqq.org>
6
* This file is part of Herqq UPnP (HUPnP) library.
8
* Herqq UPnP is free software: you can redistribute it and/or modify
9
* it under the terms of the GNU Lesser General Public License as published by
10
* the Free Software Foundation, either version 3 of the License, or
11
* (at your option) any later version.
13
* Herqq UPnP is distributed in the hope that it will be useful,
14
* but WITHOUT ANY WARRANTY; without even the implied warranty of
15
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16
* GNU Lesser General Public License for more details.
18
* You should have received a copy of the GNU Lesser General Public License
19
* along with Herqq UPnP. If not, see <http://www.gnu.org/licenses/>.
22
#ifndef HCLIENT_STATEVARIABLE_H_
23
#define HCLIENT_STATEVARIABLE_H_
25
#include <HUpnpCore/HUpnpDataTypes>
27
#include <QtCore/QObject>
28
#include <QtCore/QVariant>
36
class HStateVariablePrivate;
39
* \brief A client-side class that represents a server-side UPnP state variable.
41
* \c %HClientStateVariable is a core component of the HUPnP's client-side \ref hupnp_devicemodel
42
* and it models a UPnP state variable. The UPnP Device Architecture specifies a
43
* UPnP state variable as an item or aspect that models state in a service.
44
* In a way a state variable is an abstraction to a member variable inside a
47
* A state variable can be \e evented in which case it notifies interested listeners
48
* of changes in its value. You can see if a state variable is evented by checking
49
* the HStateVariableInfo object using info() and you can connect to the signal
50
* valueChanged() to be notified when the value of the state variable changes.
51
* Note, only evented state variables emit the valueChanged() signal.
53
* \headerfile hclientstatevariable.h HClientStateVariable
55
* \ingroup hupnp_devicemodel
59
* \remarks This class is not thread-safe.
61
class H_UPNP_CORE_EXPORT HClientStateVariable :
65
H_DISABLE_COPY(HClientStateVariable)
69
HStateVariablePrivate* h_ptr;
72
* \brief Creates a new instance.
74
* \param info specifies information of the state variable. This is often
75
* read from a service description document.
77
* \param parent specifies the UPnP service instance that contains this
80
HClientStateVariable(const HStateVariableInfo& info, HClientService* parent);
83
* Changes the value of the state variable. If the instance is evented,
84
* the valueChanged() signal is emitted after the value has been changed.
86
* \param newValue specifies the new value of the state variable. The new value
87
* must have the same underlying data type as the previous value
88
* (and the default value). If the new value has different data type, the value
89
* is not changed, no event is sent and false is returned.
91
* \retval true in case the new value was successfully set.
92
* \retval false in case the new value could not be set.
94
* \remarks the new value will be set if the value:
95
* - does not violate the defined constraints
96
* - has the same variant type or the type of the new value can be converted
97
* to the same variant type
98
* - is not QVariant::Invalid
100
bool setValue(const QVariant& newValue);
105
* \brief Destroys the instance.
107
* An \c %HClientStateVariable is always destroyed by the
108
* \c %HClientService that contains it when it is being deleted.
109
* Further, unless you hold the ownership of the \c %HClientStateVariable
110
* instance, you should never destroy it.
112
virtual ~HClientStateVariable() = 0;
115
* \brief Returns the HClientService that contains this state variable.
117
* \return The HClientService that contains this state variable.
119
* \warning the pointer is guaranteed to point to a valid object as long
120
* as the \c %HClientStateVariable exists, which ultimately is as long as the
121
* containing root device exists.
123
HClientService* parentService() const;
126
* \brief Returns the current value of the state variable.
128
* \return The current value of the state variable.
130
QVariant value() const;
133
* \brief Returns information about the state variable.
135
* \return information about the state variable. This information is often read
136
* from a service description document.
138
const HStateVariableInfo& info() const;
143
* \brief This signal is emitted when the value of the state variable has changed.
145
* \param source specifies the state variable that sent the event.
147
* \param event specifies information about the event that occurred.
149
* \remarks This signal has thread affinity to the thread where the object
150
* resides. Do not connect to this signal from other threads.
153
const Herqq::Upnp::HClientStateVariable* source,
154
const Herqq::Upnp::HStateVariableEvent& event);
160
#endif /* HCLIENT_STATEVARIABLE_H_ */