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.feature.ImsFeature;
27 import android.telephony.ims.feature.RcsFeature;
28 
29 import java.util.Set;
30 
31 /**
32  * The interface that is used by the framework to listen to events from the vendor RCS stack
33  * regarding capabilities exchange using presence server and OPTIONS.
34  * @hide
35  */
36 @SystemApi
37 public interface CapabilityExchangeEventListener {
38     /**
39      * Interface used by the framework to respond to OPTIONS requests.
40      */
41     interface OptionsRequestCallback {
42         /**
43          * Respond to a remote capability request from the contact specified with the
44          * capabilities of this device.
45          * @param ownCapabilities The capabilities of this device.
46          * @param isBlocked Whether or not the user has blocked the number requesting the
47          *         capabilities of this device. If true, the device should respond to the OPTIONS
48          *         request with a 200 OK response and no capabilities.
49          */
onRespondToCapabilityRequest(@onNull RcsContactUceCapability ownCapabilities, boolean isBlocked)50         void onRespondToCapabilityRequest(@NonNull RcsContactUceCapability ownCapabilities,
51                 boolean isBlocked);
52 
53         /**
54          * Respond to a remote capability request from the contact specified with the
55          * specified error.
56          * @param code The SIP response code to respond with.
57          * @param reason A non-null String containing the reason associated with the SIP code.
58          */
onRespondToCapabilityRequestWithError(@ntRangefrom = 100, to = 699) int code, @NonNull String reason)59         void onRespondToCapabilityRequestWithError(@IntRange(from = 100, to = 699) int code,
60                 @NonNull String reason);
61     }
62 
63     /**
64      * Trigger the framework to provide a capability update using
65      * {@link RcsCapabilityExchangeImplBase#publishCapabilities}.
66      * <p>
67      * This is typically used when trying to generate an initial PUBLISH for a new subscription to
68      * the network. The device will cache all presence publications after boot until this method is
69      * called the first time.
70      * @param publishTriggerType The reason for the capability update request.
71      * @throws ImsException If this {@link RcsCapabilityExchangeImplBase} instance is not currently
72      * connected to the framework. This can happen if the {@link RcsFeature} is not
73      * {@link ImsFeature#STATE_READY} and the {@link RcsFeature} has not received the
74      * {@link ImsFeature#onFeatureReady()} callback. This may also happen in rare cases when the
75      * Telephony stack has crashed.
76      */
onRequestPublishCapabilities( @csUceAdapter.StackPublishTriggerType int publishTriggerType)77     void onRequestPublishCapabilities(
78             @RcsUceAdapter.StackPublishTriggerType int publishTriggerType) throws ImsException;
79 
80     /**
81      * Notify the framework that the device's capabilities have been unpublished
82      * from the network.
83      *
84      * @throws ImsException If this {@link RcsCapabilityExchangeImplBase} instance is not currently
85      * connected to the framework. This can happen if the {@link RcsFeature} is not
86      * {@link ImsFeature#STATE_READY} and the {@link RcsFeature} has not received the
87      * {@link ImsFeature#onFeatureReady()} callback. This may also happen in rare cases when the
88      * Telephony stack has crashed.
89      */
onUnpublish()90     void onUnpublish() throws ImsException;
91 
92     /**
93      * Inform the framework of an OPTIONS query from a remote device for this device's UCE
94      * capabilities.
95      * <p>
96      * The framework will respond via the
97      * {@link OptionsRequestCallback#onRespondToCapabilityRequest} or
98      * {@link OptionsRequestCallback#onRespondToCapabilityRequestWithError}.
99      * @param contactUri The URI associated with the remote contact that is
100      * requesting capabilities.
101      * @param remoteCapabilities The remote contact's capability information. The capability
102      * information is in the format defined in RCC.07 section 2.6.1.3.
103      * @param callback The callback of this request which is sent from the remote user.
104      * @throws ImsException If this {@link RcsCapabilityExchangeImplBase} instance is not
105      * currently connected to the framework. This can happen if the {@link RcsFeature} is not
106      * {@link ImsFeature#STATE_READY} and the {@link RcsFeature} has not received
107      * the {@link ImsFeature#onFeatureReady()} callback. This may also happen in rare
108      * cases when the Telephony stack has crashed.
109      */
onRemoteCapabilityRequest(@onNull Uri contactUri, @NonNull Set<String> remoteCapabilities, @NonNull OptionsRequestCallback callback)110     void onRemoteCapabilityRequest(@NonNull Uri contactUri,
111             @NonNull Set<String> remoteCapabilities,
112             @NonNull OptionsRequestCallback callback) throws ImsException;
113 }
114