--- title: roPcap slug: develop/es/ropcap docTags: createdAt: 2026-07-22T15:42:22.221Z --- `roPcap` se utiliza para analizar archivos PCAP en busca de flujos de tráfico UDP, prepararlos para la reproducción (filtrando y reescribiendo encabezados opcionalmente), reproducirlos en una interfaz de red con sincronización sin deriva y extraer flujos de carga útil UDP sin procesar de capturas PCAP. Está disponible a partir de BOS 9.1.143. Si se establece un puerto de mensajes mediante `SetPort()`, el objeto publica mensajes `roPcapEvent` para eventos del ciclo de vida de la reproducción (iniciada, detenida, repetida en bucle, underrun, descartada). Solo puede existir una instancia de `roPcap` a la vez. `CreateObject("roPcap")` devuelve `Inválido` si otra instancia ya está activa. :::hint{type="warning"} Si utiliza *tmp\:/* debe tener en cuenta el tamaño del PCAP. Si es grande, no cabrá en un *tmp\:/* basado en RAM y debería usar almacenamiento local en su lugar (por ejemplo, *sd:/*) ::: *** ## ifPcap ### Analyze(filename As String) As Object Escanea todos los paquetes en `nombre de archivo` y devuelve un `roArray` de `roAssociativeArray`, una entrada por cada flujo UDP encontrado. Los flujos se ordenan por cantidad de paquetes en orden descendente. Devuelve una matriz vacía si el archivo no puede abrirse o no contiene flujos UDP. Cada entrada en la matriz devuelta contiene las siguientes claves: | **Clave** | **Tipo** | **Descripción** | | -------------- | -------- | ---------------------------------- | | `src_ip` | String | Dirección IPv4 de origen | | `src_port` | Integer | Puerto UDP de origen | | `dst_ip` | String | Dirección IPv4 de destino | | `dst_port` | Integer | Puerto UDP de destino | | `packet_count` | Integer | Número de paquetes UDP en el flujo | *** ### Prepare(params As roAssociativeArray) As Integer Filtra paquetes del PCAP de entrada y escribe un PCAP de salida listo para reproducción, reemplazando opcionalmente los encabezados de IP de destino y puerto UDP. La dirección MAC de origen y la dirección IP de origen de cada paquete de salida siempre se reescriben con los valores de la interfaz de red especificada. Si `RewriteOutputDestAddress` es una dirección multicast, la MAC de destino se deriva utilizando la fórmula RFC 1112. Si es una dirección unicast, la MAC de destino se resuelve mediante la caché ARP del kernel; el destino ya debe ser accesible (por ejemplo, mediante un ping previo) antes de llamar a `Prepare()`. Devuelve un código entero `PcapEngineError`; `0` en caso de éxito. Consulte [Códigos de error](./#cdigos-de-error). **Parámetros obligatorios:** | **Clave** | **Tipo** | **Descripción** | | -------------------- | -------- | -------------------------------------------------------------------------------------------- | | `Archivo de entrada` | String | Ruta al archivo PCAP de origen | | `ArchivoDeSalida` | String | Ruta para escribir el PCAP preparado (debe ser diferente de `Archivo de entrada`) | | `Interfaz` | String | Nombre de la interfaz de red utilizada para resolver la MAC e IP de origen (p. ej. `"eth0"`) | **Parámetros de filtro opcionales:** | **Clave** | **Tipo** | **Descripción** | | -------------------------- | -------- | ------------------------------------------------------------------------- | | `FilterInputSourceAddress` | String | Conservar solo los paquetes con esta dirección IPv4 de origen | | `FilterInputSourcePort` | Integer | Conservar solo los paquetes UDP de este puerto de origen (1024–65535) | | `FilterInputDestAddress` | String | Conservar solo los paquetes con esta dirección IPv4 de destino | | `FilterInputDestPort` | Integer | Conservar solo los paquetes UDP hacia este puerto de destino (1024–65535) | | `AutoFlowSelect` | Boolean | Vea la nota a continuación | **Parámetros de reescritura opcionales:** | **Clave** | **Tipo** | **Descripción** | | -------------------------- | -------- | ----------------------------------------------------------- | | `RewriteOutputDestAddress` | String | Reescribir la dirección IP de destino (unicast o multicast) | | `RewriteOutputDestPort` | Integer | Reescribir el puerto UDP de destino (1024–65535) | **Comportamiento predeterminado de AutoFlowSelect:** Cuando no se proporcionan claves `Campo de filtro*` keys, `AutoFlowSelect` toma el valor predeterminado de `verdadero`: el flujo con el mayor número de paquetes se selecciona automáticamente. Cuando cualquier clave `Campo de filtro*` está presente, `AutoFlowSelect` toma el valor predeterminado de `falso`: si los criterios de filtro coinciden con más de un flujo, `Prepare()` devuelve `PCAP_ERR_AMBIGUOUS_FLOW (-7)` en lugar de seleccionar uno. Una clave explícita de `AutoFlowSelect` siempre reemplaza el valor predeterminado. *** ### ExtractStream(params As roAssociativeArray) As Integer Concatena los bytes de carga útil UDP sin procesar de cada paquete coincidente en `Archivo de entrada` y los escribe en `ArchivoDeSalida`. No se requiere una llamada previa a `Prepare()`. Esto es útil para recuperar el flujo de bytes original de una captura UDP; por ejemplo, extraer un archivo MPEG-TS de una grabación TS-over-UDP. Los criterios de filtro deben resolverse exactamente en un flujo UDP. Use `AutoFlowSelect` para seleccionar automáticamente el flujo con el mayor recuento cuando el filtro es amplio. Devuelve un código entero `PcapEngineError`; `0` en caso de éxito. Consulte [Códigos de error](./#cdigos-de-error). Puede devolver `PCAP_ERR_READ_FAILED (-8)` si el archivo de entrada está dañado o truncado. **Parámetros obligatorios:** | **Clave** | **Tipo** | **Descripción** | | -------------------- | -------- | ---------------------------------------------------------- | | `Archivo de entrada` | String | Ruta al archivo PCAP de origen | | `ArchivoDeSalida` | String | Ruta donde escribir el flujo extraído; se crea o se trunca | **Parámetros de filtro opcionales:** Igual que en `Prepare()`: `FilterInputSourceAddress`, `FilterInputSourcePort`, `FilterInputDestAddress`, `FilterInputDestPort`, `AutoFlowSelect` (misma lógica predeterminada que `Prepare()`). *** ### Start(params As roAssociativeArray) As Boolean Comienza a reproducir el archivo PCAP preparado en la interfaz de red especificada. Los paquetes se sincronizan según sus intervalos originales entre paquetes utilizando marcas de tiempo monotónicas absolutas para que el exceso de tiempo en un paquete no pueda acumularse como deriva en los paquetes posteriores. Bloquea hasta que el hilo del remitente se haya iniciado o haya fallado al iniciarse. Publica un `roPcapEvent` con el tipo `1` (Started) en el puerto de mensajes en caso de éxito. Devuelve `Verdadero` en caso de éxito; `Falso` si no se pudo iniciar el hilo del remitente. **Parámetros obligatorios:** | **Clave** | **Tipo** | **Descripción** | | -------------------- | -------- | ----------------------------------------------------------------------- | | `Nombre del archivo` | String | Ruta al archivo PCAP preparado para reproducir | | `Interfaz` | String | Nombre de la interfaz de red desde la que se enviará (p. ej., `"eth0"`) | **Parámetros opcionales:** | **Clave** | **Tipo** | **Descripción** | | -------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `LoopCount` | Integer | Número de veces que se recorrerá el archivo en bucle; `0` (predeterminado) se repite indefinidamente | | `PrecargarEnMemoria` | Boolean | Si `Verdadero`, carga el archivo completo en RAM antes de que comience la reproducción (limitado al 50 % de la RAM total del sistema). Use esto cuando se requiera una temporización determinística por paquete y el archivo quepa cómodamente en la memoria. El valor predeterminado es el modo de streaming, que lee desde el disco con un búfer de lectura anticipada de 20 MiB y es adecuado para cualquier tamaño de archivo. | *** ### Stop() As Void Devuelve `Verdadero` mientras el hilo emisor está ejecutando el bucle de reproducción. Devuelve `Falso` una vez que se agota el recuento de bucles, se llama a `Stop()` o se produce un error fatal después de que `Start()` devolvió `Verdadero`. *** ### GetStats() As roAssociativeArray Devuelve una instantánea de las estadísticas de reproducción. Es seguro llamarlo en cualquier momento, incluso mientras la reproducción está en ejecución. | **Clave** | **Tipo** | **Descripción** | | --------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `packets_sent` | Integer | Tramas transmitidas correctamente desde la última llamada a `Start()` | | `packets_dropped` | Integer | Tramas descartadas debido a que no había espacio de búfer o por ocupado, desde la última llamada a `Start()` | | `loops_completed` | Integer | Pasadas de bucle completas que finalizaron correctamente | | `subdesbordamientos` | Integer | Veces que el búfer de lectura anticipada de streaming estuvo vacío; siempre `0` cuando `PrecargarEnMemoria` es `Verdadero` | | `elapsed_ms` | Integer | Milisegundos de reloj transcurridos desde la última llamada a `Start()` o `ResetStats()`; `0` cuando está detenido | | `timing_sample_count` | Integer | Número de paquetes que contribuyen a los campos de temporización a continuación | | `timing_mean_us` | Integer | Error de temporización medio en microsegundos; positivo significa que el paquete salió tarde, negativo significa que salió temprano | | `timing_min_us` | Integer | Error de temporización mínimo (más temprano) en microsegundos | | `timing_max_us` | Integer | Error de temporización máximo (más tardío) en microsegundos | | `timing_stddev_us` | Integer | Desviación estándar de muestra del error de temporización en microsegundos | Los campos de temporización son `0` hasta que se haya enviado al menos un paquete. *** ### ResetStats() como Void Restablece todas las estadísticas de reproducción a cero. Es seguro llamarlo mientras la reproducción está en ejecución. Los contadores actualizados por el hilo de reproducción después de la llamada reflejan solo la actividad desde el restablecimiento. *** ## ifMessagePort ### SetPort(port As roMessagePort) Publica mensajes de tipo `roPcapEvent` en el puerto de mensajes adjunto. *** ## ifUserData ### SetUserData(user\_data As Object) Establece los datos de usuario que se devolverán cuando se generen eventos. ### GetUserData() As Object Devuelve los datos de usuario establecidos previamente mediante `SetUserData()`. Devuelve `Inválido` si no se han establecido datos. *** ## roPcapEvent `roPcapEvent` se publica en el puerto de mensajes establecido en `roPcap` siempre que ocurre un evento del ciclo de vida de reproducción. ### ifPcapEvent ### GetInt() As Integer Devuelve el código de tipo de evento: | **Valor** | **Nombre** | **Descripción** | | --------- | ----------------- | ------------------------------------------------------------------------------------------------------------------- | | 1 | Iniciado | El hilo de reproducción se inició y está enviando paquetes | | 2 | Detenido | El hilo de reproducción se detuvo (se agotó el recuento de bucles, se llamó a `Stop()` o se produjo un error fatal) | | 3 | En bucle | Se completó una pasada completa; `GetData()` devuelve el número de bucle indexado desde 1 | | 4 | Subdesbordamiento | El búfer de lectura anticipada de streaming estaba vacío; el tiempo de reproducción puede haberse visto afectado | | 5 | Descartado | Se descartó un paquete; `GetData()` devuelve el recuento acumulado de descartes en el momento del descarte | ### GetData() As Integer Devuelve datos específicos del evento. Consulte la tabla anterior. Devuelve `0` para eventos en los que no se aplican datos adicionales. *** ## Códigos de error `Prepare()` y `ExtractStream()` devuelven uno de los siguientes códigos enteros: | **Valor** | **Nombre** | **Descripción** | | --------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 0 | PCAP\_OK | Correcto | | -1 | PCAP\_ERR\_FILE\_NOT\_FOUND | `Archivo de entrada` no existe o no puede abrirse | | -2 | PCAP\_ERR\_INVALID\_FLOW\_PORT | Un valor de puerto está fuera del rango válido \[1024, 65535] | | -3 | PCAP\_ERR\_WRITE\_FAILED | `ArchivoDeSalida` no pudo escribirse | | -4 | PCAP\_ERR\_INVALID\_INTERFACE | El nombre de la interfaz es inválido o no se encontró en el sistema | | -5 | PCAP\_ERR\_INVALID\_PARAM | Se proporcionó un parámetro inválido: formato de dirección IP incorrecto, `Archivo de entrada` y `ArchivoDeSalida` son la misma ruta, o una dirección unicast `RewriteOutputDestAddress` no pudo resolverse a una MAC mediante ARP | | -6 | PCAP\_ERR\_NO\_MATCHING\_FLOW | Los criterios de filtro no coincidieron con ningún flujo; proporcione un filtro menos restrictivo o verifique que el archivo de entrada contenga el tráfico esperado | | -7 | PCAP\_ERR\_AMBIGUOUS\_FLOW | Los criterios de filtro coincidieron con más de un flujo distinto; ajuste el filtro para seleccionar exactamente uno, o establezca `AutoFlowSelect: Verdadero` para elegir automáticamente el flujo con el mayor conteo | | -8 | PCAP\_ERR\_READ\_FAILED | `ExtractStream()` solamente: el archivo de entrada está dañado o truncado | *** ## Ejemplos ### Analizar un archivo PCAP Imprima todos los flujos UDP encontrados en un archivo de captura: ```brightscript pcap = CreateObject("roPcap") flows = pcap.Analyze("SD:/capture.pcap") for each flow in flows print flow.src_ip + ":" + flow.src_port.ToStr() + " -> " + _ flow.dst_ip + ":" + flow.dst_port.ToStr() + _ " packets=" + flow.packet_count.ToStr() end for ``` *** ### Preparar y reproducir con manejo de eventos Seleccione un flujo, reescríbalo a un grupo multicast local y reprodúzcalo tres veces mientras supervisa eventos: ```brightscript pcap = CreateObject("roPcap") port = CreateObject("roMessagePort") pcap.SetPort(port) ' Step 1 — inspect the capture to find the flow flows = pcap.Analyze("SD:/source.pcap") if flows.Count() = 0 print "No UDP flows found" stop end if ' Step 2 — prepare: filter to the largest flow, rewrite destination params = CreateObject("roAssociativeArray") params.InputFile = "SD:/source.pcap" params.OutputFile = "tmp:/prepared.pcap" params.Interface = "eth0" ' AutoFlowSelect defaults to true when no FilterInput* keys are given, ' so the highest-count flow is selected automatically. params.RewriteOutputDestAddress = "239.1.2.3" params.RewriteOutputDestPort = 1234 result = pcap.Prepare(params) if result <> 0 print "Prepare failed: " + result.ToStr() stop end if ' Step 3 — replay three times startParams = CreateObject("roAssociativeArray") startParams.Filename = "tmp:/prepared.pcap" startParams.Interface = "eth0" startParams.LoopCount = 3 if not pcap.Start(startParams) print "Start failed" stop end if ' Step 4 — event loop while True msg = Wait(0, port) if type(msg) = "roPcapEvent" select case msg.GetInt() case 3 ' Looped print "Completed loop " + msg.GetData().ToStr() case 5 ' Dropped print "Drop count: " + msg.GetData().ToStr() case 2 ' Stopped print "Replay finished" exit while end select end if end while stats = pcap.GetStats() print "Sent=" + stats.packets_sent.ToStr() + _ " Dropped=" + stats.packets_dropped.ToStr() + _ " Underruns=" + stats.underruns.ToStr() ``` *** ### Extraer un flujo sin procesar de un PCAP Recupere un archivo MPEG-TS de una captura TS-over-UDP. No se necesita ninguna `Prepare()` ni interfaz de red: ```brightscript pcap = CreateObject("roPcap") params = CreateObject("roAssociativeArray") params.InputFile = "SD:/recording.pcap" params.OutputFile = "SD:/extracted.ts" ' AutoFlowSelect defaults to true when no FilterInput* keys are given. ' Set explicit filter keys to target a specific flow in a multi-flow capture. params.FilterInputDestAddress = "239.10.20.30" params.FilterInputDestPort = 1234 ' AutoFlowSelect defaults to false because FilterInput* keys are present; ' set it explicitly to true to auto-pick if the filter still matches multiple flows. params.AutoFlowSelect = True result = pcap.ExtractStream(params) if result = 0 print "Stream extracted successfully" else print "ExtractStream failed: " + result.ToStr() end if ```