/*
 * $Header: /cvshome/build/org.osgi.service.upnp/src/org/osgi/service/upnp/UPnPDevice.java,v 1.9 2006/06/16 16:31:46 hargrave Exp $
 *
 * Copyright (c) OSGi Alliance (2002, 2006). 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</code> interface.
 * <p>
 * The relationship between a root device and its embedded devices can be
 * deduced using the <code>UPnPDevice.CHILDREN_UDN</code> and
 * <code>UPnPDevice.PARENT_UDN</code> 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)</code>.
 *  
 */
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</code>
	 * used for all UPnP devices. Value is "UPnP".
	 * 
	 * @see "<code>org.osgi.service.device.Constants.DEVICE_CATEGORY</code>"
	 */
	String	DEVICE_CATEGORY								= "UPnP";
	/**
	 * The <code>UPnP.export</code> 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</code>. The value of the
	 * property is a <code>String</code> 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</code>. It is merely provided for reasons of
	 * symmetry with the <code>UPnPService.ID</code> property. The value of the
	 * property is a <code>String</code> 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</code></li>
	 * <li>schemas-upnp-org</li>
	 * <li><code>device</code></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</code></li>
	 * <li>an ICANN domain name owned by the vendor</li>
	 * <li><code>device</code></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</code>
	 * <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</code> 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</code> 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</code> object representing the URL.
	 * Value is "UPnP.device.manufacturerURL".
	 */
	String	MANUFACTURER_URL							= "UPnP.device.manufacturerURL";
	/**
	 * Optional (but recommended) property key for a <code>String</code> 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</code> 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</code> 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</code> 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</code> 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</code> 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[]</code>). 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[]</code>. 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.
	 */
	UPnPService getService(String serviceId);

	/**
	 * Lists all services provided by this device.
	 * 
	 * @return Array of services or <code>null</code> if no services are
	 *         available.
	 */
	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>", "<code>en</code>" or "
	 *        <code>en-US</code>". The default locale of the device is specified
	 *        by passing a <code>null</code> argument.
	 * 
	 * @return Array of icons or null if no icons are available.
	 */
	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>
	 * 
	 * @param locale A language tag as defined by RFC 1766 and maintained by ISO
	 *        639. Examples include "<code>de</code>", "<code>en</code>" or "
	 *        <code>en-US</code>". The default locale of the device is specified
	 *        by passing a <code>null</code> argument.
	 * @return Dictionary mapping property name Strings to property value
	 *         Strings
	 *  
	 */
	Dictionary getDescriptions(String locale);
}