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 /**
019 * A representation of a UPnP Service.
020 *
021 * Each UPnP device contains zero or more services. The UPnP description for a
022 * service defines actions, their arguments, and event characteristics.
023 *
024 * @version $Revision: 5673 $
025 */
026 public interface UPnPService {
027 /**
028 * Property key for the optional service type uri.
029 *
030 * The service type property is used when registering UPnP Device services
031 * and UPnP Event Listener services. The property contains a <code>String</code>
032 * array (<code>String[]</code>) of service types. A UPnP Device service can
033 * thus announce what types of services it contains. A UPnP Event Listener
034 * service can announce for what type of UPnP services it wants
035 * notifications. The service version is encoded in the type string as
036 * specified in the UPnP specification. A <code>null</code> value is a
037 * wildcard, matching <b>all </b> service types. Value is
038 * "UPnP.service.type".
039 *
040 * @see UPnPService#getType()
041 */
042 String TYPE = "UPnP.service.type";
043 /**
044 * Property key for the optional service id.
045 *
046 * The service id property is used when registering UPnP Device services or
047 * UPnP Event Listener services. The value of the property contains a
048 * <code>String</code> array (<code>String[]</code>) of service ids. A UPnP
049 * Device service can thus announce what service ids it contains. A UPnP
050 * Event Listener service can announce for what UPnP service ids it wants
051 * notifications. A service id does <b>not </b> have to be universally
052 * unique. It must be unique only within a device. A <code>null</code> value
053 * is a wildcard, matching <b>all </b> services. The value is
054 * "UPnP.service.id".
055 */
056 String ID = "UPnP.service.id";
057
058 /**
059 * Returns the <code>serviceId</code> field in the UPnP service description.
060 *
061 *
062 * <p>
063 * For standard services defined by a UPnP Forum working committee, the
064 * serviceId must contain the following components in the indicated order:
065 * <ul>
066 * <li><code>urn:upnp-org:serviceId:</code></li>
067 * <li>service ID suffix</li>
068 * </ul>
069 * Example: <code>urn:upnp-org:serviceId:serviceID</code>.
070 *
071 * <p>
072 * Note that <code>upnp-org</code> is used instead of
073 * <code>schemas-upnp-org</code> in this example because an XML schema is not
074 * defined for each serviceId.
075 * </p>
076 *
077 * <p>
078 * For non-standard services specified by UPnP vendors, the serviceId must
079 * contain the following components in the indicated order:
080 * <ul>
081 * <li><code>urn:</code></li>
082 * <li>ICANN domain name owned by the vendor</li>
083 * <li><code>:serviceId:</code></li>
084 * <li>service ID suffix</li>
085 * </ul>
086 * Example: <code>urn:domain-name:serviceId:serviceID</code>.
087 *
088 * @return The service ID suffix defined by a UPnP Forum working committee
089 * or specified by a UPnP vendor. Must be <= 64 characters.
090 * Single URI.
091 */
092 String getId();
093
094 /**
095 * Returns the <code>serviceType</code> field in the UPnP service description.
096 *
097 * <p>
098 * For standard services defined by a UPnP Forum working committee, the
099 * 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 <= 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 < 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 }