RTCPeerConnection : constructeur RTCPeerConnection()

Le constructeur RTCPeerConnection() renvoie un nouvel objet RTCPeerConnection qui représente une connexion entre l'appareil local et un pair distant.

Syntaxe

js
new RTCPeerConnection()
new RTCPeerConnection(configuration)

Paramètres

configuration Facultatif

Un objet fournissant des options de configuration pour la nouvelle connexion :

bundlePolicy Facultatif

Définit comment la négociation des candidats est gérée lorsque le pair distant n'est pas compatible avec le standard SDP BUNDLE. Si le point d'accès distant est compatible avec BUNDLE, toutes les pistes de médias et les canaux de données sont regroupés dans un seul transport à la fin de la négociation, quelle que soit la politique utilisée. Les transports désormais inutiles qui auraient été créés initialement sont désormais fermés.

Autrement dit, sur le plan technique, un tel empaquetage (bundle) permet à ce que l'ensemble des médias entre deux pairs transite d'une seule adresse IP et d'un port unique depuis le premier pair vers une seule adresse IP et un seul port vers l'autre pair, en utilisant le même protocole de transport.

Cette option doit prendre l'une des valeurs suivantes (si ça ne correspond pas, c'est balanced qui sera prise par défaut) :

"balanced"

L'agent ICE crée initialement un transport (RTCDtlsTransport) pour chaque type de contenu ajouté : audio, vidéo, et canaux de données. Si le point d'accès distant n'est pas compatible avec BUNDLE, chacun de ces transports DTLS gère la communication pour un seul type de données.

"max-compat"

L'agent ICE crée initialement un transport (RTCDtlsTransport) par piste de média et un transport séparé pour les canaux de données. Si le point d'accès distant n'est pas compatible avec BUNDLE, tout est négocié sur ces transports DTLS séparés.

"max-bundle"

L'agent ICE crée initialement un seul transport (RTCDtlsTransport) pour l'ensemble des données de la connexion RTCPeerConnection. Si le point d'accès distant n'est pas compatible avec BUNDLE, seule une piste sera négociée, et le reste sera ignoré.

certificates Facultatif

Un tableau (Array) contenant des objets RTCCertificate utilisés par la connexion pour l'authentification. Si cette propriété n'est pas fournie, un ensemble de certificats est généré automatiquement pour chaque connexion RTCPeerConnection. Bien qu'un seul certificat est utilisé pour une connexion donnée, fournir des certificats basés sur des algorithmes différents pourra augmenter les chances de réussir la connexion dans certaines conditions circonstances. Voir ci-après, la section sur l'utilisation des certificats pour plus d'informations.

Note : Cette option de configuration ne peut pas être modifiée après qu'elle a été fournie initialement. Une fois que les certificats ont été paramétrés, cette propriété sera ignorée par les appels ultérieurs à RTCPeerConnection.setConfiguration().

iceCandidatePoolSize Facultatif

Un entier non-signé sur 16 bits qui indique la taille du volume de candidats ICE qui seront collectés au préalable (prefetched). La valeur par défaut est 0 (indiquant qu'aucune collecte préalable des candidats n'a lieu). Dans certains cas, l'établissement de la connexion pourra être plus rapide en permettant à l'agent ICE de récupérer les candidats ICE avant la tentative de connexion, afin qu'ils soient disponibles pour une inspection lors de l'appel à RTCPeerConnection.setLocalDescription().

Note : Modifier la taille du volume de candidats ICE pourra déclencher le début de la collecte ICE.

iceServers Facultatif

Un tableau d'objets qui décrivent chacun un serveur qui pourra être utilisé par l'agent ICE. Il s'agit généralement de serveur STUN ou TURN. Si cette propriété n'est pas fournie, la connexion sera tentée sans serveur STUN ou TURN, ce qui limitera la connexion aux pairs locaux. Les propriétés possibles pour ces objets représentant des serveurs ICE sont :

credential Facultatif

