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 HPRODUCT_TOKENS_H
23
#define HPRODUCT_TOKENS_H
25
#include <HUpnpCore/HUpnp>
27
#include <QtCore/QString>
28
#include <QtCore/QSharedDataPointer>
40
* \brief This class represents a <em>product token</em> as defined in the RFC 2616,
43
* \headerfile hproduct_tokens.h HProductToken
45
* \remarks This class is not thread-safe.
47
* \ingroup hupnp_common
49
class H_UPNP_CORE_EXPORT HProductToken
51
friend H_UPNP_CORE_EXPORT bool operator==(
52
const HProductToken& obj1, const HProductToken& obj2);
57
QString m_productVersion;
62
* \brief Creates a new, empty instance. An object created with the default
63
* constructor is invalid.
70
* Creates a new object based on the provided token data. If the token data
71
* is invalid, the object will be invalid as well.
73
* \param token specifies the token part, which is supposed to identify
74
* a product. If this is empty, the created object will be invalid.
76
* \param productVersion specifies the version part. If this is empty,
77
* the created object will be invalid.
81
HProductToken(const QString& token, const QString& productVersion);
84
* \brief Destroys the instance.
89
* \brief Indicates if the object is valid, i.e both the token and the product
90
* version are defined.
92
* \param checkLevel specifies whether the contents of the object are checked
93
* for strict validity. Only an object that is strictly valid
94
* contains information as defined in the UDA. In other words,
95
* a strictly valid product token takes the form
96
* <c>token/majorVersion.minorVersion</c>.
98
* \return true in case both the \e token and <em>product version</em>
99
* are appropriately specified.
101
* \sa token(), productVersion()
103
bool isValid(HValidityCheckLevel checkLevel) const;
106
* \brief Indicates if the object is valid, i.e both the token and the product
107
* version are defined.
109
* \param checkLevel specifies whether the contents of the object are checked
110
* for strict validity. Only an object that is strictly valid
111
* contains information as defined in the UDA. In other words,
112
* a strictly valid product token takes the form
113
* <c>UPnP/majorVersion.minorVersion</c>, where currently major version is
114
* always 1 and minor version is either 0 or 1.
116
* \return true in case both the \e token and <em>product version</em>
117
* are appropriately specified.
119
* \sa token(), productVersion()
121
bool isValidUpnpToken() const;
124
* \brief Returns the \e token part.
126
* \return The \e token part in case the object is valid.
127
* The token part is used to identify the product and an example
128
* of a token is for instance \c "Apache". An empty string is returned in case
129
* the object is invalid.
133
inline QString token() const { return m_token; }
136
* \brief Returns the \e version part.
138
* \return The \e version part in case the object is valid. An example of a
139
* version part is \c "1.0". An empty string is returned in case
140
* the object is invalid.
144
inline QString version() const { return m_productVersion; }
147
* \brief Returns a string representation of the object.
149
* The format of the returned string is \c "token"/"version".
151
* \return a string representation of the object.
153
QString toString() const;
156
* Attempts to parse the \e version part of a product token to a major and
157
* minor component and returns the minor component if the function succeeded.
159
* For the function to succeed the specified product token has to contain
160
* a version string that follows the format "major.minor". The function ignores
161
* any further "version information" after the "minor" component separated
162
* by a dot. The "minor" component has to be convertible to an integer.
164
* \return The minor version component of the specified product token or -1
165
* if the specified token does not contain a minor version component that
166
* can be represented as an integer.
168
qint32 minorVersion();
169
// TODO for v2, should be const
172
* Attempts to parse the \e version part of a product token to a major and
173
* minor component and returns the major component if the function succeeded.
175
* For the function to succeed the specified product token has to contain
176
* a version string that either
177
* - can be directly converted to an integer or
178
* - contains information following the format "major.minor", where
179
* the major component can be converted to an integer. Any data following
180
* the "minor" component and separated from it by a dot is ignored.
182
* \return The major version component of the specified product token or -1
183
* if the specified token does not contain a major version component that
184
* can be represented as an integer.
186
qint32 majorVersion();
187
// TODO for v2, should be const
191
* Compares the two objects for equality.
193
* \return \e true in case the object are logically equivalent.
195
* \relates HProductToken
197
H_UPNP_CORE_EXPORT bool operator==(const HProductToken&, const HProductToken&);
200
* Compares the two objects for inequality.
202
* \return \e true in case the objects are not logically equivalent.
204
* \relates HProductToken
206
H_UPNP_CORE_EXPORT bool operator!=(const HProductToken&, const HProductToken&);
208
class HProductTokensPrivate;
211
* \brief This class is used to parse the <em>product tokens</em> defined by HTTP/1.1.
213
* According to the HTTP/1.1, <em>Product tokens are used to allow communicating applications
214
* to identify themselves by software name and version</em>. In UDA,
215
* the <em>product tokens</em> consist of three tokens,
216
* in which <em>The first product token identifes the operating system in
217
* the form OS name/OS version, the second token represents the UPnP version and
218
* MUST be UPnP/1.1, and the third token identifes the product using the form
219
* product name/product version</em>. For example, "SERVER: unix/5.1 UPnP/1.1 MyProduct/1.0".
221
* Unfortunately, product tokens found in UPnP products are rarely conforming to
222
* the HTTP/1.1 and UDA specifications. Many products handle "product tokens" as a string that
223
* contains "key/value" pairs laid out and delimited arbitrarily. Because of this,
224
* \c %HProductTokens has to accept input that is not strictly standard-conformant.
225
* However, at absolute minimum UPnP devices have to provide the UPnP version token.
226
* Because of that, \c %HProductTokens instance is considered valid if the
227
* instance contains a valid UPnP version token. All other tokens are considered
228
* optional and they may not be present in a valid instance. In practice this means that
229
* if isValid() returns true the instance contains a valid UPnP version
230
* token, which can be retrieved using upnpToken(). In that case the tokens()
231
* returns a list at least of size one. In addition, the instance may contain other
232
* data that could not be parsed following the HTTP/1.1 and UDA specifications. This
233
* data cannot be retrieved using any of the functions that return HProductToken
234
* instances, but you can retrieve the full unparsed product tokens string using
237
* \headerfile hproduct_tokens.h HProductTokens
239
* \remarks This class is not thread-safe.
241
* \ingroup hupnp_common
243
class H_UPNP_CORE_EXPORT HProductTokens
247
QSharedDataPointer<HProductTokensPrivate> h_ptr;
252
* Constructs a new invalid and empty instance.
254
* \sa isValid(), isEmpty()
259
* Creates a new instance based on the provided argument.
261
* \param arg specifies the product tokens. In case the specified argument
262
* does not contain a valid UPnP version token the created
263
* object will be invalid. However, the object will not be empty and the
264
* provided string is returned when toString() is called.
266
* \sa isValid(), isEmpty(), toString(), upnpToken()
268
explicit HProductTokens(const QString& arg);
271
* \brief Copy constructor.
273
* Creates a copy of the other object.
275
HProductTokens(const HProductTokens&);
278
* \brief Destroys the instance.
283
* Assigns the contents of the other to this.
285
* \return a reference to this object.
287
HProductTokens& operator=(const HProductTokens&);
290
* \brief Indicates whether the object contains at least the UPnP
291
* version token defined in the UDA.
293
* \return \e true in case the object contains at least the UPnP version
294
* token defined in the UDA.
296
* \remarks an invalid object is not necessarily empty; an object may contain
297
* data that could not be parsed into HProductToken objects. In this case
298
* you can call toString() to retrieve the full product tokens string.
302
bool isValid() const;
305
* \brief Indicates whether the object contains any information at all.
307
* \return true in case the object does not contain any information.
309
* \remarks an empty object is also invalid.
313
bool isEmpty() const;
316
* \brief Returns the product token that defines information of an operating system.
318
* \return The product token that defines information of an operating system.
320
* \remarks This is not necessarily defined in a non-empty object.
324
HProductToken osToken() const;
327
* \brief Returns the product token that defines UPnP version.
329
* \return The product token that defines UPnP version. This token always
330
* follows the format "UPnP"/majorVersion.minorVersion, where \e majorVersion
331
* and \e minorVersion are positive integers. Furthermore, currently
332
* the \e majorVersion is \b always 1 and the \e minorVersion is either 0
335
* \remarks This is always defined in a valid object.
339
HProductToken upnpToken() const;
342
* \brief Returns the product token that defines the actual product in the form
343
* product name/product version.
345
* \return The product token that defines the actual product in the form
346
* product name/product version.
348
* \remarks This is not necessarily defined in a non-empty object.
352
HProductToken productToken() const;
355
* \brief Returns the extra tokens.
357
* A valid \c %HProductTokens object contains at least the
358
* upnpToken(). A strictly valid \c %HProductTokens object contains at least
359
* the osToken(), upnpToken() and producToken(). However, a \c %HProductTokens
360
* instance may contain more than these three tokens, which are called extra
361
* tokens in this context.
363
* \return The extra tokens, if such are defined and the object is valid.
365
* \sa hasExtraTokens(), isValid(), tokens()
367
QVector<HProductToken> extraTokens() const;
370
* \brief Indicates if the object contains extra tokens in addition to
371
* osToken(), upnpToken() and producToken().
373
* \return true in case the object contains extra tokens in addition to
374
* osToken(), upnpToken() and producToken().
376
bool hasExtraTokens() const;
379
* \brief Returns all product tokens the instance contains.
381
* A valid \c %HProductTokens object will return a vector that contains
382
* at least one entry, the upnpToken(). A strictly valid \c %HProductTokens
383
* object will return a vector that contains at least three entries,
384
* the osToken(), upnpToken() and producToken(). If the object contains
385
* extra tokens the extra tokens are appended to the returned vector.
387
* \return all product tokens in a vector. An invalid object returns a
388
* vector with no elements. However, even in this case the object may not be empty.
390
* \sa isValid(), isEmpty(), extraTokens(), toString()
392
QVector<HProductToken> tokens() const;
395
* \brief Returns a string representation of the object.
397
* \return a string representation of the object.
399
* \remarks This method may return a non-empty string even in case
400
* isValid() returns false. In this case the instance was created with
401
* a string that could not be tokenized according to the UDA and HTTP 1.1
404
* \sa isEmpty(), isValid()
406
QString toString() const;
410
* Compares the two objects for equality.
412
* \return \e true in case the objects are logically equivalent.
414
* \relates HProductTokens
416
H_UPNP_CORE_EXPORT bool operator==(
417
const HProductTokens&, const HProductTokens&);
420
* Compares the two objects for inequality.
422
* \return \e true in case the objects are not logically equivalent.
424
* \relates HProductTokens
426
inline bool operator!=(const HProductTokens& obj1, const HProductTokens& obj2)
428
return !(obj1 == obj2);
434
#endif /* HPRODUCT_TOKENS_H */