~apachelogger/ubuntuone-client/gsoc : contents of src/api/Subscription.h at revision 347

~apachelogger/ubuntuone-client/gsoc : (revision 347)

/*
  Copyright © 2010 Harald Sitter <apachelogger@ubuntu.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) version 3 or any later version
  accepted by the membership of KDE e.V. (or its successor approved
  by the membership of KDE e.V.), which shall act as a proxy
  defined in Section 14 of version 3 of the license.

  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.  If not, see <http://www.gnu.org/licenses/>.
*/

#ifndef U1_QT_API_SUBSCRIPTION_H
#define U1_QT_API_SUBSCRIPTION_H

#include <QtCore/QVariantMap>

#include "ApiExport.h"

namespace UbuntuOne
{
    namespace Api
    {

//////////////////////////////// OBJECT ////////////////////////////////
        class SubscriptionObjectPrivate;

        /**
          SubscriptionObject object as returned from the Ubuntu One REST API.
          This class is more like a container specific for SubscriptionObject data.

          This class should not be used itself but the real use implementations
          of a SubscriptionObject (Subscription and SubscriptionUpgrade).
          It is but the core of those two classes and the general base of
          SubscriptionObjects in the Ubuntu One API context.
        */
        class U1_QT_EXPORT SubscriptionObject : public QObject
        {
            Q_OBJECT

            Q_PROPERTY(QString currency READ currency WRITE setCurrency)
            Q_PROPERTY(QString description READ description WRITE setDescription)
            Q_PROPERTY(qulonglong id READ id WRITE setId)
            Q_PROPERTY(QString name READ name WRITE setName)
            Q_PROPERTY(double price READ price WRITE setPrice)

        public:
            explicit SubscriptionObject(QObject *parent = 0);
            virtual ~SubscriptionObject();

            /**
              The currency the subscription is priced in.

              @return currency (for example USD).
            */
            QString currency() const;

            /**
              Sets the currency of the subscription.

              @param currency the currency (for example USD).
            */
            void setCurrency(const QString &currency);

            /**
              The description of the subscription. Please note that this should
              be different from the name and actually really describe what this
              type of subscription is all about.

              A possilbe description might be:
              "Super expensive subscription with no service whatsoever."

              @return the description string.
            */
            QString description() const;

            /**
              Sets the description of the subscription.

              @param description the description.
            */
            void setDescription(const QString &description);

            /**
              The id of the subscription type.

              @return the id.
            */
            qulonglong id() const;

            /**
              Sets the id of the subscription type.

              @param id the id.
            */
            void setId(const qulonglong &id);

            /**
              The name of the subscription.

              @return the name
            */
            QString name() const;

            /**
              Sets the name of the subscription.

              @param name the name.
            */
            void setName(const QString &name);

            /**
              Price of the subscription.

              @return the price.
            */
            double price() const;

            /**
              Sets the price of the subscription.

              @param price the price.
            */
            void setPrice(const double &price);

        protected:
            SubscriptionObjectPrivate *const d_ptr;
            SubscriptionObject(SubscriptionObjectPrivate &dd, QObject *parent);

        private:
            Q_DISABLE_COPY(SubscriptionObject)
            Q_DECLARE_PRIVATE(SubscriptionObject)
        };

//////////////////////////////// UPGRADE ///////////////////////////////
        class SubscriptionUpgradePrivate;

        /**
          SubscriptionUpgrade object as returned from the Ubuntu One REST API.
          This class is more like a container specific for SubscriptionUpgrade data.

          This class implements a SubscriptionObject but additionally offers an
          upgrade URL where the user can upgrade her current subscription to
          the offered one.
        */
        class U1_QT_EXPORT SubscriptionUpgrade : public SubscriptionObject
        {
            Q_OBJECT

            Q_PROPERTY(QString upgrade_url READ upgradeUrl WRITE setUpgradeUrl)

        public:
            explicit SubscriptionUpgrade(QObject *parent = 0);
            virtual ~SubscriptionUpgrade();

            /**
              The URL where the user can upgrade to the subscription.

              @return a URL.
            */
            QString upgradeUrl() const;

