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.stub; 18 19 import android.annotation.NonNull; 20 import android.annotation.SystemApi; 21 import android.telephony.ims.DelegateRegistrationState; 22 import android.telephony.ims.DelegateRequest; 23 import android.telephony.ims.FeatureTagState; 24 import android.telephony.ims.SipDelegateConfiguration; 25 import android.telephony.ims.SipDelegateConnection; 26 import android.telephony.ims.SipDelegateImsConfiguration; 27 import android.telephony.ims.SipDelegateManager; 28 29 import java.util.Set; 30 31 /** 32 * The callback associated with a {@link SipDelegateConnection} that manages the state of the 33 * SipDelegateConnection. 34 * <p> 35 * After {@link SipDelegateManager#createSipDelegate} is used to request a new 36 * {@link SipDelegateConnection} be created, {@link #onCreated} will be called with the 37 * {@link SipDelegateConnection} instance that must be used to communicate with the remote 38 * {@link SipDelegate}. 39 * <p> 40 * After, {@link #onFeatureTagStatusChanged} will always be called at least once with the current 41 * status of the feature tags that have been requested. The application may receive multiple 42 * {@link #onFeatureTagStatusChanged} callbacks over the lifetime of the associated 43 * {@link SipDelegateConnection}, which will signal changes to how SIP messages associated with 44 * those feature tags will be handled. 45 * <p> 46 * In order to start sending SIP messages, the SIP configuration parameters will need to be 47 * received, so the messaging application should make no assumptions about these parameters and wait 48 * until {@link #onConfigurationChanged(SipDelegateConfiguration)} has been called. This is 49 * guaranteed to happen after the first {@link #onFeatureTagStatusChanged} if there is at least one 50 * feature tag that has been successfully associated with the {@link SipDelegateConnection}. If all 51 * feature tags were denied, no IMS configuration will be sent. 52 * <p> 53 * The {@link SipDelegateConnection} will stay associated with this RCS application until either the 54 * RCS application calls {@link SipDelegateManager#destroySipDelegate} or telephony destroys the 55 * {@link SipDelegateConnection}. In both cases, {@link #onDestroyed(int)} will be called. 56 * Telephony destroying the {@link SipDelegateConnection} instance is rare and will only happen in 57 * rare cases, such as if telephony itself or IMS service dies unexpectedly. See 58 * {@link SipDelegateManager.SipDelegateDestroyReason} reasons for more information on all of the 59 * cases that will trigger the {@link SipDelegateConnection} to be destroyed. 60 * 61 * @hide 62 */ 63 @SystemApi 64 public interface DelegateConnectionStateCallback { 65 66 /** 67 * A {@link SipDelegateConnection} has been successfully created for the 68 * {@link DelegateRequest} used when calling {@link SipDelegateManager#createSipDelegate}. 69 */ onCreated(@onNull SipDelegateConnection c)70 void onCreated(@NonNull SipDelegateConnection c); 71 72 /** 73 * The status of the RCS feature tags that were requested as part of the initial 74 * {@link DelegateRequest}. 75 * <p> 76 * There are four states that each RCS feature tag can be in: registered, deregistering, 77 * deregistered, and denied. 78 * <p> 79 * When a feature tag is considered registered, SIP messages associated with that feature tag 80 * may be sent and received freely. 81 * <p> 82 * When a feature tag is deregistering, the network IMS registration still contains the feature 83 * tag, however the IMS service and associated {@link SipDelegate} is in the progress of 84 * modifying the IMS registration to remove this feature tag and requires the application to 85 * perform an action before the IMS registration can change. The specific action required for 86 * the SipDelegate to continue modifying the IMS registration can be found in the definition of 87 * each {@link DelegateRegistrationState.DeregisteringReason}. 88 * <p> 89 * When a feature tag is in the deregistered state, new out-of-dialog SIP messages for that 90 * feature tag will be rejected, however due to network race conditions, the RCS application 91 * should still be able to handle new out-of-dialog SIP requests from the network. This may not 92 * be possible, however, if the IMS registration itself was lost. See the 93 * {@link DelegateRegistrationState.DeregisteredReason} reasons for more information on how SIP 94 * messages are handled in each of these cases. 95 * <p> 96 * If a feature tag is denied, no incoming messages will be routed to the associated 97 * {@link DelegateConnectionMessageCallback} and all outgoing SIP messages related to this 98 * feature tag will be rejected. See {@link SipDelegateManager.DeniedReason} 99 * reasons for more information about the conditions when this will happen. 100 * <p> 101 * The set of feature tags contained in the registered, deregistering, deregistered, and denied 102 * lists will always equal the set of feature tags requested in the initial 103 * {@link DelegateRequest}. 104 * <p> 105 * Transitions of feature tags from registered, deregistering, and deregistered and vice-versa 106 * may happen quite often, however transitions to/from denied are rare and only occur if the 107 * user has changed the role of your application to add/remove support for one or more requested 108 * feature tags or carrier provisioning has enabled or disabled single registration entirely. 109 * Please see {@link SipDelegateManager.DeniedReason} reasons for an explanation of each of 110 * these cases as well as what may cause them to change. 111 * 112 * @param registrationState The new IMS registration state of each of the feature tags 113 * associated with the {@link SipDelegate}. 114 * @param deniedFeatureTags A list of {@link FeatureTagState} objects, each containing a feature 115 * tag associated with this {@link SipDelegateConnection} that has no access to 116 * send/receive SIP messages as well as a reason for why the feature tag is denied. For more 117 * information on the reason why the feature tag was denied access, see the 118 * {@link SipDelegateManager.DeniedReason} reasons. 119 */ onFeatureTagStatusChanged(@onNull DelegateRegistrationState registrationState, @NonNull Set<FeatureTagState> deniedFeatureTags)120 void onFeatureTagStatusChanged(@NonNull DelegateRegistrationState registrationState, 121 @NonNull Set<FeatureTagState> deniedFeatureTags); 122 123 124 /** 125 * IMS configuration of the underlying IMS stack used by this IMS application for construction 126 * of the SIP messages that will be sent over the carrier's network. 127 * <p> 128 * There should never be assumptions made about the configuration of the underling IMS stack and 129 * the IMS application should wait for this indication before sending out any outgoing SIP 130 * messages. 131 * <p> 132 * Configuration may change due to IMS registration changes as well as 133 * other optional events on the carrier network. If IMS stack is already registered at the time 134 * of callback registration, then this method shall be invoked with the current configuration. 135 * Otherwise, there may be a delay in this method being called if initial IMS registration has 136 * not compleed yet. 137 * 138 * @param registeredSipConfig The configuration of the IMS stack registered on the IMS network. 139 * @removed Will not be in final API, use 140 * {@link #onConfigurationChanged(SipDelegateConfiguration)} instead}. 141 */ 142 @Deprecated onImsConfigurationChanged( @onNull SipDelegateImsConfiguration registeredSipConfig)143 default void onImsConfigurationChanged( 144 @NonNull SipDelegateImsConfiguration registeredSipConfig) { 145 onConfigurationChanged(registeredSipConfig.toNewConfig()); 146 } 147 148 /** 149 * IMS configuration of the underlying IMS stack used by this IMS application for construction 150 * of the SIP messages that will be sent over the carrier's network. 151 * <p> 152 * There should never be assumptions made about the configuration of the underling IMS stack and 153 * the IMS application should wait for this indication before sending out any outgoing SIP 154 * messages. 155 * <p> 156 * Configuration may change due to IMS registration changes as well as 157 * other optional events on the carrier network. If IMS stack is already registered at the time 158 * of callback registration, then this method shall be invoked with the current configuration. 159 * Otherwise, there may be a delay in this method being called if initial IMS registration has 160 * not compleed yet. 161 * 162 * @param registeredSipConfig The configuration of the IMS stack registered on the IMS network. 163 */ onConfigurationChanged(@onNull SipDelegateConfiguration registeredSipConfig)164 void onConfigurationChanged(@NonNull SipDelegateConfiguration registeredSipConfig); 165 166 /** 167 * The previously created {@link SipDelegateConnection} instance delivered via 168 * {@link #onCreated(SipDelegateConnection)} has been destroyed. This interface should no longer 169 * be used for any SIP message handling. 170 * 171 * @param reason The reason for the failure. 172 */ onDestroyed(@ipDelegateManager.SipDelegateDestroyReason int reason)173 void onDestroyed(@SipDelegateManager.SipDelegateDestroyReason int reason); 174 } 175