Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Make MBMS group call API changes

Browse Source 
Change the API to respond to API council comments
See bug for details

Bug: 117145859
Test: CTS
Change-Id: I4342e6e95da57fbcd550c571357ff7bc1923b70a
This commit is contained in:
Hall Liu
2018-10-08 18:23:53 -07:00
parent c02d53b081
commit c81cba4e2b
10 changed files with 117 additions and 79 deletions
Download Patch File Download Diff File Expand all files Collapse all files

31
api/current.txt
View File

@@ -42453,9 +42453,9 @@ package android.telephony {
public class MbmsGroupCallSession implements java.lang.AutoCloseable {
method public void close();
method public static android.telephony.MbmsGroupCallSession create(android.content.Context, java.util.concurrent.Executor, int, android.telephony.mbms.MbmsGroupCallSessionCallback);
method public static android.telephony.MbmsGroupCallSession create(android.content.Context, int, java.util.concurrent.Executor, android.telephony.mbms.MbmsGroupCallSessionCallback);
method public static android.telephony.MbmsGroupCallSession create(android.content.Context, java.util.concurrent.Executor, android.telephony.mbms.MbmsGroupCallSessionCallback);
method public android.telephony.mbms.GroupCall startGroupCall(java.util.concurrent.Executor, long, int[], int[], android.telephony.mbms.GroupCallCallback);
method public android.telephony.mbms.GroupCall startGroupCall(long, java.util.List<java.lang.Integer>, java.util.List<java.lang.Integer>, java.util.concurrent.Executor, android.telephony.mbms.GroupCallCallback);
}
public class MbmsStreamingSession implements java.lang.AutoCloseable {
@@ -43447,7 +43447,7 @@ package android.telephony.mbms {
public class GroupCall implements java.lang.AutoCloseable {
method public void close();
method public long getTmgi();
method public void updateGroupCall(int[], int[]);
method public void updateGroupCall(java.util.List<java.lang.Integer>, java.util.List<java.lang.Integer>);
field public static final int REASON_BY_USER_REQUEST = 1; // 0x1
field public static final int REASON_FREQUENCY_CONFLICT = 3; // 0x3
field public static final int REASON_LEFT_MBMS_BROADCAST_AREA = 6; // 0x6
@@ -43459,11 +43459,10 @@ package android.telephony.mbms {
field public static final int STATE_STOPPED = 1; // 0x1
}
public class GroupCallCallback {
ctor public GroupCallCallback();
method public void onBroadcastSignalStrengthUpdated(int);
method public void onError(int, java.lang.String);
method public void onGroupCallStateChanged(int, int);
public abstract interface GroupCallCallback {
method public abstract void onBroadcastSignalStrengthUpdated(int);
method public abstract void onError(int, java.lang.String);
method public abstract void onGroupCallStateChanged(int, int);
field public static final int SIGNAL_STRENGTH_UNAVAILABLE = -1; // 0xffffffff
}
@@ -43503,6 +43502,11 @@ package android.telephony.mbms {
field public static final int ERROR_UNABLE_TO_READ_SIM = 206; // 0xce
}
public static class MbmsErrors.GroupCallErrors {
field public static final int ERROR_DUPLICATE_START_GROUP_CALL = 502; // 0x1f6
field public static final int ERROR_UNABLE_TO_START_SERVICE = 501; // 0x1f5
}
public static class MbmsErrors.InitializationErrors {
field public static final int ERROR_APP_PERMISSIONS_NOT_GRANTED = 102; // 0x66
field public static final int ERROR_DUPLICATE_INITIALIZE = 101; // 0x65
@@ -43515,12 +43519,11 @@ package android.telephony.mbms {
field public static final int ERROR_UNABLE_TO_START_SERVICE = 302; // 0x12e
}
public class MbmsGroupCallSessionCallback {
ctor public MbmsGroupCallSessionCallback();
method public void onAvailableSaisUpdated(java.util.List<java.lang.Integer>, java.util.List<java.util.List<java.lang.Integer>>);
method public void onError(int, java.lang.String);
method public void onMiddlewareReady();
method public void onServiceInterfaceAvailable(java.lang.String, int);
public abstract interface MbmsGroupCallSessionCallback {
method public abstract void onAvailableSaisUpdated(java.util.List<java.lang.Integer>, java.util.List<java.util.List<java.lang.Integer>>);
method public abstract void onError(int, java.lang.String);
method public abstract void onMiddlewareReady();
method public abstract void onServiceInterfaceAvailable(java.lang.String, int);
}
public class MbmsStreamingSessionCallback {

4
api/system-current.txt
View File

@@ -6549,9 +6549,9 @@ package android.telephony.mbms.vendor {
method public int initialize(android.telephony.mbms.MbmsGroupCallSessionCallback, int) throws android.os.RemoteException;
method public void onAppCallbackDied(int, int);
method public android.os.IBinder onBind(android.content.Intent);
method public int startGroupCall(int, long, int[], int[], android.telephony.mbms.GroupCallCallback);
method public int startGroupCall(int, long, java.util.List<java.lang.Integer>, java.util.List<java.lang.Integer>, android.telephony.mbms.GroupCallCallback);
method public void stopGroupCall(int, long);
method public void updateGroupCall(int, long, int[], int[]);
method public void updateGroupCall(int, long, java.util.List<java.lang.Integer>, java.util.List<java.lang.Integer>);
}
public class MbmsStreamingServiceBase extends android.os.Binder {

4
api/test-current.txt
View File

@@ -1050,9 +1050,9 @@ package android.telephony.mbms.vendor {
method public int initialize(android.telephony.mbms.MbmsGroupCallSessionCallback, int) throws android.os.RemoteException;
method public void onAppCallbackDied(int, int);
method public android.os.IBinder onBind(android.content.Intent);
method public int startGroupCall(int, long, int[], int[], android.telephony.mbms.GroupCallCallback);
method public int startGroupCall(int, long, java.util.List<java.lang.Integer>, java.util.List<java.lang.Integer>, android.telephony.mbms.GroupCallCallback);
method public void stopGroupCall(int, long);
method public void updateGroupCall(int, long, int[], int[]);
method public void updateGroupCall(int, long, java.util.List<java.lang.Integer>, java.util.List<java.lang.Integer>);
}
public class MbmsStreamingServiceBase extends android.os.Binder {

24
telephony/java/android/telephony/MbmsGroupCallSession.java
View File

@@ -37,6 +37,7 @@ import android.telephony.mbms.vendor.IMbmsGroupCallService;
import android.util.ArraySet;
import android.util.Log;
import java.util.List;
import java.util.Set;
import java.util.concurrent.Executor;
import java.util.concurrent.atomic.AtomicBoolean;
@@ -107,14 +108,14 @@ public class MbmsGroupCallSession implements AutoCloseable {
* {@link MbmsGroupCallSession} that you received before calling this method again.
*
* @param context The {@link Context} to use.
* @param executor The executor on which you wish to execute callbacks.
* @param subscriptionId The subscription ID to use.
* @param executor The executor on which you wish to execute callbacks.
* @param callback A callback object on which you wish to receive results of asynchronous
* operations.
* @return An instance of {@link MbmsGroupCallSession}, or null if an error occurred.
*/
public static @Nullable MbmsGroupCallSession create(@NonNull Context context,
@NonNull Executor executor, int subscriptionId,
int subscriptionId, @NonNull Executor executor,
final @NonNull MbmsGroupCallSessionCallback callback) {
if (!sIsInitialized.compareAndSet(false, true)) {
throw new IllegalStateException("Cannot create two instances of MbmsGroupCallSession");
@@ -138,11 +139,11 @@ public class MbmsGroupCallSession implements AutoCloseable {
/**
* Create a new {@link MbmsGroupCallSession} using the system default data subscription ID.
* See {@link #create(Context, Executor, int, MbmsGroupCallSessionCallback)}.
* See {@link #create(Context, int, Executor, MbmsGroupCallSessionCallback)}.
*/
public static MbmsGroupCallSession create(@NonNull Context context,
@NonNull Executor executor, @NonNull MbmsGroupCallSessionCallback callback) {
return create(context, executor, SubscriptionManager.getDefaultSubscriptionId(), callback);
return create(context, SubscriptionManager.getDefaultSubscriptionId(), executor, callback);
}
/**
@@ -153,7 +154,7 @@ public class MbmsGroupCallSession implements AutoCloseable {
* instance of {@link MbmsGroupCallSessionCallback}, but callbacks that have already been
* enqueued will still be delivered.
*
* It is safe to call {@link #create(Context, Executor, int, MbmsGroupCallSessionCallback)} to
* It is safe to call {@link #create(Context, int, Executor, MbmsGroupCallSessionCallback)} to
* obtain another instance of {@link MbmsGroupCallSession} immediately after this method
* returns.
*
@@ -189,18 +190,19 @@ public class MbmsGroupCallSession implements AutoCloseable {
* Asynchronous errors through the callback include any of the errors in
* {@link MbmsErrors.GeneralErrors}.
*
* @param executor The executor on which you wish to execute callbacks for this stream.
* @param tmgi The TMGI, an identifier for the group call you want to join.
* @param saiArray An array of SAIs for the group call that should be negotiated separately with
* @param saiList A list of SAIs for the group call that should be negotiated separately with
* the carrier.
* @param frequencyArray An array of frequencies for the group call that should be negotiated
* @param frequencyList A lost of frequencies for the group call that should be negotiated
* separately with the carrier.
* @param executor The executor on which you wish to execute callbacks for this stream.
* @param callback The callback that you want to receive information about the call on.
* @return An instance of {@link GroupCall} through which the call can be controlled.
* May be {@code null} if an error occurred.
*/
public @Nullable GroupCall startGroupCall(@NonNull Executor executor, long tmgi, int[] saiArray,
int[] frequencyArray, @NonNull GroupCallCallback callback) {
public @Nullable GroupCall startGroupCall(long tmgi, @NonNull List<Integer> saiList,
@NonNull List<Integer> frequencyList, @NonNull Executor executor,
@NonNull GroupCallCallback callback) {
IMbmsGroupCallService groupCallService = mService.get();
if (groupCallService == null) {
throw new IllegalStateException("Middleware not yet bound");
@@ -215,7 +217,7 @@ public class MbmsGroupCallSession implements AutoCloseable {
try {
int returnCode = groupCallService.startGroupCall(
mSubscriptionId, tmgi, saiArray, frequencyArray, serviceCallback);
mSubscriptionId, tmgi, saiList, frequencyList, serviceCallback);
if (returnCode == MbmsErrors.UNKNOWN) {
// Unbind and throw an obvious error
close();

29
telephony/java/android/telephony/mbms/GroupCall.java
View File

@@ -17,6 +17,7 @@
package android.telephony.mbms;
import android.annotation.IntDef;
import android.annotation.NonNull;
import android.os.RemoteException;
import android.telephony.MbmsGroupCallSession;
import android.telephony.mbms.vendor.IMbmsGroupCallService;
@@ -24,6 +25,7 @@ import android.util.Log;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.util.List;
/**
* Class used to represent a single MBMS group call. After a call has been started with
@@ -41,8 +43,26 @@ public class GroupCall implements AutoCloseable {
@Retention(RetentionPolicy.SOURCE)
@IntDef(prefix = { "STATE_" }, value = {STATE_STOPPED, STATE_STARTED, STATE_STALLED})
public @interface GroupCallState {}
/**
* Indicates that the group call is in a stopped state
*
* This can be reported after network action or after calling {@link #close}.
*/
public static final int STATE_STOPPED = 1;
/**
* Indicates that the group call is started.
*
* Data can be transmitted and received in this state.
*/
public static final int STATE_STARTED = 2;
/**
* Indicates that the group call is stalled.
*
* This may be due to a network issue or the device being temporarily out of range.
*/
public static final int STATE_STALLED = 3;
/**
@@ -122,16 +142,17 @@ public class GroupCall implements AutoCloseable {
* Send an update to the middleware when the SAI (Service Area Identifier) list and frequency
* information of the group call has * changed. Callers must obtain this information from the
* wireless carrier independently.
* @param saiArray New array of SAIs that the call is available on.
* @param frequencyArray New array of frequencies that the call is available on.
* @param saiList New list of SAIs that the call is available on.
* @param frequencyList New list of frequencies that the call is available on.
*/
public void updateGroupCall(int[] saiArray, int[] frequencyArray) {
public void updateGroupCall(@NonNull List<Integer> saiList,
@NonNull List<Integer> frequencyList) {
if (mService == null) {
throw new IllegalStateException("No group call service attached");
}
try {
mService.updateGroupCall(mSubscriptionId, mTmgi, saiArray, frequencyArray);
mService.updateGroupCall(mSubscriptionId, mTmgi, saiList, frequencyList);
} catch (RemoteException e) {
Log.w(LOG_TAG, "Remote process died");
mService = null;

21
telephony/java/android/telephony/mbms/GroupCallCallback.java
View File

@@ -17,6 +17,7 @@
package android.telephony.mbms;
import android.annotation.IntDef;
import android.annotation.IntRange;
import android.annotation.Nullable;
import java.lang.annotation.Retention;
@@ -26,7 +27,7 @@ import java.lang.annotation.RetentionPolicy;
* A callback class for use when the application is in a group call. The middleware
* will provide updates on the status of the call via this callback.
*/
public class GroupCallCallback {
public interface GroupCallCallback {
/** @hide */
@Retention(RetentionPolicy.SOURCE)
@IntDef(value = {
@@ -40,7 +41,7 @@ public class GroupCallCallback {
MbmsErrors.GeneralErrors.ERROR_NOT_CONNECTED_TO_HOME_CARRIER_LTE,
MbmsErrors.GeneralErrors.ERROR_UNABLE_TO_READ_SIM,
MbmsErrors.GeneralErrors.ERROR_CARRIER_CHANGE_NOT_ALLOWED}, prefix = { "ERROR_" })
private @interface GroupCallError{}
@interface GroupCallError{}
/**
* Indicates broadcast signal strength is not available for this call.
@@ -48,7 +49,7 @@ public class GroupCallCallback {
* This may be due to the call no longer being available due to geography
* or timing (end of service)
*/
public static final int SIGNAL_STRENGTH_UNAVAILABLE = -1;
int SIGNAL_STRENGTH_UNAVAILABLE = -1;
/**
* Called by the middleware when it has detected an error condition in this group call. The
@@ -56,9 +57,7 @@ public class GroupCallCallback {
* @param errorCode The error code.
* @param message A human-readable message generated by the middleware for debugging purposes.
*/
public void onError(@GroupCallError int errorCode, @Nullable String message) {
// default implementation empty
}
void onError(@GroupCallError int errorCode, @Nullable String message);
/**
* Called to indicate this call has changed state.
@@ -66,10 +65,8 @@ public class GroupCallCallback {
* See {@link GroupCall#STATE_STOPPED}, {@link GroupCall#STATE_STARTED}
* and {@link GroupCall#STATE_STALLED}.
*/
public void onGroupCallStateChanged(@GroupCall.GroupCallState int state,
@GroupCall.GroupCallStateChangeReason int reason) {
// default implementation empty
}
void onGroupCallStateChanged(@GroupCall.GroupCallState int state,
@GroupCall.GroupCallStateChangeReason int reason);
/**
* Broadcast Signal Strength updated.
@@ -81,7 +78,5 @@ public class GroupCallCallback {
* {@link #SIGNAL_STRENGTH_UNAVAILABLE} if broadcast is not available
* for this call due to timing, geography or popularity.
*/
public void onBroadcastSignalStrengthUpdated(int signalStrength) {
// default implementation empty
}
void onBroadcastSignalStrengthUpdated(@IntRange(from = -1, to = 4) int signalStrength);
}

16
telephony/java/android/telephony/mbms/MbmsErrors.java
View File

@@ -140,5 +140,21 @@ public class MbmsErrors {
public static final int ERROR_UNKNOWN_FILE_INFO = 403;
}
/**
* Indicates the errors that are applicable only to the group call use-case.
*/
public static class GroupCallErrors {
private GroupCallErrors() { }
/** Indicates that the middleware was unable to start the group call. */
public static final int ERROR_UNABLE_TO_START_SERVICE = 501;
/**
* Indicates that the app called
* {@link android.telephony.MbmsGroupCallSession#startGroupCall} more than once for the
* same {@code tmgi}.
*/
public static final int ERROR_DUPLICATE_START_GROUP_CALL = 502;
}
private MbmsErrors() {}
}

30
telephony/java/android/telephony/mbms/MbmsGroupCallSessionCallback.java
View File

@@ -17,6 +17,7 @@
package android.telephony.mbms;
import android.annotation.IntDef;
import android.annotation.NonNull;
import android.annotation.Nullable;
import android.content.Context;
import android.telephony.MbmsGroupCallSession;
@@ -29,9 +30,9 @@ import java.util.concurrent.Executor;
/**
* A callback class that is used to receive information from the middleware on MBMS group-call
* services. An instance of this object should be passed into
* {@link MbmsGroupCallSession#create(Context, Executor, int, MbmsGroupCallSessionCallback)}.
* {@link MbmsGroupCallSession#create(Context, int, Executor, MbmsGroupCallSessionCallback)}.
*/
public class MbmsGroupCallSessionCallback {
public interface MbmsGroupCallSessionCallback {
/** @hide */
@Retention(RetentionPolicy.SOURCE)
@IntDef(value = {
@@ -48,7 +49,7 @@ public class MbmsGroupCallSessionCallback {
MbmsErrors.GeneralErrors.ERROR_NOT_CONNECTED_TO_HOME_CARRIER_LTE,
MbmsErrors.GeneralErrors.ERROR_UNABLE_TO_READ_SIM,
MbmsErrors.GeneralErrors.ERROR_CARRIER_CHANGE_NOT_ALLOWED}, prefix = { "ERROR_" })
private @interface GroupCallError{}
@interface GroupCallError{}
/**
* Called by the middleware when it has detected an error condition. The possible error codes
@@ -56,8 +57,7 @@ public class MbmsGroupCallSessionCallback {
* @param errorCode The error code.
* @param message A human-readable message generated by the middleware for debugging purposes.
*/
public void onError(@GroupCallError int errorCode, @Nullable String message) {
}
void onError(@GroupCallError int errorCode, @Nullable String message);
/**
* Indicates that the list of currently available SAIs has been updated. The app may use this
@@ -70,21 +70,22 @@ public class MbmsGroupCallSessionCallback {
* @param availableSais A list of lists of available SAIS in neighboring cells, where each list
* contains the available SAIs in an individual cell.
*/
public void onAvailableSaisUpdated(List<Integer> currentSais,
List<List<Integer>> availableSais) {
}
void onAvailableSaisUpdated(@NonNull List<Integer> currentSais,
@NonNull List<List<Integer>> availableSais);
/**
* Called soon after the app calls {@link MbmsGroupCallSession#create}. The information supplied
* via this callback may be used to establish a data-link interface with the modem before the
* middleware is ready.
* Note that this method may be called before {@link #onMiddlewareReady()}.
* via this callback may be used to establish a data-link interface with the modem.
*
* In order to establish the data-link interface, the multicast IP and port must be obtained
* out-of-band from the carrier. A {@link java.net.MulticastSocket} may then be constructed
* using a {@link java.net.NetworkInterface} with the name and interface supplied by this
* callback.
*
* @param interfaceName The interface name for the data link.
* @param index The index for the data link.
*/
public void onServiceInterfaceAvailable(String interfaceName, int index) {
}
void onServiceInterfaceAvailable(@NonNull String interfaceName, int index);
/**
* Called to indicate that the middleware has been initialized and is ready.
@@ -94,6 +95,5 @@ public class MbmsGroupCallSessionCallback {
* delivered via {@link #onError(int, String)} with error code
* {@link MbmsErrors.GeneralErrors#ERROR_MIDDLEWARE_NOT_YET_READY}.
*/
public void onMiddlewareReady() {
}
void onMiddlewareReady();
}

8
telephony/java/android/telephony/mbms/vendor/IMbmsGroupCallService.aidl vendored
View File

@@ -29,11 +29,11 @@ interface IMbmsGroupCallService
void stopGroupCall(int subId, long tmgi);
void updateGroupCall(int subscriptionId, long tmgi, in int[] saiArray,
in int[] frequencyArray);
void updateGroupCall(int subscriptionId, long tmgi, in List saiList,
in List frequencyList);
int startGroupCall(int subscriptionId, long tmgi, in int[] saiArray,
in int[] frequencyArray, IGroupCallCallback callback);
int startGroupCall(int subscriptionId, long tmgi, in List saiList,
in List frequencyList, IGroupCallCallback callback);
void dispose(int subId);
}

29
telephony/java/android/telephony/mbms/vendor/MbmsGroupCallServiceBase.java vendored
View File

@@ -115,15 +115,16 @@ public class MbmsGroupCallServiceBase extends Service {
}
@Override
public void updateGroupCall(int subscriptionId, long tmgi, int[] saiArray,
int[] frequencyArray) {
public void updateGroupCall(int subscriptionId, long tmgi, List saiList,
List frequencyList) {
MbmsGroupCallServiceBase.this.updateGroupCall(
subscriptionId, tmgi, saiArray, frequencyArray);
subscriptionId, tmgi, saiList, frequencyList);
}
@Override
public int startGroupCall(final int subscriptionId, final long tmgi, final int[] saiArray,
final int[] frequencyArray, final IGroupCallCallback callback)
public int startGroupCall(final int subscriptionId, final long tmgi,
final List saiList,
final List frequencyList, final IGroupCallCallback callback)
throws RemoteException {
if (callback == null) {
throw new NullPointerException("Callback must not be null");
@@ -132,7 +133,7 @@ public class MbmsGroupCallServiceBase extends Service {
final int uid = Binder.getCallingUid();
int result = MbmsGroupCallServiceBase.this.startGroupCall(
subscriptionId, tmgi, saiArray, frequencyArray, new GroupCallCallback() {
subscriptionId, tmgi, saiList, frequencyList, new GroupCallCallback() {
@Override
public void onError(final int errorCode, final String message) {
try {
@@ -209,13 +210,13 @@ public class MbmsGroupCallServiceBase extends Service {
*
* @param subscriptionId The subscription id to use.
* @param tmgi The TMGI, an identifier for the group call.
* @param saiArray An array of SAIs for the group call.
* @param frequencyArray An array of frequencies for the group call.
* @param saiList A list of SAIs for the group call.
* @param frequencyList A list of frequencies for the group call.
* @param callback The callback object on which the app wishes to receive updates.
* @return Any error in {@link MbmsErrors.GeneralErrors}
*/
public int startGroupCall(int subscriptionId, long tmgi, int[] saiArray, int[] frequencyArray,
GroupCallCallback callback) {
public int startGroupCall(int subscriptionId, long tmgi, List<Integer> saiList,
List<Integer> frequencyList, GroupCallCallback callback) {
throw new UnsupportedOperationException("Not implemented");
}
@@ -237,11 +238,11 @@ public class MbmsGroupCallServiceBase extends Service {
/**
* Called when the app receives new SAI and frequency information for the group call identified
* by {@code tmgi}.
* @param saiArray New array of SAIs that the call is available on.
* @param frequencyArray New array of frequencies that the call is available on.
* @param saiList New list of SAIs that the call is available on.
* @param frequencyList New list of frequencies that the call is available on.
*/
public void updateGroupCall(int subscriptionId, long tmgi, int[] saiArray,
int[] frequencyArray) {
public void updateGroupCall(int subscriptionId, long tmgi, List<Integer> saiList,
List<Integer> frequencyList) {
throw new UnsupportedOperationException("Not implemented");
}