sip-lab 1.12.1 → 1.12.2

package/README.md

@@ -35,6 +35,10 @@ Then install sip-lab by doing:
   npm install sip-lab
 ```
 
+Be patient because we will need to download pjproject and build it.
+
+We will also download rapidjson.
+
 To test from within this repo just build and install by doing:
 ```
   npm install -g node-gyp
@@ -44,6 +48,8 @@ And run some sample script from subfolder samples:
 ```
   node samples/simple.js
 ```
+The above script has detailed comments. 
+Please read it to undestand how to write your own test scripts.
 
 The module is known to work properly in Ubuntu 18.04.4, Ubuntu 20.04.4, Debian 8 and Debian 10 (and it is expected to work in Debian 9).
 It was originally developed with node v.10 and tested with v.12 and v16.13.1 and it is expected to work with latest versions of node.
@@ -65,4 +71,9 @@ But if you do so, you will need to set NODE_PATH for node to find it by doing:
   export NODE_PATH=$(npm root --quiet -g)
 ```
 
+### About the code
+
+Although the code in written in *.cpp/*.hpp named files, this is not actually a C++ project.
+
+It is mostly written in C using some C++ facilities.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sip-lab",
-  "version": "1.12.1",
+  "version": "1.12.2",
   "description": "",
   "main": "index.js",
   "engines": {

package/samples/send_and_receive_fax.js

@@ -21,7 +21,7 @@ async function test() {
     console.log("t1", t1)
     console.log("t2", t2)
 
-    oc = sip.call.create(t1.id, {from_uri: 'sip:a@t', to_uri: 'sip:b@127.0.0.1:5092'})
+    oc = sip.call.create(t1.id, {from_uri: 'sip:alice@test.com', to_uri: `sip:bob@${t2.address}:${t2.port}`})
 
     await z.wait([
         {
@@ -37,9 +37,9 @@ async function test() {
                 $rr: 'Trying',
                 '$(hdrcnt(via))': 1,
                 '$hdr(call-id)': m.collect('sip_call_id'),
-                $fU: 'a',
-                $fd: 't',
-                $tU: 'b',
+                $fU: 'alice',
+                $fd: 'test.com',
+                $tU: 'bob',
                 '$hdr(l)': '0',
             }),
         },
@@ -75,9 +75,9 @@ async function test() {
                 $rs: '200',
                 $rr: 'OK',
                 '$(hdrcnt(VIA))': 1,
-                $fU: 'a',
-                $fd: 't',
-                $tU: 'b',
+                $fU: 'alice',
+                $fd: 'test.com',
+                $tU: 'bob',
                 '$hdr(content-type)': 'application/sdp',
                 $rb: '!{_}a=sendrecv',
             }),

package/samples/simple.js

@@ -1,32 +1,45 @@
-var sip = require ('../index.js')
-var Zester = require('zester')
+// This test creates 2 UDP SIP endpoints, makes a call between them and disconeects.
+
+const sip = require ('../index.js')
+const Zester = require('zester')
+const m = require('data-matching')
+const sip_msg = require('sip-matching')
+
+// here we create our Zester instance
 var z = new Zester()
-var m = require('data-matching')
-var sip_msg = require('sip-matching')
 
-async function test() {
-    //sip.set_log_level(6)
-    sip.dtmf_aggregation_on(500)
 
+async function test() {
+    // here we set our zester instance to trap events generated by sip-lab event_source
     z.trap_events(sip.event_source, 'event', (evt) => {
         var e = evt.args[0]
         return e
     })
 
+    // here we start sip-lab
     console.log(sip.start((data) => { console.log(data)} ))
 
-    t1 = sip.transport.create({address: "127.0.0.1", port: 5090, type: 'udp'})
-    t2 = sip.transport.create({address: "127.0.0.1", port: 5092, type: 'udp'})
+    // Here we create the SIP endpoints (transports).
+    // Since we don't specify the port, an available port will be allocated.
+    // Since we don't specify the type ('udp' or 'tcp' or 'tls'), 'udp' will be used by default.
+    const t1 = sip.transport.create({address: "127.0.0.1"})
+    const t2 = sip.transport.create({address: "127.0.0.1"})
 
+    // here we just print the transports
     console.log("t1", t1)
     console.log("t2", t2)
 
-    oc = sip.call.create(t1.id, {from_uri: 'sip:alice@test.com', to_uri: `sip:bob@${t2.address}:${t2.port}`})
+    // make the call from t1 to t2
+    const oc = sip.call.create(t1.id, {from_uri: 'sip:alice@test.com', to_uri: `sip:bob@${t2.address}:${t2.port}`})
 
+    // Here we will wait for the call to arrive at t2
+    // We will also get a '100 Trying' that is sent by sip-lab automatically
+    // We will wait for at most 1000ms. If all events don't arrive within 1000ms, an exception will be thrown and the test will fail due to timeout.
     await z.wait([
         {
             event: "incoming_call",
             call_id: m.collect("call_id"),
+            transport_id: t2.id,
         },
         {
             event: 'response',
@@ -44,29 +57,39 @@ async function test() {
             }),
         },
     ], 1000)
-
-    ic = {
+    // Details about zester wait(list_of_events_to_wait_for, timeout_in_ms):
+    // The order of events in the list is irrelevant.
+    // What matters is that all events arrive within the specified timeout.
+    // When specifying events, you can be as detailed or succinct as you need.
+    // For example, the above event 'response' is waiting for a SIP '100 Trying' to arrive,
+    // but we are specifying things to match just to show that we can be very detailed when performing a match.
+    // But it could have been just like this:
+    //
+    //  {
+    //      event: 'response',
+    //      call_id: oc.id,
+    //      method: 'INVITE',
+    //      msg: sip_msg({
+    //          $rs: '100',
+    //      }),
+    //  }
+    // Regarding the function sip_msg() this is a special matching function provided by https://github.com/MayamaTakeshi/sip-matching that makes it 
+    // easy to match a SIP message using openser/kamailio/opensips pseudo-variables syntax.
+ 
+
+    // Here we store data for the incoming call
+    // just to organize our code (not really needed)
+    const ic = {
         id: z.store.call_id,
         sip_call_id: z.store.sip_call_id,
     }
 
+    // Now we answer the call at t2 side
     sip.call.respond(ic.id, {code: 200, reason: 'OK'})
 
+    // Then we wait for the '200 OK' at the t1 side
+    // We will also get event 'media_status' for both sides indicating media streams (RTP) were set up successfully
     await z.wait([
-        {
-            event: 'media_status',
-            call_id: oc.id,
-            status: 'setup_ok',
-            local_mode: 'sendrecv',
-            remote_mode: 'sendrecv',
-        },
-        {
-            event: 'media_status',
-            call_id: ic.id,
-            status: 'setup_ok',
-            local_mode: 'sendrecv',
-            remote_mode: 'sendrecv',
-        },
         {
             event: 'response',
             call_id: oc.id,
@@ -82,19 +105,27 @@ async function test() {
                 $rb: '!{_}a=sendrecv',
             }),
         },
-    ], 1000)
-
-    sip.call.terminate(oc.id)
-
-    await z.wait([
         {
-            event: 'call_ended',
+            event: 'media_status',
             call_id: oc.id,
+            status: 'setup_ok',
+            local_mode: 'sendrecv',
+            remote_mode: 'sendrecv',
         },
         {
-            event: 'call_ended',
+            event: 'media_status',
             call_id: ic.id,
+            status: 'setup_ok',
+            local_mode: 'sendrecv',
+            remote_mode: 'sendrecv',
         },
+    ], 1000)
+
+    // now we terminate the call from t1 side
+    sip.call.terminate(oc.id)
+
+    // and wait for termination events
+    await z.wait([
         {
             event: 'response',
             call_id: oc.id,
@@ -104,6 +135,14 @@ async function test() {
                 $rr: 'OK',
             }),
         },
+        {
+            event: 'call_ended',
+            call_id: oc.id,
+        },
+        {
+            event: 'call_ended',
+            call_id: ic.id,
+        },
     ], 1000)
 
     console.log("Success")