Crate rvoip_sip_core

Expand description

§rvoip-sip-core

Core SIP protocol implementation for the rvoip VoIP stack.

This crate provides a complete, RFC-compliant implementation of the Session Initiation Protocol (SIP), including message parsing, serialization, and manipulation. It serves as the foundation for building SIP-based communication systems like VoIP clients, proxies, and servers.

§Overview

The crate is structured around the following key components:

Message Types: Core SIP message abstractions (Request, Response, Message)
Header Types: Strongly-typed SIP headers with parsing and serialization
URI Handling: Comprehensive SIP URI parsing and manipulation
SDP Support: Session Description Protocol integration
Parsing: Robust, efficient, and RFC-compliant message parsing
Builder Patterns: Fluent APIs for constructing SIP and SDP messages
Macros: Convenient macros for creating SIP requests and responses

§Getting Started

§Creating SIP Messages

The recommended way to create SIP messages is to use either the builder pattern or macros:

§Using the Builder Pattern (recommended for complex messages)

use rvoip_sip_core::prelude::*;

// Create a SIP request with the RequestBuilder
let request = RequestBuilder::new(Method::Invite, "sip:bob@example.com").unwrap()
    .from("Alice", "sip:alice@example.com", Some("1928301774"))
    .to("Bob", "sip:bob@example.com", None)
    .call_id("a84b4c76e66710@pc33.atlanta.com")
    .cseq(314159)
    .via("pc33.atlanta.com", "UDP", Some("z9hG4bK776asdhds"))
    .max_forwards(70)
    .contact("sip:alice@pc33.atlanta.com", None)
    .content_type("application/sdp")
    .body("v=0\r\no=alice 123 456 IN IP4 127.0.0.1\r\ns=A call\r\nt=0 0\r\n")
    .build();

// Create a SIP response with the ResponseBuilder
let response = ResponseBuilder::new(StatusCode::Ok, Some("OK"))
    .from("Alice", "sip:alice@example.com", Some("1928301774"))
    .to("Bob", "sip:bob@example.com", Some("a6c85cf"))
    .call_id("a84b4c76e66710@pc33.atlanta.com")
    .cseq(1, Method::Invite)
    .via("pc33.atlanta.com", "UDP", Some("z9hG4bK776asdhds"))
    .contact("sip:bob@192.168.1.2", None)
    .content_type("application/sdp")
    .body("v=0\r\no=bob 123 456 IN IP4 192.168.1.2\r\ns=A call\r\nt=0 0\r\n")
    .build();

§Using Macros (recommended for simple messages)

use rvoip_sip_core::prelude::*;
use rvoip_sip_core::{sip_request, sip_response};

// Create a SIP request with the sip_request! macro 
let request = sip_request! {
    method: Method::Invite,
    uri: "sip:bob@example.com",
    from_name: "Alice", 
    from_uri: "sip:alice@example.com",
    from_tag: "1928301774",
    call_id: "a84b4c76e66710",
    cseq: 1
};

// Create a SIP response with the sip_response! macro
let response = sip_response! {
    status: StatusCode::Ok,
    reason: "OK",
    from_name: "Alice", 
    from_uri: "sip:alice@example.com", 
    to_name: "Bob", 
    to_uri: "sip:bob@example.com",
    call_id: "a84b4c76e66710",
    cseq: 1, 
    cseq_method: Method::Invite
};

§Creating SDP Messages

For SDP messages, you can use either the SdpBuilder (for programmatic creation) or the sdp! macro (for declarative creation):

§Using the SdpBuilder Pattern

use rvoip_sip_core::sdp_prelude::*;

// Create an SDP session with the SdpBuilder
let sdp = SdpBuilder::new("My Session")
    .origin("-", "1234567890", "2", "IN", "IP4", "127.0.0.1")
    .time("0", "0")  // Time 0-0 means permanent session
    .media_audio(49170, "RTP/AVP")
        .formats(&["0", "8"])
        .direction(MediaDirection::SendRecv)
        .rtpmap("0", "PCMU/8000")
        .rtpmap("8", "PCMA/8000")
        .done()
    .build();

§Using the sdp! Macro (recommended for simple messages)

use rvoip_sip_core::sdp;
use rvoip_sip_core::sdp_prelude::*;

// Create an SDP session with the sdp! macro
let sdp_result = sdp! {
    origin: ("-", "1234567890", "2", "IN", "IP4", "192.168.1.100"),
    session_name: "Audio Call",
    connection: ("IN", "IP4", "192.168.1.100"),
    time: ("0", "0"),
    media: {
        type: "audio",
        port: 49170,
        protocol: "RTP/AVP",
        formats: ["0", "8"],
        rtpmap: ("0", "PCMU/8000"),
        rtpmap: ("8", "PCMA/8000"),
        direction: "sendrecv"
    }
};

