am 58ef48cb: Merge "Even, Even more telecom javadoc." into lmp-mr1-dev (a79cf3c1) · Commits · e / os / android_frameworks_base

telecomm/java/android/telecom/ConnectionService.java

+58 −8

Original line number	Diff line number	Diff line
		@@ -40,8 +40,37 @@ import java.util.UUID;
		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 {
		/**
		@@ -746,7 +775,9 @@ 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)}.
		@@ -763,7 +794,9 @@ public abstract class ConnectionService extends Service {

		/**
		* 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)}.
		@@ -779,12 +812,19 @@ public abstract class ConnectionService extends Service {
		}

		/**
		* 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);
		}

		/**
		@@ -937,6 +977,16 @@ public abstract class ConnectionService extends Service {
		*/
		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) {}

		/**