最近一直在研究WebRTC，本篇是WebRTC的本地API文檔，Web developer了解一下也是有好處的，了解了API的實現原理使用起來才會更順手。決定翻譯是因為這篇字不多，翻一下加深自己的理解，如果對別人有幫助那就更好了。第一次翻譯東西拿出來，如果有錯誤還望指正，英文好一點的還是移步英文原文吧：http://www.webrtc.org/reference/native-apis
by longrenle
WebRTC Native APIs
版本2.0 (libjingle r115)
2012年2月
WebRTC native APIs文檔 是基於 WebRTC spec 文檔撰寫的.
實現WebRTC native APIs的代碼(包括Stream 和 PeerConnection APIs) 都可以在開源項目libjingle上找到. 另外在該項目中我們還提供了一個簡單的客戶端應用.
這篇文檔的預期讀者是想要用WebRTC Native APIs實現WebRTC javascript APIs或者開發本地RTC應用程序的程序員和工程師們。
內容
- 1 新的內容
- 2 模塊架構圖
- 3 調用序列
- 4 線程模型
- 5 Stream APIs (mediastream.h)
- 6 PeerConnection APIs (peerconnection.h)
- 7 引用
新的內容
與WebRTC native APIs的上一個版本 (代碼在這里，開源項目libjingle r115的一部分)相比, 主要不同是新的版本包括了Stream APIs的實現。使用Stream APIs, 視音頻媒體會在MediaTrack對象中處理，而不是直接交給PeerConnection處理。並且現在PeerConnection在調用中能夠接收和返回MediaStream對象而不是像先前版本中只能處理媒體流標簽。
除此之外，在這個版本中信令處理使用的協議改用了ROAP，這對APIs的用戶應當是透明的。
如果你開發的應用是基於以前的版本，請查看這個補丁來把你的應用遷移到新的APIs來。也可以參考上面提到的簡單的客戶端應用。
模塊架構圖
調用序列
發起通話
接受通話
結束通話
線程模型
WebRTC native APIs 擁有兩個全局線程：信令線程（signaling thread）和工作者線程（worker thread）。取決於PeerConnection factory被創建的方式，應用程序可以提供這兩個線程或者直接使用內部創建好的線程。
Stream APIs和PeerConnection APIs的調用會被代理到信令線程，這就意味着應用程序可以在任何線程調用這些APIs。
所有的回調函數都在信令線程調用。應用程序應當盡快地跳出回調函數以避免阻塞信令線程。嚴重消耗資源的過程都應當其他的線程執行。
工作者線程被用來處理資源消耗量大的過程，比如說數據流傳輸。
Stream APIs (mediastream.h)
Class MediaStreamTrackInterface
這個類聲明了一個媒體流傳輸的抽象接口，用來代表用戶代理（UA）的媒體源。
class MediaStreamTrackInterface : public talk_base::RefCountInterface,
public NotifierInterface {
public:
enum TrackState {
kInitializing,
kLive = 1,
kEnded = 2,
kFailed = 3,
};
virtual std::string kind() const = 0;
virtual std::string label() const = 0;
virtual bool enabled() const = 0;
virtual TrackState state() const = 0;
virtual bool set_enabled(bool enable) = 0;
virtual bool set_state(TrackState new_state) = 0;
};
MediaStreamTrackInterface::TrackState
這個枚舉類型定義了傳輸軌道的狀態。
語法
enum TrackState {
kInitializing,
kLive = 1,
kEnded = 2,
kFailed = 3,
};
備注
kInitializing - 傳輸正在協商.
kLive - 傳輸軌道可用.
kEnded - 傳輸軌道關閉.
kFailed - 傳輸協商失敗.
MediaStreamTrackInterface::kind
如果傳輸音頻軌道返回"audio”，如果傳輸視頻軌道則返回"video" ，或者一個用戶代理定義的其他字符串。
語法
virtual std::string kind() const = 0;
MediaStreamTrackInterface::label
如果有的話返回軌道的標簽，否則返回空串。
語法
virtual std::string label() const = 0;
MediaStreamTrackInterface::enabled
如果軌道可用返回"true”，否則返回"false”.
語法
virtual bool enabled() const = 0;
MediaStreamTrackInterface::state
返回軌道的當前狀態。
語法
virtual TrackState state() const = 0;
MediaStreamTrackInterface::set_enabled
開啟(true) 或者關閉(false) 媒體管道.
語法
virtual bool set_enabled(bool enable) = 0;
備注
Not implemented.
MediaStreamTrackInterface::set_state
設置媒體管道的狀態。
語法
virtual bool set_state(TrackState new_state) = 0;
備注
這個方法應該被PeerConnection內部調用，應用程序不應當直接調用。
Class VideoTrackInterface
類VideoTrackInterface繼承自類MediaStreamTrackInterface，增加了兩個設置和得到視頻渲染器的接口。
class VideoTrackInterface : public MediaStreamTrackInterface {
public:
virtual void SetRenderer(VideoRendererWrapperInterface* renderer) = 0;
virtual VideoRendererWrapperInterface* GetRenderer() = 0;
protected:
virtual ~VideoTrackInterface() {}};
Class LocalVideoTrackInterface
類LocalVideoTrackInterface繼承自類VideoTrackInterface，增加了一個接口得到視頻捕獲設備。.
class LocalVideoTrackInterface : public VideoTrackInterface {
public:
virtual cricket::VideoCapturer* GetVideoCapture() = 0;
protected:
virtual ~LocalVideoTrackInterface() {}
};
Class AudioTrackInterface
類AudioTrackInterface繼承自類MediaStreamTrackInterface，目前沒有其他接口。
class AudioTrackInterface : public MediaStreamTrackInterface {
public:
protected:
virtual ~AudioTrackInterface() {}
};
Class LocalAudioTrackInterface
類LocalAudioTrackInterface繼承自AudioTrackInterface，增加了一個接口來得到音頻設備。
class LocalAudioTrackInterface : public AudioTrackInterface {
public:
virtual AudioDeviceModule* GetAudioDevice() = 0;
protected:
virtual ~LocalAudioTrackInterface() {}
};
Class cricket::VideoRenderer, cricket::VideoCapturer
這些類定義在開源工程libjingle，在這里不再詳細陳述。
Class webrtc::AudioDeviceModule
類AudioDeviceModule定義在開源工程webrtc. 請點擊鏈接參考詳細定義。
Class MediaStreamInterface
這個類聲明了一個MediaStream的抽象接口，該類典型但不是必須的，表示視音頻流。
每一個MediaStream對象可以包含零到多個音頻軌道，尤其視音頻軌道。在一個MediaStream對象的所有媒體軌道在渲染的時候必須是同步的。不同的MediaStream對象不必同步。
class MediaStreamInterface : public talk_base::RefCountInterface,
public NotifierInterface {
public:
virtual std::string label() const = 0;
virtual AudioTracks* audio_tracks() = 0;
virtual VideoTracks* video_tracks() = 0;
enum ReadyState {
kInitializing,
kLive = 1, // Stream alive
kEnded = 2, // Stream have ended
};
virtual ReadyState ready_state() = 0;
protected:
virtual ~MediaStreamInterface() {}
};
MediaStreamInterface::label
返回這個媒體流的唯一標簽，目的是在這些媒體流通過PeerConnection APIs傳輸后能夠被區別清楚。
語法
virtual std::string label() const = 0;
MediaStreamInterface::audio_tracks
返回MediaStreamTrack對象列表的指針，代表與當前MediaStream對象相關的音頻流軌道列表。
語法
virtual AudioTracks* audio_tracks() = 0;
MediaStreamInterface::video_tracks
返回MediaStreamTrack對象列表的指針，代表與當前MediaStream對象相關的視頻流軌道列表。
語法
virtual VideoTracks* video_tracks() = 0;
MediaStreamInterface::ready_state
返回當前MediaStream的狀態是否就緒。
語法
virtual ReadyState ready_state() = 0;
Class LocalMediaStreamInterface
類LocalMediaStreamInterface繼承自類MediaStreamInterface，定義了兩個方法添加視音頻軌道。
class LocalMediaStreamInterface : public MediaStreamInterface {
public:
virtual bool AddTrack(AudioTrackInterface* track) = 0;
virtual bool AddTrack(VideoTrackInterface* track) = 0;}
;
PeerConnection APIs (peerconnection.h)
Class StreamCollectionInterface
這個類定義了一個MediaStream容器接口。
class StreamCollectionInterface : public talk_base::RefCountInterface {
public:
virtual size_t count() = 0;
virtual MediaStreamInterface* at(size_t index) = 0;
virtual MediaStreamInterface* find(const std::string& label) = 0;
protected:
~StreamCollectionInterface() {}
};
StreamCollectionInterface::count
返回MediaStreams集合的數量。
語法
size_t count() = 0;
StreamCollectionInterface::at
返集合中指定位置的MediaStream對象指針。
語法
MediaStreamInterface* at(size_t index) = 0;
參數
index [in] Position of a MediaStream in the collection.
StreamCollectionInterface::find
用標簽查詢MediaStream對象，如果找到返回對象指針，否者返回NULL。
語法
MediaStreamInterface* find(const std::string& label) = 0;
參數
label [in] The label value to be searched for.
Class PeerConnectionObserver
這個類為用戶定義的observer聲明了一個抽象接口。它取決於PeerConnection用戶實現的子類。當PeerConnection被創建的時候用PeerConnectionFactoryInterface類注冊observer對象。
class PeerConnectionObserver {
public:
enum StateType {
kReadyState,
kIceState,
kSdpState,
};
virtual void OnError() = 0;
virtual void OnMessage(const std::string& msg) = 0;
virtual void OnSignalingMessage(const std::string& msg) = 0;
virtual void OnStateChange(StateType state_changed) = 0;
virtual void OnAddStream(MediaStreamInterface* stream) = 0;
virtual void OnRemoveStream(MediaStreamInterface* stream) = 0;
protected:
~PeerConnectionObserver() {}
};
PeerConnectionObserver::StateType
這個枚舉定義了狀態機狀態。
語法
enum StateType {
kReadyState,
kIceState,
kSdpState,
};
PeerConnectionObserver::OnError
當PeerConnection執行中出錯時調用此方法。
語法
void OnError() = 0;
備注
尚未實現。
PeerConnectionObserver::OnMessage
當收到對端的一條文本消息是此方法被調用。
語法
void OnMessage(const std::string& msg) = 0;
PeerConnectionObserver::OnSignalingMessage
當收到信令是調用此方法。
語法
void OnSignalingMessage(const std::string& msg) = 0;
參數
msg [in] A ROAPformat signaling message.
備注
用戶應當從回調函數向對端發送信令。
The user should send the signaling message from the callback to the remote peer.
PeerConnectionObserver::OnStateChange
這個方法當狀態機狀態(ReadyState, SdpState or IceState)改變時被調用。
語法
virtual void OnStateChange(StateType state_changed) = 0;
參數
state_changed [in] Specify which state machine’s state has changed.
備注
IceState尚未實現。
該方法當從對端收到新的媒體流時被調用。
語法
virtual void OnAddStream(MediaStreamInterface* stream) = 0;
參數
stream [in] The handler to the remote media stream.
備注
用戶可以用這個事件為收到的媒體流設置渲染器。
PeerConnectionObserver::OnRemoveStream
當對端關閉媒體流時調用此方法。
語法
virtual void OnRemoveStream(MediaStreamInterface* stream) = 0;
參數
stream [in] The handler to the closed remote media stream.
Class PortAllocatorFactoryInterface
這個類聲明了一個工廠接口來創建cricket::PortAllocator對象，該對象用來做ICE協商。PeerConnection工廠使用這個接口（如果提供）為自己創建PortAllocator。應用程序也可以提供自己的PortAllocator 實現，只要實現了PortAllocatorFactoryInterface的CreatePortAllocator方法。
class PortAllocatorFactoryInterface : public talk_base::RefCountInterface {
public:
struct StunConfiguration {
StunConfiguration(const std::string& address, int port)
: server(address, port) {}
talk_base::SocketAddress server;
};
struct TurnConfiguration {
TurnConfiguration(const std::string& address,
int port,
const std::string& user_name,
const std::string& password)
: server(address, port),
username(username),
password(password) {}
talk_base::SocketAddress server;
std::string username;
std::string password;
};
virtual cricket::PortAllocator* CreatePortAllocator(
const std::vector<StunConfiguration>& stun_servers,
const std::vector<TurnConfiguration>& turn_configurations) = 0;
protected:
PortAllocatorFactoryInterface() {}
~PortAllocatorFactoryInterface() {}
};
PortAllocatorFactoryInterface::CreatePortAllocator
這個方法返回PortAllocator類的實例.
語法
virtual cricket::PortAllocator* CreatePortAllocator(
const std::vector<StunConfiguration>& stun_servers,
const std::vector<TurnConfiguration>& turn_configurations) = 0;參數
stun_servers [in] A configuration list of the STUN servers.
turn_servers [in] A configuration list of the TURN servers.
備注
TURN 尚未實現。
Class PeerConnectionFactoryInterface
PeerConnectionFactoryInterface是一個工廠接口用來創建PeerConnection對象, 媒體流和媒體軌道。
class PeerConnectionFactoryInterface : public talk_base::RefCountInterface {
public:
virtual talk_base::scoped_refptr<PeerConnectionInterface>
CreatePeerConnection(const std::string& config,
PeerConnectionObserver* observer) = 0;
virtual talk_base::scoped_refptr<LocalMediaStreamInterface>
CreateLocalMediaStream(const std::string& label) = 0;
virtual talk_base::scoped_refptr<LocalVideoTrackInterface>
CreateLocalVideoTrack(const std::string& label,
cricket::VideoCapturer* video_device) = 0;
virtual talk_base::scoped_refptr<LocalAudioTrackInterface>
CreateLocalAudioTrack(const std::string& label,
AudioDeviceModule* audio_device) = 0;
protected:
PeerConnectionFactoryInterface() {}
~PeerConnectionFactoryInterface() {}
};
PeerConnectionFactoryInterface::CreatePeerConnection
該方法創建PeerConnection類的實例。
語法
virtual talk_base::scoped_refptr<PeerConnectionInterface>
CreatePeerConnection(const std::string& config,
PeerConnectionObserver* observer) = 0;參數
config [in] STUN或TURN服務器地址用來建立連接的配置字符串。格式定義參考webrtc-api。
observer [in] 繼承PeerConnectionObserver類的實例的指針。
備注
TURN 尚未支持。
接受的配置字符串：
"TYPE 203.0.113.2:3478"表名服務器的IP和端口號。
"TYPE relay.example.net:3478
表明服務器的域名和端口號，用戶代理會從DNS查詢對應IP。
"TYPE example.net"
表明服務器的域名和端口號，用戶代理會從DNS查詢對應IP和端口。
類型"TYPE"可以是一下的一種:
STUN
表明一個STUN服務器。
STUNS
表明一個STUN 服務器並用TLS會話連接。
TURN
表明一個TURN服務器。
TURNS
表明一個TURN服務器並用TLS會話連接。
PeerConnectionFactoryInterface::CreateLocalMediaStream
創建本端媒體流的實例。
語法
virtual talk_base::scoped_refptr<LocalMediaStreamInterface>
CreateLocalMediaStream(const std::string& label) = 0;參數
label [in] Desired local media stream label.
PeerConnectionFactoryInterface::CreateLocalVideoTrack
創建本端視頻軌道的對象。
語法
virtual talk_base::scoped_refptr<LocalVideoTrackInterface>
CreateLocalVideoTrack(const std::string& label,
cricket::VideoCapturer* video_device) = 0;參數
label [in] Desired local video track label.
video_device [in] Pointer to the video capture device that is going to associate with this track.
PeerConnectionFactoryInterface::CreateLocalAudioTrack
創建本端音頻軌道的對象。
語法
virtual talk_base::scoped_refptr<LocalVideoTrackInterface>
CreateLocalAudioTrack(const std::string& label,
AudioDeviceModule* audio_device) = 0;參數
label [in] Desired local audio track label.
audio_device [in] Pointer to the audio device that is going to associate with this track.
函數 CreatePeerConnectionFactory
創建一個PeerConnectionFactoryInterface對象的實例。
語法
talk_base::scoped_refptr<PeerConnectionFactoryInterface>
CreatePeerConnectionFactory();備注
這個生成的PeerConnectionFactoryInterface對象會創建需求的內部資源，包括libjingle 線程，socket ，管理網絡的network manager factory。
函數 CreatePeerConnectionFactory
用給出的libjingle 線程和portallocator對象工廠創建一個PeerConnectionFactoryInterface對象的實例。
Syntax
talk_base::scoped_refptr<PeerConnectionFactoryInterface>
CreatePeerConnectionFactory(talk_base::Thread* worker_thread,
talk_base::Thread* signaling_thread,
PortAllocatorFactoryInterface* factory,
AudioDeviceModule* default_adm);備注
當應用程序想要提供自己實現的線程和portallocator對象時調用該方法。
這些參數的所有權不能轉移到這個對象上，必須在PeerConnectionFactoryInterface的聲明周期范圍內。
Class PeerConnectionInterface
class PeerConnectionInterface : public talk_base::RefCountInterface {
public:
enum ReadyState {
kNew,
kNegotiating,
kActive,
kClosing,
kClosed,
};
enum SdpState {
kSdpNew,
kSdpIdle,
kSdpWaiting,
};
virtual void ProcessSignalingMessage(const std::string& msg) = 0;
virtual bool Send(const std::string& msg) = 0;
virtual talk_base::scoped_refptr<StreamCollectionInterface>
local_streams() = 0;
virtual talk_base::scoped_refptr<StreamCollectionInterface>
remote_streams() = 0;
virtual void AddStream(LocalMediaStreamInterface* stream) = 0;
virtual void RemoveStream(LocalMediaStreamInterface* stream) = 0;
virtual void CommitStreamChanges() = 0;
virtual void Close() = 0;
virtual ReadyState ready_state() = 0;
virtual SdpState sdp_state() = 0;
protected:
~PeerConnectionInterface() {}
};
PeerConnectionInterface::ReadyState
該枚舉定義了就緒狀態的幾種類別狀態。
- kNew - 對象剛被創建並且他的ICE和SDP代理尚未啟動。
- kNegotiating - peerConenction 對象正在嘗試得到媒體的傳輸方式。
- kActive - 連接建立成功，如果任何媒體流協商成功，相關的媒體就可以被傳輸了。
- kClosing - close()方法被調用后對象正在被關閉。
- kClosed - 對象關閉成功。
語法
enum ReadyState {
kNew,
kNegotiating,
kActive,
kClosing,
kClosed,
};
PeerConnectionInterface::SdpState
該枚舉定義了SDP的狀態。
- kSdpNew - 對象剛被創建SDP代理尚未開始。
- kSdpIdle - 有效的請求回答已經交換，SDP代理正在等地下一個SDP事務。
- kSdpWaiting - SDP代理發送了一個SDP請求正在等待響應。.
語法
enum SdpState {
kSdpNew, // TODO(ronghuawu): kSdpNew is not defined in the spec.
kSdpIdle,
kSdpWaiting,
};
PeerConnectionInterface::ProcessSignalingMessage
該方法用來處理對端的信令。
語法
virtual void ProcessSignalingMessage(const std::string& msg) = 0;
參數
msg
[in] A ROAPformat signaling message.
備注
信令的順序是很重要的，如果傳輸的信令與對端產生信令的順序不同的話會使會話的建立失敗或會話連接質量降低。
PeerConnectionInterface::Send
該方法給對端發送一個文本信息。
語法
virtual bool Send(const std::string& msg) = 0; // TODO(ronghuawu): This is not defined in the spec.
參數
msg
[in] The text message to be sent to the remote peer.
備注
尚未實現。（好奇怪老外為什么會release這么多未實現的interface。）
PeerConnectionInterface::local_streams
返回一個用戶代理正在嘗試向對端傳送的媒體流數組（由方法AddStream()添加的視頻流）。
語法
virtual talk_base::scoped_refptr<StreamCollectionInterface>
local_streams() = 0;
PeerConnectionInterface::remote_streams
返回一個用戶代理當前正在從對端接收的媒體流數組。
這個數組當OnAddStream和OnRemoveStream回調函數被調用時被更新。
語法
virtual talk_base::scoped_refptr<StreamCollectionInterface>
remote_streams() = 0;
PeerConnectionInterface::AddStream
添加一個本地媒體流到用戶代理正在嘗試向對端傳送的媒體流數組。這個函數只是添加媒體流並不觸法任何狀態變化直到CommitStreamChanges方法被調用。
語法
virtual void AddStream(LocalMediaStreamInterface* stream) = 0;
參數
stream
[in] Pointer to the local media stream to be added.
PeerConnectionInterface::RemoveStream
刪除一個本地媒體流到用戶代理正在嘗試向對端傳送的媒體流數組。這個函數只是添加媒體流並不觸法任何媒體流狀態變化直到CommitStreamChanges方法被調用。
語法
virtual void RemoveStream(LocalMediaStreamInterface* stream) = 0;
參數
stream
[in] Pointer to the local media stream to be removed.
PeerConnectionInterface::CommitStreamChanges
提交AddStream和RemoveStream調用后造成的媒體流的變化。新媒體流被添加后開始發送媒體，媒體流被移除后停止發送媒體流。
語法
virtual void CommitStreamChanges() = 0;
PeerConnectionInterface::Close
關閉當前的會話。這會觸法發送一個Shutdown消息並且ready_state會切換到kClosing。
語法
virtual void Close() = 0;
PeerConnectionInterface::ready_state
返回PeerConnection對象的readiness state， 由枚舉類型ReadyState表示。
語法
virtual ReadyState ready_state() = 0;
PeerConnectionInterface::sdp_state
返回PeerConnection SDP代理的狀態， 由枚舉類型SdpState表示。
語法
virtual SdpState sdp_state() = 0;
引用
目前HTML5的WebRTC規范說明:
WebRTC Native API 的源碼:
https://code.google.com/p/libjingle/source/browse/trunk/talk/app/webrtc/
客戶端和服務器Demo:
https://code.google.com/p/libjingle/source/browse/trunk/talk/#talk%2Fexamples%2Fpeerconnection