WebRTC Native APIs[翻译]

最近一直在研究WebRTC，本篇是WebRTC的本地API文档，Web developer了解一下也是有好处的，了解了API的实现原理使用起来才会更顺手。决定翻译是因为这篇字不多，翻一下加深自己的理解，如果对别人有帮助那就更好了。第一次翻译东西拿出来，如果有错误还望指正，英文好一点的还是移步英文原文吧：http://www.webrtc.org/reference/native-apis
by longrenle

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;
};

enum TrackState {
kInitializing,
kLive = 1,
kEnded = 2,
kFailed = 3,
};

备注

kInitializing - 传输正在协商.
kLive - 传输轨道可用.
kEnded - 传输轨道关闭.
kFailed - 传输协商失败.

如果传输音频轨道返回"audio”，如果传输视频轨道则返回"video" ，或者一个用户代理定义的其他字符串。

语法

virtual std::string kind() const = 0;

如果有的话返回轨道的标签，否则返回空串。

语法

virtual std::string label() const = 0;

如果轨道可用返回"true”，否则返回"false”.

语法

virtual bool enabled() const = 0;

返回轨道的当前状态。

语法

virtual TrackState state() const = 0;

开启(true) 或者关闭(false) 媒体管道.

语法

virtual bool set_enabled(bool enable) = 0;

备注

Not implemented.

设置媒体管道的状态。

语法

virtual bool set_state(TrackState new_state) = 0;

备注

这个方法应该被PeerConnection内部调用，应用程序不应当直接调用。

类VideoTrackInterface继承自类MediaStreamTrackInterface，增加了两个设置和得到视频渲染器的接口。

class VideoTrackInterface : public MediaStreamTrackInterface {
public:
virtual void SetRenderer(VideoRendererWrapperInterface* renderer) = 0;
virtual VideoRendererWrapperInterface* GetRenderer() = 0;
protected:
virtual ~VideoTrackInterface() {}
};

类LocalVideoTrackInterface继承自类VideoTrackInterface，增加了一个接口得到视频捕获设备。.

class LocalVideoTrackInterface : public VideoTrackInterface {

public:

virtual cricket::VideoCapturer* GetVideoCapture() = 0;

protected:

virtual ~LocalVideoTrackInterface() {}

};

类AudioTrackInterface继承自类MediaStreamTrackInterface，目前没有其他接口。

class AudioTrackInterface : public MediaStreamTrackInterface {

public:

protected:

virtual ~AudioTrackInterface() {}

};

类LocalAudioTrackInterface继承自AudioTrackInterface，增加了一个接口来得到音频设备。

class LocalAudioTrackInterface : public AudioTrackInterface {

public:

virtual AudioDeviceModule* GetAudioDevice() = 0;

protected:

virtual ~LocalAudioTrackInterface() {}

};

这些类定义在开源工程libjingle，在这里不再详细陈述。

类AudioDeviceModule定义在开源工程webrtc. 请点击链接参考详细定义。

这个类声明了一个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() {}

};

返回这个媒体流的唯一标签，目的是在这些媒体流通过PeerConnection APIs传输后能够被区别清楚。

语法

virtual std::string label() const = 0;

返回MediaStreamTrack对象列表的指针，代表与当前MediaStream对象相关的音频流轨道列表。

语法

virtual AudioTracks* audio_tracks() = 0;

返回MediaStreamTrack对象列表的指针，代表与当前MediaStream对象相关的视频流轨道列表。

语法

virtual VideoTracks* video_tracks() = 0;

返回当前MediaStream的状态是否就绪。

语法

virtual ReadyState ready_state() = 0;

类LocalMediaStreamInterface继承自类MediaStreamInterface，定义了两个方法添加视音频轨道。

class LocalMediaStreamInterface : public MediaStreamInterface {
public:
virtual bool AddTrack(AudioTrackInterface* track) = 0;
virtual bool AddTrack(VideoTrackInterface* track) = 0;

}

[b]这个类定义了一个MediaStream容器接口。[/b]

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() {}
};

返回MediaStreams集合的数量。

语法

size_t count() = 0;

返集合中指定位置的MediaStream对象指针。

语法

MediaStreamInterface* at(size_t index) = 0;

参数

index [in] Position of a MediaStream in the collection.

用标签查询MediaStream对象，如果找到返回对象指针，否者返回NULL。

语法

MediaStreamInterface* find(const std::string& label) = 0;

参数

label [in] The label value to be searched for.

这个类为用户定义的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() {}
};

这个枚举定义了状态机状态。

语法

enum StateType {
kReadyState,
kIceState,
kSdpState,
};

当PeerConnection执行中出错时调用此方法。