let sdp = sdp_result.expect("Valid SDP");

§Parsing SIP Messages

The library provides robust parsing for SIP messages:

use rvoip_sip_core::prelude::*;
use bytes::Bytes;

// Parse a SIP message from bytes
let data = Bytes::from(
    "INVITE sip:bob@example.com SIP/2.0\r\n\
     Via: SIP/2.0/UDP pc33.atlanta.com;branch=z9hG4bK776asdhds\r\n\
     Max-Forwards: 70\r\n\
     To: Bob <sip:bob@example.com>\r\n\
     From: Alice <sip:alice@atlanta.com>;tag=1928301774\r\n\
     Call-ID: a84b4c76e66710@pc33.atlanta.com\r\n\
     CSeq: 314159 INVITE\r\n\
     Contact: <sip:alice@pc33.atlanta.com>\r\n\
     Content-Type: application/sdp\r\n\
     Content-Length: 0\r\n\r\n"
);

let message = parse_message(&data).expect("Valid SIP message");

// Access message components
if let Message::Request(request) = message {
    assert_eq!(request.method(), Method::Invite);
    assert_eq!(request.uri().to_string(), "sip:bob@example.com");
     
    // Get headers and display them
    if let Some(from_header) = request.header(&HeaderName::From) {
        println!("From: {}", from_header);
    }
    if let Some(to_header) = request.header(&HeaderName::To) {
        println!("To: {}", to_header);
    }
}

§Parsing Modes

The library supports different parsing modes to handle various levels of RFC compliance:

use rvoip_sip_core::prelude::*;
use bytes::Bytes;

let data = Bytes::from("SIP message data...");

// Standard parsing mode
let message = parse_message(&data);

// Custom parsing mode
let strict_message = parse_message_with_mode(&data, ParseMode::Strict);

§Feature Flags

lenient_parsing - Enables more lenient parsing mode for torture tests and handling of non-compliant messages

Re-exports§

pub use error::Error;
pub use error::Result;
pub use types::header::Header;
pub use types::header::HeaderValue;
pub use types::header::TypedHeader;
pub use types::header::TypedHeaderTrait;
pub use types::headers::HeaderName;
pub use types::Method;
pub use parser::parse_message;
pub use parser::message::parse_message_with_mode;
pub use parser::message::ParseMode;
pub use types::StatusCode;
pub use types::Address;
pub use types::CallId;
pub use types::Contact;
pub use types::ContentDisposition;
pub use types::ContentLength;
pub use types::ContentType;
pub use types::CSeq;
pub use types::Expires;
pub use types::From;
pub use types::MaxForwards;
pub use types::MediaType;
pub use types::sip_message::Message;
pub use types::sip_request::Request;
pub use types::sip_response::Response;
pub use types::sdp::SdpSession;
pub use types::Via;
pub use types::Warning;
pub use types::warning::WarnAgent;
pub use types::warning::WarningValue;
pub use types::sdp::MediaDescription;
pub use types::sdp::Origin;
pub use types::sdp::ConnectionData;
pub use types::sdp::TimeDescription;
pub use types::sdp::ParsedAttribute;
pub use types::sdp::RtpMapAttribute;
pub use types::sdp::FmtpAttribute;
pub use types::sdp::CandidateAttribute;
pub use types::sdp::SsrcAttribute;
pub use types::sdp::RepeatTime;
pub use types::Version;
pub use types::Allow;
pub use types::Accept;
pub use types::Subject;
pub use types::CallInfo;
pub use types::uri::Uri;
pub use types::uri::Host;
pub use sdp::attributes::MediaDirection;
pub use sdp::parser::validate_sdp;
pub use sdp::parser::validate_network_type;
pub use sdp::parser::validate_address_type;
pub use sdp::parser::is_valid_address;
pub use sdp::parser::is_valid_ipv4;
pub use sdp::parser::is_valid_ipv6;
pub use sdp::parser::is_valid_hostname;
pub use sdp::parser::parse_bandwidth_line;
pub use sdp::parser::parse_sdp;
pub use builder::SimpleRequestBuilder as RequestBuilder;
pub use builder::SimpleResponseBuilder as ResponseBuilder;
pub use types::auth::*;
pub use macros::*;

Modules§

builder: SIP Builders
error
json: JSON representation and access layer for SIP types
macros: SIP Macros
parser: SIP protocol parser implementation
prelude: Prelude module that exports commonly used types and traits
sdp: Session Description Protocol (SDP) implementation
sdp_prelude: SDP prelude module that exports SDP-related types and traits
types: SIP Protocol Types

Macros§

sdp: Creates a validated SDP session with a declarative syntax
sip_request: Macro for creating SIP request messages with a concise syntax.
sip_response: Macro for creating SIP response messages with a concise syntax.

Crate rvoip_sip_coreCopy item path