UPnPService


1   /*
2    * $Header: /cvshome/build/org.osgi.service.upnp/src/org/osgi/service/upnp/UPnPService.java,v 1.8 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  /**
21   * A representation of a UPnP Service.
22   * 
23   * Each UPnP device contains zero or more services. The UPnP description for a
24   * service defines actions, their arguments, and event characteristics.
25   */
26  public interface UPnPService {
27      /**
28       * Property key for the optional service type uri.
29       * 
30       * The service type property is used when registering UPnP Device services
31       * and UPnP Event Listener services. The property contains a <code>String</code>
32       * array (<code>String[]</code>) of service types. A UPnP Device service can
33       * thus announce what types of services it contains. A UPnP Event Listener
34       * service can announce for what type of UPnP services it wants
35       * notifications. The service version is encoded in the type string as
36       * specified in the UPnP specification. A <code>null</code> value is a
37       * wildcard, matching <b>all </b> service types. Value is
38       * "UPnP.service.type".
39       * 
40       * @see UPnPService#getType()
41       */
42      String    TYPE    = "UPnP.service.type";
43      /**
44       * Property key for the optional service id.
45       * 
46       * The service id property is used when registering UPnP Device services or
47       * UPnP Event Listener services. The value of the property contains a
48       * <code>String</code> array (<code>String[]</code>) of service ids. A UPnP
49       * Device service can thus announce what service ids it contains. A UPnP
50       * Event Listener service can announce for what UPnP service ids it wants
51       * notifications. A service id does <b>not </b> have to be universally
52       * unique. It must be unique only within a device. A <code>null</code> value
53       * is a wildcard, matching <b>all </b> services. The value is
54       * "UPnP.service.id".
55       */
56      String    ID      = "UPnP.service.id";
57  
58      /**
59       * Returns the <code>serviceId</code> field in the UPnP service description.
60       * 
61       * 
62       * <p>
63       * For standard services defined by a UPnP Forum working committee, the
64       * serviceId must contain the following components in the indicated order:
65       * <ul>
66       * <li><code>urn:upnp-org:serviceId:</code></li>
67       * <li>service ID suffix</li>
68       * </ul>
69       * Example: <code>urn:upnp-org:serviceId:serviceID</code>.
70       * 
71       * <p>
72       * Note that <code>upnp-org</code> is used instead of
73       * <code>schemas-upnp-org</code> in this example because an XML schema is not
74       * defined for each serviceId.
75       * </p>
76       * 
77       * <p>
78       * For non-standard services specified by UPnP vendors, the serviceId must
79       * contain the following components in the indicated order:
80       * <ul>
81       * <li><code>urn:</code></li>
82       * <li>ICANN domain name owned by the vendor</li>
83       * <li><code>:serviceId:</code></li>
84       * <li>service ID suffix</li>
85       * </ul>
86       * Example: <code>urn:domain-name:serviceId:serviceID</code>.
87       * 
88       * @return The service ID suffix defined by a UPnP Forum working committee
89       *         or specified by a UPnP vendor. Must be &lt;= 64 characters.
90       *         Single URI.
91       */
92      String   getId();
93  
94      /**
95       * Returns the <code>serviceType</code> field in the UPnP service description.
96       * 
97       * <p>
98       * For standard services defined by a UPnP Forum working committee, the
99       * serviceType must contain the following components in the indicated order:
100      * <ul>
101      * <li><code>urn:schemas-upnp-org:service:</code></li>
102      * <li>service type suffix:</li>
103      * <li>integer service version</li>
104      * </ul>
105      * Example: <code>urn:schemas-upnp-org:service:serviceType:v</code>.
106      * 
107      * <p>
108      * For non-standard services specified by UPnP vendors, the
109      * <code>serviceType</code> must contain the following components in the
110      * indicated order:
111      * <ul>
112      * <li><code>urn:</code></li>
113      * <li>ICANN domain name owned by the vendor</li>
114      * <li><code>:service:</code></li>
115      * <li>service type suffix:</li>
116      * <li>integer service version</li>
117      * </ul>
118      * Example: <code>urn:domain-name:service:serviceType:v</code>.
119      * 
120      * @return The service type suffix defined by a UPnP Forum working committee
121      *         or specified by a UPnP vendor. Must be &lt;= 64 characters, not
122      *         including the version suffix and separating colon. Single URI.
123      */
124     String   getType();
125 
126     /**
127      * Returns the version suffix encoded in the <code>serviceType</code> field in
128      * the UPnP service description.
129      * 
130      * @return The integer service version defined by a UPnP Forum working
131      *         committee or specified by a UPnP vendor.
132      */
133     String   getVersion();
134 
135     /**
136      * Locates a specific action by name.
137      * 
138      * Looks up an action by its name.
139      * 
140      * @param name Name of action. Must not contain hyphen or hash characters.
141      *        Should be &lt; 32 characters.
142      * 
143      * @return The requested action or <code>null</code> if no action is found.
144      */
145     UPnPAction getAction(String   name);
146 
147     /**
148      * Lists all actions provided by this service.
149      * 
150      * @return Array of actions (<code>UPnPAction[]</code> )or <code>null</code> if
151      *         no actions are defined for this service.
152      */
153     UPnPAction[] getActions();
154 
155     /**
156      * Lists all <code>UPnPStateVariable</code> objects provided by this service.
157      * 
158      * @return Array of state variables or <code>null</code> if none are defined
159      *         for this service.
160      */
161     UPnPStateVariable[] getStateVariables();
162 
163     /**
164      * Gets a <code>UPnPStateVariable</code> objects provided by this service by
165      * name
166      * 
167      * @param name Name of the State Variable
168      * 
169      * @return State variable or <code>null</code> if no such state variable
170      *         exists for this service.
171      */
172     UPnPStateVariable getStateVariable(String   name);
173 }
174
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags