Các hàm quản lý cuộc gọi trong PJSUA

Sau ựây là một số hàm thường dùng của thư viện PJSUA dùng ựể quản lý cuộc gọi trong PJSUA. - Tạo cuộc gọi : ta dùng hàm pjsua_call_make_call .Hàm có các dạng như sau :

PJ_DEF(pj_status_t) pjsua_call_make_call( pjsua_acc_id acc_id, const pj_str_t *dest_uri, unsigned options,

void *user_data,

const pjsua_msg_data *msg_data, pjsua_call_id *p_call_id)

Các tham số của hàm này là :

+acc_id : Tài khoản SIP thực hiện cuộc gọi.

+dst_uri : URI ựắch

+options : tùy chọn , thường có giá trị là 0 .

+user_data : thông tin người dùng gắn vào cuộc gọi và có thể phục hồi lại sau ựó , giá trị này

+p_call_id : biến pointer chứa ID của cuộc gọi

+Giá trị trả lại là PJ_SUCCESS nếu thành công, hoặc mã lỗi khi gặp lỗi.

Hàm này thường ựược viết như sau pjsua_call_make_call( current_acc, &dest, 0, NULL, NULL, NULL);

- Ngắt cuộc gọi : ta dùng hàm pjsua_call_hangup. Hàm có dạng như sau : PJ_DECL(pj_status_t) pjsua_call_hangup(pjsua_call_id call_id,

unsigned code,

const pj_str_t *reason,

const pjsua_msg_data *msg_data);

Hàm này sẽ ngắt cuộc gọi bất chấp trạng thái của cuộc gọi, hàm này khác với hàm

pjsua_call_answer . Hàm pjsua_call_answer() ngắt cuộc gọi bằng cách gởi các ựáp ứng

3xx-6xx trong giai ựoạn ựầu của quá trình thiết lập cuộc gọi. Trong khi ựó hàm

pjsua_call_hangup() có tác dụng kết thúc cuộc gọi bất chấp trạng thái chương trình.

Các thông số của hàm :

+call_id: ID của cuộc gọi, thông số này ựược tạo ra trong hàm.

+code: Mã ựáp ứng tùy chọn gởi ựi khi ta ngắt cuộc gọi , nếu giá trị là 0 thì ựáp ứng Ộ603/DeclineỢ sẽ ựược gởi ựi.

+reason: Lý do tùy chọn từ chối cuộc gọi, nếu giá trị là NULL thì chuỗi mặc ựịnh sẽ ựược gởi

ựi.

+msg_data: Các giá trị header tùy chọn.

Hàm này thường ựược dùng với một số chức năng như sau :

+ Ngắt cuộc gọi : ta dùng hàm pjsua_call_hangup( callId, 0, NULL, NULL); ựể gởi ựáp ứng 603/Decline.

+ Không làm phiền hoặc bận rộn : khi có cuộc gọi ựến nhưng người dùng không muốn nghe, ta có thể dùng hàm pjsua_call_hangup( callId, 486 , NULL, NULL ) ựể gởi ựáp ứng

486/Busy Here.

-Gởi ựáp ứng: ta dùng hàm pjsua_call_answer ựể gởi ựáp ứng khi ta nhận ựược một thông ựiệp INVITE từ server gởi ựến . Tùy thuộc vào ựáp ứng ta gởi mà chương trình sẽ báo với server thiết lập cuộc hoặc hủy cuộc gọi Ầ (adsbygoogle = window.adsbygoogle || []).push({});

Hàm có dạng như sau :

PJ_DECL(pj_status_t) pjsua_call_answer(pjsua_call_id call_id, unsigned code,

const pj_str_t *reason,

const pjsua_msg_data *msg_data);

Các thông số của hàm pjsua_call_answer() :

+call_id : ID của cuộc gọi ựến

+code : Mã ựáp ứng (100-699).

+reason : Lý do tùy chọn , thường có giá trị NULL, khi ựó chuỗi mặc ựịnh sẽ ựược dùng.

+msg_data : Header tùy chọn dùng ựể gắn vào thông ựiệp ựáp ứng gởi ựi

Hàm pjsua_call_answer thường ựược dùng như sau :

+ để gởi ựáp ứng báo reo chuông ( ựáp ứng 180 ) ta thường sử dụng hàm pjsua_call_answer

+ để thực hiện chức năng trả lời tự ựộng ( Auto answer ) ta gởi ựáp ứng 200/OK ngay khi vừa nhận ựược yêu cầu INVITE gởi từ server ựến. Ta sử dụng hàm pjsua_call_answer như sau :

pjsua_call_answer(callId, 200, NULL, NULL);

- Giữ cuộc gọi : để thực hiện chức năng giữ cuộc gọi , ta dùng hàm pjsua_call_set_hold. Hàm này sẽ thông báo cho phắa bên kia biết cuộc gọi sẽ ựược chuyển sang trạng thái chờ. Lúc này server sẽ thực hiện chức năng Music-on-Hold ựối với cuộc gọi này , cho ựến khi người dùng cho phục hồi lại cuộc gọi.

Hàm pjsua_call_set_hold có dạng như sau :

PJ_DECL(pj_status_t) pjsua_call_set_hold(pjsua_call_id call_id, const pjsua_msg_data *msg_data);

Các thông số của hàm như sau :

+call_id : ID của cuộc gọi.

+msg_data : Thông ựiệp tùy chọn gởi cùng với yêu cầu .

Hàm này thường ựược viết như sau :

pjsua_call_set_hold(current_call, NULL);

- Phục hồi cuộc gọi : để phục hồi cuộc gọi trong khi giữ cuộc gọi ta dùng hàm

pjsua_call_reinvite. Hàm pjsua_call_reinvite sẽ gởi yêu cầu re-INVITE ựến server ựể

phục hồi cuộc gọi ựang bị giữ. Hàm có dạng như sau :

PJ_DECL(pj_status_t) pjsua_call_reinvite(pjsua_call_id call_id, pj_bool_t unhold,

const pjsua_msg_data *msg_data);

Các thông số của hàm pjsua_call_reinvite :

+call_id : ID của cuộc gọi.

+unhold : Nếu giá trị này là số khác không thì nói sẽ phục hồi lại cuộc gọi có số ID là call_ID. (adsbygoogle = window.adsbygoogle || []).push({});

+msg_data : Thông ựiệp tùy chọn gởi kèm với yêu cầu.

Hàm này thường ựược viết như sau :

pjsua_call_reinvite(current_call, 1 , NULL);

- Chuyển cuộc gọi : để thực hiện chức năng chuyển cuộc gọi , ta có thể dùng hàm

pjsua_call_hangup().

Ta tìm hiểu qua hàm tạo Header SIP pjsip_generic_string_hdr_init2 .

Hàm này có cấu trúc như sau :

PJ_DECL(void) pjsip_generic_string_hdr_init2(pjsip_generic_string_hdr *h, pj_str_t *hname,

pj_str_t *hvalue);

Thông số của hàm như sau : +h : Header SIP cần tạo +hname : Tên của Header +hvalue : Giá trị của header

để chuyển cuộc gọi ta sử dụng hàm pjsua_call_hangup() với mã ựáp ứng là 302/Moved Temporarily. Khi nhận mã ựáp ứng 302 , server sẽ thử lại yêu cầu ở ựịa chỉ mới ựược cho bởi trường Contact.Chắnh vì vậy ta cần dùng hàm pjsip_generic_string_hdr_init2() ựể tạo trường Contact trong thông ựiệp SIP, trong trường Contact này sẽ chứa ựịa chỉ mới có dạng <sip:number@domain> .

Sau ựây là các bước lập trình chuyển cuộc gọi :

//1.) Tạo trường contact có chứa ựịa chỉ mới

pj_str_t contact_header_to_call = pj_str((char*)destUri);

//2.) Chèn trường Contact vào nội dung biến pjsua_msg_data trong hàm pjsua_call_hangup

pjsua_msg_data aStruct;

pjsua_msg_data_init(&aStruct);//Khởi tạo pjsua_msg_data

pjsip_generic_string_hdr warn;//Khai báo biến SIP header pj_str_t hname = pj_str("Contact");//Khai báo tên trường pj_str_t hvalue = contact_header_to_call;//Gán giá trị trường pjsip_generic_string_hdr_init2(&warn, &hname, &hvalue);

warn.type = PJSIP_H_CONTACT;

pj_list_push_back(&aStruct.hdr_list, &warn);//Chèn trường Contact vào pjsua_msg_data

//3.) Chuyển cuộc gọi

pjsua_call_hangup(callId, 302, NULL, &(aStruct));

- Báo hiệu DTMF : để gởi các ký tự dựa trên giao thức báo hiệu DTMF theo ựịnh dạng của RFC2833 ta dùng hàm pjsua_call_dial_dtmf .

Cấu trúc của hàm như sau :

