Android API Guides---Session Initiation Protocol

Session Initiation Protocol

Android提供支持会话初始化协议（SIP）的API。这可以让你添加基于SIP的网络电话功能，以您的应用程序。 Android包括一个完整的SIP协议栈和集成的呼叫管理服务，让应用程序轻松设置传出和传入的语音通话，而无需管理会话，传输层次的沟通，或音频记录或播放直接。


这里的类型可能使用SIP API的应用程序的例子：


视频会议。
即时通讯。
要求和限制


以下是开发一个SIP应用的要求：


你必须有一个运行Android 2.3或更高版本的移动设备。
SIP运行在无线数据连接，所以你的设备必须有一个数据连接（与移动数据服务或者Wi-Fi）。这意味着你不能在AVD-你只能一个物理设备上测试测试。有关详细信息，请参阅测试SIP应用程序。
在应用程序的通信会话每个参与者都必须有一个SIP帐号。有许多不同的SIP提供商提供SIP帐号。
SIP API类和接口


下面是包含在Android SIP API中的类和一个接口（SipRegistrationListener）的摘要：


类/接口描述
SipAudioCall处理超过SIP互联网音频呼叫。
SipAudioCall.Listener监听器与SIP电话的事件，当正在接收（“响铃”）的调用或呼叫传出，如（“呼叫”）。
SipErrorCode定义错误代码在SIP行动返回。
SipManager提供API支持SIP的任务，例如启动SIP连接，并提供访问相关的SIP服务。
SipProfile定义SIP模式，包括SIP账户，域名和服务器信息。
SipProfile.Builder Helper类创建SipProfile。
SipSession中表示与SIP对话或对话中的独立事务不相关联的SIP会话。
SipSession.Listener监听器与SIP会话的事件，例如当一个会话正在注册（“关于注册”）或呼叫传出的（“呼叫”）。
SipSession.State定义SIP会话的状态，如“注册”，“呼出”和“呼叫”。
SipRegistrationListener一个接口，是SIP注册事件的监听器。
创建清单


如果您正在开发使用SIP API的应用程序，请记住，该功能仅适用于Android 2.3（API等级9）和更高版本的平台支持。此外，运行Android 2.3（API等级9）或更高版本的设备中，不是所有的设备将提供SIP支持。


要使用SIP，添加以下权限到应用程序的清单：


android.permission.USE_SIP
android.permission.INTERNET对
为了确保您的应用程序只能在能够支持SIP设备进行安装，以下内容添加到您的应用程序的清单：


<使用-SDK安卓的minSdkVersion =“9”/>。这表示您的应用程序需要Android 2.3或更高版本。欲了解更多信息，请参阅API级别，为<用途-SDK>元素的文档。
要控制如何将应用程序从不支持SIP的设备过滤（例如，在谷歌播放），以下内容添加到您的应用程序的清单：


<使用特征的android：NAME =“android.hardware.sip.voip”/>。这说明您的应用程序使用SIP API。该声明应包括一个机器人：required属性，指示是否希望从那些不提供SIP支持设备过滤应用程序。其他<用途特征>也可能需要申报，这取决于您的实现。有关详细信息，请参阅<使用说明 - 功能>元素的文档。
如果你的应用被设计为接听电话，也必须定义在应用程序的清单接收器（BroadcastReceiver的子类）：


<接收器的android：名称=机器人“IncomingCallReceiver”：标签=“呼叫接收”/>
下面是从SipDemo清单摘录：

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
          package="com.example.android.sip">
  ...
     <receiver android:name=".IncomingCallReceiver" android:label="Call Receiver"/>
  ...
  <uses-sdk android:minSdkVersion="9" />
  <uses-permission android:name="android.permission.USE_SIP" />
  <uses-permission android:name="android.permission.INTERNET" />
  ...
  <uses-feature android:name="android.hardware.sip.voip" android:required="true" />
  <uses-feature android:name="android.hardware.wifi" android:required="true" />
  <uses-feature android:name="android.hardware.microphone" android:required="true" />
</manifest>

创建SipManager
要使用SIP API，应用程序必须创建一个SIP Manager对象。该SipManager发生在你的应用程序下面的护理：
启动SIP会话。
发起和接听电话。
注册和使用SIP提供商注销。
验证会话连接。
您实例化一个新的SipManager如下：

