001 /*
002 * Copyright (c) OSGi Alliance (2002, 2008). All Rights Reserved.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package org.osgi.service.upnp;
017
018 import java.util.Dictionary;
019
020 /**
021 * Represents a UPnP device.
022 *
023 * For each UPnP root and embedded device, an object is registered with the
024 * framework under the <code>UPnPDevice</code> interface.
025 * <p>
026 * The relationship between a root device and its embedded devices can be
027 * deduced using the <code>UPnPDevice.CHILDREN_UDN</code> and
028 * <code>UPnPDevice.PARENT_UDN</code> service registration properties.
029 * <p>
030 * The values of the UPnP property names are defined by the UPnP Forum.
031 * <p>
032 * All values of the UPnP properties are obtained from the device using the
033 * device's default locale.
034 * <p>
035 * If an application wants to query for a set of localized property values, it
036 * has to use the method <code>UPnPDevice.getDescriptions(String locale)</code>.
037 *
038 * @version $Revision: 5673 $
039 */
040 public interface UPnPDevice {
041 /*
042 * Constants for the UPnP device match scale.
043 */
044 /**
045 * Constant for the UPnP device match scale, indicating a generic match for
046 * the device. Value is 1.
047 */
048 int MATCH_GENERIC = 1;
049 /**
050 * Constant for the UPnP device match scale, indicating a match with the
051 * device type. Value is 3.
052 */
053 int MATCH_TYPE = 3;
054 /**
055 * Constant for the UPnP device match scale, indicating a match with the
056 * device model. Value is 7.
057 */
058 int MATCH_MANUFACTURER_MODEL = 7;
059 /**
060 * Constant for the UPnP device match scale, indicating a match with the
061 * device revision. Value is 15.
062 */
063 int MATCH_MANUFACTURER_MODEL_REVISION = 15;
064 /**
065 * Constant for the UPnP device match scale, indicating a match with the
066 * device revision and the serial number. Value is 31.
067 */
068 int MATCH_MANUFACTURER_MODEL_REVISION_SERIAL = 31;
069 /**
070 * Constant for the value of the service property <code>DEVICE_CATEGORY</code>
071 * used for all UPnP devices. Value is "UPnP".
072 *
073 * @see "<code>org.osgi.service.device.Constants.DEVICE_CATEGORY</code>"
074 */
075 String DEVICE_CATEGORY = "UPnP";
076 /**
077 * The <code>UPnP.export</code> service property is a hint that marks a device
078 * to be picked up and exported by the UPnP Service. Imported devices do not
079 * have this property set. The registered property requires no value.
080 * <p>
081 * The UPNP_EXPORT string is "UPnP.export".
082 */
083 String UPNP_EXPORT = "UPnP.export";
084 /**
085 * Property key for the Unique Device Name (UDN) property. It is the unique
086 * identifier of an instance of a <code>UPnPDevice</code>. The value of the
087 * property is a <code>String</code> object of the Device UDN. Value of the
088 * key is "UPnP.device.UDN". This property must be set.
089 */
090 String UDN = "UPnP.device.UDN";
091 /**
092 * Property key for the Unique Device ID property. This property is an alias
093 * to <code>UPnPDevice.UDN</code>. It is merely provided for reasons of
094 * symmetry with the <code>UPnPService.ID</code> property. The value of the
095 * property is a <code>String</code> object of the Device UDN. The value of
096 * the key is "UPnP.device.UDN".
097 */
098 String ID = UDN;
099 /**
100 * Property key for the UPnP Device Type property. Some standard property
101 * values are defined by the Universal Plug and Play Forum. The type string
102 * also includes a version number as defined in the UPnP specification. This
103 * property must be set.
104 * <p>
105 * For standard devices defined by a UPnP Forum working committee, this must
106 * consist of the following components in the given order separated by
107 * colons:
108 * <ul>
109 * <li><code>urn</code></li>
110 * <li>schemas-upnp-org</li>
111 * <li><code>device</code></li>
112 * <li>a device type suffix</li>
113 * <li>an integer device version</li>
114 * </ul>
115 * For non-standard devices specified by UPnP vendors following components
116 * must be specified in the given order separated by colons:
117 * <ul>
118 * <li><code>urn</code></li>
119 * <li>an ICANN domain name owned by the vendor</li>
120 * <li><code>device</code></li>
121 * <li>a device type suffix</li>
122 * <li>an integer device version</li>
123 * </ul>
124 * <p>
125 * To allow for backward compatibility the UPnP driver must automatically
126 * generate additional Device Type property entries for smaller versions
127 * than the current one. If for example a device announces its type as
128 * version 3, then properties for versions 2 and 1 must be automatically
129 * generated.
130 * <p>
131 * In the case of exporting a UPnPDevice, the highest available version must
132 * be announced on the network.
133 * <p>
134 * Syntax Example: <code>urn:schemas-upnp-org:device:deviceType:v</code>
135 * <p>
136 * The value is "UPnP.device.type".
137 */
138 String TYPE = "UPnP.device.type";
139 /**
140 * Mandatory property key for the device manufacturer's property. The
141 * property value holds a String representation of the device manufacturer's
142 * name. Value is "UPnP.device.manufacturer".
143 */
144 String MANUFACTURER = "UPnP.device.manufacturer";
145 /**
146 * Mandatory property key for the device model name. The property value
147 * holds a <code>String</code> object giving more information about the device
148 * model. Value is "UPnP.device.modelName".
149 */
150 String MODEL_NAME = "UPnP.device.modelName";
151 /**
152 * Mandatory property key for a short user friendly version of the device
153 * name. The property value holds a <code>String</code> object with the user
154 * friendly name of the device. Value is "UPnP.device.friendlyName".
155 */
156 String FRIENDLY_NAME = "UPnP.device.friendlyName";
157 /**
158 * Optional property key for a URL to the device manufacturers Web site. The
159 * value of the property is a <code>String</code> object representing the URL.
160 * Value is "UPnP.device.manufacturerURL".
161 */
162 String MANUFACTURER_URL = "UPnP.device.manufacturerURL";
163 /**
164 * Optional (but recommended) property key for a <code>String</code> object
165 * with a long description of the device for the end user. The value is
166 * "UPnP.device.modelDescription".
167 */
168 String MODEL_DESCRIPTION = "UPnP.device.modelDescription";
169 /**
170 * Optional (but recommended) property key for a <code>String</code> class
171 * typed property holding the model number of the device. Value is
172 * "UPnP.device.modelNumber".
173 */
174 String MODEL_NUMBER = "UPnP.device.modelNumber";
175 /**
176 * Optional property key for a <code>String</code> typed property holding a
177 * string representing the URL to the Web site for this model. Value is
178 * "UPnP.device.modelURL".
179 */
180 String MODEL_URL = "UPnP.device.modelURL";
181 /**
182 * Optional (but recommended) property key for a <code>String</code> typed
183 * property holding the serial number of the device. Value is
184 * "UPnP.device.serialNumber".
185 */
186 String SERIAL_NUMBER = "UPnP.device.serialNumber";
187 /**
188 * Optional property key for a <code>String</code> typed property holding the
189 * Universal Product Code (UPC) of the device. Value is "UPnP.device.UPC".
190 */
191 String UPC = "UPnP.device.UPC";
192 /**
193 * Optional (but recommended) property key for a <code>String</code> typed
194 * property holding a string representing the URL to a device representation
195 * Web page. Value is "UPnP.presentationURL".
196 */
197 String PRESENTATION_URL = "UPnP.presentationURL";
198 /**
199 * The property key that must be set for all embedded devices. It contains
200 * the UDN of the parent device. The property is not set for root devices.
201 * The value is "UPnP.device.parentUDN".
202 */
203 String PARENT_UDN = "UPnP.device.parentUDN";
204 /**
205 * The property key that must be set for all devices containing other
206 * embedded devices.
207 * <p>
208 * The value is an array of UDNs for each of the device's children (
209 * <code>String[]</code>). The array contains UDNs for the immediate
210 * descendants only.
211 * </p>
212 * <p>
213 * If an embedded device in turn contains embedded devices, the latter are
214 * not included in the array.
215 * </p>
216 * The UPnP Specification does not encourage more than two levels of
217 * nesting.
218 * <p>
219 * The property is not set if the device does not contain embedded devices.
220 * <p>
221 * The property is of type <code>String[]</code>. Value is
222 * "UPnP.device.childrenUDN"
223 */
224 String CHILDREN_UDN = "UPnP.device.childrenUDN";
225
226 /**
227 * Locates a specific service by its service id.
228 *
229 * @param serviceId The service id
230 * @return The requested service or null if not found.
231 */
232 UPnPService getService(String serviceId);
233
234 /**
235 * Lists all services provided by this device.
236 *
237 * @return Array of services or <code>null</code> if no services are
238 * available.
239 */
240 UPnPService[] getServices();
241
242 /**
243 * Lists all icons for this device in a given locale.
244 *
245 * The UPnP specification allows a device to present different icons based
246 * on the client's locale.
247 *
248 * @param locale A language tag as defined by RFC 1766 and maintained by ISO
249 * 639. Examples include "<code>de</code>", "<code>en</code>" or "
250 * <code>en-US</code>". The default locale of the device is specified
251 * by passing a <code>null</code> argument.
252 *
253 * @return Array of icons or null if no icons are available.
254 */
255 UPnPIcon[] getIcons(String locale);
256
257 /**
258 * Get a set of localized UPnP properties.
259 *
260 * The UPnP specification allows a device to present different device
261 * properties based on the client's locale. The properties used to register
262 * the UPnPDevice service in the OSGi registry are based on the device's
263 * default locale. To obtain a localized set of the properties, an
264 * application can use this method.
265 * <p>
266 * Not all properties might be available in all locales. This method does
267 * <b>not </b> substitute missing properties with their default locale
268 * versions.
269 * <p>
270 *
271 * @param locale A language tag as defined by RFC 1766 and maintained by ISO
272 * 639. Examples include "<code>de</code>", "<code>en</code>" or "
273 * <code>en-US</code>". The default locale of the device is specified
274 * by passing a <code>null</code> argument.
275 * @return Dictionary mapping property name Strings to property value
276 * Strings
277 *
278 */
279 Dictionary getDescriptions(String locale);
280 }