UPnPDevice


1   /*
2    * $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 $
3    *
4    * Copyright (c) OSGi Alliance (2002, 2006). All Rights Reserved.
5    *
6    * Licensed under the Apache License, Version 2.0 (the "License");
7    * you may not use this file except in compliance with the License.
8    * You may obtain a copy of the License at
9    *
10   *      http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  package org.osgi.service.upnp;
19  
20  import java.util.Dictionary  ;
21  
22  /**
23   * Represents a UPnP device.
24   * 
25   * For each UPnP root and embedded device, an object is registered with the
26   * framework under the <code>UPnPDevice</code> interface.
27   * <p>
28   * The relationship between a root device and its embedded devices can be
29   * deduced using the <code>UPnPDevice.CHILDREN_UDN</code> and
30   * <code>UPnPDevice.PARENT_UDN</code> service registration properties.
31   * <p>
32   * The values of the UPnP property names are defined by the UPnP Forum.
33   * <p>
34   * All values of the UPnP properties are obtained from the device using the
35   * device's default locale.
36   * <p>
37   * If an application wants to query for a set of localized property values, it
38   * has to use the method <code>UPnPDevice.getDescriptions(String locale)</code>.
39   *  
40   */
41  public interface UPnPDevice {
42      /*
43       * Constants for the UPnP device match scale.
44       */
45      /**
46       * Constant for the UPnP device match scale, indicating a generic match for
47       * the device. Value is 1.
48       */
49      int     MATCH_GENERIC                               = 1;
50      /**
51       * Constant for the UPnP device match scale, indicating a match with the
52       * device type. Value is 3.
53       */
54      int     MATCH_TYPE                                  = 3;
55      /**
56       * Constant for the UPnP device match scale, indicating a match with the
57       * device model. Value is 7.
58       */
59      int     MATCH_MANUFACTURER_MODEL                    = 7;
60      /**
61       * Constant for the UPnP device match scale, indicating a match with the
62       * device revision. Value is 15.
63       */
64      int     MATCH_MANUFACTURER_MODEL_REVISION           = 15;
65      /**
66       * Constant for the UPnP device match scale, indicating a match with the
67       * device revision and the serial number. Value is 31.
68       */
69      int     MATCH_MANUFACTURER_MODEL_REVISION_SERIAL    = 31;
70      /**
71       * Constant for the value of the service property <code>DEVICE_CATEGORY</code>
72       * used for all UPnP devices. Value is "UPnP".
73       * 
74       * @see "<code>org.osgi.service.device.Constants.DEVICE_CATEGORY</code>"
75       */
76      String    DEVICE_CATEGORY                             = "UPnP";
77      /**
78       * The <code>UPnP.export</code> service property is a hint that marks a device
79       * to be picked up and exported by the UPnP Service. Imported devices do not
80       * have this property set. The registered property requires no value.
81       * <p>
82       * The UPNP_EXPORT string is "UPnP.export".
83       */
84      String    UPNP_EXPORT                                 = "UPnP.export";
85      /**
86       * Property key for the Unique Device Name (UDN) property. It is the unique
87       * identifier of an instance of a <code>UPnPDevice</code>. The value of the
88       * property is a <code>String</code> object of the Device UDN. Value of the
89       * key is "UPnP.device.UDN". This property must be set.
90       */
91      String    UDN                                         = "UPnP.device.UDN";
92      /**
93       * Property key for the Unique Device ID property. This property is an alias
94       * to <code>UPnPDevice.UDN</code>. It is merely provided for reasons of
95       * symmetry with the <code>UPnPService.ID</code> property. The value of the
96       * property is a <code>String</code> object of the Device UDN. The value of
97       * the key is "UPnP.device.UDN".
98       */
99      String    ID                                          = UDN;
100     /**
101      * Property key for the UPnP Device Type property. Some standard property
102      * values are defined by the Universal Plug and Play Forum. The type string
103      * also includes a version number as defined in the UPnP specification. This
104      * property must be set.
105      * <p>
106      * For standard devices defined by a UPnP Forum working committee, this must
107      * consist of the following components in the given order separated by
108      * colons:
109      * <ul>
110      * <li><code>urn</code></li>
111      * <li>schemas-upnp-org</li>
112      * <li><code>device</code></li>
113      * <li>a device type suffix</li>
114      * <li>an integer device version</li>
115      * </ul>
116      * For non-standard devices specified by UPnP vendors following components
117      * must be specified in the given order separated by colons:
118      * <ul>
119      * <li><code>urn</code></li>
120      * <li>an ICANN domain name owned by the vendor</li>
121      * <li><code>device</code></li>
122      * <li>a device type suffix</li>
123      * <li>an integer device version</li>
124      * </ul>
125      * <p>
126      * To allow for backward compatibility the UPnP driver must automatically
127      * generate additional Device Type property entries for smaller versions
128      * than the current one. If for example a device announces its type as
129      * version 3, then properties for versions 2 and 1 must be automatically
130      * generated.
131      * <p>
132      * In the case of exporting a UPnPDevice, the highest available version must
133      * be announced on the network.
134      * <p>
135      * Syntax Example: <code>urn:schemas-upnp-org:device:deviceType:v</code>
136      * <p>
137      * The value is "UPnP.device.type".
138      */
139     String    TYPE                                        = "UPnP.device.type";
140     /**
141      * Mandatory property key for the device manufacturer's property. The
142      * property value holds a String representation of the device manufacturer's
143      * name. Value is "UPnP.device.manufacturer".
144      */
145     String    MANUFACTURER                                = "UPnP.device.manufacturer";
146     /**
147      * Mandatory property key for the device model name. The property value
148      * holds a <code>String</code> object giving more information about the device
149      * model. Value is "UPnP.device.modelName".
150      */
151     String    MODEL_NAME                                  = "UPnP.device.modelName";
152     /**
153      * Mandatory property key for a short user friendly version of the device
154      * name. The property value holds a <code>String</code> object with the user
155      * friendly name of the device. Value is "UPnP.device.friendlyName".
156      */
157     String    FRIENDLY_NAME                               = "UPnP.device.friendlyName";
158     /**
159      * Optional property key for a URL to the device manufacturers Web site. The
160      * value of the property is a <code>String</code> object representing the URL.
161      * Value is "UPnP.device.manufacturerURL".
162      */
163     String    MANUFACTURER_URL                            = "UPnP.device.manufacturerURL";
164     /**
165      * Optional (but recommended) property key for a <code>String</code> object
166      * with a long description of the device for the end user. The value is
167      * "UPnP.device.modelDescription".
168      */
169     String    MODEL_DESCRIPTION                           = "UPnP.device.modelDescription";
170     /**
171      * Optional (but recommended) property key for a <code>String</code> class
172      * typed property holding the model number of the device. Value is
173      * "UPnP.device.modelNumber".
174      */
175     String    MODEL_NUMBER                                = "UPnP.device.modelNumber";
176     /**
177      * Optional property key for a <code>String</code> typed property holding a
178      * string representing the URL to the Web site for this model. Value is
179      * "UPnP.device.modelURL".
180      */
181     String    MODEL_URL                                   = "UPnP.device.modelURL";
182     /**
183      * Optional (but recommended) property key for a <code>String</code> typed
184      * property holding the serial number of the device. Value is
185      * "UPnP.device.serialNumber".
186      */
187     String    SERIAL_NUMBER                               = "UPnP.device.serialNumber";
188     /**
189      * Optional property key for a <code>String</code> typed property holding the
190      * Universal Product Code (UPC) of the device. Value is "UPnP.device.UPC".
191      */
192     String    UPC                                         = "UPnP.device.UPC";
193     /**
194      * Optional (but recommended) property key for a <code>String</code> typed
195      * property holding a string representing the URL to a device representation
196      * Web page. Value is "UPnP.presentationURL".
197      */
198     String    PRESENTATION_URL                            = "UPnP.presentationURL";
199     /**
200      * The property key that must be set for all embedded devices. It contains
201      * the UDN of the parent device. The property is not set for root devices.
202      * The value is "UPnP.device.parentUDN".
203      */
204     String    PARENT_UDN                                  = "UPnP.device.parentUDN";
205     /**
206      * The property key that must be set for all devices containing other
207      * embedded devices.
208      * <p>
209      * The value is an array of UDNs for each of the device's children (
210      * <code>String[]</code>). The array contains UDNs for the immediate
211      * descendants only.
212      * </p>
213      * <p>
214      * If an embedded device in turn contains embedded devices, the latter are
215      * not included in the array.
216      * </p>
217      * The UPnP Specification does not encourage more than two levels of
218      * nesting.
219      * <p>
220      * The property is not set if the device does not contain embedded devices.
221      * <p>
222      * The property is of type <code>String[]</code>. Value is
223      * "UPnP.device.childrenUDN"
224      */
225     String    CHILDREN_UDN                                = "UPnP.device.childrenUDN";
226 
227     /**
228      * Locates a specific service by its service id.
229      * 
230      * @param serviceId The service id
231      * @return The requested service or null if not found.
232      */
233     UPnPService getService(String   serviceId);
234 
235     /**
236      * Lists all services provided by this device.
237      * 
238      * @return Array of services or <code>null</code> if no services are
239      *         available.
240      */
241     UPnPService[] getServices();
242 
243     /**
244      * Lists all icons for this device in a given locale.
245      * 
246      * The UPnP specification allows a device to present different icons based
247      * on the client's locale.
248      * 
249      * @param locale A language tag as defined by RFC 1766 and maintained by ISO
250      *        639. Examples include "<code>de</code>", "<code>en</code>" or "
251      *        <code>en-US</code>". The default locale of the device is specified
252      *        by passing a <code>null</code> argument.
253      * 
254      * @return Array of icons or null if no icons are available.
255      */
256     UPnPIcon[] getIcons(String   locale);
257 
258     /**
259      * Get a set of localized UPnP properties.
260      * 
261      * The UPnP specification allows a device to present different device
262      * properties based on the client's locale. The properties used to register
263      * the UPnPDevice service in the OSGi registry are based on the device's
264      * default locale. To obtain a localized set of the properties, an
265      * application can use this method.
266      * <p>
267      * Not all properties might be available in all locales. This method does
268      * <b>not </b> substitute missing properties with their default locale
269      * versions.
270      * <p>
271      * 
272      * @param locale A language tag as defined by RFC 1766 and maintained by ISO
273      *        639. Examples include "<code>de</code>", "<code>en</code>" or "
274      *        <code>en-US</code>". The default locale of the device is specified
275      *        by passing a <code>null</code> argument.
276      * @return Dictionary mapping property name Strings to property value
277      *         Strings
278      *  
279      */
280     Dictionary   getDescriptions(String   locale);
281 }
282
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags