Struct CallHandle

Source

pub struct CallHandle { /* private fields */ }

Expand description

A handle to a SIP call (specific type of dialog) for call-related operations

Provides call-specific convenience methods on top of the basic dialog operations. CallHandle extends DialogHandle with operations that are specifically relevant to voice/video calls, such as hold/resume, transfer, and media management.

§Key Features

Call Lifecycle: Answer, reject, and hang up calls
Call Control: Hold, resume, transfer, and mute operations
Media Management: Update media parameters and handle media events
Call Information: Access to call-specific metadata and state
Dialog Access: Full access to underlying dialog operations

§Examples

§Basic Call Operations

use rvoip_dialog_core::api::common::CallHandle;
use rvoip_sip_core::StatusCode;

// Get call information
let info = call.info().await?;
println!("Call {} from {} to {}", info.call_id, info.local_uri, info.remote_uri);
println!("State: {:?}", info.state);

// Answer an incoming call
call.answer(Some("SDP answer with media info".to_string())).await?;

// Or reject a call
// call.reject(StatusCode::Busy, Some("Busy right now".to_string())).await?;

§Call Control Operations

use rvoip_dialog_core::api::common::CallHandle;

// Put call on hold
let hold_sdp = "v=0\r\no=- 123 456 IN IP4 0.0.0.0\r\n...";
call.hold(Some(hold_sdp.to_string())).await?;
println!("Call on hold");

// Resume from hold
let resume_sdp = "v=0\r\no=- 123 457 IN IP4 192.168.1.100\r\n...";
call.resume(Some(resume_sdp.to_string())).await?;
println!("Call resumed");

// Transfer to another party
call.transfer("sip:alice@example.com".to_string()).await?;
println!("Call transferred");

§Advanced Call Management

use rvoip_dialog_core::api::common::CallHandle;

// Update media parameters
let new_sdp = "v=0\r\no=- 123 458 IN IP4 192.168.1.100\r\n...";
call.update_media(Some(new_sdp.to_string())).await?;

// Send call-related information
call.send_info("DTMF: 1".to_string()).await?;

// Send call event notification
call.notify("call-status".to_string(), Some("ringing".to_string())).await?;

// Advanced transfer with custom REFER
let refer_body = "Refer-To: sip:bob@example.com\r\nReplaces: abc123";
call.transfer_with_body("sip:bob@example.com".to_string(), refer_body.to_string()).await?;

§Call State Monitoring

use rvoip_dialog_core::api::common::CallHandle;
use rvoip_dialog_core::dialog::DialogState;

// Monitor call state
while call.is_active().await {
    let state = call.dialog_state().await?;
    match state {
        DialogState::Early => println!("Call ringing..."),
        DialogState::Confirmed => {
            println!("Call answered and active");
            break;
        },
        DialogState::Terminated => {
            println!("Call ended");
            break;
        },
        _ => {}
    }
    tokio::time::sleep(tokio::time::Duration::from_millis(500)).await;
}

§Integration with Dialog Operations

use rvoip_dialog_core::api::common::CallHandle;
use rvoip_sip_core::Method;

// Access underlying dialog handle
let dialog = call.dialog();
 
// Use dialog operations directly
let tx_key = dialog.send_request(Method::Options, None).await?;
println!("Sent OPTIONS via dialog: {}", tx_key);

// Or use call-specific shortcuts
let tx_key = call.send_request(Method::Info, Some("Call info".to_string())).await?;
println!("Sent INFO via call: {}", tx_key);