RTCPeerConnection
=================

La interfaz **`RTCPeerConnection`** representa una conexión WebRTC entre la computadora local y un par remoto. Proporciona métodos para conectarse a un par remoto, mantener y monitorear la conexión y cerrar la conexión una vez que ya no se necesita.

EventTarget

RTCPeerConnectionConstructor
-----------

`RTCPeerConnection()` (en-US)

Devuelve un `RTCPeerConnection` recién creado, que representa una conexión entre el dispositivo local y un par remoto.

Propiedades de instancia
------------------------

*También hereda propiedades de `EventTarget`.*

`canTrickleIceCandidates` Read only 

Devuelve un valor booleano que indica si el par remoto puede aceptar o no candidatos *trickled ICE*.

`connectionState` (en-US) Read only 

Indica el estado actual de la conexión entre pares devolviendo una de las cadenas `new`, `connecting`, `connected`, `disconnected`, `failed` o `closed`.

`currentLocalDescription` (en-US) Read only 

 Devuelve un objeto `RTCSessionDescription` (en-US) que describe el extremo local de la conexión tal como se negoció con éxito más recientemente desde la última vez que esta `RTCPeerConnection` terminó de negociar y conectarse a un par remoto.
 También se incluye una lista de los candidatos de ICE que ya puede haber generado el agente de ICE desde que se instanciaron por primera vez la oferta o respuesta representada por la descripción.


`currentRemoteDescription` (en-US) Read only 

 Devuelve un objeto `RTCSessionDescription` (en-US) que describe el extremo remoto de la conexión tal como se negoció con éxito más recientemente desde la última vez que `RTCPeerConnection` terminó de negociar y conectarse a un par remoto.
 También se incluye una lista de los candidatos de ICE que ya puede haber generado el agente de ICE desde que se instanciaron por primera vez la oferta o respuesta representada por la descripción.


`iceConnectionState` (en-US) Read only 

 Devuelve una cadena cuyo estado del agente ICE asociado con este RTCPeerConnection.
 Puede ser uno de los siguientes valores: `new`, `checking`, `connected`, `completed`, `failed`, `disconnected` o `closed`.


`iceGatheringState` (en-US) Read only 

 Devuelve una cadena que describe el estado de recopilación de ICE de la conexión. Esto le permite detectar, por ejemplo, cuándo finalizó la recopilación de candidatos de ICE.
 Los valores posibles son: `new`, `gathering` o `complete`.


`localDescription` (en-US) Read only 

Devuelve un `RTCSessionDescription` (en-US) que describe la sesión para el extremo local de la conexión. Si aún no se ha configurado, devuelve `null`.

`peerIdentity` (en-US) Read only .

Devuelve una `Promesa` que se resuelve en un `RTCIdentityAssertion` (en-US) que contiene una cadena que identifica al par remoto. Una vez que esta promesa se resuelve con éxito, la identidad resultante es la identidad del par de destino y no cambiará durante la duración de la conexión.

`pendingLocalDescription` (en-US) Read only 

Devuelve un objeto `RTCSessionDescription` (en-US) que describe un cambio de configuración pendiente para el extremo local de la conexión. Esto no describe la conexión tal como está actualmente, sino como puede existir en un futuro próximo.

`pendingRemoteDescription` (en-US) Read only 

Devuelve un objeto `RTCSessionDescription` (en-US) que describe un cambio de configuración pendiente para el extremo remoto de la conexión. Esto no describe la conexión tal como está actualmente, sino como puede existir en un futuro próximo.

`remoteDescription` (en-US) Read only 

Devuelve un objeto `RTCSessionDescription` (en-US) que describe la sesión, incluida la configuración y la información multimedia, para el extremo remoto de la conexión. Si aún no se ha establecido, devuelve `null`.

`sctp` (en-US) Read only 

Devuelve un objeto `RTCSctpTransport` (en-US) que describe la capa de transporte SCTP (en-US) sobre la que se envían y reciben los datos SCTP. Si no se ha negociado SCTP, este valor es `null`.

`signalingState` (en-US) Read only 

Devuelve una cadena que describe el estado del proceso de señalización en el extremo local de la conexión mientras se conecta o se vuelve a conectar a otro par. Es uno de los siguientes valores: `stable`, `have-local-offer`, `have-remote-offer`, `have-local-pranswer`, `have-remote-pranswer` o `closed`.

