RTCPeerConnection : constructeur RTCPeerConnection()
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since January 2020.
Le constructeur RTCPeerConnection()
renvoie un nouvel objet RTCPeerConnection
qui représente une connexion entre l'appareil local et un pair distant.
Syntaxe
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 connexionRTCPeerConnection
. 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 objetsRTCCertificate
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 connexionRTCPeerConnection
. 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 estnull
. 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