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 * UPnP Events are mapped and delivered to applications according to the OSGi
022 * whiteboard model. An application that wishes to be notified of events
023 * generated by a particular UPnP Device registers a service extending this
024 * interface.
025 * <p>
026 * The notification call from the UPnP Service to any
027 * <code>UPnPEventListener</code> object must be done asynchronous with respect
028 * to the originator (in a separate thread).
029 * <p>
030 * Upon registration of the UPnP Event Listener service with the Framework, the
031 * service is notified for each variable which it listens for with an initial
032 * event containing the current value of the variable. Subsequent notifications
033 * only happen on changes of the value of the variable.
034 * <p>
035 * A UPnP Event Listener service filter the events it receives. This event set
036 * is limited using a standard framework filter expression which is specified
037 * when the listener service is registered.
038 * <p>
039 * The filter is specified in a property named "upnp.filter" and has as a value
040 * an object of type <code>org.osgi.framework.Filter</code>.
041 * <p>
042 * When the Filter is evaluated, the folowing keywords are recognized as defined
043 * as literal constants in the <code>UPnPDevice</code> class.
044 * <p>
045 * The valid subset of properties for the registration of UPnP Event Listener
046 * services are:
047 * <ul>
048 * <li><code>UPnPDevice.TYPE</code>-- Which type of device to listen for events.
049 * </li>
050 * <li><code>UPnPDevice.ID</code>-- The ID of a specific device to listen for
051 * events.</li>
052 * <li><code>UPnPService.TYPE</code>-- The type of a specific service to listen
053 * for events.</li>
054 * <li><code>UPnPService.ID</code>-- The ID of a specific service to listen for
055 * events.</li>
056 * </ul>
057 *
058 * @version $Revision: 5673 $
059 */
060 public interface UPnPEventListener {
061 /**
062 * Key for a service property having a value that is an object of type
063 * <code>org.osgi.framework.Filter</code> and that is used to limit received
064 * events.
065 */
066 static final String UPNP_FILTER = "upnp.filter";
067
068 /**
069 * Callback method that is invoked for received events.
070 *
071 * The events are collected in a <code>Dictionary</code> object. Each entry
072 * has a <code>String</code> key representing the event name (= state variable
073 * name) and the new value of the state variable. The class of the value
074 * object must match the class specified by the UPnP State Variable
075 * associated with the event. This method must be called asynchronously
076 *
077 * @param deviceId ID of the device sending the events
078 * @param serviceId ID of the service sending the events
079 * @param events <code>Dictionary</code> object containing the new values for
080 * the state variables that have changed.
081 *
082 *
083 */
084 void notifyUPnPEvent(String deviceId, String serviceId, Dictionary events);
085 }