API Description 官方整理

API Description

WebRTC builds on the PeerConnection API. This API abstracts several key  components for realtime audio, video, networking and signal. We  encourage you to get familiarized with the PeerConnection API below, as  it represents what browser vendors will be implementing and exposing to  you as a web application developer. The Peer Connection API abstracts the underlying components.  Adopting the top level API is therefore highly recommended. Should they  be needed, the underlying APIs are available. Contents 1 PeerConnection 1.1 Calling sequences 1.2 PeerConnection Native APIs 1.2.1 Class PeerConnectionObserver 1.2.1.1 PeerConnectionObserver::OnError 1.2.1.1.1 Syntax 1.2.1.2 PeerConnectionObserver::OnSignalingMessage 1.2.1.2.1 Syntax 1.2.1.2.2 Parameters 1.2.1.2.3 Remarks 1.2.1.3 PeerConnectionObserver::OnAddStream 1.2.1.3.1 Syntax 1.2.1.3.2 Parameters 1.2.1.4 PeerConnectionObserver::OnRemoveStream 1.2.1.4.1 Syntax 1.2.1.4.2 Parameters 1.2.2 Class PeerConnection 1.2.2.1 PeerConnection::PeerConnection 1.2.2.1.1 Syntax 1.2.2.1.2 Parameters 1.2.2.1.3 Remarks 1.2.2.2 PeerConnection::Initialize 1.2.2.2.1 Syntax 1.2.2.2.2 Return Values 1.2.2.2.3 Remarks 1.2.2.3 PeerConnection::RegisterObserver 1.2.2.3.1 Syntax 1.2.2.3.2 Parameters 1.2.2.3.3 Remarks 1.2.2.4 PeerConnection::SignalingMessage 1.2.2.4.1 Syntax 1.2.2.4.2 Parameters 1.2.2.4.3 Remarks 1.2.2.5 PeerConnection::AddStream 1.2.2.5.1 Syntax 1.2.2.5.2 Parameters 1.2.2.5.3 Return Values 1.2.2.6 PeerConnection::RemoveStream 1.2.2.6.1 Syntax 1.2.2.6.2 Parameters 1.2.2.6.3 Return Values 1.2.2.6.4 Remarks 1.2.2.7 PeerConnection::Connect 1.2.2.7.1 Syntax 1.2.2.7.2 Return Values 1.2.2.7.3 Remarks 1.2.2.8 PeerConnection::Close 1.2.2.8.1 Syntax 1.2.2.8.2 Return Values 1.2.2.8.3 Remarks 1.2.2.9 PeerConnection::SetAudioDevice 1.2.2.9.1 Syntax 1.2.2.9.2 Parameters 1.2.2.9.3 Return Values 1.2.2.10 PeerConnection::SetLocalVideoRenderer 1.2.2.10.1 Syntax 1.2.2.10.2 Parameters 1.2.2.10.3 Return Values 1.2.2.11 PeerConnection::SetVideoRenderer 1.2.2.11.1 Syntax 1.2.2.11.2 Parameters 1.2.2.11.3 Return Values 1.2.2.12 PeerConnection::SetVideoCapture 1.2.2.12.1 Syntax 1.2.2.12.2 Parameters 1.2.2.12.3 Return Values 1.3 Reference PeerConnection PeerConnection is the top level API for WebRTC. The actual code that implements PeerConnection is now a part of libjingle. While PeerConnection has no session protocol and no XMPP/Jingle is  required, we've reused many useful components from the libjingle  package. This API is intended to implement the W3C WebRTC API proposal for PeerConnection JavaScript API in C++. Calling sequences Start a call Disconnect a call Receive a call from the remote peer Remote Peer initiates the disconnection PeerConnection Native APIs Class PeerConnectionObserver This class declares an abstract interface for a user defined observer.  It is up to the PeerConnection user to implement a derived class which  implements the observer class. The observer is registered using  RegisterObserver(). class  PeerConnectionObserver { public:   virtual void OnError();   virtual void OnSignalingMessage(const std::string& msg);   virtual void OnAddStream(const std::string& stream_id,                            int channel_id,                            bool video);   virtual void OnRemoveStream(const std::string& stream_id,                               int channel_id,                               bool video); }; PeerConnectionObserver::OnError This method will be called when an error occurs in PeerConnection. Syntax void OnError(); PeerConnectionObserver::OnSignalingMessage This method is called once there’s a signaling message is ready. Syntax void OnSignalingMessage(const std::string& msg); Parameters msg [in] A Json format signaling message. Remarks Signaling message consists of only SDP "type" message will not have any additional information about session. The user should send the signaling message from the callback to the remote peer. The signaling message passed to this callback has various meanings depends on the client and the current state: If the client is the initiator of a call, the message is the offer to the remote peer. If the client is not the initiator and just received an offer,  the message is an answer. If the client has called PeerConnection::Close, then this is the signal to the other end that we're shutting down. PeerConnectionObserver::OnAddStream This method is called when a remote peer accepts a media connection. Syntax void OnAddStream(const std::string& stream_id, bool video); Parameters stream_id [in] Remote media stream id. video [in] True if it’s a video stream; false if it’s a voice stream PeerConnectionObserver::OnRemoveStream This method is called when a communication channel between the peers has ended. Syntax void OnRemoveStream(const std::string& stream_id, bool video); Parameters stream_id [in] Remote media stream id. video [in] True if it’s a video stream; false if it’s a voice stream Class PeerConnection class  PeerConnection { public:   explicit PeerConnection(const std::string& config);   bool Initialize();   void RegisterObserver(PeerConnectionObserver* observer);   bool SignalingMessage(const std::string& msg);   bool AddStream(const std::string& stream_id, bool video);   bool RemoveStream(const std::string& stream_id);   bool Connect();   void Close();   bool SetAudioDevice(const std::string& wave_in_device,                       const std::string& wave_out_device);   bool SetLocalVideoRenderer(cricket::VideoRenderer* renderer);   bool SetVideoRenderer(const std::string& stream_id,                         cricket::VideoRenderer* renderer);   bool SetVideoCapture(const std::string& cam_device); }; PeerConnection::PeerConnection Constructor. Syntax PeerConnection::PeerConnection(const std::string& config); Parameters config [in] The configuration string gives the address of a STUN or TURN server to use to establish the connection Remarks The allowed formats for the config string are: "TYPE 203.0.113.2:3478" - Indicates a specific IP address and port for the server. "TYPE relay.example.net:3478" - Indicates a specific host and port for the server; the user agent will look up the IP address in DNS. "TYPE example.net" - Indicates a specific domain for the server; the user agent will look up the IP address and port in DNS. The "TYPE" is one of: STUN - Indicates a STUN server STUNS - Indicates a STUN server that is to be contacted using a TLS session. TURN - Indicates a TURN server TURNS - Indicates a TURN server that is to be contacted using a TLS session. PeerConnection::Initialize Initialize PeerConnection. Syntax bool Initialize(); Return Values The return value is true if the function succeeds. If the function fails, the return value is false. Remarks This should be called before any other PeerConnection APIs. PeerConnection::RegisterObserver Registers an instance of a user implementation of the PeerConnectionObserver. Syntax void RegisterObserver(PeerConnectionObserver* observer); Parameters observer [in] A pointer to an instance of the PeerConnectionObserver derived class. Remarks RegisterObserver must be called on the constructing thread however and once a connection has been initiated, it should not be called again as the pointer is  referenced from other threads. PeerConnection::SignalingMessage Handle a signaling message from the remote peer. Syntax void SignalingMessage(const std::string& msg); Parameters msg [in] A Json format signaling message. Remarks There is no support of mid-call session signaling exchange supported in this  version of PC. After session setup, only messages are allowed is tearing down the session ( via RemoveStream or close). PeerConnection::AddStream Attempts to starting sending the given stream to the remote peer. Syntax bool AddStream(const std::string& stream_id, bool video); Parameters stream_id [in] Local stream id. video [in] True for video; false for voice. Return Values The return value is true if the function succeeds. If the function fails, the return value is false. PeerConnection::RemoveStream Stops sending of the given stream to the remote peer. Syntax bool RemoveStream(const std::string& stream_id); Parameters stream_id [in] Local stream id. Return Values The return value is true if the function succeeds. If the function fails, the return value is false. Remarks After successfully closing the local stream, PC will invoke  OnSignalingMessage callback. This message consists of all the streams  media information and ICE candidates, but those closed stream's ICE  candidates will have port number set to 0. PeerConnection::Connect Syntax bool Connect(); Return Values The return value is true if the function succeeds. If the function fails, the return value is false. Remarks The Connect method tells PC it is time to send signaling information after  AddStream. So all AddStreams should be called before connect, otherwise  it doesn't know when to kick in sending signaling information. After calling to Connect, the PeerConnectionObserver::OnSignalingMessage will be triggered with a signaling message. This signalling message is the  offer to the remote peer. The user should send this signaling message to the remote peer he/she wants to connect. PeerConnection::Close Remove all the streams and tearing down the session. Syntax bool Close(); Return Values The return value is true if the function succeeds. If the function fails, the return value is false. Remarks After the Close() is called, the OnSignalingMessage will be invoked  asynchronously. And before OnSignalingMessage is called, OnRemoveStream  will be called for each stream that was active PeerConnection::SetAudioDevice Set the audio input & output devices. Syntax bool SetAudioDevice(const std::string& wave_in_device,                     const std::string& wave_out_device); Parameters wave_in_device  [in] Audio input device name, an empty string means to use the default device. wave_out_device  [in] Audio output device name, an empty string means to use the default device. Return Values The return value is true if the function succeeds. If the function fails, the return value is false. PeerConnection::SetLocalVideoRenderer Set the video renderer for camera preview. Syntax bool SetLocalVideoRenderer(cricket::VideoRenderer* renderer); Parameters renderer  [in] A pointer to an instance of the cricket::VideoRenderer derived class. Return Values The return value is true if the function succeeds. If the function fails, the return value is false. PeerConnection::SetVideoRenderer Set the video renderer for the specified stream. Syntax bool SetVideoRenderer(const std::string& stream_id, cricket::VideoRenderer* renderer); Parameters stream_id   [in] Remote media stream id. renderer  [in] A pointer to an instance of the cricket::VideoRenderer derived class. Return Values The return value is true if the function succeeds. If the function fails, the return value is false. PeerConnection::SetVideoCapture Set the video capture device. Syntax bool SetVideoCapture(const std::string& cam_device); Parameters cam_device   [in] Video capture device name, an empty string means to use the default device. Return Values The return value is true if the function succeeds. If the function fails, the return value is false. Reference The current HTML5 specification for video conferencing and PeerConnection is here: http://dev.w3.org/2011/webrtc/editor/webrtc.html The source code of the PeerConnection Native API is here: http://code.google.com/p/webrtc/source/browse/trunk/third_party_mods/libjingle/source/talk/app/webrtc Client and server sample apps can be found here: http://code.google.com/p/webrtc/source/browse/trunk/peerconnection/samples