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.SystemApi; 21 import android.telephony.ims.stub.SipDelegate; 22 23 /** 24 * Represents a connection to the remote {@link SipDelegate} that is managed by the 25 * {@link ImsService} implementing IMS for the subscription that is associated with it. 26 * <p> 27 * The remote delegate will handle messages sent by this {@link SipDelegateConnection}, notifying 28 * the associated {@link DelegateMessageCallback} when the message was either sent successfully or 29 * failed to be sent. 30 * <p> 31 * It is also the responsibility of this {@link SipDelegateConnection} to acknowledge when incoming 32 * SIP messages have been received successfully via 33 * {@link DelegateMessageCallback#onMessageReceived(SipMessage)} or when there was an error 34 * receiving the message using {@link #notifyMessageReceived(String)} and 35 * {@link #notifyMessageReceiveError(String, int)}. 36 * 37 * @see SipDelegateManager#createSipDelegate 38 * @hide 39 */ 40 @SystemApi 41 public interface SipDelegateConnection { 42 43 /** 44 * Send a SIP message to the SIP delegate to be sent over the carrier’s network. The 45 * {@link SipMessage} will either be acknowledged with 46 * {@link DelegateMessageCallback#onMessageSent(String)} upon successful sending of this message 47 * or {@link DelegateMessageCallback#onMessageSendFailure(String, int)} if there was an error 48 * sending the message. 49 * @param sipMessage The SipMessage to be sent. 50 * @param configVersion The SipDelegateImsConfiguration version used to construct the 51 * SipMessage. See {@link SipDelegateConfiguration#getVersion} for more 52 */ sendMessage(@onNull SipMessage sipMessage, long configVersion)53 void sendMessage(@NonNull SipMessage sipMessage, long configVersion); 54 55 /** 56 * Notify the {@link SipDelegate} that a SIP message received from 57 * {@link DelegateMessageCallback#onMessageReceived(SipMessage)} has been received successfully 58 * and is being processed. 59 * @param viaTransactionId Per RFC3261 Sec 8.1.1.7 the transaction ID associated with the Via 60 * branch parameter. 61 */ notifyMessageReceived(@onNull String viaTransactionId)62 void notifyMessageReceived(@NonNull String viaTransactionId); 63 64 /** 65 * The SIP session associated with the provided Call-ID is being closed and routing resources 66 * associated with the session are free to be released. Each SIP session may contain multiple 67 * dialogs due to SIP INVITE forking, so this method must be called after all SIP dialogs 68 * associated with the session has closed. 69 * <p> 70 * Calling this method is also mandatory for situations where the framework IMS stack is waiting 71 * for pending SIP sessions to be closed before it can perform a handover or apply a 72 * provisioning change. See {@link DelegateRegistrationState} for more information about 73 * the scenarios where this can occur. 74 * <p> 75 * This method will need to be called for each SIP session managed by this application when it 76 * is closed. 77 * @param callId The call-ID header value associated with the ongoing SIP Dialog that is 78 * closing. 79 */ cleanupSession(@onNull String callId)80 void cleanupSession(@NonNull String callId); 81 82 /** 83 * Notify the SIP delegate that the SIP message has been received from 84 * {@link DelegateMessageCallback#onMessageReceived(SipMessage)}, however there was an error 85 * processing it. 86 * @param viaTransactionId Per RFC3261 Sec 8.1.1.7 the transaction ID associated with the Via 87 * branch parameter. 88 * @param reason The reason why the error occurred. 89 */ notifyMessageReceiveError(@onNull String viaTransactionId, @SipDelegateManager.MessageFailureReason int reason)90 void notifyMessageReceiveError(@NonNull String viaTransactionId, 91 @SipDelegateManager.MessageFailureReason int reason); 92 } 93