PJ_DECL(pj_status_t) pjsua_call_dial_dtmf(pjsua_call_id call_id, const pj_str_t *digits);

Thông số của hàm như sau :

+call_id : ID của cuộc gọi

+digits : ký tự DTMF gởi ựi

Vắ dụ ựể gởi ký tự Ộ#Ợ ta viết code như sau : (adsbygoogle = window.adsbygoogle || []).push({});

pj_str_t dg = pj_str(Ộ#Ợ);

pjsua_call_dial_dtmf(call_id, &dg);

3.3 Gii thi u Bkphone

Bkphone là chương trình thoại trên máy trạm có giao diện (GUI) ựược viết bằng ngôn ngữ C# và phần lõi chương trình (VoIP engine) dựa trên thư viện PJSIP.

Hình 3.3: Giao diện chắnh của BKphone

3.3.1 Chức năng và cấu trúc Bkphone :

- Báo hiệu SIP theo tiêu chuẩn RFC3261 - Thực hiện các cuộc gọi

- Chức năng giữ cuộc gọi (Call Hold/retrieve)

-Chức năng chuyển cuộc gọi (Call Forwarding (Unconditional)) - Chức năng báo bận (Do Not Disturb)

- Chức năng tự ựộng trả lời (Auto Answer)

- Hỗ trợ ựăng ký thông tin 5 tài khoản SIP (chỉ có 1 tài khoản là mặc ựịnh ( default ) ) . - Liệt kê các cuộc gọi ựã thực hiện

Bkphone

GUI Giao diện người

dùng Telephony.dll CallManager, CMachineState, SipCommonProxy.. Pjsipdll.dll Callback, PJSUA_dll... PJSUA-LIB

Chi tiết các phần như sau :

- Pjsipdll.dll : là một file dll viết bằng C++ , gồm các hàm gọi từ thư viện PJSUA , giao tiếp trực tiếp với thư viện PJSUA.

- Telephony.dll : là một file dll viết bằng C# , có mục ựắch tương tác với thư viện Pjsua thông qua Pjsipdll.dll và giao diện GUI , gồm các lớp quan trọng sau :

+ CallManager: là lớp nhận lệnh giữa người dùng từ giao diện GUI và thông báo ra giao diện GUI các hoạt ựộng của chương trình trong quá trình quản lý các phiên cuộc gọi .

+ CMachineState: là lớp chứa thông tin của 1 cuộc gọi , trạng thái của chương trình : IDLE , INCOMING , ALERTING, ACTIVE , RELEASED, HOLDING.

+SipCommonProxy: là lớp tương tác với Pjsipdll.dll bằng cách sử dụng System.Runtime.InteropServices ựể wrapper các hàm Pjsua_dll trong Pjsipdll.dll .

- GUI : giao diện chương trình, gồm có : bàn phắm ựể thực hiện bấm số ( DTMF Dialling ) , menu Options ựể ựiền các thông tin tài khoản SIP , danh sách các cuộc gọi ựã diễn ra , các nút nhấn chức năng ựiều khiển cuộc gọi .

3.3.2 Các trạng thái hoạt ựộng của chương trình Bkphone .

BKphone gồm các trạng thái hoạt ựộng như sau: - IDLE: khi không có cuộc gọi nào diễn ra

- CONNECTING: kết nối ựến server ựể thực hiện gọi ựi

- ALERTING: chờ người ựược gọi bắt máy khi thực hiện gọi ựi - ACTIVE: hai phắa ựang nói chuyện với nhau.

- RELEASED: cuộc gọi bị ngắt - INCOMING: báo có cuộc gọi ựến - HOLDING: trạng thái chờ

STT Tên trạng thái Hoạt ựộng

1 IDLE - Chương trình sẽ chạy ở trạng thái này khi không có cuộc gọi nào diễn ra.

- Chương trình sẽ chuyển sang trạng thái CONNECTING khi người dùng muốn gọi ựi .

- Chương trình tự chuyển sang trạng INCOMING khi có cuộc gọi ựến. (adsbygoogle = window.adsbygoogle || []).push({});

2 CONNECTING - Chương trình sẽ chạy ở trạng thái này khi người sử dụng thực hiện việc gọi ựi.

- Chương trình sẽ chuyển sang trạng thái ALERTING khi nhận ựược kết quả hàm Callback onAlerting.

- Chương trình sẽ chuyển sang trạng thái RELEASED khi nhận ựược kết quả hàm Callback onReleased.