1 /*
2 * Copyright (C) 2013 4th Line GmbH, Switzerland
3 *
4 * The contents of this file are subject to the terms of either the GNU
5 * Lesser General Public License Version 2 or later ("LGPL") or the
6 * Common Development and Distribution License Version 1 or later
7 * ("CDDL") (collectively, the "License"). You may not use this file
8 * except in compliance with the License. See LICENSE.txt for more
9 * information.
10 *
11 * This program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
14 */
15
16 package org.fourthline.cling.transport.spi;
17
18 import org.fourthline.cling.transport.Router;
19
20 import java.net.NetworkInterface;
21
22 /**
23 * Service for receiving multicast UDP datagrams, one per bound network interface.
24 * <p>
25 * This services typically listens on a socket for UDP datagrams, the socket has joined
26 * the configured multicast group.
27 * </p>
28 * <p>
29 * This listening loop is started with the <code>run()</code> method,
30 * this service is <code>Runnable</code>. Any received datagram is then converted into an
31 * {@link org.fourthline.cling.model.message.IncomingDatagramMessage} and
32 * handled by the
33 * {@link org.fourthline.cling.transport.Router#received(org.fourthline.cling.model.message.IncomingDatagramMessage)}
34 * method. This conversion is the job of the {@link org.fourthline.cling.transport.spi.DatagramProcessor}.
35 * </p>
36 * <p>
37 * An implementation has to be thread-safe.
38 * </p>
39 *
40 * @param <C> The type of the service's configuration.
41 *
42 * @author Christian Bauer
43 */
44 public interface MulticastReceiver<C extends MulticastReceiverConfiguration> extends Runnable {
45
46 /**
47 * Configures the service and starts any listening sockets.
48 *
49 * @param networkInterface The network interface on which to join the multicast group on.
50 * @param router The router which handles received {@link org.fourthline.cling.model.message.IncomingDatagramMessage}s.
51 * @param networkAddressFactory The network address factory to use for local address lookup given a local interface and a remote address.
52 * @param datagramProcessor Reads and writes datagrams.
53 * @throws InitializationException If the service could not be initialized or started.
54 */
55 public void init(NetworkInterface networkInterface,
56 Router router,
57 NetworkAddressFactory networkAddressFactory,
58 DatagramProcessor datagramProcessor) throws InitializationException;
59
60 /**
61 * Stops the service, closes any listening sockets.
62 */
63 public void stop();
64
65 /**
66 * @return This service's configuration.
67 */
68 public C getConfiguration();
69
70 }