org.osgi.service.upnp.UPnPDevice Maven / Gradle / Ivy
/*
* Copyright (c) OSGi Alliance (2002, 2013). All Rights Reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.osgi.service.upnp;
import java.util.Dictionary;
/**
* Represents a UPnP device.
*
* For each UPnP root and embedded device, an object is registered with the
* framework under the {@code UPnPDevice} interface.
*
* The relationship between a root device and its embedded devices can be
* deduced using the {@code UPnPDevice.CHILDREN_UDN} and
* {@code UPnPDevice.PARENT_UDN} service registration properties.
*
* The values of the UPnP property names are defined by the UPnP Forum.
*
* All values of the UPnP properties are obtained from the device using the
* device's default locale.
*
* If an application wants to query for a set of localized property values, it
* has to use the method {@code UPnPDevice.getDescriptions(String locale)}.
*
* @author $Id: a09c1c2f31fa7a32578cbd888b1c6981e66b3cba $
*/
public interface UPnPDevice {
/*
* Constants for the UPnP device match scale.
*/
/**
* Constant for the UPnP device match scale, indicating a generic match for
* the device. Value is 1.
*/
int MATCH_GENERIC = 1;
/**
* Constant for the UPnP device match scale, indicating a match with the
* device type. Value is 3.
*/
int MATCH_TYPE = 3;
/**
* Constant for the UPnP device match scale, indicating a match with the
* device model. Value is 7.
*/
int MATCH_MANUFACTURER_MODEL = 7;
/**
* Constant for the UPnP device match scale, indicating a match with the
* device revision. Value is 15.
*/
int MATCH_MANUFACTURER_MODEL_REVISION = 15;
/**
* Constant for the UPnP device match scale, indicating a match with the
* device revision and the serial number. Value is 31.
*/
int MATCH_MANUFACTURER_MODEL_REVISION_SERIAL = 31;
/**
* Constant for the value of the service property {@code DEVICE_CATEGORY}
* used for all UPnP devices. Value is "UPnP".
*
* @see "org.osgi.service.device.Constants.DEVICE_CATEGORY"
*/
String DEVICE_CATEGORY = "UPnP";
/**
* The {@code UPnP.export} service property is a hint that marks a device to
* be picked up and exported by the UPnP Service. Imported devices do not
* have this property set. The registered property requires no value.
*
* The UPNP_EXPORT string is "UPnP.export".
*/
String UPNP_EXPORT = "UPnP.export";
/**
* Property key for the Unique Device Name (UDN) property. It is the unique
* identifier of an instance of a {@code UPnPDevice}. The value of the
* property is a {@code String} object of the Device UDN. Value of the key
* is "UPnP.device.UDN". This property must be set.
*/
String UDN = "UPnP.device.UDN";
/**
* Property key for the Unique Device ID property. This property is an alias
* to {@code UPnPDevice.UDN}. It is merely provided for reasons of symmetry
* with the {@code UPnPService.ID} property. The value of the property is a
* {@code String} object of the Device UDN. The value of the key is
* "UPnP.device.UDN".
*/
String ID = UDN;
/**
* Property key for the UPnP Device Type property. Some standard property
* values are defined by the Universal Plug and Play Forum. The type string
* also includes a version number as defined in the UPnP specification. This
* property must be set.
*
* For standard devices defined by a UPnP Forum working committee, this must
* consist of the following components in the given order separated by
* colons:
*
* - {@code urn}
* - schemas-upnp-org
* - {@code device}
* - a device type suffix
* - an integer device version
*
* For non-standard devices specified by UPnP vendors following components
* must be specified in the given order separated by colons:
*
* - {@code urn}
* - an ICANN domain name owned by the vendor
* - {@code device}
* - a device type suffix
* - an integer device version
*
*
* To allow for backward compatibility the UPnP driver must automatically
* generate additional Device Type property entries for smaller versions
* than the current one. If for example a device announces its type as
* version 3, then properties for versions 2 and 1 must be automatically
* generated.
*
* In the case of exporting a UPnPDevice, the highest available version must
* be announced on the network.
*
* Syntax Example: {@code urn:schemas-upnp-org:device:deviceType:v}
*
* The value is "UPnP.device.type".
*/
String TYPE = "UPnP.device.type";
/**
* Mandatory property key for the device manufacturer's property. The
* property value holds a String representation of the device manufacturer's
* name. Value is "UPnP.device.manufacturer".
*/
String MANUFACTURER = "UPnP.device.manufacturer";
/**
* Mandatory property key for the device model name. The property value
* holds a {@code String} object giving more information about the device
* model. Value is "UPnP.device.modelName".
*/
String MODEL_NAME = "UPnP.device.modelName";
/**
* Mandatory property key for a short user friendly version of the device
* name. The property value holds a {@code String} object with the user
* friendly name of the device. Value is "UPnP.device.friendlyName".
*/
String FRIENDLY_NAME = "UPnP.device.friendlyName";
/**
* Optional property key for a URL to the device manufacturers Web site. The
* value of the property is a {@code String} object representing the URL.
* Value is "UPnP.device.manufacturerURL".
*/
String MANUFACTURER_URL = "UPnP.device.manufacturerURL";
/**
* Optional (but recommended) property key for a {@code String} object with
* a long description of the device for the end user. The value is
* "UPnP.device.modelDescription".
*/
String MODEL_DESCRIPTION = "UPnP.device.modelDescription";
/**
* Optional (but recommended) property key for a {@code String} class typed
* property holding the model number of the device. Value is
* "UPnP.device.modelNumber".
*/
String MODEL_NUMBER = "UPnP.device.modelNumber";
/**
* Optional property key for a {@code String} typed property holding a
* string representing the URL to the Web site for this model. Value is
* "UPnP.device.modelURL".
*/
String MODEL_URL = "UPnP.device.modelURL";
/**
* Optional (but recommended) property key for a {@code String} typed
* property holding the serial number of the device. Value is
* "UPnP.device.serialNumber".
*/
String SERIAL_NUMBER = "UPnP.device.serialNumber";
/**
* Optional property key for a {@code String} typed property holding the
* Universal Product Code (UPC) of the device. Value is "UPnP.device.UPC".
*/
String UPC = "UPnP.device.UPC";
/**
* Optional (but recommended) property key for a {@code String} typed
* property holding a string representing the URL to a device representation
* Web page. Value is "UPnP.presentationURL".
*/
String PRESENTATION_URL = "UPnP.presentationURL";
/**
* The property key that must be set for all embedded devices. It contains
* the UDN of the parent device. The property is not set for root devices.
* The value is "UPnP.device.parentUDN".
*/
String PARENT_UDN = "UPnP.device.parentUDN";
/**
* The property key that must be set for all devices containing other
* embedded devices.
*
* The value is an array of UDNs for each of the device's children (
* {@code String[]}). The array contains UDNs for the immediate descendants
* only.
*
*
* If an embedded device in turn contains embedded devices, the latter are
* not included in the array.
*
* The UPnP Specification does not encourage more than two levels of
* nesting.
*
* The property is not set if the device does not contain embedded devices.
*
* The property is of type {@code String[]}. Value is
* "UPnP.device.childrenUDN"
*/
String CHILDREN_UDN = "UPnP.device.childrenUDN";
/**
* Locates a specific service by its service id.
*
* @param serviceId The service id
* @return The requested service or null if not found.
*
* @throws IllegalStateException if the UPnP device has been removed from
* the network.
*/
UPnPService getService(String serviceId);
/**
* Lists all services provided by this device.
*
* @return Array of services or {@code null} if no services are available.
*
* @throws IllegalStateException if the UPnP device has been removed from
* the network.
*/
UPnPService[] getServices();
/**
* Lists all icons for this device in a given locale.
*
* The UPnP specification allows a device to present different icons based
* on the client's locale.
*
* @param locale A language tag as defined by RFC 1766 and maintained by ISO
* 639. Examples include "{@code de}", "{@code en}" or "
* {@code en-US}". The default locale of the device is specified by
* passing a {@code null} argument.
*
* @return Array of icons or null if no icons are available.
*
* @throws IllegalStateException if the UPnP device has been removed from
* the network.
*/
UPnPIcon[] getIcons(String locale);
/**
* Get a set of localized UPnP properties.
*
* The UPnP specification allows a device to present different device
* properties based on the client's locale. The properties used to register
* the UPnPDevice service in the OSGi registry are based on the device's
* default locale. To obtain a localized set of the properties, an
* application can use this method.
*
* Not all properties might be available in all locales. This method does
* not substitute missing properties with their default locale
* versions.
*
* This method must continue to return the properties after the UPnP device
* has been removed from the network.
*
* @param locale A language tag as defined by RFC 1766 and maintained by ISO
* 639. Examples include "{@code de}", "{@code en}" or "
* {@code en-US}". The default locale of the device is specified by
* passing a {@code null} argument.
* @return Dictionary mapping property name Strings to property value
* Strings
*
*/
Dictionary getDescriptions(String locale);
}