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.IntRange; 20 import android.annotation.NonNull; 21 import android.annotation.SystemApi; 22 import android.net.Uri; 23 import android.telephony.ims.ImsException; 24 import android.telephony.ims.RcsContactUceCapability; 25 import android.telephony.ims.RcsUceAdapter; 26 import android.telephony.ims.SipDetails; 27 import android.telephony.ims.feature.ImsFeature; 28 import android.telephony.ims.feature.RcsFeature; 29 30 import java.util.Set; 31 32 /** 33 * The interface that is used by the framework to listen to events from the vendor RCS stack 34 * regarding capabilities exchange using presence server and OPTIONS. 35 * @hide 36 */ 37 @SystemApi 38 public interface CapabilityExchangeEventListener { 39 /** 40 * Interface used by the framework to respond to OPTIONS requests. 41 */ 42 interface OptionsRequestCallback { 43 /** 44 * Respond to a remote capability request from the contact specified with the 45 * capabilities of this device. 46 * @param ownCapabilities The capabilities of this device. 47 * @param isBlocked Whether or not the user has blocked the number requesting the 48 * capabilities of this device. If true, the device should respond to the OPTIONS 49 * request with a 200 OK response and no capabilities. 50 */ onRespondToCapabilityRequest(@onNull RcsContactUceCapability ownCapabilities, boolean isBlocked)51 void onRespondToCapabilityRequest(@NonNull RcsContactUceCapability ownCapabilities, 52 boolean isBlocked); 53 54 /** 55 * Respond to a remote capability request from the contact specified with the 56 * specified error. 57 * @param code The SIP response code to respond with. 58 * @param reason A non-null String containing the reason associated with the SIP code. 59 */ onRespondToCapabilityRequestWithError(@ntRangefrom = 100, to = 699) int code, @NonNull String reason)60 void onRespondToCapabilityRequestWithError(@IntRange(from = 100, to = 699) int code, 61 @NonNull String reason); 62 } 63 64 /** 65 * Trigger the framework to provide a capability update using 66 * {@link RcsCapabilityExchangeImplBase#publishCapabilities}. 67 * <p> 68 * This is typically used when trying to generate an initial PUBLISH for a new subscription to 69 * the network. The device will cache all presence publications after boot until this method is 70 * called the first time. 71 * @param publishTriggerType The reason for the capability update request. 72 * @throws ImsException If this {@link RcsCapabilityExchangeImplBase} instance is not currently 73 * connected to the framework. This can happen if the {@link RcsFeature} is not 74 * {@link ImsFeature#STATE_READY} and the {@link RcsFeature} has not received the 75 * {@link ImsFeature#onFeatureReady()} callback. This may also happen in rare cases when the 76 * Telephony stack has crashed. 77 */ onRequestPublishCapabilities( @csUceAdapter.StackPublishTriggerType int publishTriggerType)78 void onRequestPublishCapabilities( 79 @RcsUceAdapter.StackPublishTriggerType int publishTriggerType) throws ImsException; 80 81 /** 82 * Notify the framework that the device's capabilities have been unpublished 83 * from the network. 84 * 85 * @throws ImsException If this {@link RcsCapabilityExchangeImplBase} instance is not currently 86 * connected to the framework. This can happen if the {@link RcsFeature} is not 87 * {@link ImsFeature#STATE_READY} and the {@link RcsFeature} has not received the 88 * {@link ImsFeature#onFeatureReady()} callback. This may also happen in rare cases when the 89 * Telephony stack has crashed. 90 */ onUnpublish()91 void onUnpublish() throws ImsException; 92 93 /** 94 * Notify the framework that the ImsService has refreshed the PUBLISH 95 * internally, which has resulted in a new PUBLISH result. 96 * <p> 97 * This method must be called to notify the framework of SUCCESS (200 OK) and FAILURE (300+) 98 * codes in order to keep the AOSP stack up to date. 99 * @param reasonCode The SIP response code sent from the network. 100 * @param reasonPhrase The optional reason response from the network. If the 101 * network provided no reason with the sip code, the string should be empty. 102 * @param reasonHeaderCause The “cause” parameter of the “reason” header 103 * included in the SIP message. 104 * @param reasonHeaderText The “text” parameter of the “reason” header 105 * included in the SIP message. 106 * @throws ImsException If this {@link RcsCapabilityExchangeImplBase} instance is not 107 * currently connected to the framework. This can happen if the {@link RcsFeature} is not 108 * {@link ImsFeature#STATE_READY} and the {@link RcsFeature} has not received 109 * the {@link ImsFeature#onFeatureReady()} callback. This may also happen in rare 110 * cases when the Telephony stack has crashed. 111 * 112 * @deprecated Replaced sip information with the newly added 113 * {@link #onPublishUpdated(SipDetails)}. 114 */ 115 @Deprecated onPublishUpdated(int reasonCode, @NonNull String reasonPhrase, int reasonHeaderCause, @NonNull String reasonHeaderText)116 default void onPublishUpdated(int reasonCode, @NonNull String reasonPhrase, 117 int reasonHeaderCause, @NonNull String reasonHeaderText) throws ImsException { 118 onPublishUpdated(new SipDetails.Builder(SipDetails.METHOD_PUBLISH) 119 .setSipResponseCode(reasonCode, reasonPhrase) 120 .setSipResponseReasonHeader(reasonHeaderCause, reasonHeaderText) 121 .build()); 122 } 123 124 /** 125 * Notify the framework that the ImsService has refreshed the PUBLISH 126 * internally, which has resulted in a new PUBLISH result. 127 * <p> 128 * This method must be called to notify the framework of SUCCESS (200 OK) and FAILURE (300+) 129 * codes in order to keep the AOSP stack up to date. 130 * @param details The SIP information received in response to a publish operation. 131 * @throws ImsException If this {@link RcsCapabilityExchangeImplBase} instance is not 132 * currently connected to the framework. This can happen if the {@link RcsFeature} is not 133 * {@link ImsFeature#STATE_READY} and the {@link RcsFeature} has not received 134 * the {@link ImsFeature#onFeatureReady()} callback. This may also happen in rare 135 * cases when the Telephony stack has crashed. 136 */ onPublishUpdated(@onNull SipDetails details)137 default void onPublishUpdated(@NonNull SipDetails details) 138 throws ImsException { 139 } 140 /** 141 * Inform the framework of an OPTIONS query from a remote device for this device's UCE 142 * capabilities. 143 * <p> 144 * The framework will respond via the 145 * {@link OptionsRequestCallback#onRespondToCapabilityRequest} or 146 * {@link OptionsRequestCallback#onRespondToCapabilityRequestWithError}. 147 * @param contactUri The URI associated with the remote contact that is 148 * requesting capabilities. 149 * @param remoteCapabilities The remote contact's capability information. The capability 150 * information is in the format defined in RCC.07 section 2.6.1.3. 151 * @param callback The callback of this request which is sent from the remote user. 152 * @throws ImsException If this {@link RcsCapabilityExchangeImplBase} instance is not 153 * currently connected to the framework. This can happen if the {@link RcsFeature} is not 154 * {@link ImsFeature#STATE_READY} and the {@link RcsFeature} has not received 155 * the {@link ImsFeature#onFeatureReady()} callback. This may also happen in rare 156 * cases when the Telephony stack has crashed. 157 */ onRemoteCapabilityRequest(@onNull Uri contactUri, @NonNull Set<String> remoteCapabilities, @NonNull OptionsRequestCallback callback)158 void onRemoteCapabilityRequest(@NonNull Uri contactUri, 159 @NonNull Set<String> remoteCapabilities, 160 @NonNull OptionsRequestCallback callback) throws ImsException; 161 } 162