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 org.jivesoftware.smackx.jingleold.JingleSession;
020import org.jivesoftware.smackx.jingleold.nat.TransportCandidate;
021
022import java.util.ArrayList;
023import java.util.List;
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<MediaReceivedListener>();
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 transmittion
056     * @param remote       Remote accepted Transport Candidate
057     * @param local        Local accepted Transport Candidate
058     * @param mediaLocator Media Locator of the capture device
059     */
060    public JingleMediaSession(PayloadType payloadType, TransportCandidate remote,
061            TransportCandidate local, String mediaLocator, JingleSession jingleSession) {
062        this.local = local;
063        this.remote = remote;
064        this.payloadType = payloadType;
065        this.mediaLocator = mediaLocator;
066        this.jingleSession = jingleSession;
067    }
068
069    /**
070     * Returns the PayloadType of the Media Session
071     *
072     * @return the PayloadType
073     */
074    public PayloadType getPayloadType() {
075        return payloadType;
076    }
077
078    /**
079     * Returns the Media Session local Candidate
080     *
081     * @return the TransportCandidate
082     */
083    public TransportCandidate getLocal() {
084        return local;
085    }
086
087    /**
088     * Returns the Media Session remote Candidate
089     *
090     * @return the TransportCandidate
091     */
092    public TransportCandidate getRemote() {
093        return remote;
094    }
095
096    /**
097     * Return the media locator or null if not defined
098     *
099     * @return media locator
100     */
101    public String getMediaLocator() {
102        return mediaLocator;
103    }
104
105    /**
106     * Set the media locator
107     *
108     * @param mediaLocator media locator or null to use default
109     */
110    public void setMediaLocator(String mediaLocator) {
111        this.mediaLocator = mediaLocator;
112    }
113
114    /**
115     * Adds a Media Received Listener
116     *
117     * @param mediaReceivedListener
118     */
119    public void addMediaReceivedListener(MediaReceivedListener mediaReceivedListener) {
120        mediaReceivedListeners.add(mediaReceivedListener);
121    }
122
123    /**
124     * Removes a Media Received Listener
125     *
126     * @param mediaReceivedListener
127     */
128    public void removeMediaReceivedListener(MediaReceivedListener mediaReceivedListener) {
129        mediaReceivedListeners.remove(mediaReceivedListener);
130    }
131
132    /**
133     * Removes all Media Received Listeners
134     */
135    public void removeAllMediaReceivedListener() {
136        mediaReceivedListeners.clear();
137    }
138
139    /**
140     * Initialize the RTP Channel preparing to transmit and receive.
141     */
142    public abstract void initialize();
143
144    /**
145     * Starts a RTP / UDP / TCP Transmission to the remote Candidate
146     */
147    public abstract void startTrasmit();
148
149    /**
150     * Starts a RTP / UDP / TCP Receiver from the remote Candidate to local Candidate
151     */
152    public abstract void startReceive();
153
154    /**
155     * Set transmit activity. If the active is true, the instance should trasmit.
156     * If it is set to false, the instance should pause transmit.
157     *
158     * @param active
159     */
160    public abstract void setTrasmit(boolean active);
161
162    /**
163     * Stops a RTP / UDP / TCP Transmission to the remote Candidate
164     */
165    public abstract void stopTrasmit();
166
167    /**
168     * Stops a RTP / UDP / TCP Receiver from the remote Candidate to local Candidate
169     */
170    public abstract void stopReceive();
171
172    /**
173     * Called when new Media is received.
174     */
175    public void mediaReceived(String participant) {
176        for (MediaReceivedListener mediaReceivedListener : mediaReceivedListeners) {
177            mediaReceivedListener.mediaReceived(participant);
178        }
179    }
180
181    /**
182     * Gets associated JingleSession
183     * @return associated JingleSession
184     */
185    public JingleSession getJingleSession() {
186        return jingleSession;
187    }
188}