UPnPEventListener


1   /*
2    * $Header: /cvshome/build/org.osgi.service.upnp/src/org/osgi/service/upnp/UPnPEventListener.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  import java.util.Dictionary  ;
21  
22  /**
23   * UPnP Events are mapped and delivered to applications according to the OSGi
24   * whiteboard model. An application that wishes to be notified of events
25   * generated by a particular UPnP Device registers a service extending this
26   * interface.
27   * <p>
28   * The notification call from the UPnP Service to any <code>UPnPEventListener</code>
29   * object must be done asynchronous with respect to the originator (in a
30   * separate thread).
31   * <p>
32   * Upon registration of the UPnP Event Listener service with the Framework, the
33   * service is notified for each variable which it listens for with an initial
34   * event containing the current value of the variable. Subsequent notifications
35   * only happen on changes of the value of the variable.
36   * <p>
37   * A UPnP Event Listener service filter the events it receives. This event set
38   * is limited using a standard framework filter expression which is specified
39   * when the listener service is registered.
40   * <p>
41   * The filter is specified in a property named "upnp.filter" and has as a value
42   * an object of type <code>org.osgi.framework.Filter</code>.
43   * <p>
44   * When the Filter is evaluated, the folowing keywords are recognized as defined
45   * as literal constants in the <code>UPnPDevice</code> class.
46   * <p>
47   * The valid subset of properties for the registration of UPnP Event Listener
48   * services are:
49   * <ul>
50   * <li><code>UPnPDevice.TYPE</code>-- Which type of device to listen for events.
51   * </li>
52   * <li><code>UPnPDevice.ID</code>-- The ID of a specific device to listen for
53   * events.</li>
54   * <li><code>UPnPService.TYPE</code>-- The type of a specific service to listen
55   * for events.</li>
56   * <li><code>UPnPService.ID</code>-- The ID of a specific service to listen for
57   * events.</li>
58   * </ul>
59   */
60  public interface UPnPEventListener {
61      /**
62       * Key for a service property having a value that is an object of type
63       * <code>org.osgi.framework.Filter</code> and that is used to limit received
64       * events.
65       */
66      static final String   UPNP_FILTER = "upnp.filter";
67  
68      /**
69       * Callback method that is invoked for received events.
70       * 
71       * The events are collected in a <code>Dictionary</code> object. Each entry
72       * has a <code>String</code> key representing the event name (= state variable
73       * name) and the new value of the state variable. The class of the value
74       * object must match the class specified by the UPnP State Variable
75       * associated with the event. This method must be called asynchronously
76       * 
77       * @param deviceId ID of the device sending the events
78       * @param serviceId ID of the service sending the events
79       * @param events <code>Dictionary</code> object containing the new values for
80       *        the state variables that have changed.
81       * 
82       *  
83       */
84      void notifyUPnPEvent(String   deviceId, String   serviceId, Dictionary   events);
85  }
86
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags