Sofia-SIP

Rust bindings for Sofia-SIP.

Usage

Add the following to your Cargo.toml:

[dependencies]
sofia-sip = "0.1.0"

Make sure you have sofia-sip C library installed in your system (pkg-config sofia-sip-ua --modversion is working), in ubuntu and other debian based systems, you can install it by doing:

sudo apt install libsofia-sip-ua-dev

Future versions will have an option (via cargo features) to build and bundle C sofia-sip as a static library.

Also, clang/libclang and c headers are required to compile sofia-sip

sudo apt install libclang1 clang

Example

use sofia_sip::{Handle, Nua, NuaEvent, Sip, Tag, TagBuilder};

fn main() {
    /*
    A                    B
    |-------MESSAGE----->|
    |<--------200--------|
    |                    |

    A                    B
    |<------MESSAGE------|
    |--------200-------->|
    |                    |
                           ______(NETWORK)_____
                          /                    \
    A                 NUA STACK (A)
    |                     |
    |    nua::handle( )   |
    |-------------------->|
    |                     |
    |  handle::message()  |
    |------------------->[_]      [MESSAGE]
    |                    [_]------------------>
    |                    [_]
    |                    [_]
    |                    [_]      [200 OK]
    |    ReplyMessage    [_]<------------------
    |<------------------ [_]
    |                     |

                           ______(NETWORK)_____
                          /                    \
    A                 NUA STACK (A)
    |                     |       [MESSAGE]
    |  IncomingMessage   [_]<------------------
    |<-------------------[_]
    |   nua::handle(A')  [_]      [200 OK]
    |                    [_]------------------>
    |                     |
    |                     |
    */
    /* bind on :5080 */
    let sip_bind_url = "sip:*:5080";

    /* send to a SIP contact running in 192.168.0.51 on default port */
    let sip_to_url = "sip:600@192.168.0.51:5060";

    /* build params for Nua::create */
    let tags = TagBuilder::default().nutag_url(sip_bind_url).collect();

    /* create NUA stack */
    let mut nua = Nua::create(&tags).unwrap();

    /*
    Handling of the events coming from NUA stack is done
    in the callback function that is registered for NUA stack
    */
    nua.callback(
        |nua: &mut Nua,
         event: NuaEvent,
         status: u32,
         phrase: String,
         _handle: Option<&Handle>,
         sip: Sip,
         _tags: Vec<Tag>| {
            println!("({:?}) status: {} | {}", &event, status, &phrase);
            match event {
                NuaEvent::ReplyShutdown => { /* received when NUA stack is about to shutdown */ }
                NuaEvent::IncomingMessage => {
                    /* incoming NEW message */
                    println!("Received MESSAGE: {} {}", status, &phrase);
                    println!("From: {}", sip.from());
                    println!("To: {}", sip.to());
                    println!("Subject: {}", sip.subject());
                    println!("ContentType: {}", sip.content_type());
                    println!("Payload: {:?}", sip.payload().as_utf8_lossy());

                    /* quit after new message */
                    nua.quit();
                }
                NuaEvent::ReplyMessage => {
                    /* quit if response != 2XX */
                    if status < 200 || status >= 300 {
                        nua.quit();
                    }
                }
                _ => {}
            }
        },
    );

    /* Message to be send */
    let my_message = "Hi Sofia-SIP-sys";

    /* build params for Handle::create [Similar to C sofia] */
    let tags = TagBuilder::default()
        .siptag_to_str(sip_to_url)
        .nutag_url(sip_bind_url)
        .collect();

    /* create operation handle */
    let handle = Handle::create(&nua, &tags).unwrap();

    /* build params for handle.message() [Alternative] */
    let tags = TagBuilder::default()
        .tag(Tag::SipSubjectStr("NUA".into()))
        .tag(Tag::SipToStr(sip_to_url.into()))
        .tag(Tag::NuUrl(sip_to_url.into()))
        .tag(Tag::SipContentTypeStr("text/plain".into()))
        .tag(Tag::SipPayloadStr(my_message.into()))
        .collect();

    /* The message() function enqueue a SIP MESSAGE on NUA STACK */
    handle.message(&tags);

    /* enter main loop for processing of messages */
    println!("enter the main loop");
    nua.run();
    println!("the main loop exit");
}

Documentation

Sofia-SIP Rust bindings tries to mimic almost as possible the API of Sofia-SIP C library. You can start by learning the concepts of Sofia SIP User Agent Library - "nua" - High-Level User Agent Module.

After this intro, please read examples or the tests from tests directory.

Sofia-SIP C docs

NUA documentation

The best way to learn sofia-sip is by learning how to use the NUA engine, their call model and how NUA events are presented and handled.

• "NUA" - High-Level User Agent Module.
  • The NUA engine hides many low-level signaling and media management aspects from the application programmer.
• NUA Call Model.
  • The call model is used to present changes in call: when media starts to flow, when call is considered established, when call is terminated.
• NUA Event Diagrams
  • Example diagrams to present how to use NUA API with different SIP use cases.

SOFIA Modules

Sofia SIP User Agent Library - sofia-sip-ua

Common runtime library:

• Sofia SIP User Agent Library - "su" - OS Services and Utilities.
• Sofia SIP User Agent Library - "sresolv" - Asynchronous DNS Resolver.
• Sofia SIP User Agent Library - "ipt" - Utility Module.

SIP Signaling:

• Sofia SIP User Agent Library - "nua" - High-Level User Agent Module.
• Sofia SIP User Agent Library - "nea" - SIP Events Module.
• Sofia SIP User Agent Library - "iptsec" - Authentication Module.
• Sofia SIP User Agent Library - "nta" - SIP Transactions Module.
• Sofia SIP User Agent Library - "tport" - Transport Module.
• Sofia SIP User Agent Library - "sip" - SIP Parser Module.
• Sofia SIP User Agent Library - "msg" - Message Parser Module.
• Sofia SIP User Agent Library - "url" - URL Module.
• Sofia SIP User Agent Library - "bnf" - String Parser Module.

HTTP subsystem:

• Sofia SIP User Agent Library - "nth" - HTTP Transactions Module.
• Sofia SIP User Agent Library - "http" - HTTP Parser Module.

SDP processing:

• Sofia SIP User Agent Library - "soa" - SDP Offer/Answer Engine Module.
• Sofia SIP User Agent Library - "sdp" - SDP Module.

Other:

• Sofia SIP User Agent Library - "features" Module.
• Sofia SIP User Agent Library - "stun" - STUN Client and Server Module.

Acknowledgements

• Original Sofia-SIP (not currently maintained).
• Freeswitch version of Sofia-SIP (Currently maintained).

Authors

• @iuridiniz

License

• Rust bindings: MIT
• Sofia-SIP C library: LGPL-2.1-or-later

Before compiling statically, please read this.

Roadmap

• Version 0.1.0 -> DONE

  • NUA: Basic support to send and receive SIP MESSAGE's, allowing to create a chat using SIP.

• Version 0.2.0

  • NUA: Basic support to send SIP INVITE(SDP)/REGISTER(auth) and receive SIP INVITE(SDP), allowing to create a simple soft phone.
  • Others modules: basic support to make NUA objectives work.

• Version 0.3.0

  • NUA: Support receive SIP REGISTER(auth), allowing to create a simple SIP PBX.
  • Others modules: basic support to make NUA objectives work.

• Version 1.0.0

  • NUA: Full bindings for NUA.
  • SDP: Full support for SDP parsing.

NUA is the High-Level User Agent Module of lib-sofia. To learn more about sofia modules, go to reference documentation for libsofia-sip-ua submodules.