public SipManager mSipManager = null;
...
if(mSipManager == null) {
    mSipManager = SipManager.newInstance(this);
}

与SIP服务器注册
一个典型的Android SIP应用涉及到一个或多个用户，每个人都有一个SIP帐户。在Android SIP应用，每个SIP帐户由SIP模式对象表示。
一个SIP配置文件定义了SIP情景模式，包括SIP账户，域名和服务器信息。与运行应用程序的设备上的SIP账户相关联的信息被称为本地简档。该会话连接信息到被称为对等体信息。当你的SIP应用程序日志与当地SipProfile SIP服务器，这有效地将该设备注册为发送SIP的位置要求，为您的SIP地址。
本节将展示如何创建SipProfile，与SIP服务器注册，并跟踪注册事件。
您创建一个SipProfile对象，如下所示：

public SipProfile mSipProfile = null;
...

SipProfile.Builder builder = new SipProfile.Builder(username, domain);
builder.setPassword(password);
mSipProfile = builder.build();

下面的代码片段打开用于拨打电话和/或接收通用的SIP呼叫本地配置文件。来电者可以通过做后续mSipManager.makeAudioCall调用。本文节选还将设置操作android.Sip Demo.INCOMING CALL，这将是当设备接收到呼叫（请参阅设置意图过滤器来接收呼叫）的意图过滤器使用。这是在注册步骤：

Intent intent = new Intent();
intent.setAction("android.SipDemo.INCOMING_CALL");
PendingIntent pendingIntent = PendingIntent.getBroadcast(this, 0, intent, Intent.FILL_IN_DATA);
mSipManager.open(mSipProfile, pendingIntent, null);

最后，该代码设置的SipManager一个SIP注册监听器。这种跟踪是否SipProfile成功与您的SIP服务商处注册：

