Enum SipJsonError

Source

pub enum SipJsonError {
    SerializeError(Error),
    DeserializeError(Error),
    InvalidPath(String),
    InvalidQuery(String),
    TypeConversionError(String),
    Other(String),
}

Expand description

§JSON Representation and Access Layer for SIP Types

This module provides a comprehensive JSON-based interface for working with SIP types, enabling powerful, flexible access to SIP message data.

§Overview

The SIP JSON module offers several ways to interact with SIP messages:

Path-based access - Direct access via dot notation (e.g., headers.From.display_name)
Query-based access - Complex searches using JSONPath-like syntax (e.g., $..display_name)
Object conversion - Convert between SIP types and JSON structures
Convenience traits - Helper methods for common SIP header access patterns

§Core Components

SipValue - A JSON-like value representing any SIP data
SipJsonExt - Extension trait providing JSON operations on SIP types
SipMessageJson - Convenience trait for common SIP headers
path module - Functions for path-based access
query module - Functions for query-based access

§Path Access vs. Query Access

Path access is direct and specific - use when you know exactly what you’re looking for
Query access is flexible and powerful - use when searching for patterns or exploring

§Basic Usage Examples

§Path-based Access

use rvoip_sip_core::prelude::*;
use rvoip_sip_core::json::SipJsonExt;

let request = RequestBuilder::invite("sip:bob@example.com").unwrap()
    .from("Alice", "sip:alice@example.com", Some("tag12345"))
    .to("Bob", "sip:bob@example.com", None)
    .build();

// Simple path access with Option return
if let Some(from_display) = request.path("headers.From.display_name") {
    println!("From display name: {}", from_display);
}

// Direct string access with default value
let to_display = request.path_str_or("headers.To.display_name", "Unknown");
let from_tag = request.path_str_or("headers.From.params[0].Tag", "No tag");

§Query-based Access

use rvoip_sip_core::prelude::*;
use rvoip_sip_core::json::SipJsonExt;

let request = RequestBuilder::invite("sip:bob@example.com").unwrap()
    .from("Alice", "sip:alice@example.com", Some("tag12345"))
    .to("Bob", "sip:bob@example.com", Some("tag6789"))
    .via("pc33.atlanta.com", "UDP", Some("z9hG4bK776asdhds"))
    .build();

// Find all display names in the message
let display_names = request.query("$..display_name");
for name in &display_names {
    println!("Found display name: {}", name);
}

// Find all tags anywhere in the message
let tags = request.query("$..Tag");
println!("Found {} tags", tags.len());

// Complex queries are also possible
let branches = request.query("$.headers.Via[*].params[?(@.Branch)]");
for branch in &branches {
    println!("Via branch: {}", branch);
}

§Using SIP Message Helpers

use rvoip_sip_core::prelude::*;
use rvoip_sip_core::json::ext::SipMessageJson;

let request = RequestBuilder::invite("sip:bob@example.com").unwrap()
    .from("Alice", "sip:alice@example.com", Some("tag12345"))
    .to("Bob", "sip:bob@example.com", None)
    .build();

// Use helper methods for common headers
let from_uri = request.from_uri()?;
let from_tag = request.from_tag()?;
let call_id = request.call_id()?;

println!("Call-ID: {}", call_id);
println!("From URI: {}", from_uri);
println!("From tag: {}", from_tag);

// Methods return None when data isn't present
if let Some(to_tag) = request.to_tag() {
    println!("Dialog is established (to_tag present)");
} else {
    println!("Dialog not yet established (no to_tag)");
}

§Converting to/from JSON

use rvoip_sip_core::json::{SipJsonExt, SipValue, SipJsonError};
use rvoip_sip_core::prelude::*;
use rvoip_sip_core::types::sip_request::Request;
use std::error::Error;

let request = RequestBuilder::invite("sip:bob@example.com").unwrap()
    .from("Alice", "sip:alice@example.com", Some("tag12345"))
    .build();

// Convert to JSON string with proper error handling
let json_str = match request.to_json_string() {
    Ok(s) => s,
    Err(e) => return Err(Box::new(e)),
};
println!("JSON representation: {}", json_str);

// Convert to pretty-printed JSON string
let pretty_json = match request.to_json_string_pretty() {
    Ok(s) => s,
    Err(e) => return Err(Box::new(e)),
};
println!("Pretty JSON:\n{}", pretty_json);

// Create a new request from the JSON string
let new_request = match Request::from_json_str(&json_str) {
    Ok(r) => r,
    Err(e) => return Err(Box::new(e)),
};

// Convert to a SipValue for direct manipulation
let value = match request.to_sip_value() {
    Ok(v) => v,
    Err(e) => return Err(Box::new(e)),
};

// Access fields on the SipValue directly
let method = value.get_path("method").and_then(|v| v.as_str());
assert_eq!(method, Some("Invite"));

§When to Use Each Approach

Typed Headers API: When type safety is critical (production code)
Path Accessors: For direct, simple access to known fields
Query Interface: For complex searches or exploring message structure
SipMessageJson methods: For common SIP headers with a concise API
Direct SipValue manipulation: For advanced JSON operations

Error type for JSON operations.

This enum represents the various errors that can occur during JSON operations on SIP messages.

§Examples

use rvoip_sip_core::json::{SipJsonExt, SipJsonError};
use std::error::Error;

// Function that demonstrates SipJsonError handling
fn show_error_handling() {
    // Using Result with SipJsonError
    let result = "not_valid_json".parse::<serde_json::Value>()
        .map_err(|e| SipJsonError::DeserializeError(e));

    match result {
        Ok(_) => println!("Successfully parsed"),
        Err(SipJsonError::DeserializeError(e)) => println!("Deserialization error: {}", e),
        Err(e) => println!("Other error: {}", e),
    }
}