bundles/org.eclipse.osgi.services/src/org/osgi/service/upnp/UPnPDevice.java - equinox/rt.equinox.framework - Git at Google

 /*
  * Copyright (c) OSGi Alliance (2002, 2015). 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$
  */
 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<String, String> getDescriptions(String locale);
 }
	/*
	* Copyright (c) OSGi Alliance (2002, 2015). 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$
	*/
	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<String, String> getDescriptions(String locale);
	}