Merge "Even, Even more telecom javadoc." into lmp-mr1-dev

import java.util.concurrent.ConcurrentHashMap;

/**

 * A {@link android.app.Service} that provides telephone connections to processes running on an

 * Android device.

 * {@code ConnectionService} is an abstract service that should be implemented by any app which can

 * make phone calls and want those calls to be integrated into the built-in phone app.

 * Once implemented, the {@code ConnectionService} needs two additional steps before it will be

 * integrated into the phone app:

 * <p>

 * 1. <i>Registration in AndroidManifest.xml</i>

 * <br/>

 * <pre>

 * <service android:name="com.example.package.MyConnectionService"

 *    android:label="@string/some_label_for_my_connection_service"

 *    android:permission="android.permission.BIND_CONNECTION_SERVICE">

 *  <intent-filter>

 *   <action android:name="android.telecom.ConnectionService" />

 *  </intent-filter>

 * </service>

 * </pre>

 * <p>

 * 2. <i> Registration of {@link PhoneAccount} with {@link TelecomManager}.</i>

 * <br/>

 * See {@link PhoneAccount} and {@link TelecomManager#registerPhoneAccount} for more information.

 * <p>

 * Once registered and enabled by the user in the dialer settings, telecom will bind to a

 * {@code ConnectionService} implementation when it wants that {@code ConnectionService} to place

 * a call or the service has indicated that is has an incoming call through

 * {@link TelecomManager#addNewIncomingCall}. The {@code ConnectionService} can then expect a call

 * to {@link #onCreateIncomingConnection} or {@link #onCreateOutgoingConnection} wherein it

 * should provide a new instance of a {@link Connection} object.  It is through this

 * {@link Connection} object that telecom receives state updates and the {@code ConnectionService}

 * receives call-commands such as answer, reject, hold and disconnect.

 * <p>

 * When there are no more live calls, telecom will unbind from the {@code ConnectionService}.

 */

public abstract class ConnectionService extends Service {

    /**

    /**

     * Ask some other {@code ConnectionService} to create a {@code RemoteConnection} given an

     * incoming request. This is used to attach to existing incoming calls.

     * incoming request. This is used by {@code ConnectionService}s that are registered with

     * {@link PhoneAccount#CAPABILITY_CONNECTION_MANAGER} and want to be able to manage

     * SIM-based incoming calls.

     *

     * @param connectionManagerPhoneAccount See description at

     *         {@link #onCreateOutgoingConnection(PhoneAccountHandle, ConnectionRequest)}.

    /**

     * Ask some other {@code ConnectionService} to create a {@code RemoteConnection} given an

     * outgoing request. This is used to initiate new outgoing calls.

     * outgoing request. This is used by {@code ConnectionService}s that are registered with

     * {@link PhoneAccount#CAPABILITY_CONNECTION_MANAGER} and want to be able to use the

     * SIM-based {@code ConnectionService} to place its outgoing calls.

     *

     * @param connectionManagerPhoneAccount See description at

     *         {@link #onCreateOutgoingConnection(PhoneAccountHandle, ConnectionRequest)}.

    }

    /**

     * Adds two {@code RemoteConnection}s to some {@code RemoteConference}.

     * Indicates to the relevant {@code RemoteConnectionService} that the specified

     * {@link RemoteConnection}s should be merged into a conference call.

     * <p>

     * If the conference request is successful, the method {@link #onRemoteConferenceAdded} will

     * be invoked.

     *

     * @param remoteConnection1 The first of the remote connections to conference.

     * @param remoteConnection2 The second of the remote connections to conference.

     */

    public final void conferenceRemoteConnections(

            RemoteConnection a,

            RemoteConnection b) {

        mRemoteConnectionManager.conferenceRemoteConnections(a, b);

            RemoteConnection remoteConnection1,

            RemoteConnection remoteConnection2) {

        mRemoteConnectionManager.conferenceRemoteConnections(remoteConnection1, remoteConnection2);

    }

    /**

     */

    public void onConference(Connection connection1, Connection connection2) {}

    /**

     * Indicates that a remote conference has been created for existing {@link RemoteConnection}s.

     * When this method is invoked, this {@link ConnectionService} should create its own

     * representation of the conference call and send it to telecom using {@link #addConference}.

     * <p>

     * This is only relevant to {@link ConnectionService}s which are registered with

     * {@link PhoneAccount#CAPABILITY_CONNECTION_MANAGER}.

     *

     * @param conference The remote conference call.

     */

    public void onRemoteConferenceAdded(RemoteConference conference) {}

    /**