语法

void OnError() = 0;

备注

尚未实现。

当收到对端的一条文本消息是此方法被调用。

语法

void OnMessage(const std::string& msg) = 0;

当收到信令是调用此方法。

语法

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.

这个方法当状态机状态(ReadyState, SdpState or IceState)改变时被调用。

语法

virtual void OnStateChange(StateType state_changed) = 0;

参数

state_changed [in] Specify which state machine’s state has changed.

备注

IceState尚未实现。

PeerConnectionObserver::OnAddStream

该方法当从对端收到新的媒体流时被调用。

语法

virtual void OnAddStream(MediaStreamInterface* stream) = 0;

参数

stream [in] The handler to the remote media stream.

备注

用户可以用这个事件为收到的媒体流设置渲染器。

当对端关闭媒体流时调用此方法。

语法

virtual void OnRemoveStream(MediaStreamInterface* stream) = 0;

参数

stream [in] The handler to the closed remote media stream.

这个类声明了一个工厂接口来创建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() {}
};

这个方法返回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 尚未实现。

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() {}
};

该方法创建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"

"TYPE relay.example.net:3478

"TYPE example.net"

STUN

STUNS

TURN

TURNS

创建本端媒体流的实例。

语法

virtual talk_base::scoped_refptr<LocalMediaStreamInterface>
CreateLocalMediaStream(const std::string& label) = 0;

参数

label [in] Desired local media stream label.

创建本端视频轨道的对象。

语法

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.

创建本端音频轨道的对象。

语法

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.

创建一个PeerConnectionFactoryInterface对象的实例。

语法

talk_base::scoped_refptr<PeerConnectionFactoryInterface>
CreatePeerConnectionFactory();

备注

这个生成的PeerConnectionFactoryInterface对象会创建需求的内部资源，包括libjingle 线程，socket ，管理网络的network manager factory。

用给出的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 : 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() {}
};

该枚举定义了就绪状态的几种类别状态。

kNew - 对象刚被创建并且他的ICE和SDP代理尚未启动。

kNegotiating - peerConenction 对象正在尝试得到媒体的传输方式。

kActive - 连接建立成功，如果任何媒体流协商成功，相关的媒体就可以被传输了。

kClosing - close()方法被调用后对象正在被关闭。

kClosed - 对象关闭成功。

语法
enum ReadyState {
kNew,
kNegotiating,
kActive,
kClosing,
kClosed,
};

该枚举定义了SDP的状态。

kSdpNew - 对象刚被创建SDP代理尚未开始。

kSdpIdle - 有效的请求回答已经交换，SDP代理正在等地下一个SDP事务。

kSdpWaiting - SDP代理发送了一个SDP请求正在等待响应。.

语法

enum SdpState {

kSdpNew, // TODO(ronghuawu): kSdpNew is not defined in the spec.

kSdpIdle,

kSdpWaiting,

};

该方法用来处理对端的信令。

语法

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。）

返回一个用户代理正在尝试向对端传送的媒体流数组（由方法AddStream()添加的视频流）。

语法

virtual talk_base::scoped_refptr<StreamCollectionInterface>

local_streams() = 0;

返回一个用户代理当前正在从对端接收的媒体流数组。

这个数组当OnAddStream和OnRemoveStream回调函数被调用时被更新。

语法

virtual talk_base::scoped_refptr<StreamCollectionInterface>

remote_streams() = 0;

添加一个本地媒体流到用户代理正在尝试向对端传送的媒体流数组。这个函数只是添加媒体流并不触法任何状态变化直到CommitStreamChanges方法被调用。

语法

virtual void AddStream(LocalMediaStreamInterface* stream) = 0;

参数

stream

[in] Pointer to the local media stream to be added.

删除一个本地媒体流到用户代理正在尝试向对端传送的媒体流数组。这个函数只是添加媒体流并不触法任何媒体流状态变化直到CommitStreamChanges方法被调用。

语法

virtual void RemoveStream(LocalMediaStreamInterface* stream) = 0;

参数

stream

[in] Pointer to the local media stream to be removed.

提交AddStream和RemoveStream调用后造成的媒体流的变化。新媒体流被添加后开始发送媒体，媒体流被移除后停止发送媒体流。

语法

virtual void CommitStreamChanges() = 0;

关闭当前的会话。这会触法发送一个Shutdown消息并且ready_state会切换到kClosing。

语法

virtual void Close() = 0;

返回PeerConnection对象的readiness state， 由枚举类型ReadyState表示。

语法

virtual ReadyState ready_state() = 0;

返回PeerConnection SDP代理的状态， 由枚举类型SdpState表示。

语法

virtual SdpState sdp_state() = 0;