            /**
              Sets the URL where the user can upgrade.

              @param upgradeUrl the url.
            */
            void setUpgradeUrl(const QString &upgradeUrl);

        protected:
            SubscriptionUpgrade(SubscriptionUpgradePrivate &dd, QObject *parent);

        private:
            Q_DISABLE_COPY(SubscriptionUpgrade)
            Q_DECLARE_PRIVATE(SubscriptionUpgrade)
        };

///////////////////////////// SUBSCRIPTION /////////////////////////////
        class SubscriptionPrivate;

        /**
          Subscription object as returned from the Ubuntu One REST API.
          This class is more like a container specific for Subscription data.

          This class implements a SubscriptionObject but additionally provides
          information related to the currently active Subscription.
          For example a Subscription can be paied or not or be in trial stage.

          Please note that this class is only meant to present the currently
          active subscription. For subscription upgrades please refer to
          SubscriptionUpgrade.
        */
        class U1_QT_EXPORT Subscription : public SubscriptionObject
        {
            Q_OBJECT

            Q_PROPERTY(QString expires READ expires WRITE setExpires)
            Q_PROPERTY(bool paid READ paid WRITE setPaid)
            Q_PROPERTY(QString started READ started WRITE setStarted)
            Q_PROPERTY(bool trial READ trial WRITE setTrial)
            Q_PROPERTY(bool upgrade_available READ upgradeAvailable WRITE setUpgradeAvailable)
            Q_PROPERTY(SubscriptionUpgrade *upgrade_option READ upgradeOption)
            Q_PROPERTY(QVariantMap upgrade_option READ QVariantMap() WRITE setUpgradeOption)

        public:
            explicit Subscription(QObject *parent = 0);
            virtual ~Subscription();

            /**
              Returns when this subscription will expire.

              @return expiration data as string.
            */
            QString expires() const;

            /**
              Set the date when this subscription expires.

              @param expires the string information.
            */
            void setExpires(const QString &expires);

            /**
              Whether this subscription is paied.

              @return @c true if the subscription is paied.
              @return @c flase if the subscription is not paied yet.
            */
            bool paid() const;

            /**
              Set whether the subscription is paied.

              @param paid true if the subscription is paied, false if not.
            */
            void setPaid(const bool &paid);

            /**
              The date when the subscription started running.

              @return date string.
            */
            QString started() const;

            /**
              Set the date string when the subscription started.

              @param started date string.
            */
            void setStarted(const QString &started);

            /**
              Whether the subscription is in trial period.

              @return @c true if it is a trial.
              @return @c false if it is not a trial.
            */
            bool trial() const;

            /**
              Set whether the subscription is a trial.

              @param trial true if in trial period, false if not.
            */
            void setTrial(const bool &trial);

            /**
              Wether an upgrade is available.
              Only if this is true upgradeOption() will return anything meaningful.

              Most of the time it will make more sense to simply call upgradeOption()
              and check if it returned 0.

              @return @c true if an upgrade is available.
              @return @c false if no upgrades is available.
            */
            bool upgradeAvailable() const;

            /**
              Sets whether an upgrade for the subscription is available.

              @pram upgradeAvailable true if upgrade is available, false if not.
            */
            void setUpgradeAvailable(const bool &upgradeAvailable);

            /**
              Returns an upgrade option for the subscription.

              @return @c SubscriptionUpgrade if there is any.
              @return @c 0 if there is no upgrade available.
            */
            SubscriptionUpgrade *upgradeOption() const;

            /**
              Set an upgrade option for the subscription.

              @param a QVariantMap (QStringHash to be precise) of the upgrade
                     option, the map will automatically be marshalled to a
                     SubscriptionUpgrade.
            */
            void setUpgradeOption(const QVariantMap &upgradeOption);

        protected:
            Subscription(SubscriptionPrivate &dd, QObject *parent);

        private:
            Q_DISABLE_COPY(Subscription)
            Q_DECLARE_PRIVATE(Subscription)
        };

    } // namespace Api
} // namespace UbuntuOne

#endif // API_SUBSCRIPTION_H

