UPnPDevice.java

/*
 * 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.
 * <p>
 * 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.
 * <p>
 * The values of the UPnP property names are defined by the UPnP Forum.
 * <p>
 * All values of the UPnP properties are obtained from the device using the
 * device's default locale.
 * <p>
 * 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.
	 * <p>
	 * 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.
	 * <p>
	 * For standard devices defined by a UPnP Forum working committee, this must
	 * consist of the following components in the given order separated by
	 * colons:
	 * <ul>
	 * <li>{@code urn}</li>
	 * <li>schemas-upnp-org</li>
	 * <li>{@code device}</li>
	 * <li>a device type suffix</li>
	 * <li>an integer device version</li>
	 * </ul>
	 * For non-standard devices specified by UPnP vendors following components
	 * must be specified in the given order separated by colons:
	 * <ul>
	 * <li>{@code urn}</li>
	 * <li>an ICANN domain name owned by the vendor</li>
	 * <li>{@code device}</li>
	 * <li>a device type suffix</li>
	 * <li>an integer device version</li>
	 * </ul>
	 * <p>
	 * 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.
	 * <p>
	 * In the case of exporting a UPnPDevice, the highest available version must
	 * be announced on the network.
	 * <p>
	 * Syntax Example: {@code urn:schemas-upnp-org:device:deviceType:v}
	 * <p>
	 * 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.
	 * <p>
	 * 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.
	 * </p>
	 * <p>
	 * If an embedded device in turn contains embedded devices, the latter are
	 * not included in the array.
	 * </p>
	 * The UPnP Specification does not encourage more than two levels of
	 * nesting.
	 * <p>
	 * The property is not set if the device does not contain embedded devices.
	 * <p>
	 * 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.
	 * <p>
	 * Not all properties might be available in all locales. This method does
	 * <b>not </b> substitute missing properties with their default locale
	 * versions.
	 * <p>
	 * 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);
}