Participant.java

/*
 * @(#)Participant.java	1.6 02/08/21
 *
 * Copyright (c) 1996-2002 Sun Microsystems, Inc.  All rights reserved.
 */

package javax.media.rtp;
import java.util.*;

/**
 * This interface represents one participant in an RTP session.
 * Within a session,  a participant is defined to be the application
 * sending and  receiving data on that session.  Note  that this doesn't
 * necessarily  imply that participants are human. A single participant
 * may be the source of zero or more streams of RTP data packets, each
 * of which is represented by an RTPStream  object obtainable via the
 * getStreams().<P>
 *
 * RTPSM only creates instances of the two subclasses of this class,
 * RTPRemoteParticipant and RTPLocalParticipant.  Of all the
 * Participants  objects managed by the  RTPSessionManager, only one
 * is the local participant and thus an instance of
 * RTPLocalParticipant. <P>
 *
 * All the other Participants in the session (obtainable via
 * RTPSM.getRemoteParticipants()) are "remote" and are instances of
 * RTPRemoteParticipant; calls to getStreams() on  remote participants
 * return a Vector of ReceiveStream objects.  The client can determine
 * whether  an Participant is local doing a simple "instanceof" test. <P>
 *
 * Participants are identified by the CNAME string, which is
 * transmitted in every  RTCP packet.Since a participant may begin
 * sending data packets *before* the CNAME of the  participant has
 * arrived in an RTCP packet, it is possible that a data stream will
 * exist, for a  short time, as "unassociated" with any participant.
 * See ReceiveStream for more details.  <P>
 *
 * Note that this abstraction defines a participant *within* a
 * session; in real  life, "participants"
 * can be involved in more than one RTP session at a time. <P>
 *
 */
public interface Participant
{
    /**
     * Retrieves a Vector which is the set of all RTPStream objects for
     * this  participant.  Note that if the participant is not sending a
     * stream  of RTP packets (i.e. it is a  "passive" participant),this
     * method  will return an empty Vector. Note that if this call is
     * made  after  data has started coming in from a new SSRC from this
     * participant, but before an RTCP packet  has arrived to map that
     * SSRC to this  participant, that receive stream will not turn up
     * in this call; when and if said RTCP packet arrives and the orphan
     * stream can  be associated with an  Participant, the
     * recvStreamMapped callback will be issued to all RTPSessionListeners.<P>
     *
     * If this is the local participant, the returned Vector will
     * contain null. if it is a remote participant it
     * will contain ReceiveStream objects.    <P>
     *
     * @return the Vector of RTPStream objects. <P>
     */
    public Vector 
    getStreams();
    /**
     * Returns a Vector of RTCPReport objects, each representing the
     * most recent  RTCP report for an SSRC sent by this participant.  In
     * most cases,  this Vector will contain  exactly one report, be it an
     * SR or RR,  because most participants (passive receivers and
     * single-stream senders) only send out one SSRC.  The exceptions are
     * those  participants sending multiple  data streams, in which case
     * there will be one report per stream (i.e. per SSRC); these reports
     * would also  be accessible via the getReport() call on each
     * individual  RTPStream.    <P>
     */
    public Vector
    getReports();
    /**
     * Provides a quick method to get the CNAME of this participant.
     * This value  can also be obtained from the RTCPReport objects
     * returned through getReports() on this participant. <P>
     *
     * @return the CNAME identifying this participant.   <P>
     */
    public String 
    getCNAME();
    /** 
     * Returns a Vector of RTCPSourceDescription objects.  Each such
     * object is one  field from the most recent RTCP SDES packet for
     * this  participant. Since typically the most recent SDES packet
     * will not contain all of the RTCPSourceDescription objects
     * simultaneously, the returned Vector contains the most recent SDES type
     * received from this participant, possibly from many RTCP
     * reports. (Each of the returned SDES types therefore may not be
     * from the  latest RTCP report necessarliy). A convenient method
     * to get at the source description  without having to go through
     * calling  getReports(),  enumerating the Vector, and  then
     * calling getSourceDescription()  on the  RTCPReport.<P>
     * @return the Vector representing the latest SDES report from this
     * participant.  May be an empty Vector.    <P>
     */
    public Vector
    getSourceDescription();
    
}