56.1.25 by Harald Sitter License headers++	1	/*
	2	Copyright © 2010 Harald Sitter <apachelogger@ubuntu.com>
	3
	4	This program is free software; you can redistribute it and/or
	5	modify it under the terms of the GNU General Public License as
	6	published by the Free Software Foundation; either version 2 of
	7	the License or (at your option) version 3 or any later version
	8	accepted by the membership of KDE e.V. (or its successor approved
	9	by the membership of KDE e.V.), which shall act as a proxy
	10	defined in Section 14 of version 3 of the license.
	11
	12	This program is distributed in the hope that it will be useful,
	13	but WITHOUT ANY WARRANTY; without even the implied warranty of
	14	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
	15	GNU General Public License for more details.
	16
	17	You should have received a copy of the GNU General Public License
	18	along with this program. If not, see <http://www.gnu.org/licenses/>.
	19	*/
	20
123 by Harald Sitter more explicit include guards	21	#ifndef U1_QT_API_SUBSCRIPTION_H
123 by Harald Sitter more explicit include guards	22	#define U1_QT_API_SUBSCRIPTION_H
56.1.23 by Harald Sitter Work around issue with qvariant and custom types by marshaling the childs of account manually	23
76 by Harald Sitter More sanity for the api -- off to bed commit (technically I already am ;))	24	#include <QtCore/QVariantMap>
56.1.23 by Harald Sitter Work around issue with qvariant and custom types by marshaling the childs of account manually	25
75 by Harald Sitter Make api a shared lib	26	#include "ApiExport.h"
56.1.23 by Harald Sitter Work around issue with qvariant and custom types by marshaling the childs of account manually	27
136 by Harald Sitter formatting++	28	namespace UbuntuOne
136 by Harald Sitter formatting++	29	{
156 by Harald Sitter namespace indention ... spec does not define whether namespaces are indented or not, so general rule of indention is supposedly to be applied	30	namespace Api
	31	{
136 by Harald Sitter formatting++	32
136 by Harald Sitter formatting++	33	//////////////////////////////// OBJECT ////////////////////////////////
156 by Harald Sitter namespace indention ... spec does not define whether namespaces are indented or not, so general rule of indention is supposedly to be applied	34	class SubscriptionObjectPrivate;
300 by Harald Sitter documentation+++++++	35
	36	/**
	37	SubscriptionObject object as returned from the Ubuntu One REST API.
	38	This class is more like a container specific for SubscriptionObject data.
	39
	40	This class should not be used itself but the real use implementations
	41	of a SubscriptionObject (Subscription and SubscriptionUpgrade).
	42	It is but the core of those two classes and the general base of
	43	SubscriptionObjects in the Ubuntu One API context.
	44	*/
156 by Harald Sitter namespace indention ... spec does not define whether namespaces are indented or not, so general rule of indention is supposedly to be applied	45	class U1_QT_EXPORT SubscriptionObject : public QObject
	46	{
	47	Q_OBJECT
	48
	49	Q_PROPERTY(QString currency READ currency WRITE setCurrency)
	50	Q_PROPERTY(QString description READ description WRITE setDescription)
	51	Q_PROPERTY(qulonglong id READ id WRITE setId)
	52	Q_PROPERTY(QString name READ name WRITE setName)
	53	Q_PROPERTY(double price READ price WRITE setPrice)
	54
	55	public:
	56	explicit SubscriptionObject(QObject *parent = 0);
	57	virtual ~SubscriptionObject();
	58
300 by Harald Sitter documentation+++++++	59	/**
	60	The currency the subscription is priced in.
	61
	62	@return currency (for example USD).
	63	*/
156 by Harald Sitter namespace indention ... spec does not define whether namespaces are indented or not, so general rule of indention is supposedly to be applied	64	QString currency() const;
300 by Harald Sitter documentation+++++++	65
	66	/**
	67	Sets the currency of the subscription.
	68
	69	@param currency the currency (for example USD).
	70	*/
156 by Harald Sitter namespace indention ... spec does not define whether namespaces are indented or not, so general rule of indention is supposedly to be applied	71	void setCurrency(const QString &currency);
	72
300 by Harald Sitter documentation+++++++	73	/**
	74	The description of the subscription. Please note that this should
	75	be different from the name and actually really describe what this
	76	type of subscription is all about.
	77
	78	A possilbe description might be:
	79	"Super expensive subscription with no service whatsoever."
	80
	81	@return the description string.
	82	*/
156 by Harald Sitter namespace indention ... spec does not define whether namespaces are indented or not, so general rule of indention is supposedly to be applied	83	QString description() const;
300 by Harald Sitter documentation+++++++	84
	85	/**
	86	Sets the description of the subscription.
	87
	88	@param description the description.
	89	*/
156 by Harald Sitter namespace indention ... spec does not define whether namespaces are indented or not, so general rule of indention is supposedly to be applied	90	void setDescription(const QString &description);
	91
300 by Harald Sitter documentation+++++++	92	/**
	93	The id of the subscription type.
	94
	95	@return the id.
	96	*/
156 by Harald Sitter namespace indention ... spec does not define whether namespaces are indented or not, so general rule of indention is supposedly to be applied	97	qulonglong id() const;
300 by Harald Sitter documentation+++++++	98
	99	/**
	100	Sets the id of the subscription type.
	101
	102	@param id the id.
	103	*/
156 by Harald Sitter namespace indention ... spec does not define whether namespaces are indented or not, so general rule of indention is supposedly to be applied	104	void setId(const qulonglong &id);
	105
300 by Harald Sitter documentation+++++++	106	/**
	107	The name of the subscription.
	108
	109	@return the name
	110	*/
156 by Harald Sitter namespace indention ... spec does not define whether namespaces are indented or not, so general rule of indention is supposedly to be applied	111	QString name() const;
300 by Harald Sitter documentation+++++++	112
	113	/**
	114	Sets the name of the subscription.
	115
	116	@param name the name.
	117	*/
156 by Harald Sitter namespace indention ... spec does not define whether namespaces are indented or not, so general rule of indention is supposedly to be applied	118	void setName(const QString &name);
	119
300 by Harald Sitter documentation+++++++	120	/**
	121	Price of the subscription.
	122
	123	@return the price.
	124	*/
156 by Harald Sitter namespace indention ... spec does not define whether namespaces are indented or not, so general rule of indention is supposedly to be applied	125	double price() const;
300 by Harald Sitter documentation+++++++	126
	127	/**
	128	Sets the price of the subscription.
	129
	130	@param price the price.
	131	*/
156 by Harald Sitter namespace indention ... spec does not define whether namespaces are indented or not, so general rule of indention is supposedly to be applied	132	void setPrice(const double &price);
	133
	134	protected:
	135	SubscriptionObjectPrivate *const d_ptr;
	136	SubscriptionObject(SubscriptionObjectPrivate &dd, QObject *parent);
	137
	138	private:
	139	Q_DISABLE_COPY(SubscriptionObject)
	140	Q_DECLARE_PRIVATE(SubscriptionObject)
	141	};
136 by Harald Sitter formatting++	142
136 by Harald Sitter formatting++	143	//////////////////////////////// UPGRADE ///////////////////////////////
156 by Harald Sitter namespace indention ... spec does not define whether namespaces are indented or not, so general rule of indention is supposedly to be applied	144	class SubscriptionUpgradePrivate;
300 by Harald Sitter documentation+++++++	145
	146	/**
	147	SubscriptionUpgrade object as returned from the Ubuntu One REST API.
	148	This class is more like a container specific for SubscriptionUpgrade data.
	149
	150	This class implements a SubscriptionObject but additionally offers an
	151	upgrade URL where the user can upgrade her current subscription to
	152	the offered one.
	153	*/
156 by Harald Sitter namespace indention ... spec does not define whether namespaces are indented or not, so general rule of indention is supposedly to be applied	154	class U1_QT_EXPORT SubscriptionUpgrade : public SubscriptionObject
	155	{
	156	Q_OBJECT
	157
	158	Q_PROPERTY(QString upgrade_url READ upgradeUrl WRITE setUpgradeUrl)
	159
	160	public:
	161	explicit SubscriptionUpgrade(QObject *parent = 0);
	162	virtual ~SubscriptionUpgrade();
	163
300 by Harald Sitter documentation+++++++	164	/**
	165	The URL where the user can upgrade to the subscription.
	166
	167	@return a URL.
	168	*/
156 by Harald Sitter namespace indention ... spec does not define whether namespaces are indented or not, so general rule of indention is supposedly to be applied	169	QString upgradeUrl() const;
300 by Harald Sitter documentation+++++++	170
	171	/**
	172	Sets the URL where the user can upgrade.
	173
	174	@param upgradeUrl the url.
	175	*/
156 by Harald Sitter namespace indention ... spec does not define whether namespaces are indented or not, so general rule of indention is supposedly to be applied	176	void setUpgradeUrl(const QString &upgradeUrl);
	177
	178	protected:
	179	SubscriptionUpgrade(SubscriptionUpgradePrivate &dd, QObject *parent);
	180
	181	private:
	182	Q_DISABLE_COPY(SubscriptionUpgrade)
	183	Q_DECLARE_PRIVATE(SubscriptionUpgrade)
	184	};
136 by Harald Sitter formatting++	185
136 by Harald Sitter formatting++	186	///////////////////////////// SUBSCRIPTION /////////////////////////////
156 by Harald Sitter namespace indention ... spec does not define whether namespaces are indented or not, so general rule of indention is supposedly to be applied	187	class SubscriptionPrivate;
300 by Harald Sitter documentation+++++++	188
	189	/**
	190	Subscription object as returned from the Ubuntu One REST API.
	191	This class is more like a container specific for Subscription data.
	192
	193	This class implements a SubscriptionObject but additionally provides
	194	information related to the currently active Subscription.
	195	For example a Subscription can be paied or not or be in trial stage.
	196
	197	Please note that this class is only meant to present the currently
	198	active subscription. For subscription upgrades please refer to
	199	SubscriptionUpgrade.
	200	*/
156 by Harald Sitter namespace indention ... spec does not define whether namespaces are indented or not, so general rule of indention is supposedly to be applied	201	class U1_QT_EXPORT Subscription : public SubscriptionObject
	202	{
	203	Q_OBJECT
	204
	205	Q_PROPERTY(QString expires READ expires WRITE setExpires)
	206	Q_PROPERTY(bool paid READ paid WRITE setPaid)
	207	Q_PROPERTY(QString started READ started WRITE setStarted)
	208	Q_PROPERTY(bool trial READ trial WRITE setTrial)
300 by Harald Sitter documentation+++++++	209	Q_PROPERTY(bool upgrade_available READ upgradeAvailable WRITE setUpgradeAvailable)
156 by Harald Sitter namespace indention ... spec does not define whether namespaces are indented or not, so general rule of indention is supposedly to be applied	210	Q_PROPERTY(SubscriptionUpgrade *upgrade_option READ upgradeOption)
	211	Q_PROPERTY(QVariantMap upgrade_option READ QVariantMap() WRITE setUpgradeOption)
	212
	213	public:
	214	explicit Subscription(QObject *parent = 0);
	215	virtual ~Subscription();
	216
300 by Harald Sitter documentation+++++++	217	/**
	218	Returns when this subscription will expire.
	219
	220	@return expiration data as string.
	221	*/
156 by Harald Sitter namespace indention ... spec does not define whether namespaces are indented or not, so general rule of indention is supposedly to be applied	222	QString expires() const;
300 by Harald Sitter documentation+++++++	223
	224	/**
	225	Set the date when this subscription expires.
	226
	227	@param expires the string information.
	228	*/
156 by Harald Sitter namespace indention ... spec does not define whether namespaces are indented or not, so general rule of indention is supposedly to be applied	229	void setExpires(const QString &expires);
	230
300 by Harald Sitter documentation+++++++	231	/**
	232	Whether this subscription is paied.
	233
	234	@return @c true if the subscription is paied.
	235	@return @c flase if the subscription is not paied yet.
	236	*/
156 by Harald Sitter namespace indention ... spec does not define whether namespaces are indented or not, so general rule of indention is supposedly to be applied	237	bool paid() const;
300 by Harald Sitter documentation+++++++	238
	239	/**
	240	Set whether the subscription is paied.
	241
	242	@param paid true if the subscription is paied, false if not.
	243	*/
156 by Harald Sitter namespace indention ... spec does not define whether namespaces are indented or not, so general rule of indention is supposedly to be applied	244	void setPaid(const bool &paid);
	245
300 by Harald Sitter documentation+++++++	246	/**
	247	The date when the subscription started running.
	248
	249	@return date string.
	250	*/
156 by Harald Sitter namespace indention ... spec does not define whether namespaces are indented or not, so general rule of indention is supposedly to be applied	251	QString started() const;
300 by Harald Sitter documentation+++++++	252
	253	/**
	254	Set the date string when the subscription started.
	255
	256	@param started date string.
	257	*/
156 by Harald Sitter namespace indention ... spec does not define whether namespaces are indented or not, so general rule of indention is supposedly to be applied	258	void setStarted(const QString &started);
	259
300 by Harald Sitter documentation+++++++	260	/**
	261	Whether the subscription is in trial period.
	262
	263	@return @c true if it is a trial.
	264	@return @c false if it is not a trial.
	265	*/
156 by Harald Sitter namespace indention ... spec does not define whether namespaces are indented or not, so general rule of indention is supposedly to be applied	266	bool trial() const;
300 by Harald Sitter documentation+++++++	267
	268	/**
	269	Set whether the subscription is a trial.
	270
	271	@param trial true if in trial period, false if not.
	272	*/
156 by Harald Sitter namespace indention ... spec does not define whether namespaces are indented or not, so general rule of indention is supposedly to be applied	273	void setTrial(const bool &trial);
	274
300 by Harald Sitter documentation+++++++	275	/**
	276	Wether an upgrade is available.
	277	Only if this is true upgradeOption() will return anything meaningful.
	278
	279	Most of the time it will make more sense to simply call upgradeOption()
	280	and check if it returned 0.
	281
	282	@return @c true if an upgrade is available.
	283	@return @c false if no upgrades is available.
	284	*/
156 by Harald Sitter namespace indention ... spec does not define whether namespaces are indented or not, so general rule of indention is supposedly to be applied	285	bool upgradeAvailable() const;
300 by Harald Sitter documentation+++++++	286
	287	/**
	288	Sets whether an upgrade for the subscription is available.
	289
	290	@pram upgradeAvailable true if upgrade is available, false if not.
	291	*/
156 by Harald Sitter namespace indention ... spec does not define whether namespaces are indented or not, so general rule of indention is supposedly to be applied	292	void setUpgradeAvailable(const bool &upgradeAvailable);
	293
300 by Harald Sitter documentation+++++++	294	/**
	295	Returns an upgrade option for the subscription.
	296
	297	@return @c SubscriptionUpgrade if there is any.
	298	@return @c 0 if there is no upgrade available.
	299	*/
156 by Harald Sitter namespace indention ... spec does not define whether namespaces are indented or not, so general rule of indention is supposedly to be applied	300	SubscriptionUpgrade *upgradeOption() const;
300 by Harald Sitter documentation+++++++	301
	302	/**
	303	Set an upgrade option for the subscription.
	304
	305	@param a QVariantMap (QStringHash to be precise) of the upgrade
	306	option, the map will automatically be marshalled to a
	307	SubscriptionUpgrade.
	308	*/
156 by Harald Sitter namespace indention ... spec does not define whether namespaces are indented or not, so general rule of indention is supposedly to be applied	309	void setUpgradeOption(const QVariantMap &upgradeOption);
	310
	311	protected:
	312	Subscription(SubscriptionPrivate &dd, QObject *parent);
	313
	314	private:
	315	Q_DISABLE_COPY(Subscription)
	316	Q_DECLARE_PRIVATE(Subscription)
	317	};
	318
	319	} // namespace Api
56.1.23 by Harald Sitter Work around issue with qvariant and custom types by marshaling the childs of account manually	320	} // namespace UbuntuOne
	321
56.1.26 by Harald Sitter rename inlude guards	322	#endif // API_SUBSCRIPTION_H