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)
HDiscoveryTypeoperator= (const HDiscoveryType &)
Type type () const
const HUdnudn () const
void setUdn (const HUdn &udn, HValidityCheckLevel checkLevel=StrictChecks)
const HResourceTyperesourceType () 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

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:
udnspecifies 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.
isRootDeviceindicates 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.
checkLevelspecifies 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:
resourceTypespecifies the contents of the object. In case the provided argument is valid the type() of the created object is either

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:
udnspecifies the Unique Device Name.
resourceTypespecifies the resource type.
checkLevelspecifies 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:
resourcespecifies 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.
checkLevelspecifies 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:
udnspecifies 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.
checkLevelspecifies 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:
resourceTypespecifies 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.