Public Member Functions | Related Functions

# HProductTokens Class Reference
[Common]

This class is used to parse the product tokens defined by HTTP/1.1. More...

`#include <HProductTokens>`

List of all members.

## Public Member Functions
| HProductTokens ()
| HProductTokens (const QString &arg)
| HProductTokens (const HProductTokens &)
| ~HProductTokens ()
HProductTokens & | operator= (const HProductTokens &)
bool | isValid () const
bool | isEmpty () const
HProductToken | osToken () const
HProductToken | upnpToken () const
HProductToken | productToken () const
QVector< HProductToken > | extraTokens () const
bool | hasExtraTokens () const
QVector< HProductToken > | tokens () const
QString | toString () const
## Related Functions
(Note that these are not member functions.)
H_UPNP_CORE_EXPORT bool | operator== (const HProductTokens &, const HProductTokens &)
H_UPNP_CORE_EXPORT bool | operator!= (const HProductTokens &, const HProductTokens &)

## Detailed Description

According to the HTTP/1.1, Product tokens are used to allow communicating applications to identify themselves by software name and version. In UDA, the product tokens consist of three tokens, in which The first product token identifes the operating system in the form OS name/OS version, the second token represents the UPnP version and MUST be UPnP/1.1, and the third token identifes the product using the form product name/product version. For example, "SERVER: unix/5.1 UPnP/1.1 MyProduct/1.0".

Unfortunately, product tokens found in UPnP products are rarely conforming to the HTTP/1.1 and UDA specifications. Many products handle "product tokens" as a string that contains "key/value" pairs laid out and delimited arbitrarily. Because of this, `HProductTokens` has to accept input that is not strictly standard-conformant. However, at absolute minimum UPnP devices have to provide the UPnP version token. Because of that, `HProductTokens` instance is considered valid if the instance contains a valid UPnP version token. All other tokens are considered optional and they may not be present in a valid instance. In practice this means that if isValid() returns true the instance contains a valid UPnP version token, which can be retrieved using upnpToken(). In that case the tokens() returns a list at least of size one. In addition, the instance may contain other data that could not be parsed following the HTTP/1.1 and UDA specifications. This data cannot be retrieved using any of the functions that return HProductToken instances, but you can retrieve the full unparsed product tokens string using toString().

Remarks:
  this class is not thread-safe.

## Constructor & Destructor Documentation

HProductTokens | ( |  | ) |

Constructs a new invalid and empty instance.

See also:
  isValid(), isEmpty()

HProductTokens | ( | const QString & | arg | ) | `[explicit]`

Creates a new instance based on the provided argument.

Parameters:

  | arg | specifies the product tokens. In case the specified argument does not contain a valid UPnP version token the created object will be invalid. However, the object will not be empty and the provided string is returned when toString() is called.

See also:
  isValid(), isEmpty(), toString(), upnpToken()

HProductTokens | ( | const HProductTokens & | other | ) |

Copy constructor.

Creates a copy of the other object.

~HProductTokens | ( |  | ) |

Destroys the instance.

## Member Function Documentation

HProductTokens & operator= | ( | const HProductTokens & | other | ) |

Assigns the contents of the other to this.

Returns:
  a reference to this object.

bool isValid | ( |  | ) | const

Indicates whether the object contains at least the UPnP version token defined in the UDA.

Returns:
  true in case the object contains at least the UPnP version token defined in the UDA.

Remarks:
  an invalid object is not necessarily empty; an object may contain data that could not be parsed into HProductToken objects. In this case you can call toString() to retrieve the full product tokens string.

See also:
  isEmpty()

bool isEmpty | ( |  | ) | const

Indicates whether the object contains any information at all.

Returns:
  true in case the object does not contain any information.

Remarks:
  an empty object is also invalid.

See also:
  isValid()

HProductToken osToken | ( |  | ) | const

Returns the product token that defines information of an operating system.

Returns:
  the product token that defines information of an operating system.

Remarks:
  this is not necessarily defined in a non-empty object.

See also:
  isValid()

HProductToken upnpToken | ( |  | ) | const

Returns the product token that defines UPnP version.

Returns:
  the product token that defines UPnP version. This token always follows the format "UPnP"/majorVersion.minorVersion, where majorVersion and minorVersion are positive integers. Furthermore, currently the majorVersion is always 1 and the minorVersion is either 0 or 1.

Remarks:
  this is always defined in a valid object.

See also:
  isValid()

HProductToken productToken | ( |  | ) | const

Returns the product token that defines the actual product in the form product name/product version.

Returns:
  the product token that defines the actual product in the form product name/product version.

Remarks:
  this is not necessarily defined in a non-empty object.

See also:
  isValid()

QVector< HProductToken > extraTokens | ( |  | ) | const

Returns the extra tokens.

A valid `HProductTokens` object contains at least the upnpToken(). A strictly valid `HProductTokens` object contains at least the osToken(), upnpToken() and producToken(). However, a `HProductTokens` instance may contain more than these three tokens, which are called extra tokens in this context.

Returns:
  the extra tokens, if such are defined and the object is valid.

See also:
  hasExtraTokens(), isValid(), tokens()

bool hasExtraTokens | ( |  | ) | const

Indicates if the object contains extra tokens in addition to osToken(), upnpToken() and producToken().

Returns:
  true in case the object contains extra tokens in addition to osToken(), upnpToken() and producToken().

QVector< HProductToken > tokens | ( |  | ) | const

Returns all product tokens the instance contains.

A valid `HProductTokens` object will return a vector that contains at least one entry, the upnpToken(). A strictly valid `HProductTokens` object will return a vector that contains at least three entries, the osToken(), upnpToken() and producToken(). If the object contains extra tokens the extra tokens are appended to the returned vector.

Returns:
  all product tokens in a vector. An invalid object returns a vector with no elements. However, even in this case the object may not be empty.

See also:
  isValid(), isEmpty(), extraTokens(), toString()

QString toString | ( |  | ) | const

Returns a string representation of the object.

Returns:
  a string representation of the object.

Remarks:
  this method may return a non-empty string even in case isValid() returns false. In this case the instance was created with a string that could not be tokenized according to the UDA and HTTP 1.1 specifications.

See also:
  isEmpty(), isValid()

## Friends And Related Function Documentation

H_UPNP_CORE_EXPORT bool operator== | ( | const HProductTokens & | ,
|  | const HProductTokens & |  |
| ) |  |  | `[related]`

Compares the two objects for equality.

Returns:
  true in case the objects are logically equivalent.

H_UPNP_CORE_EXPORT bool operator!= | ( | const HProductTokens & | ,
|  | const HProductTokens & |  |
| ) |  |  | `[related]`

Compares the two objects for inequality.

Returns:
  true in case the objects are not logically equivalent.