Métodos estáticos
-----------------

`generateCertificate()` (en-US)

Crea un certificado X.509 y su clave privada correspondiente, devolviendo una `Promesa` que se resuelve con el nuevo `RTCCertificate` (en-US) una vez que se genera.

Métodos de instancia
--------------------

*También hereda métodos de `EventTarget`.*

`addIceCandidate()` (en-US)

Agrega un nuevo candidato remoto a la descripción remota de `RTCPeerConnection`, que describe el estado del extremo remoto de la conexión.

`addTrack()` (en-US)

Agrega un nuevo `MediaStreamTrack` al conjunto de pistas que se transmitirán al otro par.

`addTransceiver()` (en-US)

Crea un nuevo `RTCRtpTransceiver` (en-US) y lo agrega al conjunto de transceptores asociados con la conexión. Cada transceptor representa un flujo bidireccional, con `RTCRtpSender` (en-US) y `RTCRtpReceiver` asociados con él.

`close()` (en-US)

Cierra la conexión de pares actual.

`createAnswer()` (en-US)

 Inicia la creación de una respuesta SDP (en-US) a una oferta recibida de un par remoto durante la negociación de oferta/respuesta de una conexión WebRTC.
 La respuesta contiene información sobre cualquier medio ya adjunto a la sesión, códecs y opciones compatibles con el navegador, y cualquier candidato ICE (en-US) ya recopilado.


`createDataChannel()` (en-US)

Inicia la creación de un nuevo canal vinculado con el par remoto, sobre el cual se puede transmitir cualquier tipo de datos. Esto puede ser útil para contenido de canal secundario, como imágenes, transferencia de archivos, chat de texto, paquetes de actualización de juegos, etc.

`createOffer()` (en-US)

 Inicia la creación de una oferta de SDP (en-US) con el fin de iniciar una nueva conexión WebRTC a un interlocutor remoto.
 La oferta de SDP incluye información sobre cualquier objeto `MediaStreamTrack` ya adjunto a la sesión, el códec y las opciones de WebRTC admitidos por el navegador, así como cualquier candidato ya recopilado por el agente ICE (en-US), con el fin de ser enviado por el canal de señalización a un posible par para solicitar una conexión o actualizar la configuración de una conexión existente.


`getConfiguration()` (en-US)

Devuelve un objeto que indica la configuración actual de la conexión.

`getIdentityAssertion()` (en-US)

Inicia la recopilación de una afirmación de identidad y devuelve una `Promesa` que se resuelve en una afirmación de identidad codificada como una cadena. Esto tiene efecto solo si `signalingState` (en-US) no es `closed`.

`getReceivers()` (en-US)

Devuelve un arreglo de objetos `RTCRtpReceiver`, cada uno de los cuales representa un receptor RTP (en-US).

`getSenders()` (en-US)

Devuelve un arrreglo de objetos `RTCRtpSender` (en-US), cada uno de los cuales representa el remitente RTP (en-US) responsable de transmitir los datos de una pista.

`getStats()` (en-US)

Devuelve una `Promesa` que se resuelve con datos que proporcionan estadísticas sobre la conexión general o sobre el `MediaStreamTrack` especificado.

`getTransceivers()` (en-US)

Devuelve una lista de todos los objetos `RTCRtpTransceiver` (en-US) que se utilizan para enviar y recibir datos en la conexión.

`removeTrack()` (en-US)

Le dice al extremo local de la conexión que deje de enviar medios desde la pista especificada, sin eliminar realmente el `RTCRtpSender` (en-US) correspondiente de la lista de remitentes según lo informado por  `getSenders()` (en-US). Si la pista ya está detenida o no está en la lista de remitentes de la conexión, este método no tiene efecto.

`restartIce()` (en-US)

Permite solicitar fácilmente que la recopilación de candidatos ICE se rehaga en ambos extremos de la conexión. Esto simplifica el proceso al permitir que la persona que llama o el receptor utilicen el mismo método para activar un reinicio ICE (en-US).

`setConfiguration()` (en-US)

Establece la configuración actual de la conexión en función de los valores incluidos en el objeto especificado. Esto le permite cambiar los servidores ICE (en-US) utilizados por la conexión y qué políticas de transporte utilizar.

