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.protocol;
17
18 import org.fourthline.cling.UpnpService;
19 import org.fourthline.cling.model.action.ActionInvocation;
20 import org.fourthline.cling.model.meta.LocalDevice;
21 import org.fourthline.cling.model.gena.LocalGENASubscription;
22 import org.fourthline.cling.model.gena.RemoteGENASubscription;
23 import org.fourthline.cling.model.message.IncomingDatagramMessage;
24 import org.fourthline.cling.model.message.StreamRequestMessage;
25 import org.fourthline.cling.model.message.header.UpnpHeader;
26 import org.fourthline.cling.protocol.async.SendingNotificationAlive;
27 import org.fourthline.cling.protocol.async.SendingNotificationByebye;
28 import org.fourthline.cling.protocol.async.SendingSearch;
29 import org.fourthline.cling.protocol.sync.SendingAction;
30 import org.fourthline.cling.protocol.sync.SendingEvent;
31 import org.fourthline.cling.protocol.sync.SendingRenewal;
32 import org.fourthline.cling.protocol.sync.SendingSubscribe;
33 import org.fourthline.cling.protocol.sync.SendingUnsubscribe;
34
35 import java.net.URL;
36
37 /**
38 * Factory for UPnP protocols, the core implementation of the UPnP specification.
39 * <p>
40 * This factory creates an executable protocol either based on the received UPnP messsage, or
41 * on local device/search/service metadata). A protocol is an aspect of the UPnP specification,
42 * you can override individual protocols to customize the behavior of the UPnP stack.
43 * </p>
44 * <p>
45 * An implementation has to be thread-safe.
46 * </p>
47 *
48 * @author Christian Bauer
49 */
50 public interface ProtocolFactory {
51
52 public UpnpService getUpnpService();
53
54 /**
55 * Creates a {@link org.fourthline.cling.protocol.async.ReceivingNotification},
56 * {@link org.fourthline.cling.protocol.async.ReceivingSearch},
57 * or {@link org.fourthline.cling.protocol.async.ReceivingSearchResponse} protocol.
58 *
59 * @param message The incoming message, either {@link org.fourthline.cling.model.message.UpnpRequest} or
60 * {@link org.fourthline.cling.model.message.UpnpResponse}.
61 * @return The appropriate protocol that handles the messages or <code>null</code> if the message should be dropped.
62 * @throws ProtocolCreationException If no protocol could be found for the message.
63 */
64 public ReceivingAsync createReceivingAsync(IncomingDatagramMessage message) throws ProtocolCreationException;
65
66 /**
67 * Creates a {@link org.fourthline.cling.protocol.sync.ReceivingRetrieval},
68 * {@link org.fourthline.cling.protocol.sync.ReceivingAction},
69 * {@link org.fourthline.cling.protocol.sync.ReceivingSubscribe},
70 * {@link org.fourthline.cling.protocol.sync.ReceivingUnsubscribe}, or
71 * {@link org.fourthline.cling.protocol.sync.ReceivingEvent} protocol.
72 *
73 * @param requestMessage The incoming message, examime {@link org.fourthline.cling.model.message.UpnpRequest.Method}
74 * to determine the protocol.
75 * @return The appropriate protocol that handles the messages.
76 * @throws ProtocolCreationException If no protocol could be found for the message.
77 */
78 public ReceivingSync createReceivingSync(StreamRequestMessage requestMessage) throws ProtocolCreationException;
79
80 /**
81 * Called by the {@link org.fourthline.cling.registry.Registry}, creates a protocol for announcing local devices.
82 */
83 public SendingNotificationAlive createSendingNotificationAlive(LocalDevice localDevice);
84
85 /**
86 * Called by the {@link org.fourthline.cling.registry.Registry}, creates a protocol for announcing local devices.
87 */
88 public SendingNotificationByebye createSendingNotificationByebye(LocalDevice localDevice);
89
90 /**
91 * Called by the {@link org.fourthline.cling.controlpoint.ControlPoint}, creates a protocol for a multicast search.
92 */
93 public SendingSearch createSendingSearch(UpnpHeader searchTarget, int mxSeconds);
94
95 /**
96 * Called by the {@link org.fourthline.cling.controlpoint.ControlPoint}, creates a protocol for executing an action.
97 */
98 public SendingAction createSendingAction(ActionInvocation actionInvocation, URL controlURL);
99
100 /**
101 * Called by the {@link org.fourthline.cling.controlpoint.ControlPoint}, creates a protocol for GENA subscription.
102 */
103 public SendingSubscribe createSendingSubscribe(RemoteGENASubscription subscription) throws ProtocolCreationException;
104
105 /**
106 * Called by the {@link org.fourthline.cling.controlpoint.ControlPoint}, creates a protocol for GENA renewal.
107 */
108 public SendingRenewal createSendingRenewal(RemoteGENASubscription subscription);
109
110 /**
111 * Called by the {@link org.fourthline.cling.controlpoint.ControlPoint}, creates a protocol for GENA unsubscription.
112 */
113 public SendingUnsubscribe createSendingUnsubscribe(RemoteGENASubscription subscription);
114
115 /**
116 * Called by the {@link org.fourthline.cling.model.gena.GENASubscription}, creates a protocol for sending GENA events.
117 */
118 public SendingEvent createSendingEvent(LocalGENASubscription subscription);
119 }