Public Types | Public Member Functions | Static Public Member Functions | Friends | Related Functions

# HDiscoveryType Class Reference
[Common]

A class that depicts the different discovery types used in UPnP networking. More...

`#include <HDiscoveryType>`

List of all members.

## Public Types
enum | Type { Undefined = 0, All, RootDevices, SpecificRootDevice, SpecificDevice, DeviceType, SpecificDeviceWithType, ServiceType, SpecificServiceWithType }
## Public Member Functions
| HDiscoveryType ()
| HDiscoveryType (const HUdn &udn, bool isRootDevice=false, HValidityCheckLevel checkLevel=StrictChecks)
| HDiscoveryType (const HResourceType &resourceType)
| HDiscoveryType (const HUdn &udn, const HResourceType &resourceType, HValidityCheckLevel checkLevel=StrictChecks)
| HDiscoveryType (const QString &resource, HValidityCheckLevel checkLevel=StrictChecks)
HDiscoveryType & | operator= (const HDiscoveryType &)
Type | type () const
const HUdn & | udn () const
void | setUdn (const HUdn &udn, HValidityCheckLevel checkLevel=StrictChecks)
const HResourceType & | resourceType () const
void | setResourceType (const HResourceType &resourceType)
QString | toString () const
## Static Public Member Functions
static HDiscoveryType | createDiscoveryTypeForRootDevices ()
static HDiscoveryType | createDiscoveryTypeForAllResources ()
## Friends
H_UPNP_CORE_EXPORT bool | operator== (const HDiscoveryType &, const HDiscoveryType &)
## Related Functions
(Note that these are not member functions.)
H_UPNP_CORE_EXPORT bool | operator!= (const HDiscoveryType &, const HDiscoveryType &)

## Detailed Description

The UPnP discovery is based on SSDP messages that provide information about UPnP devices and services the UPnP devices provide. When UPnP devices use SSDP messages they advertise themselves and the embedded devices and services they contain. When UPnP control points use SSDP messages they search UPnP devices or services matching some criteria. In HUPnP these different search and and advertisement types are called discovery types represented by instances of this class.

For instance, if a UPnP device advertises itself to the network the discovery type is HDiscoveryType::SpecificDevice, since the Unique Device Name that identifies the device is known. On the other hand, a control point may be interested in searching all UPnP root devices on a network in which case the discovery type would be HDiscoveryType::RootDevices. Then again, if a control point is interested in searching some specific UPnP root device it can issue a search with the discovery type set to HDiscoveryType::SpecificRootDevice and the UDN set to the desired value.

The above example implies that a discovery type may identify a UPnP device. If a discovery type identifies a UPnP device you can call udn() to retrieve the Unique Device Name. Similarly, you can call setUdn() to specify the desired UDN.

A discovery type may also have a resource type associated with it. A resource type specifies the exact type of a device or a service and whether it is standard or vendor defined. If the resource type is specified you can call resourceType() to retrieve it. Similarly, you can call setResourceType() to specify it.

Remarks:
  this class is not thread-safe.

See also:
  Type, type()

## Member Enumeration Documentation

enum Type

Specifies the discovery type.

See UPnP v1.1 Device Architecture specification chapter 1 for more information.