`setIdentityProvider()` (en-US)

Establece el proveedor de identidad (IdP) en el triplete dado en el parámetro: su nombre, el protocolo utilizado para comunicarse con él y un nombre de usuario. El protocolo y el nombre de usuario son opcionales.

`setLocalDescription()` (en-US)

 Cambia la descripción local asociada con la conexión. Esta descripción especifica las propiedades del extremo local de la conexión, incluido el formato de medios.
 Devuelve una `Promesa` que se cumple una vez que se ha cambiado la descripción, de forma asíncrona.


`setRemoteDescription()` (en-US)

 Establece la descripción de la sesión especificada como la oferta o respuesta actual del interlocutor remoto. La descripción especifica las propiedades del extremo remoto de la conexión, incluido el formato de medios.
 Devuelve una `Promesa` que se cumple una vez que se ha cambiado la descripción, de forma asíncrona.


### Métodos obsoletos

`addStream()` (en-US) 
Obsoleto

Non-standard

Agrega un `MediaStream` (en-US) como fuente local de audio o video. En lugar de usar este método obsoleto, debe usar `addTrack()` (en-US) una vez por cada pista que desee enviar al interlocutor remoto.

`createDTMFSender()` 
Obsoleto

Crea un nuevo `RTCDTMFSender` (en-US), asociado a un `MediaStreamTrack` específico, que podrá enviar señalización telefónica DTMF (en-US) a través de la conexión .

`removeStream()` (en-US) 
Obsoleto

Non-standard

 Elimina un `MediaStream` (en-US) como fuente local de audio o video.
 Debido a que este método está obsoleto, en su lugar debe usar `removeTrack()` (en-US).


Eventos
-------

Detecte estos eventos usando `addEventListener()` o asignando un detector de eventos a la propiedad `oneventname` de esta interfaz.

`connectionstatechange` (en-US)

Enviado cuando cambia el estado general de conectividad de `RTCPeerConnection`.

`datachannel` (en-US)

Enviado cuando el par remoto agrega un `RTCDataChannel` (en-US) a la conexión.

`icecandidate` (en-US)

Enviado para solicitar que el candidato especificado se transmita al par remoto.

`icecandidateerror` (en-US)

Enviado a la conexión si se produjo un error durante la recopilación de candidatos ICE (en-US). El evento describe el error.

`iceconnectionstatechange` (en-US)

Se envía cuando cambia el estado de la conexión ICE (en-US), como cuando se desconecta.

`icegatheringstatechange` (en-US)

 Se envía cuando cambia el estado de recopilación de la capa ICE (en-US), reflejado por `iceGatheringState` (en-US).
 Esto indica si la negociación de ICE aún no ha comenzado (`new`), ha comenzado a reunir candidatos (`gathering`) o ha finalizado (`complete`).


`negotiationneeded` (en-US)

Enviado cuando es necesario realizar la negociación o renegociación de la conexión ICE (en-US); esto puede suceder tanto cuando se abre una conexión por primera vez como cuando es necesario adaptarse a las condiciones cambiantes de la red. El receptor debe responder creando una oferta y enviándola al otro par.

`signalingstatechange` (en-US)

Se envía cuando cambia el estado de señalización del ICE (en-US) de la conexión.

`track` (en-US)

Enviado después de que se haya agregado una nueva pista a una de las instancias `RTCRtpReceiver` que componen la conexión.

### Eventos obsoletos

`addstream` (en-US) 
Obsoleto

Non-standard

Enviado cuando se agrega un nuevo `MediaStream` (en-US) a la conexión. En lugar de detectar este evento obsoleto, debe detectar los eventos `track` (en-US); se envía uno por cada `MediaStreamTrack` agregado a la conexión.

`removestream` (en-US) 
Obsoleto

Non-standard

Enviado cuando se elimina un `MediaStream` (en-US) de la conexión. En lugar de detectar este evento obsoleto, debe detectar los eventos `removetrack` (en-US) en cada transmisión.

Especificaciones
----------------

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # interface-definition |

Compatibilidad con navegadores
------------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Véase también
-------------

* https://github.com/jesup/nightly-gupshup/blob/master/static/js/chat.js
* Comience con WebRTC
* TutorRoom: Captura de video HTML Node.js, aplicación de intercambio de archivos y video entre pares (fuente en GitHub)