1 /*
2  * Copyright (C) 2010 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.net.sip;
18 
19 import android.net.sip.ISipSessionListener;
20 import android.net.sip.SipProfile;
21 
22 /**
23  * A SIP session that is associated with a SIP dialog or a transaction that is
24  * not within a dialog.
25  * @hide
26  */
27 interface ISipSession {
28     /**
29      * Gets the IP address of the local host on which this SIP session runs.
30      *
31      * @return the IP address of the local host
32      */
getLocalIp()33     String getLocalIp();
34 
35     /**
36      * Gets the SIP profile that this session is associated with.
37      *
38      * @return the SIP profile that this session is associated with
39      */
getLocalProfile()40     SipProfile getLocalProfile();
41 
42     /**
43      * Gets the SIP profile that this session is connected to. Only available
44      * when the session is associated with a SIP dialog.
45      *
46      * @return the SIP profile that this session is connected to
47      */
getPeerProfile()48     SipProfile getPeerProfile();
49 
50     /**
51      * Gets the session state. The value returned must be one of the states in
52      * {@link SipSessionState}.
53      *
54      * @return the session state
55      */
getState()56     int getState();
57 
58     /**
59      * Checks if the session is in a call.
60      *
61      * @return true if the session is in a call
62      */
isInCall()63     boolean isInCall();
64 
65     /**
66      * Gets the call ID of the session.
67      *
68      * @return the call ID
69      */
getCallId()70     String getCallId();
71 
72 
73     /**
74      * Sets the listener to listen to the session events. A {@link ISipSession}
75      * can only hold one listener at a time. Subsequent calls to this method
76      * override the previous listener.
77      *
78      * @param listener to listen to the session events of this object
79      */
setListener(in ISipSessionListener listener)80     void setListener(in ISipSessionListener listener);
81 
82 
83     /**
84      * Performs registration to the server specified by the associated local
85      * profile. The session listener is called back upon success or failure of
86      * registration. The method is only valid to call when the session state is
87      * in {@link SipSessionState#READY_TO_CALL}.
88      *
89      * @param duration duration in second before the registration expires
90      * @see ISipSessionListener
91      */
register(int duration)92     void register(int duration);
93 
94     /**
95      * Performs unregistration to the server specified by the associated local
96      * profile. Unregistration is technically the same as registration with zero
97      * expiration duration. The session listener is called back upon success or
98      * failure of unregistration. The method is only valid to call when the
99      * session state is in {@link SipSessionState#READY_TO_CALL}.
100      *
101      * @see ISipSessionListener
102      */
unregister()103     void unregister();
104 
105     /**
106      * Initiates a call to the specified profile. The session listener is called
107      * back upon defined session events. The method is only valid to call when
108      * the session state is in {@link SipSessionState#READY_TO_CALL}.
109      *
110      * @param callee the SIP profile to make the call to
111      * @param sessionDescription the session description of this call
112      * @param timeout the session will be timed out if the call is not
113      *        established within {@code timeout} seconds
114      * @see ISipSessionListener
115      */
makeCall(in SipProfile callee, String sessionDescription, int timeout)116     void makeCall(in SipProfile callee, String sessionDescription, int timeout);
117 
118     /**
119      * Answers an incoming call with the specified session description. The
120      * method is only valid to call when the session state is in
121      * {@link SipSessionState#INCOMING_CALL}.
122      *
123      * @param sessionDescription the session description to answer this call
124      * @param timeout the session will be timed out if the call is not
125      *        established within {@code timeout} seconds
126      */
answerCall(String sessionDescription, int timeout)127     void answerCall(String sessionDescription, int timeout);
128 
129     /**
130      * Ends an established call, terminates an outgoing call or rejects an
131      * incoming call. The method is only valid to call when the session state is
132      * in {@link SipSessionState#IN_CALL},
133      * {@link SipSessionState#INCOMING_CALL},
134      * {@link SipSessionState#OUTGOING_CALL} or
135      * {@link SipSessionState#OUTGOING_CALL_RING_BACK}.
136      */
endCall()137     void endCall();
138 
139     /**
140      * Changes the session description during a call. The method is only valid
141      * to call when the session state is in {@link SipSessionState#IN_CALL}.
142      *
143      * @param sessionDescription the new session description
144      * @param timeout the session will be timed out if the call is not
145      *        established within {@code timeout} seconds
146      */
changeCall(String sessionDescription, int timeout)147     void changeCall(String sessionDescription, int timeout);
148 }
149