/*
 * Copyright (c) OSGi Alliance (2002, 2015). All Rights Reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.osgi.service.upnp;

import java.util.Dictionary;

/**
 * UPnP Events are mapped and delivered to applications according to the OSGi
 * whiteboard model. An application that wishes to be notified of events
 * generated by a particular UPnP Device registers a service extending this
 * interface.
 * <p>
 * The notification call from the UPnP Service to any {@code UPnPEventListener}
 * object must be done asynchronous with respect to the originator (in a
 * separate thread).
 * <p>
 * Upon registration of the UPnP Event Listener service with the Framework, the
 * service is notified for each variable which it listens for with an initial
 * event containing the current value of the variable. Subsequent notifications
 * only happen on changes of the value of the variable.
 * <p>
 * A UPnP Event Listener service filter the events it receives. This event set
 * is limited using a standard framework filter expression which is specified
 * when the listener service is registered.
 * <p>
 * The filter is specified in a property named "upnp.filter" and has as a value
 * an object of type {@code org.osgi.framework.Filter}.
 * <p>
 * When the Filter is evaluated, the following keywords are recognized as
 * defined as literal constants in the {@code UPnPDevice} class.
 * <p>
 * The valid subset of properties for the registration of UPnP Event Listener
 * services are:
 * <ul>
 * <li>{@code UPnPDevice.TYPE}-- Which type of device to listen for events.</li>
 * <li>{@code UPnPDevice.ID}-- The ID of a specific device to listen for events.
 * </li>
 * <li>{@code UPnPService.TYPE}-- The type of a specific service to listen for
 * events.</li>
 * <li>{@code UPnPService.ID}-- The ID of a specific service to listen for
 * events.</li>
 * </ul>
 * 
 * @author $Id$
 */
public interface UPnPEventListener {
	/**
	 * Key for a service property having a value that is an object of type
	 * {@code org.osgi.framework.Filter} and that is used to limit received
	 * events.
	 */
	static final String	UPNP_FILTER	= "upnp.filter";

	/**
	 * Callback method that is invoked for received events.
	 * 
	 * The events are collected in a {@code Dictionary} object. Each entry has a
	 * {@code String} key representing the event name (= state variable name)
	 * and the new value of the state variable. The class of the value object
	 * must match the class specified by the UPnP State Variable associated with
	 * the event. This method must be called asynchronously
	 * 
	 * @param deviceId ID of the device sending the events
	 * @param serviceId ID of the service sending the events
	 * @param events {@code Dictionary} object containing the new values for the
	 *        state variables that have changed.
	 * 
	 * 
	 */
	void notifyUPnPEvent(String deviceId, String serviceId, Dictionary<String, ?> events);
}