Enumerator:

  Undefined | The discovery type is unspecified. This value is used when the discovery type is invalid.
  All | The discovery type is `"ssdp:all"`. This is used when the discovery type specifies all UPnP devices and services. This value is used by control points to perform a device discovery for all UPnP devices and services.
  RootDevices | The discovery type is `"upnp:rootdevice"`. This is used when the discovery type specifies all UPnP root devices. This value is used by control points to perform a device discovery for all UPnP root devices.
  SpecificRootDevice | The discovery type is `"uuid:device-UUID::upnp:rootdevice"`. This is used when the discovery type specifies a particular UPnP root device. This value is used by control points and UPnP devices to search or advertise a specific UPnP root device.
  SpecificDevice | The discovery type is `"uuid:device-UUID"`. This is used when the discovery type specifies a particular UPnP device, which may be a root or an embedded device. This value is used by control points and UPnP devices to search or advertise a specific UPnP device.
  DeviceType | The discovery type is `"urn:schemas-upnp-org:device:deviceType:ver"` or `"urn:domain-name:device:deviceType:ver"`. This is used when the discovery type specifies devices of certain type. This value is used by control points to perform discovery for specific type of UPnP devices.
  SpecificDeviceWithType | The discovery type is `"uuid-device-UUID::urn:schemas-upnp-org:device:deviceType:ver"` or `"uuid-device-UUID::urn:domain-name:device:deviceType:ver"`. This is used when the discovery type specifies a particular device that is of certain type. This value is used by control points and UPnP devices to search or advertise a specific UPnP device that is of specific type.
  ServiceType | The discovery type is `"urn:schemas-upnp-org:service:serviceType:ver"` or `"urn:domain-name:service:serviceType:ver"`. This is used when the discovery type specifies services of certain type. This value is used by control points to perform discovery for specific type of UPnP services.
  SpecificServiceWithType | The discovery type is `"uuid-device-UUID::urn:schemas-upnp-org:service:serviceType:ver"` or `"uuid-device-UUID::urn:domain-name:service:serviceType:ver"`. This is used when the discovery type specifies particular service that is of certain type. This value is used by control points and UPnP devices to search or advertise a specific type of UPnP service within a specific UPnP device.

## Constructor & Destructor Documentation

HDiscoveryType | ( |  | ) |

Creates a new empty instance.

The type is set to HDiscoveryType::Undefined.

See also:
  type()

HDiscoveryType | ( | const HUdn & | udn,
|  | bool | isRootDevice = `false`,
|  | HValidityCheckLevel | checkLevel = `StrictChecks` |
| ) |  |  | `[explicit]`

Creates a new instance.

A discovery type created using a valid UDN identifies a UPnP device as the resource. The resource type is not specified.

Parameters:

  | udn | specifies the contents of the object. In case the provided argument is valid the type() of the created object is HDiscoveryType::SpecificDevice. Otherwise the type is set to HDiscoveryType::Undefined.
  | isRootDevice | indicates whether the specified UDN belongs to a root device. If the value is true the type() is set to HDiscoveryType::SpecificRootDevice. If the value is false the type is set to HDiscoveryType::SpecificDevice.
  | checkLevel | specifies the level of strictness used in validating the specified arguments. This parameter is optional.

See also:
  type()

HDiscoveryType | ( | const HResourceType & | resourceType | ) | `[explicit]`

Creates a new instance.

A discovery type created using a valid resource type specifies the device or service type. No UDN is provided, which means the discovery type does not specify a UPnP device.

Parameters:

  | resourceType | specifies the contents of the object. In case the provided argument is valid the type() of the created object is either HDiscoveryType::DeviceType or HDiscoveryType::ServiceType depending of the argument. In case the provided argument is invalid the type is set to HDiscoveryType::Undefined.

See also:
  type(), setUdn()

HDiscoveryType | ( | const HUdn & | udn,
|  | const HResourceType & | resourceType,
|  | HValidityCheckLevel | checkLevel = `StrictChecks` |
| ) |  |  |

Creates a new instance.

A discovery type created with a valid UDN and a valid resource type identifies a specific UPnP device or UPnP service that is of certain type. Both of the provided arguments have to be valid in order to create a valid type. Otherwise the type() is set to HDiscoveryType::Undefined.

Parameters:

  | udn | specifies the Unique Device Name.
  | resourceType | specifies the resource type.
  | checkLevel | specifies the level of strictness used in validating the specified arguments. This parameter is optional.

See also:
  type(), udn(), resourceType()

HDiscoveryType | ( | const QString & | resource,
|  | HValidityCheckLevel | checkLevel = `StrictChecks` |
| ) |  |  | `[explicit]`

Creates a new instance.