mSipManager.setRegistrationListener(mSipProfile.getUriString(), new SipRegistrationListener() {

public void onRegistering(String localProfileUri) {
    updateStatus("Registering with SIP Server...");
}

public void onRegistrationDone(String localProfileUri, long expiryTime) {
    updateStatus("Ready");
}
   
public void onRegistrationFailed(String localProfileUri, int errorCode,
    String errorMessage) {
    updateStatus("Registration failed.  Please check settings.");
}

当你的应用程序使用的配置文件完成的，它应该关闭它来释放相关联的对象到内存中，并从服务器上注销该设备。 例如：

public void closeLocalProfile() {
    if (mSipManager == null) {
       return;
    }
    try {
       if (mSipProfile != null) {
          mSipManager.close(mSipProfile.getUriString());
       }
     } catch (Exception ee) {
       Log.d("WalkieTalkieActivity/onDestroy", "Failed to close local profile.", ee);
     }
}

制作音频呼叫
为了使一个音频呼叫，您必须到位如下：
一个SIP配置文件，进行调用（“本地配置文件”），以及一个有效的SIP地址接收呼叫（“同行配置文件”）。
一个SipManager对象。
若要使音频呼叫，你应该建立一个SipAudioCall.Listener。大部分客户与SIP堆栈的交互发生通过侦听器。在这个片段中，你看到的是建立呼叫后SipAudioCall.Listener如何设置的东西了：

SipAudioCall.Listener listener = new SipAudioCall.Listener() {
  
   @Override
   public void onCallEstablished(SipAudioCall call) {
      call.startAudio();
      call.setSpeakerMode(true);
      call.toggleMute();
         ...
   }
   
   @Override
   public void onCallEnded(SipAudioCall call) {
      // Do something.
   }
};

一旦你设置了SipAudioCall.Listener，就可以拨打电话。该SipManager方法makeAudioCall采用下列参数：


本地SIP配置文件（主叫）。
对等SIP配置文件（用户调用）。
一个SipAudioCall.Listener听从SipAudioCall呼叫事件。这可以为null，但是如上图所示，听者使用一次通话建立设置的东西了。
超时值，以秒为单位。
例如：

 call = mSipManager.makeAudioCall(mSipProfile.getUriString(), sipAddress, listener, 30);

接听电话
要接听电话，SIP应用程序必须包括广播接收器的子类有向表明有来电的意图作出反应的能力。因此，你必须做你的应用程序如下：
在AndroidManifest.xml中，声明<接收>。在SipDemo，这是<android的接收器：名称=“。IncomingCallReceiver”机器人：标签=“呼叫接收”/>。
实施接收器，这是广播接收器的一个子类。在SipDemo，这是来电接收器。
初始化挂起的意图是激发你的接收机，当有人呼叫本地配置本地配置文件（SipProfile）。
设置一个意图过滤器，通过代表来电动作过滤器。在SipDemo，这个动作android.SipDemo.INCOMING_CALL。
子类广播接收器
要接听电话，您的SIP应用必须继承广播接收器。 Android系统处理拨入SIP呼叫，并播放了“来电”的意图（如应用程序定义），当它接收到呼叫。下面是从SipDemo子类的广播接收器的代码。要查看完​​整的例子，去SipDemo样品，其中包括在SDK样本英寸有关下载和安装SDK样的信息，请参见获取样本。

/*** Listens for incoming SIP calls, intercepts and hands them off to WalkieTalkieActivity.
 */
public class IncomingCallReceiver extends BroadcastReceiver {
    /**
     * Processes the incoming call, answers it, and hands it over to the
     * WalkieTalkieActivity.
     * @param context The context under which the receiver is running.
     * @param intent The intent being received.
     */
    @Override
    public void onReceive(Context context, Intent intent) {
        SipAudioCall incomingCall = null;
        try {
            SipAudioCall.Listener listener = new SipAudioCall.Listener() {
                @Override
                public void onRinging(SipAudioCall call, SipProfile caller) {
                    try {
                        call.answerCall(30);
                    } catch (Exception e) {
                        e.printStackTrace();
                    }
                }
            };
            WalkieTalkieActivity wtActivity = (WalkieTalkieActivity) context;
            incomingCall = wtActivity.mSipManager.takeAudioCall(intent, listener);
            incomingCall.answerCall(30);
            incomingCall.startAudio();
            incomingCall.setSpeakerMode(true);
            if(incomingCall.isMuted()) {
                incomingCall.toggleMute();
            }
            wtActivity.call = incomingCall;
            wtActivity.updateStatus(incomingCall);
        } catch (Exception e) {
            if (incomingCall != null) {
                incomingCall.close();
            }
        }
    }
}

建立一个意图过滤器来接听电话
当SIP服务接收一个新的呼叫时，它发出与应用程序提供的操作字符串的意图。在SipDemo，这个动作字符串是android.Sip Demo.INCOMING CALL。
从SipDemo这段代码摘录显示了SipProfile对象被如何使用基于操作字符串android.Sip Demo.INCOMING CALL挂起的意图创建。在SipProfile收到呼叫时的PendingIntent对象将执行广播：

public SipManager mSipManager = null;
public SipProfile mSipProfile = null;
...

Intent intent = new Intent(); 
intent.setAction("android.SipDemo.INCOMING_CALL"); 
PendingIntent pendingIntent = PendingIntent.getBroadcast(this, 0, intent, Intent.FILL_IN_DATA); 
mSipManager.open(mSipProfile, pendingIntent, null);

广播将由意图过滤器，然后将火接收机（来电呼叫接收器）被截获。您可以指定应用程序的清单文件的意图过滤器，或做在代码中的SipDemo示例应用程序的onCreate（）方法的应用程序的活动：

public class WalkieTalkieActivity extends Activity implements View.OnTouchListener {
...
    public IncomingCallReceiver callReceiver;
    ...

    @Override
    public void onCreate(Bundle savedInstanceState) {

       IntentFilter filter = new IntentFilter();
       filter.addAction("android.SipDemo.INCOMING_CALL");
       callReceiver = new IncomingCallReceiver();
       this.registerReceiver(callReceiver, filter);
       ...
    }
    ...
}

测试SIP应用程序


为了测试SIP应用程序，需要具备以下条件：


运行Android 2.3或更高的移动设备。 SIP运行在无线，所以你必须测试在实际设备上。在AVD测试将无法正常工作。
一个SIP帐户。有许多不同的SIP提供商提供SIP帐号。
如果您在发出呼叫，它也必须是有效的SIP帐户。
要测试SIP应用：


在设备上，连接到无线（设置>无线和网络>无线网络连接> Wi-Fi设置）
设置您的移动设备进行测试，在开发上的设备描述。
在移动设备上运行应用程序，在开发上的设备描述。
如果您使用的是Eclipse，则可以使用LogCat中（窗口>显示视图>其它> Android的> LogCat中）在Eclipse中查看应用程序日志输出。