Asterisk.Core.Responses 1.0.0

Asterisk.Core.Responses

Introducción

Asterisk.Core.Responses es una biblioteca ligera de C# que proporciona las clases base y tipadas para manejar las respuestas del Asterisk Manager Interface (AMI).

Este paquete se enfoca en recibir, deserializar y tipar la información devuelta por el servidor Asterisk tras la ejecución de una acción (Action). Al utilizar clases específicas como LoginResponse o PingResponse, se garantiza la seguridad de tipos (type-safety) y un manejo claro de los datos de respuesta.

Características Principales

• Tipificación Rigurosa: Todas las respuestas AMI se mapean a clases tipadas y fuertemente inmutables (readonly struct y propiedades { get; }).
• Clase Base Unificada: Utiliza ResponseBase como punto de partida, lo que asegura que cada respuesta incluye campos esenciales como el estado de éxito (Success), el ID de Acción (ActionID) y la marca de tiempo de recepción (Received).
• Optimización de C#: Implementa propiedades de solo lectura para maximizar la eficiencia y la inmutabilidad de los datos.

Instalación

Puedes instalar el paquete a través de NuGet:

dotnet add package Asterisk.Core.Responses

O en la Consola del Administrador de Paquetes de Visual Studio:

Install-Package Asterisk.Core.Responses

Uso Básico

Todas las respuestas heredan de la clase abstracta ResponseBase. Cuando envías una acción al servidor AMI, esperas una de estas clases tipadas como resultado.

Caso de Uso: Obtención de Respuestas por Eventos

En esta arquitectura, las respuestas se obtienen mediante la suscripción a un delegado ResponseReceived asociado a la acción enviada. Las clases de este paquete son los argumentos (TResponse) que permiten acceder a los datos de forma segura.

Flujo de Login-Challenge

Este ejemplo muestra cómo el cliente AMI (presumiblemente usando clases de Asterisk.Core.Actions) obtiene las respuestas de manera asíncrona a través de eventos para orquestar la secuencia de autenticación.

Paso 1: Enviar ChallengeAction y Suscribirse al ChallengeResponse

El cliente envía la acción y adjunta un método handler que recibirá la respuesta tipada.

// Enviado por el cliente AMI
var challengeAction = new ChallengeAction();
// El delegate espera una respuesta tipada 'ChallengeResponse'
challengeAction.ResponseReceived += SendLoginWhenChallengeReceived; 

_action.SendAction(challengeAction);

Paso 2: El Handler Recibe la Respuesta Tipada (ChallengeResponse)

El método SendLoginWhenChallengeReceived recibe el objeto ChallengeResponse y accede a su propiedad Challenge de forma segura.

private void SendLoginWhenChallengeReceived(object? sender, ChallengeResponse e)
{
    // Las clases tipadas de este paquete (e.g., ChallengeResponse)
    // proporcionan acceso directo a los campos AMI.
    if (!e.Success)
    {
        Console.WriteLine($"Error: Fallo al obtener Challenge (ActionID: {e.ActionID}).");
        return;
    }

    Console.WriteLine($"Token de Desafío recibido: {e.Challenge}");

    // Utilizamos el dato tipado (e.Challenge) para construir la siguiente acción
    var loginAction = new LoginAction(_username, _secret);
    loginAction.Key = e.Challenge;
    
    // Suscribimos el siguiente paso en el flujo a la respuesta tipada 'LoginResponse'
    loginAction.ResponseReceived += EnableReconnectedWhenAuthenticationAccepted;

    _action.SendAction(loginAction);
}

Paso 3: El Handler Recibe la Respuesta Tipada (LoginResponse)

El método EnableReconnectedWhenAuthenticationAccepted utiliza el objeto LoginResponse para verificar el estado de la autenticación y reaccionar.

private void EnableReconnectedWhenAuthenticationAccepted(object? sender, LoginResponse e)
{
    // Uso del estado de éxito tipado de ResponseBase
    if (e.Success)
    {
        Console.WriteLine($"✅ Autenticación aceptada. Mensaje: {e.Message}");
        _state.Login = true;
        // ... (Iniciar el ping periódico o el siguiente paso)
    }
    else
    {
        // Acceso al mensaje específico de la respuesta
        Console.WriteLine($"❌ Autenticación fallida. Mensaje: {e.Message}");
    }
}

Estructura de Clases Tipadas

Las siguientes clases de respuesta están tipadas y derivadas de ResponseBase:

Contribución

¡Las contribuciones son bienvenidas! Si deseas añadir nuevas clases de respuesta o mejorar la documentación, por favor, abre un issue o envía una pull request a nuestro repositorio.

Licencia

Distribuido bajo la licencia MIT.