本文档由我们(Doubango Telecom)编写,旨在帮助开发人员快速为桌面和移动平台创建创新的多媒体应用程序。如果你是一个开发人员,并且正在寻找为这些平台开发一个无插件的NGN(VoIP、消息、视频会议等)应用程序的最佳方法,那么,你就在正确的地方了。
如果你想得到帮助或有一些反馈,那么请访问开发者的网站或订阅我们的开发者邮件列表。
我们强烈建议检查其他SIPML5组件:webrtc2sip、点击呼叫、webrtc4all和SIP TelePresence(视频组聊天)客户端。
这里提供完整的API
用API编程
类图
下载API
初始化发动机
注册/登录
拨打/接听音频/视频通话
共享屏幕/桌面
发送/接收SIP消息(类似SMS)
发布状态
订阅状态更改
技术帮助
用API编程
本节简要介绍了主要功能,可能缺少详细信息。有关每个功能的详细信息,请单击它。
一个功能齐全的演示在http://sipml5.org/call.htm。
下面是一个非常简洁的代码,演示如何初始化引擎、启动堆栈并在不到15行的时间内从bob向alice进行视频调用:
SIPml.init(
function(e){
var stack = new SIPml.Stack({realm: 'example.org', impi: 'bob', impu: 'sip:bob@example.org', password: 'mysecret',
events_listener: { events: 'started', listener: function(e){
var callSession = stack.newSession('call-audiovideo', {
video_local: document.getElementById('video-local'),
video_remote: document.getElementById('video-remote'),
audio_remote: document.getElementById('audio-remote')
});
callSession.call('alice');
}
}
});
stack.start();
}
);
类图
下图是主要类和函数的概述:
下载API
API是一个可以在这里下载的javascript文件。这个文件是按照这里的说明生成的。
初始化引擎
这是为了初始化媒体和信令引擎而调用的第一个函数。
var readyCallback = function(e){
createSipStack(); // see next section
};
var errorCallback = function(e){
console.error('Failed to initialize the engine: ’ + e.message);
}
SIPml.init(readyCallback, errorCallback);
创建SIP堆栈
SIP堆栈是一个基本对象,必须在尝试拨打/接收呼叫、发送消息或管理状态之前创建。本节介绍如何创建堆栈并启动它。启动堆栈是一个异步函数,这意味着您必须使用事件侦听器才能收到状态更改的通知。
var sipStack;
var eventsListener = function(e){
if(e.type == ‘started’){
login();
}
else if(e.type == ‘i_new_message’){ // incoming new SIP MESSAGE (SMS-like)
acceptMessage(e);
}
else if(e.type == ‘i_new_call’){ // incoming audio/video call
acceptCall(e);
}
}
function createSipStack(){
sipStack = new SIPml.Stack({
realm: 'example.org', // mandatory: domain name
impi: 'bob', // mandatory: authorization name (IMS Private Identity)
impu: 'sip:bob@example.org', // mandatory: valid SIP Uri (IMS Public Identity)
password: 'mysecret', // optional
display_name: 'Bob legend', // optional
websocket_proxy_url: 'wss://sipml5.org:10062', // optional
outbound_proxy_url: 'udp://example.org:5060', // optional
enable_rtcweb_breaker: false, // optional
events_listener: { events: '*', listener: eventsListener }, // optional: '*' means all events
sip_headers: [ // optional
{ name: 'User-Agent', value: 'IM-client/OMA1.0 sipML5-v1.0.0.0' },
{ name: 'Organization', value: 'Doubango Telecom' }
]
}
);
}
sipStack.start();
注册/登录
不需要注册到服务器才能进行音频/视频呼叫或发送消息。
var registerSession;
var eventsListener = function(e){
console.info('session event = ’ + e.type);
if(e.type == ‘connected’ && e.session == registerSession){
makeCall();
sendMessage();
publishPresence();
subscribePresence(‘johndoe’); // watch johndoe’s presence status change
}
}
var login = function(){
registerSession = sipStack.newSession(‘register’, {
events_listener: { events: ‘’, listener: eventsListener } // optional: '’ means all events
});
registerSession.register();
}
拨打/接听音频/视频通话
不需要登录就可以进行音频/视频通话,但如果您不是在p2p模式下使用堆栈,则强烈建议您这样做。
var callSession;
var eventsListener = function(e){
console.info(‘session event = ’ + e.type);
}
var makeCall = function(){
callSession = sipStack.newSession(‘call-audiovideo’, {
video_local: document.getElementById(‘video-local’),
video_remote: document.getElementById(‘video-remote’),
audio_remote: document.getElementById(‘audio-remote’),
events_listener: { events: ‘’, listener: eventsListener } // optional: '’ means all events
});
callSession.call(‘johndoe’);
}
要接受传入的音频/视频呼叫:
var acceptCall = function(e){
e.newSession.accept(); // e.newSession.reject() to reject the call
}
共享屏幕/桌面
与任何SIP客户端共享屏幕或桌面就像进行视频通话一样,唯一的区别是会话调用类型(调用屏幕共享而不是调用音频视频)。
屏幕/桌面共享会话不包含音频流,这意味着您需要进行第二次仅音频呼叫才能与远程方通话。您不需要打开另一个页面,因为支持多行。
有关屏幕/桌面共享的详细信息,请查看此处。
发送/接收SIP消息(类似SMS)
发送SIP消息(类似SMS)时不需要登录,但如果不在p2p模式下使用堆栈,则强烈建议这样做。
var messageSession;
var eventsListener = function(e){
console.info(‘session event = ’ + e.type);
}
var sendMessage = function(){
messageSession = sipStack.newSession(‘message’, {
events_listener: { events: ‘’, listener: eventsListener } // optional: '’ means all events
});
messageSession.send(‘johndoe’, ‘Pêche à la moule’, ‘text/plain;charset=utf-8’);
}
要接受传入的SIP消息:
var acceptMessage = function(e){
e.newSession.accept(); // e.newSession.reject(); to reject the message
console.info(‘SMS-content = ’ + e.getContentString() + ’ and SMS-content-type = ’ + e.getContentType());
}
发布状态
不需要登录就可以发布您的状态,但是如果您不在p2p模式下使用堆栈,则强烈建议您登录。
状态发布用于向您的联系人(很可能是您的通讯簿中的联系人)显示您的状态(例如在线)、心情(例如高兴)或任何个人信息。在未来的版本中,存在特性将与XCAP相结合,以允许开发功能齐全的RCS-e应用程序。
var publishSession;
var eventsListener = function(e){
console.info(‘session event = ’ + e.type);
}
var publishPresence = function(){
publishSession = sipStack.newSession(‘publish’, {
events_listener: { events: ‘’, listener: eventsListener } // optional: '’ means all events
});
var contentType = ‘application/pidf+xml’;
var content = ‘<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n’ +
‘<presence xmlns=“urn:ietf:params:xml:ns:pidf”\n’ +
’ xmlns:im=“urn:ietf:params:xml:ns:pidf:im”’ +
’ entity=“sip:bob@example.com”>\n’ +
‘<tuple id=“s8794”>\n’ +
‘\n’+
’ open\n’ +
’ im:imaway</im:im>\n’ +
‘\n’ +
‘<contact priority=“0.8”>tel:+33600000000\n’ +
‘<note xml:lang=“fr”>Bonjour de Paris 😃\n’ +
‘\n’ +
‘’;
// send the PUBLISH request
publishSession.publish(content, contentType,{
expires: 200,
sip_caps: [
{ name: '+g.oma.sip-im' },
{ name: '+sip.ice' },
{ name: 'language', value: '\"en,fr\"' }
],
sip_headers: [
{ name: 'Event', value: 'presence' },
{ name: 'Organization', value: 'Doubango Telecom' }
]
});
}
订阅状态
订阅用于监视SIP实体的状态。此SIP实体可以通过您的地址簿、rls服务、语音邮件等进行联系。当实体状态更改时,将使用SIP通知请求通知订阅者。
下面的代码展示了如何订阅johndoe的状态,并解析从服务器接收到的NOTIFY请求的内容。
var subscribeSession;
var eventsListener = function(e){
console.info('session event = ’ + e.type);
if(e.type == ‘i_notify’){
console.info('NOTIFY content = ’ + e.getContentString());
console.info('NOTIFY content-type = ’ + e.getContentType());
if (e.getContentType() == 'application/pidf+xml') {
if (window.DOMParser) {
var parser = new DOMParser();
var xmlDoc = parser ? parser.parseFromString(e.getContentString(), "text/xml") : null;
var presenceNode = xmlDoc ? xmlDoc.getElementsByTagName ("presence")[0] : null;
if(presenceNode){
var entityUri = presenceNode.getAttribute ("entity");
var tupleNode = presenceNode.getElementsByTagName ("tuple")[0];
if(entityUri && tupleNode){
var statusNode = tupleNode.getElementsByTagName ("status")[0];
if(statusNode){
var basicNode = statusNode.getElementsByTagName ("basic")[0];
if(basicNode){
console.info('Presence notification: Uri = ' + entityUri + ' status = ' + basicNode.textContent);
}
}
}
}
}
}
}
}
var subscribePresence = function(to){
subscribeSession = sipStack.newSession('subscribe', {
expires: 200,
events_listener: { events: '*', listener: eventsListener },
sip_headers: [
{ name: 'Event', value: 'presence' }, // only notify for 'presence' events
{ name: 'Accept', value: 'application/pidf+xml' } // supported content types (COMMA-sparated)
],
sip_caps: [
{ name: '+g.oma.sip-im', value: null },
{ name: '+audio', value: null },
{ name: 'language', value: '\"en,fr\"' }
]
});
// start watching for entity's presence status (You may track event type 'connected' to be sure that the request has been accepted by the server)
subscribeSession.subscribe(to);
}
技术帮助
如果您有任何问题,请检查我们的问题跟踪者或开发小组。
© Doubango Telecom 2012
Inspiring the future