Les informations d'authentification à utiliser pour se connecter au serveur. Cette propriété est uniquement utilisée si l'objet représente un serveur TURN.

credentialType Facultatif Obsolète Non-standard

Si l'objet représente un serveur TURN, cet attribut définit le type d'information d'authentification (voir credential) utilisée. La valeur par défaut est "password".

urls

Cette propriété nécessaire est une chaîne de caractères ou un tableau de chaînes de caractères qui sont des URL pouvant être utilisées pour se connecter au serveur.

username Facultatif

Si le serveur est un serveur TURN, il s'agit du nom d'utilisateur à utiliser lors de l'authentification.

iceTransportPolicy Facultatif

Une chaîne de caractères représentant la politique de transport ICE courante. Les valeurs possibles sont :

"all"

L'ensemble des candidats ICE est pris en compte. Il s'agit de la valeur par défaut.

"public" Obsolète

Seuls les candidats ICE dotés d'une adresse IP publique seront pris en compte.

"relay"

Seuls les candidats ICE dont les adresses IP sont relayées seront pris en compte (par exemple ceux qui passent par un serveur TURN).

peerIdentity Facultatif

Une chaîne de caractères qui définit l'identité cible pour le pair distant, pour la connexion RTCPeerConnection. Si cette valeur est définie, la connexion ne s'établira pas avec le pair distant à moins de s'authentifier correctement avec le nom fourni. La valeur par défaut est null.

rtcpMuxPolicy Facultatif

Une chaîne de caractères représentant la politique de multiplexage RTCP à utiliser lors de la collecte des candidats ICE afin de prendre en charge le RTCP non-multiplexé. Les valeurs possibles sont :

"negotiate"

Indique à l'agent ICE de collecter les candidats RTP et RTCP. Si le pair distant prend en charge le RTCP multiplexé, les candidats RTCP sur multiplexés par-dessus les candidats RTP correspondants. Sinon, les candidats RTP et RTCP sont renvoyés séparément.

"require"

Indique à l'agent ICE de collecter les candidats uniquement pour RTP et de multiplexer RTCP par-dessus. Si le pair distant ne prend pas en charge le multiplexage RTCP, la négociation de la session échoue. Il s'agit de la valeur par défaut.

Valeur de retour

Un nouvel objet RTCPeerConnection, configuré avec les options données par l'argument configuration, s'il a été fourni, sinon la connexion est configurée avec des paramètres par défaut simples et appropriés.

Utiliser des certificats

Lorsque vous souhaitez fournir vos propres certificats à utiliser dans une connexion RTCPeerConnection (plutôt que la création de RTCPeerConnection les génère automatiquement), il vous faut appeler la fonction statique RTCPeerConnection.generateCertificate().

La propriété de la valeur certificates ne peut pas être changée une fois qu'elle a été spécifiée. Si cette propriété est incluse plus tard dans la configuration passée dans un appel à setConfiguration(), elle sera alors ignorée.

Cet attribut prend en charge la fourniture de plusieurs certificats, même si une connexion DTLS donnée n'utilisera qu'un seul certificat. Fournir plusieurs certificats permet de prendre en charge plusieurs algorithmes de chiffrement. C'est l'implémentation de RTCPeerConnection qui choisira le certificat à utiliser, en fonction des algorithmes que l'agent et le pair distant prennent en charge, ce qui est déterminé lors de la poignée de main DTLS.

Si vous ne fournissez pas de certificats, de nouveaux sont générés automatiquement. Fournir ses propres certificats aura comme avantage de permettre une continuité de l'identité, telle que perçue par le pair distant (qui pourra comprendre qu'il s'agit toujours du même appelant). Par ailleurs, cela évite le coût de génération de nouvelles clés à chaque connexion.

Spécifications

Specification
WebRTC: Real-Time Communication in Browsers
# dom-peerconnection

Compatibilité des navigateurs

BCD tables only load in the browser

Voir aussi