Parameters:

  | resource | specifies the contents of the object. In case the the provided argument cannot be parsed to a valid resource identifier the type() is set to HDiscoveryType::Undefined.
  | checkLevel | specifies the level of strictness used in validating the specified arguments. This parameter is optional.

Valid string formats are:

- `ssdp:all` to specify "any UPnP device and service",
- `[uuid:device-UUID]` to spesify a specific UPnP device,
- `[uuid:device-UUID::]upnp:rootdevice` to specify a specific UPnP root device,
- `[uuid:device-UUID::]urn:schemas-upnp-org:device:deviceType:ver` to specify a specific UPnP device, which type is standard defined.
- `[uuid:device-UUID::]urn:domain-name:device:deviceType:ver` to specify a specific UPnP device that, which type is vendor defined.
- `[uuid:device-UUID::]urn:schemas-upnp-org:service:serviceType:ver` to specify a specific UPnP service, which type is standard defined.
- `[uuid:device-UUID::]urn:domain-name:service:serviceType:ver` to specify a specific UPnP device, which type is vendor defined.

The content inside square brackets (uuid:device-UUID) is optional and does not have to be provided.

## Member Function Documentation

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

Assigns the contents of the other object to this.

Returns:
  a reference to this object.

HDiscoveryType::Type type | ( |  | ) | const

Returns the type of the object.

Returns:
  the type of the object. If the resource is not specified the type returned is HDiscoveryType::Undefined.

const HUdn & udn | ( |  | ) | const

Returns the Unique Device Name of the resource.

Returns:
  the Unique Device Name of the resource if it is set. Note, the UDN is never set when the type() is either HDiscoveryType::AllDevices or HDiscoveryType::Undefined.

See also:
  setUdn()

void setUdn | ( | const HUdn & | udn,
|  | HValidityCheckLevel | checkLevel = `StrictChecks` |
| ) |  |  |

Sets the UDN of the object.

Note:
  Changing the UDN may change the resourceType() and the type(). For instance, if the object did not have UDN set before, changing the UDN will change the type() of the object.

Parameters:

  | udn | specifies the new UDN. The specified UDN has to be valid in terms of the level of validity checks being run. Otherwise the UDN will not be set.
  | checkLevel | specifies the level of strictness used in validating the specified UDN. This parameter is optional, but by default the UDN is verified strictly.

See also:
  udn()

const HResourceType & resourceType | ( |  | ) | const

Returns the resource type associated with this identifier, if any.

Returns:
  the resource type associated with this identifier if it is set. Note, the returned object is valid only when the type() is either standard or vendor specified device or service type.

See also:
  setResourceType()

void setResourceType | ( | const HResourceType & | resourceType | ) |

Sets the resource type of the object.

Parameters:

  | resourceType | specifies the new resource type.

See also:
  resourceType()

QString toString | ( |  | ) | const

Returns a string representation of the object.

Returns:
  a string representation of the object or an empty string, if the object does not specify a valid resource.

See also:
  Type

HDiscoveryType createDiscoveryTypeForRootDevices | ( |  | ) | `[static]`

Creates an object, which type is set to HDiscoveryType::RootDevices.

Returns:
  an object, which type is set to HDiscoveryType::RootDevices.

Remarks:
  this is only a helper method. A logically equivalent object can be constructed with the string `"upnp:rootdevice"`.

HDiscoveryType createDiscoveryTypeForAllResources | ( |  | ) | `[static]`

Creates an object, which type is set to HDiscoveryType::All.

Returns:
  an object, which type is set to HDiscoveryType::All.

Remarks:
  this is only a helper method. A logically equivalent object can be constructed with the string `"ssdp:all"`.

## Friends And Related Function Documentation

H_UPNP_CORE_EXPORT bool operator== | ( | const HDiscoveryType & | ,
|  | const HDiscoveryType & |  |
| ) |  |  | `[friend]`

Compares the two objects for equality.

Returns:
  true in case the objects are logically equivalent.

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

Compares the two objects for inequality.

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