WebRTCPeerConnection
Hereda: RefCounted < Object
Heredado por: WebRTCPeerConnectionExtension
Interfaz a una conexión de pares WebRTC.
Descripción
Una conexión WebRTC entre el equipo local y un par remoto. Proporciona una interfaz para conectar, mantener y monitorizar la conexión.
Configurar una conexión WebRTC entre dos pares puede no parecer una tarea trivial, pero puede dividirse en 3 pasos principales:
El par que quiere iniciar la conexión (
Aa partir de ahora) crea una oferta y la envía al otro par (Ba partir de ahora).Brecibe la oferta, la genera y responde, y la envía aA).AyBgeneran e intercambian candidatos ICE entre sí.
Después de estos pasos, la conexión debería establecerse. Sigue leyendo o consulta el tutorial para obtener más información.
Métodos
add_ice_candidate(media: String, index: int, name: String) |
|
void |
close() |
create_data_channel(label: String, options: Dictionary = {}) |
|
get_connection_state() const |
|
get_gathering_state() const |
|
get_signaling_state() const |
|
initialize(configuration: Dictionary = {}) |
|
poll() |
|
void |
set_default_extension(extension_class: StringName) static |
set_local_description(type: String, sdp: String) |
|
set_remote_description(type: String, sdp: String) |
Señales
data_channel_received(channel: WebRTCDataChannel) 🔗
Emitida cuando se recibe un nuevo canal en banda, es decir, cuando el canal fue creado con negotiated: false (por defecto).
El objeto será una instancia de WebRTCDataChannel. Debe mantener una referencia de él o se cerrará automáticamente. Véase create_data_channel().
ice_candidate_created(media: String, index: int, name: String) 🔗
Emitida cuando se ha creado un nuevo candidato ICE. Los tres parámetros deben pasarse al par remoto a través del servidor de señalización.
session_description_created(type: String, sdp: String) 🔗
Emitida después de una llamada exitosa a create_offer() o set_remote_description() (cuando genera una respuesta). Los parámetros deben ser pasados a set_local_description() en este objeto, y enviados al par remoto a través del servidor de señales.
Enumeraciones
enum ConnectionState: 🔗
ConnectionState STATE_NEW = 0
La conexión es nueva, se pueden crear canales de datos y una oferta en este estado.
ConnectionState STATE_CONNECTING = 1
El par está conectando, el ICE está en marcha, ninguno de los transportes ha fallado.
ConnectionState STATE_CONNECTED = 2
El par está conectado, todos los transportes de ICE están conectados.
ConnectionState STATE_DISCONNECTED = 3
Al menos un transporte ICE está desconectado.
ConnectionState STATE_FAILED = 4
Uno o más de los transportes ICE fallaron.
ConnectionState STATE_CLOSED = 5
La conexión entre pares se cierra (después de llamar a close() por ejemplo).
enum GatheringState: 🔗
GatheringState GATHERING_STATE_NEW = 0
La conexión par se acaba de crear y aún no ha realizado ninguna conexión de red.
GatheringState GATHERING_STATE_GATHERING = 1
El agente ICE está en proceso de recopilación de candidatos para la conexión.
GatheringState GATHERING_STATE_COMPLETE = 2
El agente ICE ha terminado de recopilar candidatos. Si sucede algo que requiere la recopilación de nuevos candidatos, como la adición de una nueva interfaz o la adición de un nuevo servidor ICE, el estado volverá a la recopilación para reunir esos candidatos.
enum SignalingState: 🔗
SignalingState SIGNALING_STATE_STABLE = 0
No hay ningún intercambio de oferta y respuesta en curso. Esto puede significar que el WebRTCPeerConnection es nuevo (STATE_NEW) o que la negociación se ha completado y se ha establecido una conexión (STATE_CONNECTED).
SignalingState SIGNALING_STATE_HAVE_LOCAL_OFFER = 1
El par local ha llamado a set_local_description(), pasando el SDP que representa una oferta (generalmente creada llamando a create_offer()), y la oferta se ha aplicado correctamente.
SignalingState SIGNALING_STATE_HAVE_REMOTE_OFFER = 2
El par remoto ha creado una oferta y ha utilizado el servidor de señalización para entregarla al par local, que ha establecido la oferta como la descripción remota llamando a set_remote_description().
SignalingState SIGNALING_STATE_HAVE_LOCAL_PRANSWER = 3
La oferta enviada por el par remoto se ha aplicado y se ha creado y aplicado una respuesta llamando a set_local_description(). Esta respuesta provisional describe los formatos de medios admitidos, etc., pero es posible que no tenga un conjunto completo de candidatos ICE incluidos. Otros candidatos se entregarán por separado más adelante.
SignalingState SIGNALING_STATE_HAVE_REMOTE_PRANSWER = 4
Se ha recibido una respuesta provisional y se ha aplicado correctamente en respuesta a una oferta enviada y establecida previamente llamando a set_local_description().
SignalingState SIGNALING_STATE_CLOSED = 5
El WebRTCPeerConnection ha sido cerrado.
Descripciones de Métodos
Error add_ice_candidate(media: String, index: int, name: String) 🔗
Añade un candidato de hielo generado por un par remoto (y recibido a través del servidor de señales). Véase ice_candidate_created.
void close() 🔗
Cierra la conexión del par y todos los canales de datos asociados a ella.
Nota: No puedes reutilizar este objeto para una nueva conexión a menos que llames a initialize().
WebRTCDataChannel create_data_channel(label: String, options: Dictionary = {}) 🔗
Devuelve un nuevo WebRTCDataChannel (o null si falla) con la label dada y, opcionalmente, configurado mediante el diccionario options. Este método solo se puede llamar cuando la conexión está en el estado STATE_NEW.
Hay dos formas de crear un canal de datos en funcionamiento: llamar a create_data_channel() solo en uno de los pares y escuchar data_channel_received en el otro, o llamar a create_data_channel() en ambos pares, con los mismos valores, y la opción "negotiated" establecida en true.
Las options válidas son:
{
"negotiated": true, # Cuando se establece en true (desactivado de forma predeterminada), significa que el canal se negocia fuera de banda. También se debe establecer "id". No se llamará a "data_channel_received".
"id": 1, # Cuando "negotiated" es true, este valor también se debe establecer en el mismo valor en ambos pares.
# Solo se puede especificar uno de maxRetransmits y maxPacketLifeTime, no ambos. Hacen que el canal no sea fiable (pero también mejor en tiempo real).
"maxRetransmits": 1, # Especifica el número máximo de intentos que hará el par para retransmitir paquetes si no se reconocen.
"maxPacketLifeTime": 100, # Especifica la cantidad máxima de tiempo antes de renunciar a la retransmisión de paquetes no reconocidos (en milisegundos).
"ordered": true, # Cuando está en modo no fiable (es decir, se establece "maxRetransmits" o "maxPacketLifetime"), "ordered" (true de forma predeterminada) especifica si se va a aplicar el orden de paquetes.
"protocol": "mi-protocolo-personalizado", # Una string de sub-protocolo personalizada para este canal.
}
Nota: Debe mantener una referencia a los canales creados de esta manera, o se cerrarán.
Crea una nueva oferta SDP para iniciar una conexión WebRTC con un par remoto. Al menos una WebRTCDataChannel debe haber sido creada antes de llamar a este método.
Si esta función devuelve @GlobalScope.OK, se llamará a session_description_created cuando la sesión esté lista para ser enviada.
ConnectionState get_connection_state() const 🔗
Devuelve el estado de la conexión.
GatheringState get_gathering_state() const 🔗
Devuelve el GatheringState ICE de la conexión. Esto te permite detectar, por ejemplo, cuando la recopilación de candidatos ICE ha terminado.
SignalingState get_signaling_state() const 🔗
Devuelve el estado de señalización en el extremo local de la conexión mientras se conecta o se vuelve a conectar a otro par.
Error initialize(configuration: Dictionary = {}) 🔗
Reinicializa esta conexión de pares, cerrando cualquier conexión activa anteriormente y volviendo al estado STATE_NEW. Se puede pasar un diccionario de opciones de configuration para configurar la conexión de pares.
Las opciones válidas de configuration son:
{
"iceServers": [
{
"urls": [ "stun:stun.example.com:3478" ], # Uno o más servidores STUN.
},
{
"urls": [ "turn:turn.example.com:3478" ], # Uno o más servidores TURN.
"username": "a_username", # Nombre de usuario opcional para el servidor TURN.
"credential": "a_password", # Contraseña opcional para el servidor TURN.
}
]
}
Llama a este método con frecuencia (por ejemplo, en Node._process() o Node._physics_process()) para recibir correctamente las señales.
void set_default_extension(extension_class: StringName) static 🔗
Establece la extension_class como la WebRTCPeerConnectionExtension por defecto que se devuelve al crear un nuevo WebRTCPeerConnection.
Error set_local_description(type: String, sdp: String) 🔗
Establece la descripción del SDP del par local. Esto debe ser llamado en respuesta a session_description_created.
Después de llamar a esta función el par empezará a emitir ice_candidate_created (a menos que se devuelva un Error diferente de @GlobalScope.OK).
Error set_remote_description(type: String, sdp: String) 🔗
Establece la descripción SDP del par remoto. Esto debe llamarse con los valores generados por un par remoto y recibidos a través del servidor de señalización.
Si type es "offer", el par emitirá session_description_created con la respuesta adecuada.
Si type es "answer", el par comenzará a emitir ice_candidate_created.