diff options
Diffstat (limited to 'telecomm/java/android')
13 files changed, 354 insertions, 41 deletions
diff --git a/telecomm/java/android/telecom/AudioState.java b/telecomm/java/android/telecom/AudioState.java index d0e2860..43da38f 100644 --- a/telecomm/java/android/telecom/AudioState.java +++ b/telecomm/java/android/telecom/AudioState.java @@ -22,7 +22,8 @@ import android.os.Parcelable; import java.util.Locale; /** - * Encapsulates all audio states during a call. + * Encapsulates the telecom audio state, including the current audio routing, supported audio + * routing and mute. */ public final class AudioState implements Parcelable { /** Direct the audio stream through the device's earpiece. */ @@ -53,10 +54,10 @@ public final class AudioState implements Parcelable { /** True if the call is muted, false otherwise. */ public final boolean isMuted; - /** The route to use for the audio stream. */ + /** The current audio route being used. */ public final int route; - /** Bit vector of all routes supported by this call. */ + /** Bit mask of all routes supported by this call. */ public final int supportedRouteMask; public AudioState(boolean isMuted, int route, int supportedRouteMask) { diff --git a/telecomm/java/android/telecom/Conference.java b/telecomm/java/android/telecom/Conference.java index 15cb786..6480a8a 100644 --- a/telecomm/java/android/telecom/Conference.java +++ b/telecomm/java/android/telecom/Conference.java @@ -207,6 +207,13 @@ public abstract class Conference { } /** + * @return The {@link DisconnectCause} for this connection. + */ + public final DisconnectCause getDisconnectCause() { + return mDisconnectCause; + } + + /** * Sets the capabilities of a conference. See {@link PhoneCapabilities} for valid values. * * @param capabilities A bitmask of the {@code PhoneCapabilities} of the conference call. @@ -334,6 +341,19 @@ public abstract class Conference { } /** + * Retrieves the primary connection associated with the conference. The primary connection is + * the connection from which the conference will retrieve its current state. + * + * @return The primary connection. + */ + public Connection getPrimaryConnection() { + if (mUnmodifiableChildConnections == null || mUnmodifiableChildConnections.isEmpty()) { + return null; + } + return mUnmodifiableChildConnections.get(0); + } + + /** * Inform this Conference that the state of its audio output has been changed externally. * * @param state The new audio state. diff --git a/telecomm/java/android/telecom/Connection.java b/telecomm/java/android/telecom/Connection.java index 9bdbba8..34d0660 100644 --- a/telecomm/java/android/telecom/Connection.java +++ b/telecomm/java/android/telecom/Connection.java @@ -974,6 +974,15 @@ public abstract class Connection { public void onDisconnect() {} /** + * Notifies this Connection of a request to disconnect a participant of the conference managed + * by the connection. + * + * @param endpoint the {@link Uri} of the participant to disconnect. + * @hide + */ + public void onDisconnectConferenceParticipant(Uri endpoint) {} + + /** * Notifies this Connection of a request to separate from its parent conference. */ public void onSeparate() {} diff --git a/telecomm/java/android/telecom/ConnectionService.java b/telecomm/java/android/telecom/ConnectionService.java index 649533e..4648d78 100644 --- a/telecomm/java/android/telecom/ConnectionService.java +++ b/telecomm/java/android/telecom/ConnectionService.java @@ -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); } /** @@ -822,6 +862,40 @@ public abstract class ConnectionService extends Service { } /** + * Adds a connection created by the {@link ConnectionService} and informs telecom of the new + * connection. + * + * @param phoneAccountHandle The phone account handle for the connection. + * @param connection The connection to add. + */ + public final void addExistingConnection(PhoneAccountHandle phoneAccountHandle, + Connection connection) { + + String id = addExistingConnectionInternal(connection); + if (id != null) { + List<String> emptyList = new ArrayList<>(0); + + ParcelableConnection parcelableConnection = new ParcelableConnection( + phoneAccountHandle, + connection.getState(), + connection.getCallCapabilities(), + connection.getAddress(), + connection.getAddressPresentation(), + connection.getCallerDisplayName(), + connection.getCallerDisplayNamePresentation(), + connection.getVideoProvider() == null ? + null : connection.getVideoProvider().getInterface(), + connection.getVideoState(), + connection.isRingbackRequested(), + connection.getAudioModeIsVoip(), + connection.getStatusHints(), + connection.getDisconnectCause(), + emptyList); + mAdapter.addExistingConnection(id, parcelableConnection); + } + } + + /** * Returns all the active {@code Connection}s for which this {@code ConnectionService} * has taken responsibility. * @@ -903,9 +977,25 @@ 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) {} /** + * Called when an existing connection is added remotely. + * @param connection The existing connection which was added. + */ + public void onRemoteExistingConnectionAdded(RemoteConnection connection) {} + + /** * @hide */ public boolean containsConference(Conference conference) { @@ -917,6 +1007,11 @@ public abstract class ConnectionService extends Service { onRemoteConferenceAdded(remoteConference); } + /** {@hide} */ + void addRemoteExistingConnection(RemoteConnection remoteConnection) { + onRemoteExistingConnectionAdded(remoteConnection); + } + private void onAccountsInitialized() { mAreAccountsInitialized = true; for (Runnable r : mPreInitializationConnectionRequests) { @@ -925,6 +1020,18 @@ public abstract class ConnectionService extends Service { mPreInitializationConnectionRequests.clear(); } + /** + * Adds an existing connection to the list of connections, identified by a new UUID. + * + * @param connection The connection. + * @return The UUID of the connection (e.g. the call-id). + */ + private String addExistingConnectionInternal(Connection connection) { + String id = UUID.randomUUID().toString(); + addConnection(id, connection); + return id; + } + private void addConnection(String callId, Connection connection) { mConnectionById.put(callId, connection); mIdByConnection.put(connection, callId); diff --git a/telecomm/java/android/telecom/ConnectionServiceAdapter.java b/telecomm/java/android/telecom/ConnectionServiceAdapter.java index c676172..e67af8c 100644 --- a/telecomm/java/android/telecom/ConnectionServiceAdapter.java +++ b/telecomm/java/android/telecom/ConnectionServiceAdapter.java @@ -344,4 +344,20 @@ final class ConnectionServiceAdapter implements DeathRecipient { } } } + + /** + * Informs telecom of an existing connection which was added by the {@link ConnectionService}. + * + * @param callId The unique ID of the call being added. + * @param connection The connection. + */ + void addExistingConnection(String callId, ParcelableConnection connection) { + Log.v(this, "addExistingConnection: %s", callId); + for (IConnectionServiceAdapter adapter : mAdapters) { + try { + adapter.addExistingConnection(callId, connection); + } catch (RemoteException ignored) { + } + } + } } diff --git a/telecomm/java/android/telecom/ConnectionServiceAdapterServant.java b/telecomm/java/android/telecom/ConnectionServiceAdapterServant.java index 217dbc3..519a400 100644 --- a/telecomm/java/android/telecom/ConnectionServiceAdapterServant.java +++ b/telecomm/java/android/telecom/ConnectionServiceAdapterServant.java @@ -57,6 +57,7 @@ final class ConnectionServiceAdapterServant { private static final int MSG_SET_ADDRESS = 18; private static final int MSG_SET_CALLER_DISPLAY_NAME = 19; private static final int MSG_SET_CONFERENCEABLE_CONNECTIONS = 20; + private static final int MSG_ADD_EXISTING_CONNECTION = 21; private final IConnectionServiceAdapter mDelegate; @@ -199,6 +200,16 @@ final class ConnectionServiceAdapterServant { } break; } + case MSG_ADD_EXISTING_CONNECTION: { + SomeArgs args = (SomeArgs) msg.obj; + try { + mDelegate.addExistingConnection( + (String) args.arg1, (ParcelableConnection) args.arg2); + } finally { + args.recycle(); + } + break; + } } } }; @@ -345,6 +356,15 @@ final class ConnectionServiceAdapterServant { args.arg2 = conferenceableConnectionIds; mHandler.obtainMessage(MSG_SET_CONFERENCEABLE_CONNECTIONS, args).sendToTarget(); } + + @Override + public final void addExistingConnection( + String connectionId, ParcelableConnection connection) { + SomeArgs args = SomeArgs.obtain(); + args.arg1 = connectionId; + args.arg2 = connection; + mHandler.obtainMessage(MSG_ADD_EXISTING_CONNECTION, args).sendToTarget(); + } }; public ConnectionServiceAdapterServant(IConnectionServiceAdapter delegate) { diff --git a/telecomm/java/android/telecom/DisconnectCause.java b/telecomm/java/android/telecom/DisconnectCause.java index 9be0138..73bcd0c 100644 --- a/telecomm/java/android/telecom/DisconnectCause.java +++ b/telecomm/java/android/telecom/DisconnectCause.java @@ -25,9 +25,10 @@ import java.util.Objects; /** * Describes the cause of a disconnected call. This always includes a code describing the generic - * cause of the disconnect. Optionally, it may include a localized label and/or localized description - * to display to the user which is provided by the {@link ConnectionService}. It also may contain a - * reason for the the disconnect, which is intended for logging and not for display to the user. + * cause of the disconnect. Optionally, it may include a label and/or description to display to the + * user. It is the responsibility of the {@link ConnectionService} to provide localized versions of + * the label and description. It also may contain a reason for the disconnect, which is intended for + * logging and not for display to the user. */ public final class DisconnectCause implements Parcelable { @@ -57,6 +58,11 @@ public final class DisconnectCause implements Parcelable { public static final int RESTRICTED = 8; /** Disconnected for reason not described by other disconnect codes. */ public static final int OTHER = 9; + /** + * Disconnected because the connection manager did not support the call. The call will be tried + * again without a connection manager. See {@link PhoneAccount#CAPABILITY_CONNECTION_MANAGER}. + */ + public static final int CONNECTION_MANAGER_NOT_SUPPORTED = 10; private int mDisconnectCode; private CharSequence mDisconnectLabel; @@ -85,6 +91,7 @@ public final class DisconnectCause implements Parcelable { /** * Creates a new DisconnectCause. + * * @param label The localized label to show to the user to explain the disconnect. * @param code The code for the disconnect cause. * @param description The localized description to show to the user to explain the disconnect. @@ -218,7 +225,10 @@ public final class DisconnectCause implements Parcelable { @Override public String toString() { String code = ""; - switch (getCode()) { + switch (mDisconnectCode) { + case UNKNOWN: + code = "UNKNOWN"; + break; case ERROR: code = "ERROR"; break; @@ -228,6 +238,9 @@ public final class DisconnectCause implements Parcelable { case REMOTE: code = "REMOTE"; break; + case CANCELED: + code = "CANCELED"; + break; case MISSED: code = "MISSED"; break; @@ -243,9 +256,12 @@ public final class DisconnectCause implements Parcelable { case OTHER: code = "OTHER"; break; - case UNKNOWN: + case CONNECTION_MANAGER_NOT_SUPPORTED: + code = "CONNECTION_MANAGER_NOT_SUPPORTED"; + break; default: - code = "UNKNOWN"; + code = "invalid code: " + mDisconnectCode; + break; } String label = mDisconnectLabel == null ? "" : mDisconnectLabel.toString(); String description = mDisconnectDescription == null diff --git a/telecomm/java/android/telecom/GatewayInfo.java b/telecomm/java/android/telecom/GatewayInfo.java index 583c3e2..7105602 100644 --- a/telecomm/java/android/telecom/GatewayInfo.java +++ b/telecomm/java/android/telecom/GatewayInfo.java @@ -23,12 +23,16 @@ import android.os.Parcelable; import android.text.TextUtils; /** - * When calls are made, they may contain gateway information for services which route phone calls - * through their own service/numbers. The data consists of a number to call and the package name of - * the service. This data is used in two ways: + * Encapsulated gateway address information for outgoing call. When calls are made, the system + * provides a facility to specify two addresses for the call: one to display as the address being + * dialed and a separate (gateway) address to actually dial. Telecom provides this information to + * {@link ConnectionService}s when placing the call as an instance of {@code GatewayInfo}. + * <p> + * The data consists of an address to call, an address to display and the package name of the + * service. This data is used in two ways: * <ol> - * <li> Call the appropriate routing number - * <li> Display information about how the call is being routed to the user + * <li> Call the appropriate gateway address. + * <li> Display information about how the call is being routed to the user. * </ol> */ public class GatewayInfo implements Parcelable { @@ -46,31 +50,39 @@ public class GatewayInfo implements Parcelable { } /** - * Package name of the gateway provider service. used to place the call with. + * Package name of the gateway provider service that provided the gateway information. + * This can be used to identify the gateway address source and to load an appropriate icon when + * displaying gateway information in the in-call UI. */ public String getGatewayProviderPackageName() { return mGatewayProviderPackageName; } /** - * Gateway provider address to use when actually placing the call. + * Returns the gateway address to dial when placing the call. */ public Uri getGatewayAddress() { return mGatewayAddress; } /** - * The actual call address that the user is trying to connect to via the gateway. + * Returns the address that the user is trying to connect to via the gateway. */ public Uri getOriginalAddress() { return mOriginalAddress; } + /** + * Indicates whether this {@code GatewayInfo} instance contains any data. A returned value of + * false indicates that no gateway number is being used for the call. + */ public boolean isEmpty() { return TextUtils.isEmpty(mGatewayProviderPackageName) || mGatewayAddress == null; } - /** Implement the Parcelable interface */ + /** + * The Parcelable interface. + * */ public static final Parcelable.Creator<GatewayInfo> CREATOR = new Parcelable.Creator<GatewayInfo> () { diff --git a/telecomm/java/android/telecom/PhoneAccountHandle.java b/telecomm/java/android/telecom/PhoneAccountHandle.java index 768188b..bc4cc8c 100644 --- a/telecomm/java/android/telecom/PhoneAccountHandle.java +++ b/telecomm/java/android/telecom/PhoneAccountHandle.java @@ -23,7 +23,16 @@ import android.os.Parcelable; import java.util.Objects; /** - * The unique identifier for a {@link PhoneAccount}. + * The unique identifier for a {@link PhoneAccount}. A {@code PhoneAccountHandle} is made of two + * parts: + * <ul> + * <li>The component name of the associated {@link ConnectionService}.</li> + * <li>A string identifier that is unique across {@code PhoneAccountHandle}s with the same + * component name.</li> + * </ul> + * + * See {@link PhoneAccount}, + * {@link TelecomManager#registerPhoneAccount TelecomManager.registerPhoneAccount}. */ public class PhoneAccountHandle implements Parcelable { private ComponentName mComponentName; diff --git a/telecomm/java/android/telecom/PhoneCapabilities.java b/telecomm/java/android/telecom/PhoneCapabilities.java index 9c67503..3d3c6bd 100644 --- a/telecomm/java/android/telecom/PhoneCapabilities.java +++ b/telecomm/java/android/telecom/PhoneCapabilities.java @@ -17,8 +17,8 @@ package android.telecom; /** - * Defines capabilities a phone call can support, such as conference calling and video telephony. - * Also defines properties of a phone call, such as whether it is using VoLTE technology. + * Defines capabilities for {@link Connection}s and {@link Conference}s such as hold, swap, and + * merge. */ public final class PhoneCapabilities { /** Call can currently be put on hold or unheld. */ @@ -28,15 +28,22 @@ public final class PhoneCapabilities { public static final int SUPPORT_HOLD = 0x00000002; /** - * Calls within a conference can be merged. Some connection services create a conference call - * only after two calls have been merged. However, a conference call can also be added the - * moment there are more than one call. CDMA calls are implemented in this way because the call - * actions are more limited when more than one call exists. This flag allows merge to be exposed - * as a capability on the conference call instead of individual calls. + * Calls within a conference can be merged. A {@link ConnectionService} has the option to + * add a {@link Conference} call before the child {@link Connection}s are merged. This is how + * CDMA-based {@link Connection}s are implemented. For these unmerged {@link Conference}s, this + * capability allows a merge button to be shown while the conference call is in the foreground + * of the in-call UI. + * <p> + * This is only intended for use by a {@link Conference}. */ public static final int MERGE_CONFERENCE = 0x00000004; - /** Calls withing a conference can be swapped between foreground and background. */ + /** + * Calls within a conference can be swapped between foreground and background. + * See {@link #MERGE_CONFERENCE} for additional information. + * <p> + * This is only intended for use by a {@link Conference}. + */ public static final int SWAP_CONFERENCE = 0x00000008; /** Call currently supports adding another call to this one. */ @@ -49,8 +56,8 @@ public final class PhoneCapabilities { public static final int MUTE = 0x00000040; /** - * Call supports conference call management. This capability only applies to conference calls - * which can have other calls as children. + * Call supports conference call management. This capability only applies to {@link Conference} + * calls which can have {@link Connection}s as children. */ public static final int MANAGE_CONFERENCE = 0x00000080; diff --git a/telecomm/java/android/telecom/RemoteConnection.java b/telecomm/java/android/telecom/RemoteConnection.java index 9a094df..816e2bf 100644 --- a/telecomm/java/android/telecom/RemoteConnection.java +++ b/telecomm/java/android/telecom/RemoteConnection.java @@ -407,6 +407,29 @@ public final class RemoteConnection { } /** + * @hide + */ + RemoteConnection(String callId, IConnectionService connectionService, + ParcelableConnection connection) { + mConnectionId = callId; + mConnectionService = connectionService; + mConnected = true; + mState = connection.getState(); + mDisconnectCause = connection.getDisconnectCause(); + mRingbackRequested = connection.isRingbackRequested(); + mCallCapabilities = connection.getCapabilities(); + mVideoState = connection.getVideoState(); + mVideoProvider = new RemoteConnection.VideoProvider(connection.getVideoProvider()); + mIsVoipAudioMode = connection.getIsVoipAudioMode(); + mStatusHints = connection.getStatusHints(); + mAddress = connection.getHandle(); + mAddressPresentation = connection.getHandlePresentation(); + mCallerDisplayName = connection.getCallerDisplayName(); + mCallerDisplayNamePresentation = connection.getCallerDisplayNamePresentation(); + mConference = null; + } + + /** * Create a RemoteConnection which is used for failed connections. Note that using it for any * "real" purpose will almost certainly fail. Callers should note the failure and act * accordingly (moving on to another RemoteConnection, for example) @@ -415,7 +438,7 @@ public final class RemoteConnection { * @hide */ RemoteConnection(DisconnectCause disconnectCause) { - this("NULL", null, null); + mConnectionId = "NULL"; mConnected = false; mState = Connection.STATE_DISCONNECTED; mDisconnectCause = disconnectCause; diff --git a/telecomm/java/android/telecom/RemoteConnectionService.java b/telecomm/java/android/telecom/RemoteConnectionService.java index af4ee22..4bb78c0 100644 --- a/telecomm/java/android/telecom/RemoteConnectionService.java +++ b/telecomm/java/android/telecom/RemoteConnectionService.java @@ -41,8 +41,9 @@ import java.util.UUID; */ final class RemoteConnectionService { + // Note: Casting null to avoid ambiguous constructor reference. private static final RemoteConnection NULL_CONNECTION = - new RemoteConnection("NULL", null, null); + new RemoteConnection("NULL", null, (ConnectionRequest) null); private static final RemoteConference NULL_CONFERENCE = new RemoteConference("NULL", null); @@ -286,6 +287,15 @@ final class RemoteConnectionService { .setConferenceableConnections(conferenceable); } } + + @Override + public void addExistingConnection(String callId, ParcelableConnection connection) { + // TODO: add contents of this method + RemoteConnection remoteConnction = new RemoteConnection(callId, + mOutgoingConnectionServiceRpc, connection); + + mOurConnectionServiceImpl.addRemoteExistingConnection(remoteConnction); + } }; private final ConnectionServiceAdapterServant mServant = diff --git a/telecomm/java/android/telecom/TelecomManager.java b/telecomm/java/android/telecom/TelecomManager.java index bc51a70..d98a255 100644 --- a/telecomm/java/android/telecom/TelecomManager.java +++ b/telecomm/java/android/telecom/TelecomManager.java @@ -17,6 +17,7 @@ package android.telecom; import android.annotation.SystemApi; import android.content.ComponentName; import android.content.Context; +import android.net.Uri; import android.os.Bundle; import android.os.RemoteException; import android.os.ServiceManager; @@ -31,7 +32,17 @@ import java.util.Collections; import java.util.List; /** - * Provides access to Telecom-related functionality. + * Provides access to information about active calls and registration/call-management functionality. + * Apps can use methods in this class to determine the current call state. Apps can also register new + * {@link PhoneAccount}s and get a listing of existing {@link PhoneAccount}s. + * <p> + * Apps do not instantiate this class directly; instead, they retrieve a reference to an instance + * through {@link Context#getSystemService Context.getSystemService(Context.TELECOM_SERVICE)}. + * <p> + * Note that access to some telecom information is permission-protected. Your app cannot access the + * protected information or gain access to protected functionality unless it has the appropriate + * permissions declared in its manifest file. Where permissions apply, they are noted in the method + * descriptions. */ public class TelecomManager { @@ -583,7 +594,16 @@ public class TelecomManager { } /** - * Register a {@link PhoneAccount} for use by the system. + * Register a {@link PhoneAccount} for use by the system. When registering + * {@link PhoneAccount}s, existing registrations will be overwritten if the + * {@link PhoneAccountHandle} matches that of a {@link PhoneAccount} which is already + * registered. Once registered, the {@link PhoneAccount} is listed to the user as an option + * when placing calls. The user may still need to enable the {@link PhoneAccount} within + * the phone app settings before the account is usable. + * <p> + * A {@link SecurityException} will be thrown if an app tries to register a + * {@link PhoneAccountHandle} where the package name specified within + * {@link PhoneAccountHandle#getComponentName()} does not match the package name of the app. * * @param account The complete {@link PhoneAccount}. */ @@ -876,6 +896,7 @@ public class TelecomManager { * Processes the specified dial string as an MMI code. * MMI codes are any sequence of characters entered into the dialpad that contain a "*" or "#". * Some of these sequences launch special behavior through handled by Telephony. + * This method uses the default subscription. * <p> * Requires that the method-caller be set as the system dialer app. * </p> @@ -896,6 +917,48 @@ public class TelecomManager { } /** + * Processes the specified dial string as an MMI code. + * MMI codes are any sequence of characters entered into the dialpad that contain a "*" or "#". + * Some of these sequences launch special behavior through handled by Telephony. + * <p> + * Requires that the method-caller be set as the system dialer app. + * </p> + * + * @param accountHandle The handle for the account the MMI code should apply to. + * @param dialString The digits to dial. + * @return True if the digits were processed as an MMI code, false otherwise. + */ + public boolean handleMmi(PhoneAccountHandle accountHandle, String dialString) { + ITelecomService service = getTelecomService(); + if (service != null) { + try { + return service.handlePinMmiForPhoneAccount(accountHandle, dialString); + } catch (RemoteException e) { + Log.e(TAG, "Error calling ITelecomService#handlePinMmi", e); + } + } + return false; + } + + /** + * @param accountHandle The handle for the account to derive an adn query URI for or + * {@code null} to return a URI which will use the default account. + * @return The URI (with the content:// scheme) specific to the specified {@link PhoneAccount} + * for the the content retrieve. + */ + public Uri getAdnUriForPhoneAccount(PhoneAccountHandle accountHandle) { + ITelecomService service = getTelecomService(); + if (service != null && accountHandle != null) { + try { + return service.getAdnUriForPhoneAccount(accountHandle); + } catch (RemoteException e) { + Log.e(TAG, "Error calling ITelecomService#getAdnUriForPhoneAccount", e); + } + } + return Uri.parse("content://icc/adn"); + } + + /** * Removes the missed-call notification if one is present. * <p> * Requires that the method-caller be set as the system dialer app. |