001/**
002 *
003 * Copyright 2003-2006 Jive Software.
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 *     http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.jivesoftware.smackx.jingleold.media;
018
019import java.util.ArrayList;
020import java.util.List;
021
022import org.jivesoftware.smackx.jingleold.JingleSession;
023import org.jivesoftware.smackx.jingleold.nat.TransportCandidate;
024
025/**
026 * Public Abstract Class provides a clear interface between Media Session and Jingle API.
027 * <p>
028 * When a Jingle Session is fully stablished, we will have a Payload Type and two transport candidates defined for it.
029 * Smack Jingle API don't implement Media Transmit and Receive methods.
030 * But provides an interface to let the user implements it using another API. For instance: JMF.
031 * </p>
032 * <i>The Class that implements this one, must have the support to transmit and receive the jmf.</i>
033 * <i>This interface let the user choose his own jmf API.</i>
034 *
035 * @author Thiago Camargo
036 */
037public abstract class JingleMediaSession {
038
039    // Payload Type of the Session
040    private PayloadType payloadType;
041    // Local Transport details
042    private TransportCandidate local;
043    // Remote Transport details
044    private TransportCandidate remote;
045    // Media Locator
046    private String mediaLocator;
047    // Media Received Listener
048    private List<MediaReceivedListener> mediaReceivedListeners = new ArrayList<>();
049    // Jingle Session
050    private JingleSession jingleSession;
051
052    /**
053     * Creates a new JingleMediaSession Instance to handle Media methods.
054     *
055     * @param payloadType  Payload Type of the transmission
056     * @param remote       Remote accepted Transport Candidate
057     * @param local        Local accepted Transport Candidate
058     * @param mediaLocator Media Locator of the capture device
059     * @param jingleSession the jingle session.
060     */
061    public JingleMediaSession(PayloadType payloadType, TransportCandidate remote,
062            TransportCandidate local, String mediaLocator, JingleSession jingleSession) {
063        this.local = local;
064        this.remote = remote;
065        this.payloadType = payloadType;
066        this.mediaLocator = mediaLocator;
067        this.jingleSession = jingleSession;
068    }
069
070    /**
071     * Returns the PayloadType of the Media Session.
072     *
073     * @return the PayloadType
074     */
075    public PayloadType getPayloadType() {
076        return payloadType;
077    }
078
079    /**
080     * Returns the Media Session local Candidate.
081     *
082     * @return the TransportCandidate
083     */
084    public TransportCandidate getLocal() {
085        return local;
086    }
087
088    /**
089     * Returns the Media Session remote Candidate.
090     *
091     * @return the TransportCandidate
092     */
093    public TransportCandidate getRemote() {
094        return remote;
095    }
096
097    /**
098     * Return the media locator or null if not defined.
099     *
100     * @return media locator
101     */
102    public String getMediaLocator() {
103        return mediaLocator;
104    }
105
106    /**
107     * Set the media locator.
108     *
109     * @param mediaLocator media locator or null to use default
110     */
111    public void setMediaLocator(String mediaLocator) {
112        this.mediaLocator = mediaLocator;
113    }
114
115    /**
116     * Adds a Media Received Listener.
117     *
118     * @param mediaReceivedListener TODO javadoc me please
119     */
120    public void addMediaReceivedListener(MediaReceivedListener mediaReceivedListener) {
121        mediaReceivedListeners.add(mediaReceivedListener);
122    }
123
124    /**
125     * Removes a Media Received Listener.
126     *
127     * @param mediaReceivedListener TODO javadoc me please
128     */
129    public void removeMediaReceivedListener(MediaReceivedListener mediaReceivedListener) {
130        mediaReceivedListeners.remove(mediaReceivedListener);
131    }
132
133    /**
134     * Removes all Media Received Listeners.
135     */
136    public void removeAllMediaReceivedListener() {
137        mediaReceivedListeners.clear();
138    }
139
140    /**
141     * Initialize the RTP Channel preparing to transmit and receive.
142     */
143    public abstract void initialize();
144
145    /**
146     * Starts a RTP / UDP / TCP Transmission to the remote Candidate.
147     */
148    public abstract void startTransmit();
149
150    /**
151     * Starts a RTP / UDP / TCP Receiver from the remote Candidate to local Candidate.
152     */
153    public abstract void startReceive();
154
155    /**
156     * Set transmit activity. If the active is true, the instance should trasmit.
157     * If it is set to false, the instance should pause transmit.
158     *
159     * @param active TODO javadoc me please
160     */
161    public abstract void setTransmit(boolean active);
162
163    /**
164     * Stops a RTP / UDP / TCP Transmission to the remote Candidate.
165     */
166    public abstract void stopTransmit();
167
168    /**
169     * Stops a RTP / UDP / TCP Receiver from the remote Candidate to local Candidate.
170     */
171    public abstract void stopReceive();
172
173    /**
174     * Called when new Media is received.
175     *
176     * @param participant the particpant.
177     */
178    public void mediaReceived(String participant) {
179        for (MediaReceivedListener mediaReceivedListener : mediaReceivedListeners) {
180            mediaReceivedListener.mediaReceived(participant);
181        }
182    }
183
184    /**
185     * Gets associated JingleSession.
186     * @return associated JingleSession
187     */
188    public JingleSession getJingleSession() {
189        return jingleSession;
190    }
191}