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
17package android.net.sip;
18
19import android.net.sip.ISipSessionListener;
20import 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 */
27interface 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     */
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     */
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     */
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     */
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     */
63    boolean isInCall();
64
65    /**
66     * Gets the call ID of the session.
67     *
68     * @return the call ID
69     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
147    void changeCall(String sessionDescription, int timeout);
148}
149