Search this site

API Description

Obsolete version!

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. 1 PeerConnection
    1. 1.1 Calling sequences
    2. 1.2 PeerConnection Native APIs
      1. 1.2.1 Class PeerConnectionObserver
        1. 1.2.1.1 PeerConnectionObserver::OnError
          1. 1.2.1.1.1 Syntax
        2. 1.2.1.2 PeerConnectionObserver::OnSignalingMessage
          1. 1.2.1.2.1 Syntax
          2. 1.2.1.2.2 Parameters
          3. 1.2.1.2.3 Remarks
        3. 1.2.1.3 PeerConnectionObserver::OnAddStream
          1. 1.2.1.3.1 Syntax
          2. 1.2.1.3.2 Parameters
        4. 1.2.1.4 PeerConnectionObserver::OnRemoveStream
          1. 1.2.1.4.1 Syntax
          2. 1.2.1.4.2 Parameters
      2. 1.2.2 Class PeerConnection
        1. 1.2.2.1 PeerConnection::PeerConnection
          1. 1.2.2.1.1 Syntax
          2. 1.2.2.1.2 Parameters
          3. 1.2.2.1.3 Remarks
        2. 1.2.2.2 PeerConnection::Initialize
          1. 1.2.2.2.1 Syntax
          2. 1.2.2.2.2 Return Values
          3. 1.2.2.2.3 Remarks
        3. 1.2.2.3 PeerConnection::RegisterObserver
          1. 1.2.2.3.1 Syntax
          2. 1.2.2.3.2 Parameters
          3. 1.2.2.3.3 Remarks
        4. 1.2.2.4 PeerConnection::SignalingMessage
          1. 1.2.2.4.1 Syntax
          2. 1.2.2.4.2 Parameters
          3. 1.2.2.4.3 Remarks
        5. 1.2.2.5 PeerConnection::AddStream
          1. 1.2.2.5.1 Syntax
          2. 1.2.2.5.2 Parameters
          3. 1.2.2.5.3 Return Values
        6. 1.2.2.6 PeerConnection::RemoveStream
          1. 1.2.2.6.1 Syntax
          2. 1.2.2.6.2 Parameters
          3. 1.2.2.6.3 Return Values
          4. 1.2.2.6.4 Remarks
        7. 1.2.2.7 PeerConnection::Connect
          1. 1.2.2.7.1 Syntax
          2. 1.2.2.7.2 Return Values
          3. 1.2.2.7.3 Remarks
        8. 1.2.2.8 PeerConnection::Close
          1. 1.2.2.8.1 Syntax
          2. 1.2.2.8.2 Return Values
          3. 1.2.2.8.3 Remarks
        9. 1.2.2.9 PeerConnection::SetAudioDevice
          1. 1.2.2.9.1 Syntax
          2. 1.2.2.9.2 Parameters
          3. 1.2.2.9.3 Return Values
        10. 1.2.2.10 PeerConnection::SetLocalVideoRenderer
          1. 1.2.2.10.1 Syntax
          2. 1.2.2.10.2 Parameters
          3. 1.2.2.10.3 Return Values
        11. 1.2.2.11 PeerConnection::SetVideoRenderer
          1. 1.2.2.11.1 Syntax
          2. 1.2.2.11.2 Parameters
          3. 1.2.2.11.3 Return Values
        12. 1.2.2.12 PeerConnection::SetVideoCapture
          1. 1.2.2.12.1 Syntax
          2. 1.2.2.12.2 Parameters
          3. 1.2.2.12.3 Return Values
    3. 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:

The source code of the PeerConnection Native API is here:

Client and server sample apps can be found here:

Comments