1 /* 2 * Copyright (C) 2020 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package android.telephony.ims; 18 19 import android.annotation.NonNull; 20 import android.annotation.Nullable; 21 import android.annotation.SuppressLint; 22 import android.annotation.SystemApi; 23 import android.telephony.ims.stub.SipDelegate; 24 import android.telephony.ims.stub.SipTransportImplBase; 25 26 import java.util.Set; 27 28 /** 29 * Callback interface to notify a remote application of the following: 30 * <ul> 31 * <li>the {@link SipDelegate} associated with this callback has been created or destroyed in 32 * response to a creation or destruction request from the framework</li> 33 * <li>the SIP IMS configuration associated with this {@link SipDelegate} has changed</li> 34 * <li>the IMS registration of the feature tags associated with this {@link SipDelegate} have 35 * changed.</li> 36 * </ul> 37 * @hide 38 */ 39 @SystemApi 40 public interface DelegateStateCallback { 41 42 /** 43 * This must be called by the ImsService after {@link SipTransportImplBase#createSipDelegate} is 44 * called by the framework to notify the framework and remote application that the 45 * {@link SipDelegate} has been successfully created. 46 * @param delegate The SipDelegate created to service the DelegateRequest. 47 * @param deniedTags A Set of {@link FeatureTagState}s, which contain the feature tags 48 * associated with this {@link SipDelegate} that have no access to send/receive SIP messages 49 * as well as a reason for why the feature tag is denied. For more information on the reason 50 * why the feature tag was denied access, see the 51 * {@link SipDelegateManager.DeniedReason} reasons. This is considered a permanent denial due 52 * to this {@link SipDelegate} not supporting a feature or this ImsService already 53 * implementing this feature elsewhere. If all features of this {@link SipDelegate} are 54 * denied, this method should still be called. 55 */ onCreated(@onNull SipDelegate delegate, @SuppressLint("NullableCollection") @Nullable Set<FeatureTagState> deniedTags)56 void onCreated(@NonNull SipDelegate delegate, 57 @SuppressLint("NullableCollection") // TODO(b/154763999): Mark deniedTags @Nonnull 58 @Nullable Set<FeatureTagState> deniedTags); 59 60 /** 61 * This must be called by the ImsService after the framework calls 62 * {@link SipTransportImplBase#destroySipDelegate} to notify the framework and remote 63 * application that the procedure to destroy the {@link SipDelegate} has been completed. 64 * @param reasonCode The reason for closing this delegate. 65 */ onDestroyed(@ipDelegateManager.SipDelegateDestroyReason int reasonCode)66 void onDestroyed(@SipDelegateManager.SipDelegateDestroyReason int reasonCode); 67 68 /** 69 * Call to notify the remote application of a configuration change associated with this 70 * {@link SipDelegate}. 71 * <p> 72 * The remote application will not be able to proceed sending SIP messages until after this 73 * configuration is sent the first time, so this configuration should be sent as soon as the 74 * {@link SipDelegate} has access to these configuration parameters. 75 * <p> 76 * Incoming SIP messages should not be routed to the remote application until AFTER this 77 * configuration change is sent to ensure that the remote application can respond correctly. 78 * Similarly, if there is an event that triggers the IMS configuration to change, incoming SIP 79 * messages routing should be delayed until the {@link SipDelegate} sends the IMS configuration 80 * change event to reduce conditions where the remote application is using a stale IMS 81 * configuration. 82 * @removed This is being removed from API surface, Use 83 * {@link #onConfigurationChanged(SipDelegateConfiguration)} instead. 84 */ 85 @Deprecated onImsConfigurationChanged(@onNull SipDelegateImsConfiguration config)86 void onImsConfigurationChanged(@NonNull SipDelegateImsConfiguration config); 87 88 /** 89 * Call to notify the remote application of a configuration change associated with this 90 * {@link SipDelegate}. 91 * <p> 92 * The remote application will not be able to proceed sending SIP messages until after this 93 * configuration is sent the first time, so this configuration should be sent as soon as the 94 * {@link SipDelegate} has access to these configuration parameters. 95 * <p> 96 * Incoming SIP messages should not be routed to the remote application until AFTER this 97 * configuration change is sent to ensure that the remote application can respond correctly. 98 * Similarly, if there is an event that triggers the IMS configuration to change, incoming SIP 99 * messages routing should be delayed until the {@link SipDelegate} sends the IMS configuration 100 * change event to reduce conditions where the remote application is using a stale IMS 101 * configuration. 102 */ onConfigurationChanged(@onNull SipDelegateConfiguration config)103 void onConfigurationChanged(@NonNull SipDelegateConfiguration config); 104 105 /** 106 * Call to notify the remote application that the {@link SipDelegate} has modified the IMS 107 * registration state of the RCS feature tags that were requested as part of the initial 108 * {@link DelegateRequest}. 109 * <p> 110 * See {@link DelegateRegistrationState} for more information about how IMS Registration state 111 * should be communicated the associated SipDelegateConnection in cases such as 112 * IMS deregistration, handover, PDN change, provisioning changes, etc… 113 * <p> 114 * Note: Even after the status of the feature tags are updated here to deregistered, the 115 * SipDelegate must still be able to handle these messages and call 116 * {@link DelegateMessageCallback#onMessageSendFailure} to notify the RCS application that the 117 * message was not sent. 118 * 119 * @param registrationState The current network IMS registration state for all feature tags 120 * associated with this SipDelegate. 121 */ onFeatureTagRegistrationChanged(@onNull DelegateRegistrationState registrationState)122 void onFeatureTagRegistrationChanged(@NonNull DelegateRegistrationState registrationState); 123 } 124