· 8 years ago · Jun 15, 2018, 05:12 PM
1/* $Id$ */
2/*
3 * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
4 * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
5 *
6 * This program is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation; either version 2 of the License, or
9 * (at your option) any later version.
10 *
11 * This program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
15 *
16 * You should have received a copy of the GNU General Public License
17 * along with this program; if not, write to the Free Software
18 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
19 */
20#ifndef __PJSUA_H__
21#define __PJSUA_H__
22
23/**
24 * @file pjsua.h
25 * @brief PJSUA API.
26 */
27
28
29/* Include all PJSIP core headers. */
30#include <pjsip.h>
31
32/* Include all PJMEDIA headers. */
33#include <pjmedia.h>
34
35/* Include all PJMEDIA-CODEC headers. */
36#include <pjmedia-codec.h>
37
38/* Videodev too */
39#include <pjmedia_videodev.h>
40
41/* Include all PJSIP-UA headers */
42#include <pjsip_ua.h>
43
44/* Include all PJSIP-SIMPLE headers */
45#include <pjsip_simple.h>
46
47/* Include all PJNATH headers */
48#include <pjnath.h>
49
50/* Include all PJLIB-UTIL headers. */
51#include <pjlib-util.h>
52
53/* Include all PJLIB headers. */
54#include <pjlib.h>
55
56
57PJ_BEGIN_DECL
58
59
60/**
61 * @defgroup PJSUA_LIB PJSUA API - High Level Softphone API
62 * @brief Very high level API for constructing SIP UA applications.
63 * @{
64 *
65 * @section pjsua_api_intro A SIP User Agent API for C/C++
66 *
67 * PJSUA API is very high level API for constructing SIP multimedia user agent
68 * applications. It wraps together the signaling and media functionalities
69 * into an easy to use call API, provides account management, buddy
70 * management, presence, instant messaging, along with multimedia
71 * features such as conferencing, file streaming, local playback,
72 * voice recording, and so on.
73 *
74 * @subsection pjsua_for_c_cpp C/C++ Binding
75 * Application must link with <b>pjsua-lib</b> to use this API. In addition,
76 * this library depends on the following libraries:
77 * - <b>pjsip-ua</b>,
78 * - <b>pjsip-simple</b>,
79 * - <b>pjsip-core</b>,
80 * - <b>pjmedia</b>,
81 * - <b>pjmedia-codec</b>,
82 * - <b>pjlib-util</b>, and
83 * - <b>pjlib</b>,
84 *
85 * so application must also link with these libraries as well. For more
86 * information, please refer to
87 * <A HREF="http://www.pjsip.org/using.htm">Getting Started with PJSIP</A>
88 * page.
89 *
90 * @section pjsua_samples
91 *
92 * Few samples are provided:
93 *
94 - @ref page_pjsip_sample_simple_pjsuaua_c\n
95 Very simple SIP User Agent with registration, call, and media, using
96 PJSUA-API, all in under 200 lines of code.
97
98 - @ref page_pjsip_samples_pjsua\n
99 This is the reference implementation for PJSIP and PJMEDIA.
100 PJSUA is a console based application, designed to be simple enough
101 to be readble, but powerful enough to demonstrate all features
102 available in PJSIP and PJMEDIA.\n
103
104 * @section root_using_pjsua_lib Using PJSUA API
105 *
106 * Please refer to @ref PJSUA_LIB_BASE on how to create and initialize the API.
107 * And then see the Modules on the bottom of this page for more information
108 * about specific subject.
109 */
110
111
112
113/*****************************************************************************
114 * BASE API
115 */
116
117/**
118 * @defgroup PJSUA_LIB_BASE PJSUA-API Basic API
119 * @ingroup PJSUA_LIB
120 * @brief Basic application creation/initialization, logging configuration, etc.
121 * @{
122 *
123 * The base PJSUA API controls PJSUA creation, initialization, and startup, and
124 * also provides various auxiliary functions.
125 *
126 * @section using_pjsua_lib Using PJSUA Library
127 *
128 * @subsection creating_pjsua_lib Creating PJSUA
129 *
130 * Before anything else, application must create PJSUA by calling
131 * #pjsua_create().
132 * This, among other things, will initialize PJLIB, which is crucial before
133 * any PJLIB functions can be called, PJLIB-UTIL, and create a SIP endpoint.
134 *
135 * After this function is called, application can create a memory pool (with
136 * #pjsua_pool_create()) and read configurations from command line or file to
137 * build the settings to initialize PJSUA below.
138 *
139 * @subsection init_pjsua_lib Initializing PJSUA
140 *
141 * After PJSUA is created, application can initialize PJSUA by calling
142 * #pjsua_init(). This function takes several optional configuration settings
143 * in the argument, if application wants to set them.
144 *
145 * @subsubsection init_pjsua_lib_c_cpp PJSUA-LIB Initialization (in C)
146 * Sample code to initialize PJSUA in C code:
147 \code
148
149 #include <pjsua-lib/pjsua.h>
150
151 #define THIS_FILE __FILE__
152
153 static pj_status_t app_init(void)
154 {
155 pjsua_config ua_cfg;
156 pjsua_logging_config log_cfg;
157 pjsua_media_config media_cfg;
158 pj_status_t status;
159
160 // Must create pjsua before anything else!
161 status = pjsua_create();
162 if (status != PJ_SUCCESS) {
163 pjsua_perror(THIS_FILE, "Error initializing pjsua", status);
164 return status;
165 }
166
167 // Initialize configs with default settings.
168 pjsua_config_default(&ua_cfg);
169 pjsua_logging_config_default(&log_cfg);
170 pjsua_media_config_default(&media_cfg);
171
172 // At the very least, application would want to override
173 // the call callbacks in pjsua_config:
174 ua_cfg.cb.on_incoming_call = ...
175 ua_cfg.cb.on_call_state = ..
176 ...
177
178 // Customize other settings (or initialize them from application specific
179 // configuration file):
180 ...
181
182 // Initialize pjsua
183 status = pjsua_init(&ua_cfg, &log_cfg, &media_cfg);
184 if (status != PJ_SUCCESS) {
185 pjsua_perror(THIS_FILE, "Error initializing pjsua", status);
186 return status;
187 }
188 .
189 ...
190 }
191 \endcode
192 *
193 *
194
195
196 * @subsection other_init_pjsua_lib Other Initialization
197 *
198 * After PJSUA is initialized with #pjsua_init(), application will normally
199 * need/want to perform the following tasks:
200 *
201 * - create SIP transport with #pjsua_transport_create(). Application would
202 * to call #pjsua_transport_create() for each transport types that it
203 * wants to support (for example, UDP, TCP, and TLS). Please see
204 * @ref PJSUA_LIB_TRANSPORT section for more info.
205 * - create one or more SIP accounts with #pjsua_acc_add() or
206 * #pjsua_acc_add_local(). The SIP account is used for registering with
207 * the SIP server, if any. Please see @ref PJSUA_LIB_ACC for more info.
208 * - add one or more buddies with #pjsua_buddy_add(). Please see
209 * @ref PJSUA_LIB_BUDDY section for more info.
210 * - optionally configure the sound device, codec settings, and other
211 * media settings. Please see @ref PJSUA_LIB_MEDIA for more info.
212 *
213 *
214 * @subsection starting_pjsua_lib Starting PJSUA
215 *
216 * After all initializations have been done, application must call
217 * #pjsua_start() to start PJSUA. This function will check that all settings
218 * have been properly configured, and apply default settings when they haven't,
219 * or report error status when it is unable to recover from missing settings.
220 *
221 * Most settings can be changed during run-time. For example, application
222 * may add, modify, or delete accounts, buddies, or change media settings
223 * during run-time.
224 *
225 * @subsubsection starting_pjsua_lib_c C Example for Starting PJSUA
226 * Sample code:
227 \code
228 static pj_status_t app_run(void)
229 {
230 pj_status_t status;
231
232 // Start pjsua
233 status = pjsua_start();
234 if (status != PJ_SUCCESS) {
235 pjsua_destroy();
236 pjsua_perror(THIS_FILE, "Error starting pjsua", status);
237 return status;
238 }
239
240 // Run application loop
241 while (1) {
242 char choice[10];
243
244 printf("Select menu: ");
245 fgets(choice, sizeof(choice), stdin);
246 ...
247 }
248 }
249 \endcode
250
251 */
252
253/** Constant to identify invalid ID for all sorts of IDs. */
254enum pjsua_invalid_id_const_
255{
256 PJSUA_INVALID_ID = -1
257};
258
259/** Disabled features temporarily for media reorganization */
260#define DISABLED_FOR_TICKET_1185 0
261
262/** Call identification */
263typedef int pjsua_call_id;
264
265/** Account identification */
266typedef int pjsua_acc_id;
267
268/** Buddy identification */
269typedef int pjsua_buddy_id;
270
271/** File player identification */
272typedef int pjsua_player_id;
273
274/** File recorder identification */
275typedef int pjsua_recorder_id;
276
277/** Conference port identification */
278typedef int pjsua_conf_port_id;
279
280/** Opaque declaration for server side presence subscription */
281typedef struct pjsua_srv_pres pjsua_srv_pres;
282
283/** Forward declaration for pjsua_msg_data */
284typedef struct pjsua_msg_data pjsua_msg_data;
285
286/** Forward declaration for pj_stun_resolve_result */
287typedef struct pj_stun_resolve_result pj_stun_resolve_result;
288
289
290/**
291 * Maximum proxies in account.
292 */
293#ifndef PJSUA_ACC_MAX_PROXIES
294# define PJSUA_ACC_MAX_PROXIES 8
295#endif
296
297/**
298 * Default value of SRTP mode usage. Valid values are PJMEDIA_SRTP_DISABLED,
299 * PJMEDIA_SRTP_OPTIONAL, and PJMEDIA_SRTP_MANDATORY.
300 */
301#ifndef PJSUA_DEFAULT_USE_SRTP
302 #define PJSUA_DEFAULT_USE_SRTP PJMEDIA_SRTP_DISABLED
303#endif
304
305/**
306 * Default value of secure signaling requirement for SRTP.
307 * Valid values are:
308 * 0: SRTP does not require secure signaling
309 * 1: SRTP requires secure transport such as TLS
310 * 2: SRTP requires secure end-to-end transport (SIPS)
311 */
312#ifndef PJSUA_DEFAULT_SRTP_SECURE_SIGNALING
313 #define PJSUA_DEFAULT_SRTP_SECURE_SIGNALING 1
314#endif
315
316/**
317 * Controls whether PJSUA-LIB should add ICE media feature tag
318 * parameter (the ";+sip.ice" parameter) to Contact header if ICE
319 * is enabled in the config.
320 *
321 * Default: 1
322 */
323#ifndef PJSUA_ADD_ICE_TAGS
324# define PJSUA_ADD_ICE_TAGS 1
325#endif
326
327/**
328 * Timeout value used to acquire mutex lock on a particular call.
329 *
330 * Default: 2000 ms
331 */
332#ifndef PJSUA_ACQUIRE_CALL_TIMEOUT
333# define PJSUA_ACQUIRE_CALL_TIMEOUT 2000
334#endif
335
336/**
337 * Is video enabled.
338 */
339#ifndef PJSUA_HAS_VIDEO
340# define PJSUA_HAS_VIDEO PJMEDIA_HAS_VIDEO
341#endif
342
343
344/**
345 * Interval between two keyframe requests, in milliseconds.
346 *
347 * Default: 3000 ms
348 */
349#ifndef PJSUA_VID_REQ_KEYFRAME_INTERVAL
350# define PJSUA_VID_REQ_KEYFRAME_INTERVAL 3000
351#endif
352
353
354/**
355 * Specify whether timer heap events will be polled by a separate worker
356 * thread. If this is set/enabled, a worker thread will be dedicated to
357 * poll timer heap events only, and the rest worker thread(s) will poll
358 * ioqueue/network events only.
359 *
360 * Note that if worker thread count setting (i.e: pjsua_config.thread_cnt)
361 * is set to zero, this setting will be ignored.
362 *
363 * Default: 0 (disabled)
364 */
365#ifndef PJSUA_SEPARATE_WORKER_FOR_TIMER
366# define PJSUA_SEPARATE_WORKER_FOR_TIMER 0
367#endif
368
369
370/**
371 * This enumeration represents pjsua state.
372 */
373typedef enum pjsua_state
374{
375 /**
376 * The library has not been initialized.
377 */
378 PJSUA_STATE_NULL,
379
380 /**
381 * After pjsua_create() is called but before pjsua_init() is called.
382 */
383 PJSUA_STATE_CREATED,
384
385 /**
386 * After pjsua_init() is called but before pjsua_start() is called.
387 */
388 PJSUA_STATE_INIT,
389
390 /**
391 * After pjsua_start() is called but before everything is running.
392 */
393 PJSUA_STATE_STARTING,
394
395 /**
396 * After pjsua_start() is called and before pjsua_destroy() is called.
397 */
398 PJSUA_STATE_RUNNING,
399
400 /**
401 * After pjsua_destroy() is called but before the function returns.
402 */
403 PJSUA_STATE_CLOSING
404
405} pjsua_state;
406
407
408/**
409 * Logging configuration, which can be (optionally) specified when calling
410 * #pjsua_init(). Application must call #pjsua_logging_config_default() to
411 * initialize this structure with the default values.
412 */
413typedef struct pjsua_logging_config
414{
415 /**
416 * Log incoming and outgoing SIP message? Yes!
417 */
418 pj_bool_t msg_logging;
419
420 /**
421 * Input verbosity level. Value 5 is reasonable.
422 */
423 unsigned level;
424
425 /**
426 * Verbosity level for console. Value 4 is reasonable.
427 */
428 unsigned console_level;
429
430 /**
431 * Log decoration.
432 */
433 unsigned decor;
434
435 /**
436 * Optional log filename.
437 */
438 pj_str_t log_filename;
439
440 /**
441 * Additional flags to be given to #pj_file_open() when opening
442 * the log file. By default, the flag is PJ_O_WRONLY. Application
443 * may set PJ_O_APPEND here so that logs are appended to existing
444 * file instead of overwriting it.
445 *
446 * Default is 0.
447 */
448 unsigned log_file_flags;
449
450 /**
451 * Optional callback function to be called to write log to
452 * application specific device. This function will be called for
453 * log messages on input verbosity level.
454 */
455 void (*cb)(int level, const char *data, int len);
456
457
458} pjsua_logging_config;
459
460
461/**
462 * Use this function to initialize logging config.
463 *
464 * @param cfg The logging config to be initialized.
465 */
466PJ_DECL(void) pjsua_logging_config_default(pjsua_logging_config *cfg);
467
468
469/**
470 * Use this function to duplicate logging config.
471 *
472 * @param pool Pool to use.
473 * @param dst Destination config.
474 * @param src Source config.
475 */
476PJ_DECL(void) pjsua_logging_config_dup(pj_pool_t *pool,
477 pjsua_logging_config *dst,
478 const pjsua_logging_config *src);
479
480
481/**
482 * Structure to be passed on MWI callback.
483 */
484typedef struct pjsua_mwi_info
485{
486 pjsip_evsub *evsub; /**< Event subscription session, for
487 reference. */
488 pjsip_rx_data *rdata; /**< The received NOTIFY request. */
489} pjsua_mwi_info;
490
491
492/**
493 * Structure to be passed on registration callback.
494 */
495typedef struct pjsua_reg_info
496{
497 struct pjsip_regc_cbparam *cbparam; /**< Parameters returned by
498 registration callback. */
499 pjsip_regc *regc; /**< Client registration
500 structure. */
501 pj_bool_t renew; /**< Non-zero for registration and
502 zero for unregistration. */
503} pjsua_reg_info;
504
505
506/**
507 * Structure to be passed to on stream created callback.
508 * See #on_stream_created2().
509 */
510typedef struct pjsua_on_stream_created_param
511{
512 /**
513 * The media stream, read-only.
514 */
515 pjmedia_stream *stream;
516
517 /**
518 * Stream index in the media session, read-only.
519 */
520 unsigned stream_idx;
521
522 /**
523 * Specify if PJSUA should take ownership of the port returned in
524 * the port parameter below. If set to PJ_TRUE,
525 * pjmedia_port_destroy() will be called on the port when it is
526 * no longer needed.
527 *
528 * Default: PJ_FALSE
529 */
530 pj_bool_t destroy_port;
531
532 /**
533 * On input, it specifies the media port of the stream. Application
534 * may modify this pointer to point to different media port to be
535 * registered to the conference bridge.
536 */
537 pjmedia_port *port;
538
539} pjsua_on_stream_created_param;
540
541
542/**
543 * Enumeration of media transport state types.
544 */
545typedef enum pjsua_med_tp_st
546{
547 /** Null, this is the state before media transport is created. */
548 PJSUA_MED_TP_NULL,
549
550 /**
551 * Just before media transport is created, which can finish
552 * asynchronously later.
553 */
554 PJSUA_MED_TP_CREATING,
555
556 /** Media transport creation is completed, but not initialized yet. */
557 PJSUA_MED_TP_IDLE,
558
559 /** Initialized (media_create() has been called). */
560 PJSUA_MED_TP_INIT,
561
562 /** Running (media_start() has been called). */
563 PJSUA_MED_TP_RUNNING,
564
565 /** Disabled (transport is initialized, but media is being disabled). */
566 PJSUA_MED_TP_DISABLED
567
568} pjsua_med_tp_st;
569
570
571/**
572 * Structure to be passed on media transport state callback.
573 */
574typedef struct pjsua_med_tp_state_info
575{
576 /**
577 * The media index.
578 */
579 unsigned med_idx;
580
581 /**
582 * The media transport state
583 */
584 pjsua_med_tp_st state;
585
586 /**
587 * The last error code related to the media transport state.
588 */
589 pj_status_t status;
590
591 /**
592 * Optional SIP error code.
593 */
594 int sip_err_code;
595
596 /**
597 * Optional extended info, the content is specific for each transport type.
598 */
599 void *ext_info;
600
601} pjsua_med_tp_state_info;
602
603
604/**
605 * Type of callback to be called when media transport state is changed.
606 *
607 * @param call_id The call ID.
608 * @param info The media transport state info.
609 *
610 * @return The callback must return PJ_SUCCESS at the moment.
611 */
612typedef pj_status_t
613(*pjsua_med_tp_state_cb)(pjsua_call_id call_id,
614 const pjsua_med_tp_state_info *info);
615
616
617/**
618 * Typedef of callback to be registered to #pjsua_resolve_stun_servers()
619 * and to be called when STUN resolution completes.
620 */
621typedef void (*pj_stun_resolve_cb)(const pj_stun_resolve_result *result);
622
623
624/**
625 * This enumeration specifies the options for custom media transport creation.
626 */
627typedef enum pjsua_create_media_transport_flag
628{
629 /**
630 * This flag indicates that the media transport must also close its
631 * "member" or "child" transport when pjmedia_transport_close() is
632 * called. If this flag is not specified, then the media transport
633 * must not call pjmedia_transport_close() of its member transport.
634 */
635 PJSUA_MED_TP_CLOSE_MEMBER = 1
636
637} pjsua_create_media_transport_flag;
638
639
640/**
641 * Specify SRTP media transport settings.
642 */
643typedef struct pjsua_srtp_opt
644{
645 /**
646 * Specify the number of crypto suite settings. If set to zero, all
647 * available cryptos will be enabled. Note that available crypto names
648 * can be enumerated using pjmedia_srtp_enum_crypto().
649 *
650 * Default is zero.
651 */
652 unsigned crypto_count;
653
654 /**
655 * Specify individual crypto suite setting and its priority order.
656 *
657 * Notes for DTLS-SRTP keying:
658 * - Currently only supports these cryptos: AES_CM_128_HMAC_SHA1_80,
659 * AES_CM_128_HMAC_SHA1_32, AEAD_AES_256_GCM, and AEAD_AES_128_GCM.
660 * - SRTP key is not configurable.
661 */
662 pjmedia_srtp_crypto crypto[PJMEDIA_SRTP_MAX_CRYPTOS];
663
664 /**
665 * Specify the number of enabled keying methods. If set to zero, all
666 * keyings will be enabled. Maximum value is PJMEDIA_SRTP_MAX_KEYINGS.
667 * Note that available keying methods can be enumerated using
668 * pjmedia_srtp_enum_keying().
669 *
670 * Default is zero (all keyings are enabled with priority order:
671 * SDES, DTLS-SRTP).
672 */
673 unsigned keying_count;
674
675 /**
676 * Specify enabled keying methods and its priority order. Keying method
677 * with higher priority will be given earlier chance to process the SDP,
678 * for example as currently only one keying is supported in the SDP offer,
679 * keying with first priority will be likely used in the SDP offer.
680 */
681 pjmedia_srtp_keying_method keying[PJMEDIA_SRTP_KEYINGS_COUNT];
682
683} pjsua_srtp_opt;
684
685
686/**
687 * This enumeration specifies the contact rewrite method.
688 */
689typedef enum pjsua_contact_rewrite_method
690{
691 /**
692 * The Contact update will be done by sending unregistration
693 * to the currently registered Contact, while simultaneously sending new
694 * registration (with different Call-ID) for the updated Contact.
695 */
696 PJSUA_CONTACT_REWRITE_UNREGISTER = 1,
697
698 /**
699 * The Contact update will be done in a single, current
700 * registration session, by removing the current binding (by setting its
701 * Contact's expires parameter to zero) and adding a new Contact binding,
702 * all done in a single request.
703 */
704 PJSUA_CONTACT_REWRITE_NO_UNREG = 2,
705
706 /**
707 * The Contact update will be done when receiving any registration final
708 * response. If this flag is not specified, contact update will only be
709 * done upon receiving 2xx response. This flag MUST be used with
710 * PJSUA_CONTACT_REWRITE_UNREGISTER or PJSUA_CONTACT_REWRITE_NO_UNREG
711 * above to specify how the Contact update should be performed when
712 * receiving 2xx response.
713 */
714 PJSUA_CONTACT_REWRITE_ALWAYS_UPDATE = 4
715
716} pjsua_contact_rewrite_method;
717
718
719/**
720 * This enumeration specifies the operation when handling IP change.
721 */
722typedef enum pjsua_ip_change_op {
723 /**
724 * Hasn't start ip change process.
725 */
726 PJSUA_IP_CHANGE_OP_NULL,
727
728 /**
729 * The restart listener process.
730 */
731 PJSUA_IP_CHANGE_OP_RESTART_LIS,
732
733 /**
734 * The shutdown transport process.
735 */
736 PJSUA_IP_CHANGE_OP_ACC_SHUTDOWN_TP,
737
738 /**
739 * The update contact process.
740 */
741 PJSUA_IP_CHANGE_OP_ACC_UPDATE_CONTACT,
742
743 /**
744 * The hanging up call process.
745 */
746 PJSUA_IP_CHANGE_OP_ACC_HANGUP_CALLS,
747
748 /**
749 * The re-INVITE call process.
750 */
751 PJSUA_IP_CHANGE_OP_ACC_REINVITE_CALLS
752
753} pjsua_ip_change_op;
754
755
756/**
757 * This will contain the information of the callback \a on_ip_change_progress.
758 */
759typedef union pjsua_ip_change_op_info {
760 /**
761 * The information from listener restart operation.
762 */
763 struct {
764 int transport_id;
765 } lis_restart;
766
767 /**
768 * The information from shutdown transport.
769 */
770 struct {
771 int acc_id;
772 } acc_shutdown_tp;
773
774 /**
775 * The information from updating contact.
776 */
777 struct {
778 pjsua_acc_id acc_id;
779 pj_bool_t is_register; /**< SIP Register if PJ_TRUE. */
780 int code; /**< SIP status code received. */
781 } acc_update_contact;
782
783 /**
784 * The information from hanging up call operation.
785 */
786 struct {
787 pjsua_acc_id acc_id;
788 pjsua_call_id call_id;
789 } acc_hangup_calls;
790
791 /**
792 * The information from re-Invite call operation.
793 */
794 struct {
795 pjsua_acc_id acc_id;
796 pjsua_call_id call_id;
797 } acc_reinvite_calls;
798} pjsua_ip_change_op_info;
799
800
801/**
802 * Call settings.
803 */
804typedef struct pjsua_call_setting
805{
806 /**
807 * Bitmask of #pjsua_call_flag constants.
808 *
809 * Default: PJSUA_CALL_INCLUDE_DISABLED_MEDIA
810 */
811 unsigned flag;
812
813 /**
814 * This flag controls what methods to request keyframe are allowed on
815 * the call. Value is bitmask of #pjsua_vid_req_keyframe_method.
816 *
817 * Default: PJSUA_VID_REQ_KEYFRAME_SIP_INFO
818 */
819 unsigned req_keyframe_method;
820
821 /**
822 * Number of simultaneous active audio streams for this call. Setting
823 * this to zero will disable audio in this call.
824 *
825 * Default: 1
826 */
827 unsigned aud_cnt;
828
829 /**
830 * Number of simultaneous active video streams for this call. Setting
831 * this to zero will disable video in this call.
832 *
833 * Default: 1 (if video feature is enabled, otherwise it is zero)
834 */
835 unsigned vid_cnt;
836
837} pjsua_call_setting;
838
839
840/**
841 * This structure describes application callback to receive various event
842 * notification from PJSUA-API. All of these callbacks are OPTIONAL,
843 * although definitely application would want to implement some of
844 * the important callbacks (such as \a on_incoming_call).
845 */
846typedef struct pjsua_callback
847{
848 /**
849 * Notify application when call state has changed.
850 * Application may then query the call info to get the
851 * detail call states by calling pjsua_call_get_info() function.
852 *
853 * @param call_id The call index.
854 * @param e Event which causes the call state to change.
855 */
856 void (*on_call_state)(pjsua_call_id call_id, pjsip_event *e);
857
858 /**
859 * Notify application on incoming call.
860 *
861 * @param acc_id The account which match the incoming call.
862 * @param call_id The call id that has just been created for
863 * the call.
864 * @param rdata The incoming INVITE request.
865 */
866 void (*on_incoming_call)(pjsua_acc_id acc_id, pjsua_call_id call_id,
867 pjsip_rx_data *rdata);
868
869 /**
870 * This is a general notification callback which is called whenever
871 * a transaction within the call has changed state. Application can
872 * implement this callback for example to monitor the state of
873 * outgoing requests, or to answer unhandled incoming requests
874 * (such as INFO) with a final response.
875 *
876 * @param call_id Call identification.
877 * @param tsx The transaction which has changed state.
878 * @param e Transaction event that caused the state change.
879 */
880 void (*on_call_tsx_state)(pjsua_call_id call_id,
881 pjsip_transaction *tsx,
882 pjsip_event *e);
883
884 /**
885 * Notify application when media state in the call has changed.
886 * Normal application would need to implement this callback, e.g.
887 * to connect the call's media to sound device. When ICE is used,
888 * this callback will also be called to report ICE negotiation
889 * failure. When DTLS-SRTP is used, this callback will also be called
890 * to report DTLS negotiation failure.
891 *
892 * @param call_id The call index.
893 */
894 void (*on_call_media_state)(pjsua_call_id call_id);
895
896
897 /**
898 * Notify application when a call has just created a local SDP (for
899 * initial or subsequent SDP offer/answer). Application can implement
900 * this callback to modify the SDP, before it is being sent and/or
901 * negotiated with remote SDP, for example to apply per account/call
902 * basis codecs priority or to add custom/proprietary SDP attributes.
903 *
904 * @param call_id The call index.
905 * @param sdp The SDP has just been created.
906 * @param pool The pool instance, application should use this pool
907 * to modify the SDP.
908 * @param rem_sdp The remote SDP, will be NULL if local is SDP offerer.
909 */
910 void (*on_call_sdp_created)(pjsua_call_id call_id,
911 pjmedia_sdp_session *sdp,
912 pj_pool_t *pool,
913 const pjmedia_sdp_session *rem_sdp);
914
915
916 /**
917 * Notify application when media session is created and before it is
918 * registered to the conference bridge. Application may return different
919 * media port if it has added media processing port to the stream. This
920 * media port then will be added to the conference bridge instead.
921 *
922 * Note: if implemented, #on_stream_created2() callback will be called
923 * instead of this one.
924 *
925 * @param call_id Call identification.
926 * @param strm Media stream.
927 * @param stream_idx Stream index in the media session.
928 * @param p_port On input, it specifies the media port of the
929 * stream. Application may modify this pointer to
930 * point to different media port to be registered
931 * to the conference bridge.
932 */
933 void (*on_stream_created)(pjsua_call_id call_id,
934 pjmedia_stream *strm,
935 unsigned stream_idx,
936 pjmedia_port **p_port);
937
938 /**
939 * Notify application when media session is created and before it is
940 * registered to the conference bridge. Application may return different
941 * media port if it has added media processing port to the stream. This
942 * media port then will be added to the conference bridge instead.
943 *
944 * @param call_id Call identification.
945 * @param param The on stream created callback parameter.
946 */
947 void (*on_stream_created2)(pjsua_call_id call_id,
948 pjsua_on_stream_created_param *param);
949
950 /**
951 * Notify application when media session has been unregistered from the
952 * conference bridge and about to be destroyed.
953 *
954 * @param call_id Call identification.
955 * @param strm Media stream.
956 * @param stream_idx Stream index in the media session.
957 */
958 void (*on_stream_destroyed)(pjsua_call_id call_id,
959 pjmedia_stream *strm,
960 unsigned stream_idx);
961
962 /**
963 * Notify application upon incoming DTMF digits.
964 *
965 * @param call_id The call index.
966 * @param digit DTMF ASCII digit.
967 */
968 void (*on_dtmf_digit)(pjsua_call_id call_id, int digit);
969
970 /**
971 * Notify application on call being transferred (i.e. REFER is received).
972 * Application can decide to accept/reject transfer request
973 * by setting the code (default is 202). When this callback
974 * is not defined, the default behavior is to accept the
975 * transfer. See also on_call_transfer_request2() callback for
976 * the version with \a pjsua_call_setting in the argument list.
977 *
978 * @param call_id The call index.
979 * @param dst The destination where the call will be
980 * transferred to.
981 * @param code Status code to be returned for the call transfer
982 * request. On input, it contains status code 200.
983 */
984 void (*on_call_transfer_request)(pjsua_call_id call_id,
985 const pj_str_t *dst,
986 pjsip_status_code *code);
987
988 /**
989 * Notify application on call being transferred (i.e. REFER is received).
990 * Application can decide to accept/reject transfer request
991 * by setting the code (default is 202). When this callback
992 * is not defined, the default behavior is to accept the
993 * transfer.
994 *
995 * @param call_id The call index.
996 * @param dst The destination where the call will be
997 * transferred to.
998 * @param code Status code to be returned for the call transfer
999 * request. On input, it contains status code 200.
1000 * @param opt The current call setting, application can update
1001 * this setting for the call being transferred.
1002 */
1003 void (*on_call_transfer_request2)(pjsua_call_id call_id,
1004 const pj_str_t *dst,
1005 pjsip_status_code *code,
1006 pjsua_call_setting *opt);
1007
1008 /**
1009 * Notify application of the status of previously sent call
1010 * transfer request. Application can monitor the status of the
1011 * call transfer request, for example to decide whether to
1012 * terminate existing call.
1013 *
1014 * @param call_id Call ID.
1015 * @param st_code Status progress of the transfer request.
1016 * @param st_text Status progress text.
1017 * @param final If non-zero, no further notification will
1018 * be reported. The st_code specified in
1019 * this callback is the final status.
1020 * @param p_cont Initially will be set to non-zero, application
1021 * can set this to FALSE if it no longer wants
1022 * to receie further notification (for example,
1023 * after it hangs up the call).
1024 */
1025 void (*on_call_transfer_status)(pjsua_call_id call_id,
1026 int st_code,
1027 const pj_str_t *st_text,
1028 pj_bool_t final,
1029 pj_bool_t *p_cont);
1030
1031 /**
1032 * Notify application about incoming INVITE with Replaces header.
1033 * Application may reject the request by setting non-2xx code.
1034 * See also on_call_replace_request2() callback for the version
1035 * with \a pjsua_call_setting in the argument list.
1036 *
1037 * @param call_id The call ID to be replaced.
1038 * @param rdata The incoming INVITE request to replace the call.
1039 * @param st_code Status code to be set by application. Application
1040 * should only return a final status (200-699).
1041 * @param st_text Optional status text to be set by application.
1042 */
1043 void (*on_call_replace_request)(pjsua_call_id call_id,
1044 pjsip_rx_data *rdata,
1045 int *st_code,
1046 pj_str_t *st_text);
1047
1048 /**
1049 * Notify application about incoming INVITE with Replaces header.
1050 * Application may reject the request by setting non-2xx code.
1051 *
1052 * @param call_id The call ID to be replaced.
1053 * @param rdata The incoming INVITE request to replace the call.
1054 * @param st_code Status code to be set by application. Application
1055 * should only return a final status (200-699).
1056 * @param st_text Optional status text to be set by application.
1057 * @param opt The current call setting, application can update
1058 * this setting for the call being replaced.
1059 */
1060 void (*on_call_replace_request2)(pjsua_call_id call_id,
1061 pjsip_rx_data *rdata,
1062 int *st_code,
1063 pj_str_t *st_text,
1064 pjsua_call_setting *opt);
1065
1066 /**
1067 * Notify application that an existing call has been replaced with
1068 * a new call. This happens when PJSUA-API receives incoming INVITE
1069 * request with Replaces header.
1070 *
1071 * After this callback is called, normally PJSUA-API will disconnect
1072 * \a old_call_id and establish \a new_call_id.
1073 *
1074 * @param old_call_id Existing call which to be replaced with the
1075 * new call.
1076 * @param new_call_id The new call.
1077 * @param rdata The incoming INVITE with Replaces request.
1078 */
1079 void (*on_call_replaced)(pjsua_call_id old_call_id,
1080 pjsua_call_id new_call_id);
1081
1082
1083 /**
1084 * Notify application when call has received new offer from remote
1085 * (i.e. re-INVITE/UPDATE with SDP is received, or from the
1086 * INVITE response in the case that the initial outgoing INVITE
1087 * has no SDP). Application can
1088 * decide to accept/reject the offer by setting the code (default
1089 * is 200). If the offer is accepted, application can update the
1090 * call setting to be applied in the answer. When this callback is
1091 * not defined, the default behavior is to accept the offer using
1092 * current call setting.
1093 *
1094 * @param call_id The call index.
1095 * @param offer The new offer received.
1096 * @param reserved Reserved param, currently not used.
1097 * @param code Status code to be returned for answering the
1098 * offer. On input, it contains status code 200.
1099 * Currently, valid values are only 200 and 488.
1100 * @param opt The current call setting, application can update
1101 * this setting for answering the offer.
1102 */
1103 void (*on_call_rx_offer)(pjsua_call_id call_id,
1104 const pjmedia_sdp_session *offer,
1105 void *reserved,
1106 pjsip_status_code *code,
1107 pjsua_call_setting *opt);
1108
1109
1110 /**
1111 * Notify application when call has received INVITE with no SDP offer.
1112 * Application can update the call setting (e.g: add audio/video), or
1113 * enable/disable codecs, or update other media session settings from
1114 * within the callback, however, as mandated by the standard (RFC3261
1115 * section 14.2), it must ensure that the update overlaps with the
1116 * existing media session (in codecs, transports, or other parameters)
1117 * that require support from the peer, this is to avoid the need for
1118 * the peer to reject the offer.
1119 *
1120 * When this callback is not defined, the default behavior is to send
1121 * SDP offer using current active media session (with all enabled codecs
1122 * on each media type).
1123 *
1124 * @param call_id The call index.
1125 * @param reserved Reserved param, currently not used.
1126 * @param opt The current call setting, application can update
1127 * this setting for generating the offer.
1128 */
1129 void (*on_call_tx_offer)(pjsua_call_id call_id,
1130 void *reserved,
1131 pjsua_call_setting *opt);
1132
1133
1134 /**
1135 * Notify application when registration or unregistration has been
1136 * initiated. Note that this only notifies the initial registration
1137 * and unregistration. Once registration session is active, subsequent
1138 * refresh will not cause this callback to be called.
1139 *
1140 * @param acc_id The account ID.
1141 * @param renew Non-zero for registration and zero for
1142 * unregistration.
1143 */
1144 void (*on_reg_started)(pjsua_acc_id acc_id, pj_bool_t renew);
1145
1146 /**
1147 * This is the alternative version of the \a on_reg_started() callback with
1148 * \a pjsua_reg_info argument.
1149 *
1150 * @param acc_id The account ID.
1151 * @param info The registration info.
1152 */
1153 void (*on_reg_started2)(pjsua_acc_id acc_id,
1154 pjsua_reg_info *info);
1155
1156 /**
1157 * Notify application when registration status has changed.
1158 * Application may then query the account info to get the
1159 * registration details.
1160 *
1161 * @param acc_id The account ID.
1162 */
1163 void (*on_reg_state)(pjsua_acc_id acc_id);
1164
1165 /**
1166 * Notify application when registration status has changed.
1167 * Application may inspect the registration info to get the
1168 * registration status details.
1169 *
1170 * @param acc_id The account ID.
1171 * @param info The registration info.
1172 */
1173 void (*on_reg_state2)(pjsua_acc_id acc_id, pjsua_reg_info *info);
1174
1175 /**
1176 * Notification when incoming SUBSCRIBE request is received. Application
1177 * may use this callback to authorize the incoming subscribe request
1178 * (e.g. ask user permission if the request should be granted).
1179 *
1180 * If this callback is not implemented, all incoming presence subscription
1181 * requests will be accepted.
1182 *
1183 * If this callback is implemented, application has several choices on
1184 * what to do with the incoming request:
1185 * - it may reject the request immediately by specifying non-200 class
1186 * final response in the \a code argument.
1187 * - it may immediately accept the request by specifying 200 as the
1188 * \a code argument. This is the default value if application doesn't
1189 * set any value to the \a code argument. In this case, the library
1190 * will automatically send NOTIFY request upon returning from this
1191 * callback.
1192 * - it may delay the processing of the request, for example to request
1193 * user permission whether to accept or reject the request. In this
1194 * case, the application MUST set the \a code argument to 202, then
1195 * IMMEDIATELY calls #pjsua_pres_notify() with state
1196 * PJSIP_EVSUB_STATE_PENDING and later calls #pjsua_pres_notify()
1197 * again to accept or reject the subscription request.
1198 *
1199 * Any \a code other than 200 and 202 will be treated as 200.
1200 *
1201 * Application MUST return from this callback immediately (e.g. it must
1202 * not block in this callback while waiting for user confirmation).
1203 *
1204 * @param srv_pres Server presence subscription instance. If
1205 * application delays the acceptance of the request,
1206 * it will need to specify this object when calling
1207 * #pjsua_pres_notify().
1208 * @param acc_id Account ID most appropriate for this request.
1209 * @param buddy_id ID of the buddy matching the sender of the
1210 * request, if any, or PJSUA_INVALID_ID if no
1211 * matching buddy is found.
1212 * @param from The From URI of the request.
1213 * @param rdata The incoming request.
1214 * @param code The status code to respond to the request. The
1215 * default value is 200. Application may set this
1216 * to other final status code to accept or reject
1217 * the request.
1218 * @param reason The reason phrase to respond to the request.
1219 * @param msg_data If the application wants to send additional
1220 * headers in the response, it can put it in this
1221 * parameter.
1222 */
1223 void (*on_incoming_subscribe)(pjsua_acc_id acc_id,
1224 pjsua_srv_pres *srv_pres,
1225 pjsua_buddy_id buddy_id,
1226 const pj_str_t *from,
1227 pjsip_rx_data *rdata,
1228 pjsip_status_code *code,
1229 pj_str_t *reason,
1230 pjsua_msg_data *msg_data);
1231
1232 /**
1233 * Notification when server side subscription state has changed.
1234 * This callback is optional as application normally does not need
1235 * to do anything to maintain server side presence subscription.
1236 *
1237 * @param acc_id The account ID.
1238 * @param srv_pres Server presence subscription object.
1239 * @param remote_uri Remote URI string.
1240 * @param state New subscription state.
1241 * @param event PJSIP event that triggers the state change.
1242 */
1243 void (*on_srv_subscribe_state)(pjsua_acc_id acc_id,
1244 pjsua_srv_pres *srv_pres,
1245 const pj_str_t *remote_uri,
1246 pjsip_evsub_state state,
1247 pjsip_event *event);
1248
1249 /**
1250 * Notify application when the buddy state has changed.
1251 * Application may then query the buddy into to get the details.
1252 *
1253 * @param buddy_id The buddy id.
1254 */
1255 void (*on_buddy_state)(pjsua_buddy_id buddy_id);
1256
1257
1258 /**
1259 * Notify application when the state of client subscription session
1260 * associated with a buddy has changed. Application may use this
1261 * callback to retrieve more detailed information about the state
1262 * changed event.
1263 *
1264 * @param buddy_id The buddy id.
1265 * @param sub Event subscription session.
1266 * @param event The event which triggers state change event.
1267 */
1268 void (*on_buddy_evsub_state)(pjsua_buddy_id buddy_id,
1269 pjsip_evsub *sub,
1270 pjsip_event *event);
1271
1272 /**
1273 * Notify application on incoming pager (i.e. MESSAGE request).
1274 * Argument call_id will be -1 if MESSAGE request is not related to an
1275 * existing call.
1276 *
1277 * See also \a on_pager2() callback for the version with \a pjsip_rx_data
1278 * passed as one of the argument.
1279 *
1280 * @param call_id Containts the ID of the call where the IM was
1281 * sent, or PJSUA_INVALID_ID if the IM was sent
1282 * outside call context.
1283 * @param from URI of the sender.
1284 * @param to URI of the destination message.
1285 * @param contact The Contact URI of the sender, if present.
1286 * @param mime_type MIME type of the message.
1287 * @param body The message content.
1288 */
1289 void (*on_pager)(pjsua_call_id call_id, const pj_str_t *from,
1290 const pj_str_t *to, const pj_str_t *contact,
1291 const pj_str_t *mime_type, const pj_str_t *body);
1292
1293 /**
1294 * This is the alternative version of the \a on_pager() callback with
1295 * \a pjsip_rx_data argument.
1296 *
1297 * @param call_id Containts the ID of the call where the IM was
1298 * sent, or PJSUA_INVALID_ID if the IM was sent
1299 * outside call context.
1300 * @param from URI of the sender.
1301 * @param to URI of the destination message.
1302 * @param contact The Contact URI of the sender, if present.
1303 * @param mime_type MIME type of the message.
1304 * @param body The message content.
1305 * @param rdata The incoming MESSAGE request.
1306 * @param acc_id Account ID most suitable for this message.
1307 */
1308 void (*on_pager2)(pjsua_call_id call_id, const pj_str_t *from,
1309 const pj_str_t *to, const pj_str_t *contact,
1310 const pj_str_t *mime_type, const pj_str_t *body,
1311 pjsip_rx_data *rdata, pjsua_acc_id acc_id);
1312
1313 /**
1314 * Notify application about the delivery status of outgoing pager
1315 * request. See also on_pager_status2() callback for the version with
1316 * \a pjsip_rx_data in the argument list.
1317 *
1318 * @param call_id Containts the ID of the call where the IM was
1319 * sent, or PJSUA_INVALID_ID if the IM was sent
1320 * outside call context.
1321 * @param to Destination URI.
1322 * @param body Message body.
1323 * @param user_data Arbitrary data that was specified when sending
1324 * IM message.
1325 * @param status Delivery status.
1326 * @param reason Delivery status reason.
1327 */
1328 void (*on_pager_status)(pjsua_call_id call_id,
1329 const pj_str_t *to,
1330 const pj_str_t *body,
1331 void *user_data,
1332 pjsip_status_code status,
1333 const pj_str_t *reason);
1334
1335 /**
1336 * Notify application about the delivery status of outgoing pager
1337 * request.
1338 *
1339 * @param call_id Containts the ID of the call where the IM was
1340 * sent, or PJSUA_INVALID_ID if the IM was sent
1341 * outside call context.
1342 * @param to Destination URI.
1343 * @param body Message body.
1344 * @param user_data Arbitrary data that was specified when sending
1345 * IM message.
1346 * @param status Delivery status.
1347 * @param reason Delivery status reason.
1348 * @param tdata The original MESSAGE request.
1349 * @param rdata The incoming MESSAGE response, or NULL if the
1350 * message transaction fails because of time out
1351 * or transport error.
1352 * @param acc_id Account ID from this the instant message was
1353 * send.
1354 */
1355 void (*on_pager_status2)(pjsua_call_id call_id,
1356 const pj_str_t *to,
1357 const pj_str_t *body,
1358 void *user_data,
1359 pjsip_status_code status,
1360 const pj_str_t *reason,
1361 pjsip_tx_data *tdata,
1362 pjsip_rx_data *rdata,
1363 pjsua_acc_id acc_id);
1364
1365 /**
1366 * Notify application about typing indication.
1367 *
1368 * @param call_id Containts the ID of the call where the IM was
1369 * sent, or PJSUA_INVALID_ID if the IM was sent
1370 * outside call context.
1371 * @param from URI of the sender.
1372 * @param to URI of the destination message.
1373 * @param contact The Contact URI of the sender, if present.
1374 * @param is_typing Non-zero if peer is typing, or zero if peer
1375 * has stopped typing a message.
1376 */
1377 void (*on_typing)(pjsua_call_id call_id, const pj_str_t *from,
1378 const pj_str_t *to, const pj_str_t *contact,
1379 pj_bool_t is_typing);
1380
1381 /**
1382 * Notify application about typing indication.
1383 *
1384 * @param call_id Containts the ID of the call where the IM was
1385 * sent, or PJSUA_INVALID_ID if the IM was sent
1386 * outside call context.
1387 * @param from URI of the sender.
1388 * @param to URI of the destination message.
1389 * @param contact The Contact URI of the sender, if present.
1390 * @param is_typing Non-zero if peer is typing, or zero if peer
1391 * has stopped typing a message.
1392 * @param rdata The received request.
1393 * @param acc_id Account ID most suitable for this message.
1394 */
1395 void (*on_typing2)(pjsua_call_id call_id, const pj_str_t *from,
1396 const pj_str_t *to, const pj_str_t *contact,
1397 pj_bool_t is_typing, pjsip_rx_data *rdata,
1398 pjsua_acc_id acc_id);
1399
1400 /**
1401 * Callback when the library has finished performing NAT type
1402 * detection.
1403 *
1404 * @param res NAT detection result.
1405 */
1406 void (*on_nat_detect)(const pj_stun_nat_detect_result *res);
1407
1408 /**
1409 * This callback is called when the call is about to resend the
1410 * INVITE request to the specified target, following the previously
1411 * received redirection response.
1412 *
1413 * Application may accept the redirection to the specified target,
1414 * reject this target only and make the session continue to try the next
1415 * target in the list if such target exists, stop the whole
1416 * redirection process altogether and cause the session to be
1417 * disconnected, or defer the decision to ask for user confirmation.
1418 *
1419 * This callback is optional. If this callback is not implemented,
1420 * the default behavior is to NOT follow the redirection response.
1421 *
1422 * @param call_id The call ID.
1423 * @param target The current target to be tried.
1424 * @param e The event that caused this callback to be called.
1425 * This could be the receipt of 3xx response, or
1426 * 4xx/5xx response received for the INVITE sent to
1427 * subsequent targets, or NULL if this callback is
1428 * called from within #pjsua_call_process_redirect()
1429 * context.
1430 *
1431 * @return Action to be performed for the target. Set this
1432 * parameter to one of the value below:
1433 * - PJSIP_REDIRECT_ACCEPT: immediately accept the
1434 * redirection. When set, the call will immediately
1435 * resend INVITE request to the target.
1436 * - PJSIP_REDIRECT_ACCEPT_REPLACE: immediately accept
1437 * the redirection and replace the To header with the
1438 * current target. When set, the call will immediately
1439 * resend INVITE request to the target.
1440 * - PJSIP_REDIRECT_REJECT: immediately reject this
1441 * target. The call will continue retrying with
1442 * next target if present, or disconnect the call
1443 * if there is no more target to try.
1444 * - PJSIP_REDIRECT_STOP: stop the whole redirection
1445 * process and immediately disconnect the call. The
1446 * on_call_state() callback will be called with
1447 * PJSIP_INV_STATE_DISCONNECTED state immediately
1448 * after this callback returns.
1449 * - PJSIP_REDIRECT_PENDING: set to this value if
1450 * no decision can be made immediately (for example
1451 * to request confirmation from user). Application
1452 * then MUST call #pjsua_call_process_redirect()
1453 * to either accept or reject the redirection upon
1454 * getting user decision.
1455 */
1456 pjsip_redirect_op (*on_call_redirected)(pjsua_call_id call_id,
1457 const pjsip_uri *target,
1458 const pjsip_event *e);
1459
1460 /**
1461 * This callback is called when message waiting indication subscription
1462 * state has changed. Application can then query the subscription state
1463 * by calling #pjsip_evsub_get_state().
1464 *
1465 * @param acc_id The account ID.
1466 * @param evsub The subscription instance.
1467 */
1468 void (*on_mwi_state)(pjsua_acc_id acc_id, pjsip_evsub *evsub);
1469
1470 /**
1471 * This callback is called when a NOTIFY request for message summary /
1472 * message waiting indication is received.
1473 *
1474 * @param acc_id The account ID.
1475 * @param mwi_info Structure containing details of the event,
1476 * including the received NOTIFY request in the
1477 * \a rdata field.
1478 */
1479 void (*on_mwi_info)(pjsua_acc_id acc_id, pjsua_mwi_info *mwi_info);
1480
1481 /**
1482 * This callback is called when transport state is changed. See also
1483 * #pjsip_tp_state_callback.
1484 */
1485 pjsip_tp_state_callback on_transport_state;
1486
1487 /**
1488 * This callback is called when media transport state is changed. See
1489 * also #pjsua_med_tp_state_cb.
1490 */
1491 pjsua_med_tp_state_cb on_call_media_transport_state;
1492
1493 /**
1494 * This callback is called to report error in ICE media transport.
1495 * Currently it is used to report TURN Refresh error.
1496 *
1497 * @param index Transport index.
1498 * @param op Operation which trigger the failure.
1499 * @param status Error status.
1500 * @param param Additional info about the event. Currently this will
1501 * always be set to NULL.
1502 */
1503 void (*on_ice_transport_error)(int index, pj_ice_strans_op op,
1504 pj_status_t status, void *param);
1505
1506 /**
1507 * Callback when the sound device is about to be opened or closed.
1508 * This callback will be called even when null sound device or no
1509 * sound device is configured by the application (i.e. the
1510 * #pjsua_set_null_snd_dev() and #pjsua_set_no_snd_dev() APIs).
1511 * Application can use the API #pjsua_get_snd_dev() to get the info
1512 * about which sound device is going to be opened/closed.
1513 *
1514 * This callback is mostly useful when the application wants to manage
1515 * the sound device by itself (i.e. with #pjsua_set_no_snd_dev()),
1516 * to get notified when it should open or close the sound device.
1517 *
1518 * @param operation The value will be set to 0 to signal that sound
1519 * device is about to be closed, and 1 to be opened.
1520 *
1521 * @return The callback must return PJ_SUCCESS at the moment.
1522 */
1523 pj_status_t (*on_snd_dev_operation)(int operation);
1524
1525 /**
1526 * Notification about media events such as video notifications. This
1527 * callback will most likely be called from media threads, thus
1528 * application must not perform heavy processing in this callback.
1529 * Especially, application must not destroy the call or media in this
1530 * callback. If application needs to perform more complex tasks to
1531 * handle the event, it should post the task to another thread.
1532 *
1533 * @param call_id The call id.
1534 * @param med_idx The media stream index.
1535 * @param event The media event.
1536 */
1537 void (*on_call_media_event)(pjsua_call_id call_id,
1538 unsigned med_idx,
1539 pjmedia_event *event);
1540
1541 /**
1542 * This callback can be used by application to implement custom media
1543 * transport adapter for the call, or to replace the media transport
1544 * with something completely new altogether.
1545 *
1546 * This callback is called when a new call is created. The library has
1547 * created a media transport for the call, and it is provided as the
1548 * \a base_tp argument of this callback. Upon returning, the callback
1549 * must return an instance of media transport to be used by the call.
1550 *
1551 * @param call_id Call ID
1552 * @param media_idx The media index in the SDP for which this media
1553 * transport will be used.
1554 * @param base_tp The media transport which otherwise will be
1555 * used by the call has this callback not been
1556 * implemented.
1557 * @param flags Bitmask from pjsua_create_media_transport_flag.
1558 *
1559 * @return The callback must return an instance of media
1560 * transport to be used by the call.
1561 */
1562 pjmedia_transport* (*on_create_media_transport)(pjsua_call_id call_id,
1563 unsigned media_idx,
1564 pjmedia_transport *base_tp,
1565 unsigned flags);
1566
1567 /**
1568 * Warning: deprecated and may be removed in future release. Application
1569 * can set SRTP crypto settings (including keys) and keying methods
1570 * via pjsua_srtp_opt in pjsua_config and pjsua_acc_config.
1571 * See also ticket #2100.
1572 *
1573 * This callback is called before SRTP media transport is created.
1574 * Application can modify the SRTP setting \a srtp_opt to specify
1575 * the cryptos & keys and keying methods which are going to be used.
1576 * Note that only some fields of pjmedia_srtp_setting can be overriden
1577 * from this callback, i.e: "crypto_count", "crypto", "keying_count",
1578 * "keying", and "use" (only for initial INVITE), any modification in
1579 * other fields will be ignored.
1580 *
1581 * @param call_id Call ID
1582 * @param media_idx The media index in the SDP for which this SRTP
1583 * media transport will be used.
1584 * @param srtp_opt The SRTP setting. Application can modify this.
1585 */
1586 void (*on_create_media_transport_srtp)(pjsua_call_id call_id,
1587 unsigned media_idx,
1588 pjmedia_srtp_setting *srtp_opt);
1589
1590 /**
1591 * This callback can be used by application to override the account
1592 * to be used to handle an incoming message. Initially, the account to
1593 * be used will be calculated automatically by the library. This initial
1594 * account will be used if application does not implement this callback,
1595 * or application sets an invalid account upon returning from this
1596 * callback.
1597 *
1598 * Note that currently the incoming messages requiring account assignment
1599 * are INVITE, MESSAGE, SUBSCRIBE, and unsolicited NOTIFY. This callback
1600 * may be called before the callback of the SIP event itself, i.e:
1601 * incoming call, pager, subscription, or unsolicited-event.
1602 *
1603 * @param rdata The incoming message.
1604 * @param acc_id On input, initial account ID calculated automatically
1605 * by the library. On output, the account ID prefered
1606 * by application to handle the incoming message.
1607 */
1608 void (*on_acc_find_for_incoming)(const pjsip_rx_data *rdata,
1609 pjsua_acc_id* acc_id);
1610
1611 /**
1612 * Calling #pjsua_init() will initiate an async process to resolve and
1613 * contact each of the STUN server entries to find which is usable.
1614 * This callback is called when the process is complete, and can be
1615 * used by the application to start creating and registering accounts.
1616 * This way, the accounts can avoid call setup delay caused by pending
1617 * STUN resolution.
1618 *
1619 * See also #pj_stun_resolve_cb.
1620 */
1621 pj_stun_resolve_cb on_stun_resolution_complete;
1622
1623 /**
1624 * Calling #pjsua_handle_ip_change() may involve different operation. This
1625 * callback is called to report the progress of each enabled operation.
1626 *
1627 * @param op The operation.
1628 * @param status The status of operation.
1629 * @param info The info from the operation
1630 *
1631 */
1632 void (*on_ip_change_progress)(pjsua_ip_change_op op,
1633 pj_status_t status,
1634 const pjsua_ip_change_op_info *info);
1635
1636} pjsua_callback;
1637
1638
1639/**
1640 * This enumeration specifies the usage of SIP Session Timers extension.
1641 */
1642typedef enum pjsua_sip_timer_use
1643{
1644 /**
1645 * When this flag is specified, Session Timers will not be used in any
1646 * session, except it is explicitly required in the remote request.
1647 */
1648 PJSUA_SIP_TIMER_INACTIVE,
1649
1650 /**
1651 * When this flag is specified, Session Timers will be used in all
1652 * sessions whenever remote supports and uses it.
1653 */
1654 PJSUA_SIP_TIMER_OPTIONAL,
1655
1656 /**
1657 * When this flag is specified, Session Timers support will be
1658 * a requirement for the remote to be able to establish a session.
1659 */
1660 PJSUA_SIP_TIMER_REQUIRED,
1661
1662 /**
1663 * When this flag is specified, Session Timers will always be used
1664 * in all sessions, regardless whether remote supports/uses it or not.
1665 */
1666 PJSUA_SIP_TIMER_ALWAYS
1667
1668} pjsua_sip_timer_use;
1669
1670
1671/**
1672 * This constants controls the use of 100rel extension.
1673 */
1674typedef enum pjsua_100rel_use
1675{
1676 /**
1677 * Not used. For UAC, support for 100rel will be indicated in Supported
1678 * header so that peer can opt to use it if it wants to. As UAS, this
1679 * option will NOT cause 100rel to be used even if UAC indicates that
1680 * it supports this feature.
1681 */
1682 PJSUA_100REL_NOT_USED,
1683
1684 /**
1685 * Mandatory. UAC will place 100rel in Require header, and UAS will
1686 * reject incoming calls unless it has 100rel in Supported header.
1687 */
1688 PJSUA_100REL_MANDATORY,
1689
1690 /**
1691 * Optional. Similar to PJSUA_100REL_NOT_USED, except that as UAS, this
1692 * option will cause 100rel to be used if UAC indicates that it supports it.
1693 */
1694 PJSUA_100REL_OPTIONAL
1695
1696} pjsua_100rel_use;
1697
1698
1699/**
1700 * This structure describes the settings to control the API and
1701 * user agent behavior, and can be specified when calling #pjsua_init().
1702 * Before setting the values, application must call #pjsua_config_default()
1703 * to initialize this structure with the default values.
1704 */
1705typedef struct pjsua_config
1706{
1707
1708 /**
1709 * Maximum calls to support (default: 4). The value specified here
1710 * must be smaller than the compile time maximum settings
1711 * PJSUA_MAX_CALLS, which by default is 32. To increase this
1712 * limit, the library must be recompiled with new PJSUA_MAX_CALLS
1713 * value.
1714 */
1715 unsigned max_calls;
1716
1717 /**
1718 * Number of worker threads. Normally application will want to have at
1719 * least one worker thread, unless when it wants to poll the library
1720 * periodically, which in this case the worker thread can be set to
1721 * zero.
1722 */
1723 unsigned thread_cnt;
1724
1725 /**
1726 * Number of nameservers. If no name server is configured, the SIP SRV
1727 * resolution would be disabled, and domain will be resolved with
1728 * standard pj_gethostbyname() function.
1729 */
1730 unsigned nameserver_count;
1731
1732 /**
1733 * Array of nameservers to be used by the SIP resolver subsystem.
1734 * The order of the name server specifies the priority (first name
1735 * server will be used first, unless it is not reachable).
1736 */
1737 pj_str_t nameserver[4];
1738
1739 /**
1740 * Force loose-route to be used in all route/proxy URIs (outbound_proxy
1741 * and account's proxy settings). When this setting is enabled, the
1742 * library will check all the route/proxy URIs specified in the settings
1743 * and append ";lr" parameter to the URI if the parameter is not present.
1744 *
1745 * Default: 1
1746 */
1747 pj_bool_t force_lr;
1748
1749 /**
1750 * Number of outbound proxies in the \a outbound_proxy array.
1751 */
1752 unsigned outbound_proxy_cnt;
1753
1754 /**
1755 * Specify the URL of outbound proxies to visit for all outgoing requests.
1756 * The outbound proxies will be used for all accounts, and it will
1757 * be used to build the route set for outgoing requests. The final
1758 * route set for outgoing requests will consists of the outbound proxies
1759 * and the proxy configured in the account.
1760 */
1761 pj_str_t outbound_proxy[4];
1762
1763 /**
1764 * Warning: deprecated, please use \a stun_srv field instead. To maintain
1765 * backward compatibility, if \a stun_srv_cnt is zero then the value of
1766 * this field will be copied to \a stun_srv field, if present.
1767 *
1768 * Specify domain name to be resolved with DNS SRV resolution to get the
1769 * address of the STUN server. Alternatively application may specify
1770 * \a stun_host instead.
1771 *
1772 * If DNS SRV resolution failed for this domain, then DNS A resolution
1773 * will be performed only if \a stun_host is specified.
1774 */
1775 pj_str_t stun_domain;
1776
1777 /**
1778 * Warning: deprecated, please use \a stun_srv field instead. To maintain
1779 * backward compatibility, if \a stun_srv_cnt is zero then the value of
1780 * this field will be copied to \a stun_srv field, if present.
1781 *
1782 * Specify STUN server to be used, in "HOST[:PORT]" format. If port is
1783 * not specified, default port 3478 will be used.
1784 */
1785 pj_str_t stun_host;
1786
1787 /**
1788 * Number of STUN server entries in \a stun_srv array.
1789 */
1790 unsigned stun_srv_cnt;
1791
1792 /**
1793 * Array of STUN servers to try. The library will try to resolve and
1794 * contact each of the STUN server entry until it finds one that is
1795 * usable. Each entry may be a domain name, host name, IP address, and
1796 * it may contain an optional port number. For example:
1797 * - "pjsip.org" (domain name)
1798 * - "sip.pjsip.org" (host name)
1799 * - "pjsip.org:33478" (domain name and a non-standard port number)
1800 * - "10.0.0.1:3478" (IP address and port number)
1801 *
1802 * When nameserver is configured in the \a pjsua_config.nameserver field,
1803 * if entry is not an IP address, it will be resolved with DNS SRV
1804 * resolution first, and it will fallback to use DNS A resolution if this
1805 * fails. Port number may be specified even if the entry is a domain name,
1806 * in case the DNS SRV resolution should fallback to a non-standard port.
1807 *
1808 * When nameserver is not configured, entries will be resolved with
1809 * #pj_gethostbyname() if it's not an IP address. Port number may be
1810 * specified if the server is not listening in standard STUN port.
1811 */
1812 pj_str_t stun_srv[8];
1813
1814 /**
1815 * This specifies if the library should try to do an IPv6 resolution of
1816 * the STUN servers if the IPv4 resolution fails. It can be useful
1817 * in an IPv6-only environment, including on NAT64.
1818 *
1819 * Default: PJ_FALSE
1820 */
1821 pj_bool_t stun_try_ipv6;
1822
1823 /**
1824 * This specifies if the library should ignore failure with the
1825 * STUN servers. If this is set to PJ_FALSE, the library will refuse to
1826 * start if it fails to resolve or contact any of the STUN servers.
1827 *
1828 * This setting will also determine what happens if STUN servers are
1829 * unavailable during runtime (if set to PJ_FALSE, calls will
1830 * directly fail, otherwise (if PJ_TRUE) call medias will
1831 * fallback to proceed as though not using STUN servers.
1832 *
1833 * Default: PJ_TRUE
1834 */
1835 pj_bool_t stun_ignore_failure;
1836
1837 /**
1838 * This specifies whether STUN requests for resolving socket mapped
1839 * address should use the new format, i.e: having STUN magic cookie
1840 * in its transaction ID.
1841 *
1842 * Default: PJ_FALSE
1843 */
1844 pj_bool_t stun_map_use_stun2;
1845
1846 /**
1847 * Support for adding and parsing NAT type in the SDP to assist
1848 * troubleshooting. The valid values are:
1849 * - 0: no information will be added in SDP, and parsing is disabled.
1850 * - 1: only the NAT type number is added.
1851 * - 2: add both NAT type number and name.
1852 *
1853 * Default: 1
1854 */
1855 int nat_type_in_sdp;
1856
1857 /**
1858 * Specify how the support for reliable provisional response (100rel/
1859 * PRACK) should be used by default. Note that this setting can be
1860 * further customized in account configuration (#pjsua_acc_config).
1861 *
1862 * Default: PJSUA_100REL_NOT_USED
1863 */
1864 pjsua_100rel_use require_100rel;
1865
1866 /**
1867 * Specify the usage of Session Timers for all sessions. See the
1868 * #pjsua_sip_timer_use for possible values. Note that this setting can be
1869 * further customized in account configuration (#pjsua_acc_config).
1870 *
1871 * Default: PJSUA_SIP_TIMER_OPTIONAL
1872 */
1873 pjsua_sip_timer_use use_timer;
1874
1875 /**
1876 * Handle unsolicited NOTIFY requests containing message waiting
1877 * indication (MWI) info. Unsolicited MWI is incoming NOTIFY requests
1878 * which are not requested by client with SUBSCRIBE request.
1879 *
1880 * If this is enabled, the library will respond 200/OK to the NOTIFY
1881 * request and forward the request to \a on_mwi_info() callback.
1882 *
1883 * See also \a mwi_enabled field #on pjsua_acc_config.
1884 *
1885 * Default: PJ_TRUE
1886 *
1887 */
1888 pj_bool_t enable_unsolicited_mwi;
1889
1890 /**
1891 * Specify Session Timer settings, see #pjsip_timer_setting.
1892 * Note that this setting can be further customized in account
1893 * configuration (#pjsua_acc_config).
1894 */
1895 pjsip_timer_setting timer_setting;
1896
1897 /**
1898 * Number of credentials in the credential array.
1899 */
1900 unsigned cred_count;
1901
1902 /**
1903 * Array of credentials. These credentials will be used by all accounts,
1904 * and can be used to authenticate against outbound proxies. If the
1905 * credential is specific to the account, then application should set
1906 * the credential in the pjsua_acc_config rather than the credential
1907 * here.
1908 */
1909 pjsip_cred_info cred_info[PJSUA_ACC_MAX_PROXIES];
1910
1911 /**
1912 * Application callback to receive various event notifications from
1913 * the library.
1914 */
1915 pjsua_callback cb;
1916
1917 /**
1918 * Optional user agent string (default empty). If it's empty, no
1919 * User-Agent header will be sent with outgoing requests.
1920 */
1921 pj_str_t user_agent;
1922
1923 /**
1924 * Specify default value of secure media transport usage.
1925 * Valid values are PJMEDIA_SRTP_DISABLED, PJMEDIA_SRTP_OPTIONAL, and
1926 * PJMEDIA_SRTP_MANDATORY.
1927 *
1928 * Note that this setting can be further customized in account
1929 * configuration (#pjsua_acc_config).
1930 *
1931 * Default: #PJSUA_DEFAULT_USE_SRTP
1932 */
1933 pjmedia_srtp_use use_srtp;
1934
1935 /**
1936 * Specify whether SRTP requires secure signaling to be used. This option
1937 * is only used when \a use_srtp option above is non-zero.
1938 *
1939 * Valid values are:
1940 * 0: SRTP does not require secure signaling
1941 * 1: SRTP requires secure transport such as TLS
1942 * 2: SRTP requires secure end-to-end transport (SIPS)
1943 *
1944 * Note that this setting can be further customized in account
1945 * configuration (#pjsua_acc_config).
1946 *
1947 * Default: #PJSUA_DEFAULT_SRTP_SECURE_SIGNALING
1948 */
1949 int srtp_secure_signaling;
1950
1951 /**
1952 * This setting has been deprecated and will be ignored.
1953 */
1954 pj_bool_t srtp_optional_dup_offer;
1955
1956 /**
1957 * Specify SRTP transport setting. Application can initialize it with
1958 * default values using pjsua_srtp_opt_default().
1959 */
1960 pjsua_srtp_opt srtp_opt;
1961
1962 /**
1963 * Disconnect other call legs when more than one 2xx responses for
1964 * outgoing INVITE are received due to forking. Currently the library
1965 * is not able to handle simultaneous forked media, so disconnecting
1966 * the other call legs is necessary.
1967 *
1968 * With this setting enabled, the library will handle only one of the
1969 * connected call leg, and the other connected call legs will be
1970 * disconnected.
1971 *
1972 * Default: PJ_TRUE (only disable this setting for testing purposes).
1973 */
1974 pj_bool_t hangup_forked_call;
1975
1976} pjsua_config;
1977
1978
1979/**
1980 * Flags to be given to pjsua_destroy2()
1981 */
1982typedef enum pjsua_destroy_flag
1983{
1984 /**
1985 * Allow sending outgoing messages (such as unregistration, event
1986 * unpublication, BYEs, unsubscription, etc.), but do not wait for
1987 * responses. This is useful to perform "best effort" clean up
1988 * without delaying the shutdown process waiting for responses.
1989 */
1990 PJSUA_DESTROY_NO_RX_MSG = 1,
1991
1992 /**
1993 * If this flag is set, do not send any outgoing messages at all.
1994 * This flag is useful if application knows that the network which
1995 * the messages are to be sent on is currently down.
1996 */
1997 PJSUA_DESTROY_NO_TX_MSG = 2,
1998
1999 /**
2000 * Do not send or receive messages during destroy. This flag is
2001 * shorthand for PJSUA_DESTROY_NO_RX_MSG + PJSUA_DESTROY_NO_TX_MSG.
2002 */
2003 PJSUA_DESTROY_NO_NETWORK = PJSUA_DESTROY_NO_RX_MSG |
2004 PJSUA_DESTROY_NO_TX_MSG
2005
2006} pjsua_destroy_flag;
2007
2008/**
2009 * Use this function to initialize pjsua config.
2010 *
2011 * @param cfg pjsua config to be initialized.
2012 */
2013PJ_DECL(void) pjsua_config_default(pjsua_config *cfg);
2014
2015
2016/** The implementation has been moved to sip_auth.h */
2017#define pjsip_cred_dup pjsip_cred_info_dup
2018
2019
2020/**
2021 * Duplicate pjsua_config.
2022 *
2023 * @param pool The pool to get memory from.
2024 * @param dst Destination config.
2025 * @param src Source config.
2026 */
2027PJ_DECL(void) pjsua_config_dup(pj_pool_t *pool,
2028 pjsua_config *dst,
2029 const pjsua_config *src);
2030
2031
2032/**
2033 * This structure describes additional information to be sent with
2034 * outgoing SIP message. It can (optionally) be specified for example
2035 * with #pjsua_call_make_call(), #pjsua_call_answer(), #pjsua_call_hangup(),
2036 * #pjsua_call_set_hold(), #pjsua_call_send_im(), and many more.
2037 *
2038 * Application MUST call #pjsua_msg_data_init() to initialize this
2039 * structure before setting its values.
2040 */
2041struct pjsua_msg_data
2042{
2043 /**
2044 * Optional remote target URI (i.e. Target header). If NULL, the target
2045 * will be set to the remote URI (To header). This field is used by
2046 * pjsua_call_make_call(), pjsua_im_send(), pjsua_call_reinvite(),
2047 * pjsua_call_set_hold(), and pjsua_call_update().
2048 */
2049 pj_str_t target_uri;
2050
2051 /**
2052 * Additional message headers as linked list. Application can add
2053 * headers to the list by creating the header, either from the heap/pool
2054 * or from temporary local variable, and add the header using
2055 * linked list operation. See pjsua_app.c for some sample codes.
2056 */
2057 pjsip_hdr hdr_list;
2058
2059 /**
2060 * MIME type of optional message body.
2061 */
2062 pj_str_t content_type;
2063
2064 /**
2065 * Optional message body to be added to the message, only when the
2066 * message doesn't have a body.
2067 */
2068 pj_str_t msg_body;
2069
2070 /**
2071 * Content type of the multipart body. If application wants to send
2072 * multipart message bodies, it puts the parts in \a parts and set
2073 * the content type in \a multipart_ctype. If the message already
2074 * contains a body, the body will be added to the multipart bodies.
2075 */
2076 pjsip_media_type multipart_ctype;
2077
2078 /**
2079 * List of multipart parts. If application wants to send multipart
2080 * message bodies, it puts the parts in \a parts and set the content
2081 * type in \a multipart_ctype. If the message already contains a body,
2082 * the body will be added to the multipart bodies.
2083 */
2084 pjsip_multipart_part multipart_parts;
2085};
2086
2087
2088/**
2089 * Initialize message data.
2090 *
2091 * @param msg_data Message data to be initialized.
2092 */
2093PJ_DECL(void) pjsua_msg_data_init(pjsua_msg_data *msg_data);
2094
2095
2096/**
2097 * Clone message data.
2098 *
2099 * @param pool Pool to allocate memory for the new message data.
2100 * @param rhs Message data to be cloned.
2101 *
2102 * @return The new message data.
2103 */
2104PJ_DECL(pjsua_msg_data*) pjsua_msg_data_clone(pj_pool_t *pool,
2105 const pjsua_msg_data *rhs);
2106
2107
2108/**
2109 * Instantiate pjsua application. Application must call this function before
2110 * calling any other functions, to make sure that the underlying libraries
2111 * are properly initialized. Once this function has returned success,
2112 * application must call pjsua_destroy() before quitting.
2113 *
2114 * @return PJ_SUCCESS on success, or the appropriate error code.
2115 */
2116PJ_DECL(pj_status_t) pjsua_create(void);
2117
2118
2119/** Forward declaration */
2120typedef struct pjsua_media_config pjsua_media_config;
2121
2122
2123/**
2124 * Initialize pjsua with the specified settings. All the settings are
2125 * optional, and the default values will be used when the config is not
2126 * specified.
2127 *
2128 * Note that #pjsua_create() MUST be called before calling this function.
2129 *
2130 * @param ua_cfg User agent configuration.
2131 * @param log_cfg Optional logging configuration.
2132 * @param media_cfg Optional media configuration.
2133 *
2134 * @return PJ_SUCCESS on success, or the appropriate error code.
2135 */
2136PJ_DECL(pj_status_t) pjsua_init(const pjsua_config *ua_cfg,
2137 const pjsua_logging_config *log_cfg,
2138 const pjsua_media_config *media_cfg);
2139
2140
2141/**
2142 * Application is recommended to call this function after all initialization
2143 * is done, so that the library can do additional checking set up
2144 * additional
2145 *
2146 * Application may call this function anytime after #pjsua_init().
2147 *
2148 * @return PJ_SUCCESS on success, or the appropriate error code.
2149 */
2150PJ_DECL(pj_status_t) pjsua_start(void);
2151
2152
2153/**
2154 * Destroy pjsua. Application is recommended to perform graceful shutdown
2155 * before calling this function (such as unregister the account from the SIP
2156 * server, terminate presense subscription, and hangup active calls), however,
2157 * this function will do all of these if it finds there are active sessions
2158 * that need to be terminated. This function will approximately block for
2159 * one second to wait for replies from remote.
2160 *
2161 * Application.may safely call this function more than once if it doesn't
2162 * keep track of it's state.
2163 *
2164 * @see pjsua_destroy2()
2165 *
2166 * @return PJ_SUCCESS on success, or the appropriate error code.
2167 */
2168PJ_DECL(pj_status_t) pjsua_destroy(void);
2169
2170
2171/**
2172 * Retrieve pjsua state.
2173 *
2174 * @return pjsua state.
2175 */
2176PJ_DECL(pjsua_state) pjsua_get_state(void);
2177
2178
2179/**
2180 * Variant of destroy with additional flags.
2181 *
2182 * @param flags Combination of pjsua_destroy_flag enumeration.
2183 *
2184 * @return PJ_SUCCESS on success, or the appropriate error code.
2185 */
2186PJ_DECL(pj_status_t) pjsua_destroy2(unsigned flags);
2187
2188
2189/**
2190 * Poll pjsua for events, and if necessary block the caller thread for
2191 * the specified maximum interval (in miliseconds).
2192 *
2193 * Application doesn't normally need to call this function if it has
2194 * configured worker thread (\a thread_cnt field) in pjsua_config structure,
2195 * because polling then will be done by these worker threads instead.
2196 *
2197 * @param msec_timeout Maximum time to wait, in miliseconds.
2198 *
2199 * @return The number of events that have been handled during the
2200 * poll. Negative value indicates error, and application
2201 * can retrieve the error as (status = -return_value).
2202 */
2203PJ_DECL(int) pjsua_handle_events(unsigned msec_timeout);
2204
2205
2206/**
2207 * Signal all worker threads to quit. This will only wait until internal
2208 * threads are done.
2209 */
2210PJ_DECL(void) pjsua_stop_worker_threads(void);
2211
2212
2213/**
2214 * Create memory pool to be used by the application. Once application
2215 * finished using the pool, it must be released with pj_pool_release().
2216 *
2217 * @param name Optional pool name.
2218 * @param init_size Initial size of the pool.
2219 * @param increment Increment size.
2220 *
2221 * @return The pool, or NULL when there's no memory.
2222 */
2223PJ_DECL(pj_pool_t*) pjsua_pool_create(const char *name, pj_size_t init_size,
2224 pj_size_t increment);
2225
2226
2227/**
2228 * Application can call this function at any time (after pjsua_create(), of
2229 * course) to change logging settings.
2230 *
2231 * @param c Logging configuration.
2232 *
2233 * @return PJ_SUCCESS on success, or the appropriate error code.
2234 */
2235PJ_DECL(pj_status_t) pjsua_reconfigure_logging(const pjsua_logging_config *c);
2236
2237
2238/**
2239 * Internal function to get SIP endpoint instance of pjsua, which is
2240 * needed for example to register module, create transports, etc.
2241 * Only valid after #pjsua_init() is called.
2242 *
2243 * @return SIP endpoint instance.
2244 */
2245PJ_DECL(pjsip_endpoint*) pjsua_get_pjsip_endpt(void);
2246
2247/**
2248 * Internal function to get media endpoint instance.
2249 * Only valid after #pjsua_init() is called.
2250 *
2251 * @return Media endpoint instance.
2252 */
2253PJ_DECL(pjmedia_endpt*) pjsua_get_pjmedia_endpt(void);
2254
2255/**
2256 * Internal function to get PJSUA pool factory.
2257 * Only valid after #pjsua_create() is called.
2258 *
2259 * @return Pool factory currently used by PJSUA.
2260 */
2261PJ_DECL(pj_pool_factory*) pjsua_get_pool_factory(void);
2262
2263
2264
2265/*****************************************************************************
2266 * Utilities.
2267 *
2268 */
2269
2270/**
2271 * This structure is used to represent the result of the STUN server
2272 * resolution and testing, the #pjsua_resolve_stun_servers() function.
2273 * This structure will be passed in #pj_stun_resolve_cb callback.
2274 */
2275struct pj_stun_resolve_result
2276{
2277 /**
2278 * Arbitrary data that was passed to #pjsua_resolve_stun_servers()
2279 * function.
2280 */
2281 void *token;
2282
2283 /**
2284 * This will contain PJ_SUCCESS if at least one usable STUN server
2285 * is found, otherwise it will contain the last error code during
2286 * the operation.
2287 */
2288 pj_status_t status;
2289
2290 /**
2291 * The server name that yields successful result. This will only
2292 * contain value if status is successful.
2293 */
2294 pj_str_t name;
2295
2296 /**
2297 * The server IP address. This will only contain value if status
2298 * is successful.
2299 */
2300 pj_sockaddr addr;
2301
2302 /**
2303 * The index of the usable STUN server.
2304 */
2305 unsigned index;
2306};
2307
2308
2309/**
2310 * This structure describe the parameter passed to #pjsua_handle_ip_change().
2311 */
2312typedef struct pjsua_ip_change_param
2313{
2314 /**
2315 * If set to PJ_TRUE, this will restart the transport listener.
2316 *
2317 * Default : PJ_TRUE
2318 */
2319 pj_bool_t restart_listener;
2320
2321 /**
2322 * If \a restart listener is set to PJ_TRUE, some delay might be needed
2323 * for the listener to be restarted. Use this to set the delay.
2324 *
2325 * Default : PJSUA_TRANSPORT_RESTART_DELAY_TIME
2326 */
2327 unsigned restart_lis_delay;
2328
2329} pjsua_ip_change_param;
2330
2331
2332/**
2333 * This structure describe the account config specific to IP address change.
2334 */
2335typedef struct pjsua_ip_change_acc_cfg
2336{
2337 /**
2338 * Shutdown the transport used for account registration. If this is set to
2339 * PJ_TRUE, the transport will be shutdown altough it's used by multiple
2340 * account. Shutdown transport will be followed by re-Registration if
2341 * pjsua_acc_config.allow_contact_rewrite is enabled.
2342 *
2343 * Default: PJ_TRUE
2344 */
2345 pj_bool_t shutdown_tp;
2346
2347 /**
2348 * Hangup active calls associated with the account. If this is set to
2349 * PJ_TRUE, then the calls will be hang up.
2350 *
2351 * Default: PJ_FALSE
2352 */
2353 pj_bool_t hangup_calls;
2354
2355 /**
2356 * Specify the call flags used in the re-INVITE when \a hangup_calls is set
2357 * to PJ_FALSE. If this is set to 0, no re-INVITE will be sent. The
2358 * re-INVITE will be sent after re-Registration is finished.
2359 *
2360 * Default: PJSUA_CALL_REINIT_MEDIA | PJSUA_CALL_UPDATE_CONTACT |
2361 * PJSUA_CALL_UPDATE_VIA
2362 */
2363 unsigned reinvite_flags;
2364
2365} pjsua_ip_change_acc_cfg;
2366
2367
2368/**
2369 * Call this function to initialize \a pjsua_ip_change_param with default
2370 * values.
2371 *
2372 * @param param The IP change param to be initialized.
2373 */
2374PJ_DECL(void) pjsua_ip_change_param_default(pjsua_ip_change_param *param);
2375
2376
2377/**
2378 * This is a utility function to detect NAT type in front of this
2379 * endpoint. Once invoked successfully, this function will complete
2380 * asynchronously and report the result in \a on_nat_detect() callback
2381 * of pjsua_callback.
2382 *
2383 * After NAT has been detected and the callback is called, application can
2384 * get the detected NAT type by calling #pjsua_get_nat_type(). Application
2385 * can also perform NAT detection by calling #pjsua_detect_nat_type()
2386 * again at later time.
2387 *
2388 * Note that STUN must be enabled to run this function successfully.
2389 *
2390 * @return PJ_SUCCESS on success, or the appropriate error code.
2391 */
2392PJ_DECL(pj_status_t) pjsua_detect_nat_type(void);
2393
2394
2395/**
2396 * Get the NAT type as detected by #pjsua_detect_nat_type() function.
2397 * This function will only return useful NAT type after #pjsua_detect_nat_type()
2398 * has completed successfully and \a on_nat_detect() callback has been called.
2399 *
2400 * @param type NAT type.
2401 *
2402 * @return When detection is in progress, this function will
2403 * return PJ_EPENDING and \a type will be set to
2404 * PJ_STUN_NAT_TYPE_UNKNOWN. After NAT type has been
2405 * detected successfully, this function will return
2406 * PJ_SUCCESS and \a type will be set to the correct
2407 * value. Other return values indicate error and
2408 * \a type will be set to PJ_STUN_NAT_TYPE_ERR_UNKNOWN.
2409 *
2410 * @see pjsua_call_get_rem_nat_type()
2411 */
2412PJ_DECL(pj_status_t) pjsua_get_nat_type(pj_stun_nat_type *type);
2413
2414
2415/**
2416 * Update the STUN servers list. The #pjsua_init() must have been called
2417 * before calling this function.
2418 *
2419 * @param count Number of STUN server entries.
2420 * @param srv Array of STUN server entries to try. Please see
2421 * the \a stun_srv field in the #pjsua_config
2422 * documentation about the format of this entry.
2423 * @param wait Specify non-zero to make the function block until
2424 * it gets the result. In this case, the function
2425 * will block while the resolution is being done,
2426 * and the callback will be called before this function
2427 * returns.
2428 *
2429 * @return If \a wait parameter is non-zero, this will return
2430 * PJ_SUCCESS if one usable STUN server is found.
2431 * Otherwise it will always return PJ_SUCCESS, and
2432 * application will be notified about the result in
2433 * the callback #on_stun_resolution_complete.
2434 */
2435PJ_DECL(pj_status_t) pjsua_update_stun_servers(unsigned count, pj_str_t srv[],
2436 pj_bool_t wait);
2437
2438
2439/**
2440 * Auxiliary function to resolve and contact each of the STUN server
2441 * entries (sequentially) to find which is usable. The #pjsua_init() must
2442 * have been called before calling this function.
2443 *
2444 * @param count Number of STUN server entries to try.
2445 * @param srv Array of STUN server entries to try. Please see
2446 * the \a stun_srv field in the #pjsua_config
2447 * documentation about the format of this entry.
2448 * @param wait Specify non-zero to make the function block until
2449 * it gets the result. In this case, the function
2450 * will block while the resolution is being done,
2451 * and the callback will be called before this function
2452 * returns.
2453 * @param token Arbitrary token to be passed back to application
2454 * in the callback.
2455 * @param cb Callback to be called to notify the result of
2456 * the function.
2457 *
2458 * @return If \a wait parameter is non-zero, this will return
2459 * PJ_SUCCESS if one usable STUN server is found.
2460 * Otherwise it will always return PJ_SUCCESS, and
2461 * application will be notified about the result in
2462 * the callback.
2463 */
2464PJ_DECL(pj_status_t) pjsua_resolve_stun_servers(unsigned count,
2465 pj_str_t srv[],
2466 pj_bool_t wait,
2467 void *token,
2468 pj_stun_resolve_cb cb);
2469
2470/**
2471 * Cancel pending STUN resolution which match the specified token.
2472 *
2473 * @param token The token to match. This token was given to
2474 * #pjsua_resolve_stun_servers()
2475 * @param notify_cb Boolean to control whether the callback should
2476 * be called for cancelled resolutions. When the
2477 * callback is called, the status in the result
2478 * will be set as PJ_ECANCELLED.
2479 *
2480 * @return PJ_SUCCESS if there is at least one pending STUN
2481 * resolution cancelled, or PJ_ENOTFOUND if there is
2482 * no matching one, or other error.
2483 */
2484PJ_DECL(pj_status_t) pjsua_cancel_stun_resolution(void *token,
2485 pj_bool_t notify_cb);
2486
2487
2488/**
2489 * This is a utility function to verify that valid SIP url is given. If the
2490 * URL is a valid SIP/SIPS scheme, PJ_SUCCESS will be returned.
2491 *
2492 * @param url The URL, as NULL terminated string.
2493 *
2494 * @return PJ_SUCCESS on success, or the appropriate error code.
2495 *
2496 * @see pjsua_verify_url()
2497 */
2498PJ_DECL(pj_status_t) pjsua_verify_sip_url(const char *url);
2499
2500
2501/**
2502 * This is a utility function to verify that valid URI is given. Unlike
2503 * pjsua_verify_sip_url(), this function will return PJ_SUCCESS if tel: URI
2504 * is given.
2505 *
2506 * @param url The URL, as NULL terminated string.
2507 *
2508 * @return PJ_SUCCESS on success, or the appropriate error code.
2509 *
2510 * @see pjsua_verify_sip_url()
2511 */
2512PJ_DECL(pj_status_t) pjsua_verify_url(const char *url);
2513
2514
2515/**
2516 * Schedule a timer entry. Note that the timer callback may be executed
2517 * by different thread, depending on whether worker thread is enabled or
2518 * not.
2519 *
2520 * @param entry Timer heap entry.
2521 * @param delay The interval to expire.
2522 *
2523 * @return PJ_SUCCESS on success, or the appropriate error code.
2524 *
2525 * @see pjsip_endpt_schedule_timer()
2526 */
2527#if PJ_TIMER_DEBUG
2528#define pjsua_schedule_timer(e,d) pjsua_schedule_timer_dbg(e,d,\
2529 __FILE__,__LINE__)
2530
2531PJ_DECL(pj_status_t) pjsua_schedule_timer_dbg(pj_timer_entry *entry,
2532 const pj_time_val *delay,
2533 const char *src_file,
2534 int src_line);
2535#else
2536PJ_DECL(pj_status_t) pjsua_schedule_timer(pj_timer_entry *entry,
2537 const pj_time_val *delay);
2538#endif
2539
2540/**
2541 * Schedule a callback function to be called after a specified time interval.
2542 * Note that the callback may be executed by different thread, depending on
2543 * whether worker thread is enabled or not.
2544 *
2545 * @param cb The callback function.
2546 * @param user_data The user data.
2547 * @param msec_delay The time interval in msec.
2548 *
2549 * @return PJ_SUCCESS on success, or the appropriate error code.
2550 */
2551#if PJ_TIMER_DEBUG
2552#define pjsua_schedule_timer2(cb,u,d) \
2553 pjsua_schedule_timer2_dbg(cb,u,d,__FILE__,__LINE__)
2554
2555PJ_DECL(pj_status_t) pjsua_schedule_timer2_dbg(void (*cb)(void *user_data),
2556 void *user_data,
2557 unsigned msec_delay,
2558 const char *src_file,
2559 int src_line);
2560#else
2561PJ_DECL(pj_status_t) pjsua_schedule_timer2(void (*cb)(void *user_data),
2562 void *user_data,
2563 unsigned msec_delay);
2564#endif
2565
2566/**
2567 * Cancel the previously scheduled timer.
2568 *
2569 * @param entry Timer heap entry.
2570 *
2571 * @see pjsip_endpt_cancel_timer()
2572 */
2573PJ_DECL(void) pjsua_cancel_timer(pj_timer_entry *entry);
2574
2575
2576/**
2577 * This is a utility function to display error message for the specified
2578 * error code. The error message will be sent to the log.
2579 *
2580 * @param sender The log sender field.
2581 * @param title Message title for the error.
2582 * @param status Status code.
2583 */
2584PJ_DECL(void) pjsua_perror(const char *sender, const char *title,
2585 pj_status_t status);
2586
2587
2588/**
2589 * This is a utility function to dump the stack states to log, using
2590 * verbosity level 3.
2591 *
2592 * @param detail Will print detailed output (such as list of
2593 * SIP transactions) when non-zero.
2594 */
2595PJ_DECL(void) pjsua_dump(pj_bool_t detail);
2596
2597
2598/**
2599 * Inform the stack that IP address change event was detected.
2600 * The stack will:
2601 * 1. Restart the listener (this step is configurable via
2602 * \a pjsua_ip_change_param.restart_listener).
2603 * 2. Shutdown the transport used by account registration (this step is
2604 * configurable via \a pjsua_acc_config.ip_change_cfg.shutdown_tp).
2605 * 3. Update contact URI by sending re-Registration (this step is configurable
2606 * via a\ pjsua_acc_config.allow_contact_rewrite and
2607 * a\ pjsua_acc_config.contact_rewrite_method)
2608 * 4. Hangup active calls (this step is configurable via
2609 * a\ pjsua_acc_config.ip_change_cfg.hangup_calls) or
2610 * continue the call by sending re-INVITE
2611 * (configurable via \a pjsua_acc_config.ip_change_cfg.reinvite_flags).
2612 *
2613 * @param param The IP change parameter, have a look at
2614 * #pjsua_ip_change_param.
2615 *
2616 * @return PJ_SUCCESS on success, other on error.
2617 */
2618PJ_DECL(pj_status_t) pjsua_handle_ip_change(
2619 const pjsua_ip_change_param *param);
2620
2621
2622/**
2623 * @}
2624 */
2625
2626
2627
2628/*****************************************************************************
2629 * TRANSPORT API
2630 */
2631
2632/**
2633 * @defgroup PJSUA_LIB_TRANSPORT PJSUA-API Signaling Transport
2634 * @ingroup PJSUA_LIB
2635 * @brief API for managing SIP transports
2636 * @{
2637 *
2638 * PJSUA-API supports creating multiple transport instances, for example UDP,
2639 * TCP, and TLS transport. SIP transport must be created before adding an
2640 * account.
2641 */
2642
2643
2644/** SIP transport identification.
2645 */
2646typedef int pjsua_transport_id;
2647
2648
2649/**
2650 * Transport configuration for creating transports for both SIP
2651 * and media. Before setting some values to this structure, application
2652 * MUST call #pjsua_transport_config_default() to initialize its
2653 * values with default settings.
2654 */
2655typedef struct pjsua_transport_config
2656{
2657 /**
2658 * UDP port number to bind locally. This setting MUST be specified
2659 * even when default port is desired. If the value is zero, the
2660 * transport will be bound to any available port, and application
2661 * can query the port by querying the transport info.
2662 */
2663 unsigned port;
2664
2665 /**
2666 * Specify the port range for socket binding, relative to the start
2667 * port number specified in \a port. Note that this setting is only
2668 * applicable when the start port number is non zero.
2669 *
2670 * Default value is zero.
2671 */
2672 unsigned port_range;
2673
2674 /**
2675 * Optional address to advertise as the address of this transport.
2676 * Application can specify any address or hostname for this field,
2677 * for example it can point to one of the interface address in the
2678 * system, or it can point to the public address of a NAT router
2679 * where port mappings have been configured for the application.
2680 *
2681 * Note: this option can be used for both UDP and TCP as well!
2682 */
2683 pj_str_t public_addr;
2684
2685 /**
2686 * Optional address where the socket should be bound to. This option
2687 * SHOULD only be used to selectively bind the socket to particular
2688 * interface (instead of 0.0.0.0), and SHOULD NOT be used to set the
2689 * published address of a transport (the public_addr field should be
2690 * used for that purpose).
2691 *
2692 * Note that unlike public_addr field, the address (or hostname) here
2693 * MUST correspond to the actual interface address in the host, since
2694 * this address will be specified as bind() argument.
2695 */
2696 pj_str_t bound_addr;
2697
2698 /**
2699 * This specifies TLS settings for TLS transport. It is only be used
2700 * when this transport config is being used to create a SIP TLS
2701 * transport.
2702 */
2703 pjsip_tls_setting tls_setting;
2704
2705 /**
2706 * QoS traffic type to be set on this transport. When application wants
2707 * to apply QoS tagging to the transport, it's preferable to set this
2708 * field rather than \a qos_param fields since this is more portable.
2709 *
2710 * Default is QoS not set.
2711 */
2712 pj_qos_type qos_type;
2713
2714 /**
2715 * Set the low level QoS parameters to the transport. This is a lower
2716 * level operation than setting the \a qos_type field and may not be
2717 * supported on all platforms.
2718 *
2719 * Default is QoS not set.
2720 */
2721 pj_qos_params qos_params;
2722
2723 /**
2724 * Specify options to be set on the transport.
2725 *
2726 * By default there is no options.
2727 *
2728 */
2729 pj_sockopt_params sockopt_params;
2730
2731} pjsua_transport_config;
2732
2733
2734/**
2735 * Call this function to initialize UDP config with default values.
2736 *
2737 * @param cfg The UDP config to be initialized.
2738 */
2739PJ_DECL(void) pjsua_transport_config_default(pjsua_transport_config *cfg);
2740
2741
2742/**
2743 * Duplicate transport config.
2744 *
2745 * @param pool The pool.
2746 * @param dst The destination config.
2747 * @param src The source config.
2748 */
2749PJ_DECL(void) pjsua_transport_config_dup(pj_pool_t *pool,
2750 pjsua_transport_config *dst,
2751 const pjsua_transport_config *src);
2752
2753
2754/**
2755 * This structure describes transport information returned by
2756 * #pjsua_transport_get_info() function.
2757 */
2758typedef struct pjsua_transport_info
2759{
2760 /**
2761 * PJSUA transport identification.
2762 */
2763 pjsua_transport_id id;
2764
2765 /**
2766 * Transport type.
2767 */
2768 pjsip_transport_type_e type;
2769
2770 /**
2771 * Transport type name.
2772 */
2773 pj_str_t type_name;
2774
2775 /**
2776 * Transport string info/description.
2777 */
2778 pj_str_t info;
2779
2780 /**
2781 * Transport flag (see ##pjsip_transport_flags_e).
2782 */
2783 unsigned flag;
2784
2785 /**
2786 * Local address length.
2787 */
2788 unsigned addr_len;
2789
2790 /**
2791 * Local/bound address.
2792 */
2793 pj_sockaddr local_addr;
2794
2795 /**
2796 * Published address (or transport address name).
2797 */
2798 pjsip_host_port local_name;
2799
2800 /**
2801 * Current number of objects currently referencing this transport.
2802 */
2803 unsigned usage_count;
2804
2805
2806} pjsua_transport_info;
2807
2808
2809/**
2810 * Create and start a new SIP transport according to the specified
2811 * settings.
2812 *
2813 * @param type Transport type.
2814 * @param cfg Transport configuration.
2815 * @param p_id Optional pointer to receive transport ID.
2816 *
2817 * @return PJ_SUCCESS on success, or the appropriate error code.
2818 */
2819PJ_DECL(pj_status_t) pjsua_transport_create(pjsip_transport_type_e type,
2820 const pjsua_transport_config *cfg,
2821 pjsua_transport_id *p_id);
2822
2823/**
2824 * Register transport that has been created by application. This function
2825 * is useful if application wants to implement custom SIP transport and use
2826 * it with pjsua.
2827 *
2828 * @param tp Transport instance.
2829 * @param p_id Optional pointer to receive transport ID.
2830 *
2831 * @return PJ_SUCCESS on success, or the appropriate error code.
2832 */
2833PJ_DECL(pj_status_t) pjsua_transport_register(pjsip_transport *tp,
2834 pjsua_transport_id *p_id);
2835
2836
2837/**
2838 * Register transport factory that has been created by application.
2839 * This function is useful if application wants to implement custom SIP
2840 * transport and use it with pjsua.
2841 *
2842 * @param tf Transport factory instance.
2843 * @param p_id Optional pointer to receive transport ID.
2844 *
2845 * @return PJ_SUCCESS on success, or the appropriate error code.
2846 */
2847PJ_DEF(pj_status_t) pjsua_tpfactory_register( pjsip_tpfactory *tf,
2848 pjsua_transport_id *p_id);
2849
2850/**
2851 * Enumerate all transports currently created in the system. This function
2852 * will return all transport IDs, and application may then call
2853 * #pjsua_transport_get_info() function to retrieve detailed information
2854 * about the transport.
2855 *
2856 * @param id Array to receive transport ids.
2857 * @param count In input, specifies the maximum number of elements.
2858 * On return, it contains the actual number of elements.
2859 *
2860 * @return PJ_SUCCESS on success, or the appropriate error code.
2861 */
2862PJ_DECL(pj_status_t) pjsua_enum_transports( pjsua_transport_id id[],
2863 unsigned *count );
2864
2865
2866/**
2867 * Get information about transports.
2868 *
2869 * @param id Transport ID.
2870 * @param info Pointer to receive transport info.
2871 *
2872 * @return PJ_SUCCESS on success, or the appropriate error code.
2873 */
2874PJ_DECL(pj_status_t) pjsua_transport_get_info(pjsua_transport_id id,
2875 pjsua_transport_info *info);
2876
2877
2878/**
2879 * Disable a transport or re-enable it. By default transport is always
2880 * enabled after it is created. Disabling a transport does not necessarily
2881 * close the socket, it will only discard incoming messages and prevent
2882 * the transport from being used to send outgoing messages.
2883 *
2884 * @param id Transport ID.
2885 * @param enabled Non-zero to enable, zero to disable.
2886 *
2887 * @return PJ_SUCCESS on success, or the appropriate error code.
2888 */
2889PJ_DECL(pj_status_t) pjsua_transport_set_enable(pjsua_transport_id id,
2890 pj_bool_t enabled);
2891
2892
2893/**
2894 * Close the transport. If transport is forcefully closed, it will be
2895 * immediately closed, and any pending transactions that are using the
2896 * transport may not terminate properly (it may even crash). Otherwise,
2897 * the system will wait until all transactions are closed while preventing
2898 * new users from using the transport, and will close the transport when
2899 * it is safe to do so.
2900 *
2901 * @param id Transport ID.
2902 * @param force Non-zero to immediately close the transport. This
2903 * is not recommended!
2904 *
2905 * @return PJ_SUCCESS on success, or the appropriate error code.
2906 */
2907PJ_DECL(pj_status_t) pjsua_transport_close( pjsua_transport_id id,
2908 pj_bool_t force );
2909
2910
2911/**
2912 * Start the listener of the transport. This is useful when listener is not
2913 * automatically started when creating the transport.
2914 *
2915 * @param id Transport ID.
2916 * @param cfg The new transport config used by the listener.
2917 * Only port, public_addr and bound_addr are used at the
2918 * moment.
2919 *
2920 * @return PJ_SUCCESS on success, or the appropriate error code.
2921 */
2922PJ_DECL(pj_status_t) pjsua_transport_lis_start( pjsua_transport_id id,
2923 const pjsua_transport_config *cfg);
2924
2925
2926/**
2927 * @}
2928 */
2929
2930
2931
2932
2933/*****************************************************************************
2934 * ACCOUNT API
2935 */
2936
2937
2938/**
2939 * @defgroup PJSUA_LIB_ACC PJSUA-API Accounts Management
2940 * @ingroup PJSUA_LIB
2941 * @brief PJSUA Accounts management
2942 * @{
2943 *
2944 * PJSUA accounts provide identity (or identities) of the user who is currently
2945 * using the application. In SIP terms, the identity is used as the <b>From</b>
2946 * header in outgoing requests.
2947 *
2948 * PJSUA-API supports creating and managing multiple accounts. The maximum
2949 * number of accounts is limited by a compile time constant
2950 * <tt>PJSUA_MAX_ACC</tt>.
2951 *
2952 * Account may or may not have client registration associated with it.
2953 * An account is also associated with <b>route set</b> and some <b>authentication
2954 * credentials</b>, which are used when sending SIP request messages using the
2955 * account. An account also has presence's <b>online status</b>, which
2956 * will be reported to remote peer when they subscribe to the account's
2957 * presence, or which is published to a presence server if presence
2958 * publication is enabled for the account.
2959 *
2960 * At least one account MUST be created in the application. If no user
2961 * association is required, application can create a userless account by
2962 * calling #pjsua_acc_add_local(). A userless account identifies local endpoint
2963 * instead of a particular user, and it correspond with a particular
2964 * transport instance.
2965 *
2966 * Also one account must be set as the <b>default account</b>, which is used as
2967 * the account to use when PJSUA fails to match a request with any other
2968 * accounts.
2969 *
2970 * When sending outgoing SIP requests (such as making calls or sending
2971 * instant messages), normally PJSUA requires the application to specify
2972 * which account to use for the request. If no account is specified,
2973 * PJSUA may be able to select the account by matching the destination
2974 * domain name, and fall back to default account when no match is found.
2975 */
2976
2977/**
2978 * Maximum accounts.
2979 */
2980#ifndef PJSUA_MAX_ACC
2981# define PJSUA_MAX_ACC 8
2982#endif
2983
2984
2985/**
2986 * Default registration interval.
2987 */
2988#ifndef PJSUA_REG_INTERVAL
2989# define PJSUA_REG_INTERVAL 300
2990#endif
2991
2992
2993/**
2994 * Default maximum time to wait for account unregistration transactions to
2995 * complete during library shutdown sequence.
2996 *
2997 * Default: 4000 (4 seconds)
2998 */
2999#ifndef PJSUA_UNREG_TIMEOUT
3000# define PJSUA_UNREG_TIMEOUT 4000
3001#endif
3002
3003
3004/**
3005 * Default PUBLISH expiration
3006 */
3007#ifndef PJSUA_PUBLISH_EXPIRATION
3008# define PJSUA_PUBLISH_EXPIRATION PJSIP_PUBC_EXPIRATION_NOT_SPECIFIED
3009#endif
3010
3011
3012/**
3013 * Default account priority.
3014 */
3015#ifndef PJSUA_DEFAULT_ACC_PRIORITY
3016# define PJSUA_DEFAULT_ACC_PRIORITY 0
3017#endif
3018
3019
3020/**
3021 * Maximum time to wait for unpublication transaction(s) to complete
3022 * during shutdown process, before sending unregistration. The library
3023 * tries to wait for the unpublication (un-PUBLISH) to complete before
3024 * sending REGISTER request to unregister the account, during library
3025 * shutdown process. If the value is set too short, it is possible that
3026 * the unregistration is sent before unpublication completes, causing
3027 * unpublication request to fail.
3028 *
3029 * Default: 2000 (2 seconds)
3030 */
3031#ifndef PJSUA_UNPUBLISH_MAX_WAIT_TIME_MSEC
3032# define PJSUA_UNPUBLISH_MAX_WAIT_TIME_MSEC 2000
3033#endif
3034
3035
3036/**
3037 * Default auto retry re-registration interval, in seconds. Set to 0
3038 * to disable this. Application can set the timer on per account basis
3039 * by setting the pjsua_acc_config.reg_retry_interval field instead.
3040 *
3041 * Default: 300 (5 minutes)
3042 */
3043#ifndef PJSUA_REG_RETRY_INTERVAL
3044# define PJSUA_REG_RETRY_INTERVAL 300
3045#endif
3046
3047
3048/**
3049 * This macro specifies the default value for \a contact_rewrite_method
3050 * field in pjsua_acc_config. It specifies how Contact update will be
3051 * done with the registration, if \a allow_contact_rewrite is enabled in
3052 * the account config. See \a pjsua_contact_rewrite_method for the options.
3053 *
3054 * Value PJSUA_CONTACT_REWRITE_UNREGISTER(1) is the legacy behavior.
3055 *
3056 * Default value: PJSUA_CONTACT_REWRITE_NO_UNREG(2) |
3057 * PJSUA_CONTACT_REWRITE_ALWAYS_UPDATE(4)
3058 */
3059#ifndef PJSUA_CONTACT_REWRITE_METHOD
3060# define PJSUA_CONTACT_REWRITE_METHOD (PJSUA_CONTACT_REWRITE_NO_UNREG | \
3061 PJSUA_CONTACT_REWRITE_ALWAYS_UPDATE)
3062#endif
3063
3064
3065/**
3066 * Bit value used in pjsua_acc_config.reg_use_proxy field to indicate that
3067 * the global outbound proxy list should be added to the REGISTER request.
3068 */
3069#define PJSUA_REG_USE_OUTBOUND_PROXY 1
3070
3071
3072/**
3073 * Bit value used in pjsua_acc_config.reg_use_proxy field to indicate that
3074 * the account proxy list should be added to the REGISTER request.
3075 */
3076#define PJSUA_REG_USE_ACC_PROXY 2
3077
3078
3079/**
3080 * This enumeration specifies how we should offer call hold request to
3081 * remote peer. The default value is set by compile time constant
3082 * PJSUA_CALL_HOLD_TYPE_DEFAULT, and application may control the setting
3083 * on per-account basis by manipulating \a call_hold_type field in
3084 * #pjsua_acc_config.
3085 */
3086typedef enum pjsua_call_hold_type
3087{
3088 /**
3089 * This will follow RFC 3264 recommendation to use a=sendonly,
3090 * a=recvonly, and a=inactive attribute as means to signal call
3091 * hold status. This is the correct value to use.
3092 */
3093 PJSUA_CALL_HOLD_TYPE_RFC3264,
3094
3095 /**
3096 * This will use the old and deprecated method as specified in RFC 2543,
3097 * and will offer c=0.0.0.0 in the SDP instead. Using this has many
3098 * drawbacks such as inability to keep the media transport alive while
3099 * the call is being put on hold, and should only be used if remote
3100 * does not understand RFC 3264 style call hold offer.
3101 */
3102 PJSUA_CALL_HOLD_TYPE_RFC2543
3103
3104} pjsua_call_hold_type;
3105
3106
3107/**
3108 * Specify the default call hold type to be used in #pjsua_acc_config.
3109 *
3110 * Default is PJSUA_CALL_HOLD_TYPE_RFC3264, and there's no reason to change
3111 * this except if you're communicating with an old/non-standard peer.
3112 */
3113#ifndef PJSUA_CALL_HOLD_TYPE_DEFAULT
3114# define PJSUA_CALL_HOLD_TYPE_DEFAULT PJSUA_CALL_HOLD_TYPE_RFC3264
3115#endif
3116
3117/**
3118 * This enumeration controls the use of STUN in the account.
3119 */
3120typedef enum pjsua_stun_use
3121{
3122 /**
3123 * Follow the default setting in the global \a pjsua_config.
3124 */
3125 PJSUA_STUN_USE_DEFAULT,
3126
3127 /**
3128 * Disable STUN. If STUN is not enabled in the global \a pjsua_config,
3129 * this setting has no effect.
3130 */
3131 PJSUA_STUN_USE_DISABLED,
3132
3133 /**
3134 * Retry other STUN servers if the STUN server selected during
3135 * startup (#pjsua_init()) or after calling #pjsua_update_stun_servers()
3136 * is unavailable during runtime. This setting is valid only for
3137 * account's media STUN setting and if the call is using UDP media
3138 * transport.
3139 */
3140 PJSUA_STUN_RETRY_ON_FAILURE
3141
3142} pjsua_stun_use;
3143
3144/**
3145 * This enumeration controls the use of ICE settings in the account.
3146 */
3147typedef enum pjsua_ice_config_use
3148{
3149 /**
3150 * Use the default settings in the global \a pjsua_media_config.
3151 */
3152 PJSUA_ICE_CONFIG_USE_DEFAULT,
3153
3154 /**
3155 * Use the custom \a pjsua_ice_config setting in the account.
3156 */
3157 PJSUA_ICE_CONFIG_USE_CUSTOM
3158
3159} pjsua_ice_config_use;
3160
3161/**
3162 * This enumeration controls the use of TURN settings in the account.
3163 */
3164typedef enum pjsua_turn_config_use
3165{
3166 /**
3167 * Use the default setting in the global \a pjsua_media_config.
3168 */
3169 PJSUA_TURN_CONFIG_USE_DEFAULT,
3170
3171 /**
3172 * Use the custom \a pjsua_turn_config setting in the account.
3173 */
3174 PJSUA_TURN_CONFIG_USE_CUSTOM
3175
3176} pjsua_turn_config_use;
3177
3178/**
3179 * ICE setting. This setting is used in the pjsua_acc_config.
3180 */
3181typedef struct pjsua_ice_config
3182{
3183 /**
3184 * Enable ICE.
3185 */
3186 pj_bool_t enable_ice;
3187
3188 /**
3189 * Set the maximum number of host candidates.
3190 *
3191 * Default: -1 (maximum not set)
3192 */
3193 int ice_max_host_cands;
3194
3195 /**
3196 * ICE session options.
3197 */
3198 pj_ice_sess_options ice_opt;
3199
3200 /**
3201 * Disable RTCP component.
3202 *
3203 * Default: no
3204 */
3205 pj_bool_t ice_no_rtcp;
3206
3207 /**
3208 * Send re-INVITE/UPDATE every after ICE connectivity check regardless
3209 * the default ICE transport address is changed or not. When this is set
3210 * to PJ_FALSE, re-INVITE/UPDATE will be sent only when the default ICE
3211 * transport address is changed.
3212 *
3213 * Default: yes
3214 */
3215 pj_bool_t ice_always_update;
3216
3217} pjsua_ice_config;
3218
3219/**
3220 * TURN setting. This setting is used in the pjsua_acc_config.
3221 */
3222typedef struct pjsua_turn_config
3223{
3224 /**
3225 * Enable TURN candidate in ICE.
3226 */
3227 pj_bool_t enable_turn;
3228
3229 /**
3230 * Specify TURN domain name or host name, in in "DOMAIN:PORT" or
3231 * "HOST:PORT" format.
3232 */
3233 pj_str_t turn_server;
3234
3235 /**
3236 * Specify the connection type to be used to the TURN server. Valid
3237 * values are PJ_TURN_TP_UDP or PJ_TURN_TP_TCP.
3238 *
3239 * Default: PJ_TURN_TP_UDP
3240 */
3241 pj_turn_tp_type turn_conn_type;
3242
3243 /**
3244 * Specify the credential to authenticate with the TURN server.
3245 */
3246 pj_stun_auth_cred turn_auth_cred;
3247
3248} pjsua_turn_config;
3249
3250/**
3251 * Specify how IPv6 transport should be used in account config.
3252 */
3253typedef enum pjsua_ipv6_use
3254{
3255 /**
3256 * IPv6 is not used.
3257 */
3258 PJSUA_IPV6_DISABLED,
3259
3260 /**
3261 * IPv6 is enabled.
3262 */
3263 PJSUA_IPV6_ENABLED
3264
3265} pjsua_ipv6_use;
3266
3267/**
3268 * Specify NAT64 options to be used in account config.
3269 */
3270typedef enum pjsua_nat64_opt
3271{
3272 /**
3273 * NAT64 is not used.
3274 */
3275 PJSUA_NAT64_DISABLED,
3276
3277 /**
3278 * NAT64 is enabled.
3279 */
3280 PJSUA_NAT64_ENABLED
3281
3282} pjsua_nat64_opt;
3283
3284
3285/**
3286 * This structure describes account configuration to be specified when
3287 * adding a new account with #pjsua_acc_add(). Application MUST initialize
3288 * this structure first by calling #pjsua_acc_config_default().
3289 */
3290typedef struct pjsua_acc_config
3291{
3292 /**
3293 * Arbitrary user data to be associated with the newly created account.
3294 * Application may set this later with #pjsua_acc_set_user_data() and
3295 * retrieve it with #pjsua_acc_get_user_data().
3296 */
3297 void *user_data;
3298
3299 /**
3300 * Account priority, which is used to control the order of matching
3301 * incoming/outgoing requests. The higher the number means the higher
3302 * the priority is, and the account will be matched first.
3303 */
3304 int priority;
3305
3306 /**
3307 * The full SIP URL for the account. The value can take name address or
3308 * URL format, and will look something like "sip:account@serviceprovider"
3309 * or "\"Display Name\" <sip:account@provider>".
3310 *
3311 * This field is mandatory.
3312 */
3313 pj_str_t id;
3314
3315 /**
3316 * This is the URL to be put in the request URI for the registration,
3317 * and will look something like "sip:serviceprovider".
3318 *
3319 * This field should be specified if registration is desired. If the
3320 * value is empty, no account registration will be performed.
3321 */
3322 pj_str_t reg_uri;
3323
3324 /**
3325 * The optional custom SIP headers to be put in the registration
3326 * request.
3327 */
3328 pjsip_hdr reg_hdr_list;
3329
3330 /**
3331 * Additional parameters that will be appended in the Contact header
3332 * for this account. This will only affect REGISTER requests and
3333 * will be appended after \a contact_params;
3334 *
3335 * The parameters should be preceeded by semicolon, and all strings must
3336 * be properly escaped. Example:
3337 * ";my-param=X;another-param=Hi%20there"
3338 */
3339 pj_str_t reg_contact_params;
3340
3341 /**
3342 * The optional custom SIP headers to be put in the presence
3343 * subscription request.
3344 */
3345 pjsip_hdr sub_hdr_list;
3346
3347 /**
3348 * Subscribe to message waiting indication events (RFC 3842).
3349 *
3350 * See also \a enable_unsolicited_mwi field on #pjsua_config.
3351 *
3352 * Default: no
3353 */
3354 pj_bool_t mwi_enabled;
3355
3356 /**
3357 * Specify the default expiration time for Message Waiting Indication
3358 * (RFC 3842) event subscription. This must not be zero.
3359 *
3360 * Default: PJSIP_MWI_DEFAULT_EXPIRES
3361 */
3362 unsigned mwi_expires;
3363
3364 /**
3365 * If this flag is set, the presence information of this account will
3366 * be PUBLISH-ed to the server where the account belongs.
3367 *
3368 * Default: PJ_FALSE
3369 */
3370 pj_bool_t publish_enabled;
3371
3372 /**
3373 * Event publication options.
3374 */
3375 pjsip_publishc_opt publish_opt;
3376
3377 /**
3378 * Maximum time to wait for unpublication transaction(s) to complete
3379 * during shutdown process, before sending unregistration. The library
3380 * tries to wait for the unpublication (un-PUBLISH) to complete before
3381 * sending REGISTER request to unregister the account, during library
3382 * shutdown process. If the value is set too short, it is possible that
3383 * the unregistration is sent before unpublication completes, causing
3384 * unpublication request to fail.
3385 *
3386 * Default: PJSUA_UNPUBLISH_MAX_WAIT_TIME_MSEC
3387 */
3388 unsigned unpublish_max_wait_time_msec;
3389
3390 /**
3391 * Authentication preference.
3392 */
3393 pjsip_auth_clt_pref auth_pref;
3394
3395 /**
3396 * Optional PIDF tuple ID for outgoing PUBLISH and NOTIFY. If this value
3397 * is not specified, a random string will be used.
3398 */
3399 pj_str_t pidf_tuple_id;
3400
3401 /**
3402 * Optional URI to be put as Contact for this account. It is recommended
3403 * that this field is left empty, so that the value will be calculated
3404 * automatically based on the transport address.
3405 */
3406 pj_str_t force_contact;
3407
3408 /**
3409 * Additional parameters that will be appended in the Contact header
3410 * for this account. This will affect the Contact header in all SIP
3411 * messages sent on behalf of this account, including but not limited to
3412 * REGISTER, INVITE, and SUBCRIBE requests or responses.
3413 *
3414 * The parameters should be preceeded by semicolon, and all strings must
3415 * be properly escaped. Example:
3416 * ";my-param=X;another-param=Hi%20there"
3417 */
3418 pj_str_t contact_params;
3419
3420 /**
3421 * Additional URI parameters that will be appended in the Contact URI
3422 * for this account. This will affect the Contact URI in all SIP
3423 * messages sent on behalf of this account, including but not limited to
3424 * REGISTER, INVITE, and SUBCRIBE requests or responses.
3425 *
3426 * The parameters should be preceeded by semicolon, and all strings must
3427 * be properly escaped. Example:
3428 * ";my-param=X;another-param=Hi%20there"
3429 */
3430 pj_str_t contact_uri_params;
3431
3432 /**
3433 * Specify how support for reliable provisional response (100rel/
3434 * PRACK) should be used for all sessions in this account. See the
3435 * documentation of pjsua_100rel_use enumeration for more info.
3436 *
3437 * Default: The default value is taken from the value of
3438 * require_100rel in pjsua_config.
3439 */
3440 pjsua_100rel_use require_100rel;
3441
3442 /**
3443 * Specify the usage of Session Timers for all sessions. See the
3444 * #pjsua_sip_timer_use for possible values.
3445 *
3446 * Default: PJSUA_SIP_TIMER_OPTIONAL
3447 */
3448 pjsua_sip_timer_use use_timer;
3449
3450 /**
3451 * Specify Session Timer settings, see #pjsip_timer_setting.
3452 */
3453 pjsip_timer_setting timer_setting;
3454
3455 /**
3456 * Number of proxies in the proxy array below.
3457 */
3458 unsigned proxy_cnt;
3459
3460 /**
3461 * Optional URI of the proxies to be visited for all outgoing requests
3462 * that are using this account (REGISTER, INVITE, etc). Application need
3463 * to specify these proxies if the service provider requires that requests
3464 * destined towards its network should go through certain proxies first
3465 * (for example, border controllers).
3466 *
3467 * These proxies will be put in the route set for this account, with
3468 * maintaining the orders (the first proxy in the array will be visited
3469 * first). If global outbound proxies are configured in pjsua_config,
3470 * then these account proxies will be placed after the global outbound
3471 * proxies in the routeset.
3472 */
3473 pj_str_t proxy[PJSUA_ACC_MAX_PROXIES];
3474
3475 /**
3476 * If remote sends SDP answer containing more than one format or codec in
3477 * the media line, send re-INVITE or UPDATE with just one codec to lock
3478 * which codec to use.
3479 *
3480 * Default: 1 (Yes). Set to zero to disable.
3481 */
3482 unsigned lock_codec;
3483
3484 /**
3485 * Optional interval for registration, in seconds. If the value is zero,
3486 * default interval will be used (PJSUA_REG_INTERVAL, 300 seconds).
3487 */
3488 unsigned reg_timeout;
3489
3490 /**
3491 * Specify the number of seconds to refresh the client registration
3492 * before the registration expires.
3493 *
3494 * Default: PJSIP_REGISTER_CLIENT_DELAY_BEFORE_REFRESH, 5 seconds
3495 */
3496 unsigned reg_delay_before_refresh;
3497
3498 /**
3499 * Specify the maximum time to wait for unregistration requests to
3500 * complete during library shutdown sequence.
3501 *
3502 * Default: PJSUA_UNREG_TIMEOUT
3503 */
3504 unsigned unreg_timeout;
3505
3506 /**
3507 * Number of credentials in the credential array.
3508 */
3509 unsigned cred_count;
3510
3511 /**
3512 * Array of credentials. If registration is desired, normally there should
3513 * be at least one credential specified, to successfully authenticate
3514 * against the service provider. More credentials can be specified, for
3515 * example when the requests are expected to be challenged by the
3516 * proxies in the route set.
3517 */
3518 pjsip_cred_info cred_info[PJSUA_ACC_MAX_PROXIES];
3519
3520 /**
3521 * Optionally bind this account to specific transport. This normally is
3522 * not a good idea, as account should be able to send requests using
3523 * any available transports according to the destination. But some
3524 * application may want to have explicit control over the transport to
3525 * use, so in that case it can set this field.
3526 *
3527 * Default: -1 (PJSUA_INVALID_ID)
3528 *
3529 * @see pjsua_acc_set_transport()
3530 */
3531 pjsua_transport_id transport_id;
3532
3533 /**
3534 * This option is used to update the transport address and the Contact
3535 * header of REGISTER request. When this option is enabled, the library
3536 * will keep track of the public IP address from the response of REGISTER
3537 * request. Once it detects that the address has changed, it will
3538 * unregister current Contact, update the Contact with transport address
3539 * learned from Via header, and register a new Contact to the registrar.
3540 * This will also update the public name of UDP transport if STUN is
3541 * configured.
3542 *
3543 * See also contact_rewrite_method field.
3544 *
3545 * Default: 1 (yes)
3546 */
3547 pj_bool_t allow_contact_rewrite;
3548
3549 /**
3550 * Specify how Contact update will be done with the registration, if
3551 * \a allow_contact_rewrite is enabled. The value is bitmask combination of
3552 * \a pjsua_contact_rewrite_method. See also pjsua_contact_rewrite_method.
3553 *
3554 * Value PJSUA_CONTACT_REWRITE_UNREGISTER(1) is the legacy behavior.
3555 *
3556 * Default value: PJSUA_CONTACT_REWRITE_METHOD
3557 * (PJSUA_CONTACT_REWRITE_NO_UNREG | PJSUA_CONTACT_REWRITE_ALWAYS_UPDATE)
3558 */
3559 int contact_rewrite_method;
3560
3561 /**
3562 * Specify if source TCP port should be used as the initial Contact
3563 * address if TCP/TLS transport is used. Note that this feature will
3564 * be automatically turned off when nameserver is configured because
3565 * it may yield different destination address due to DNS SRV resolution.
3566 * Also some platforms are unable to report the local address of the
3567 * TCP socket when it is still connecting. In these cases, this
3568 * feature will also be turned off.
3569 *
3570 * Default: PJ_TRUE (yes).
3571 */
3572 pj_bool_t contact_use_src_port;
3573
3574 /**
3575 * This option is used to overwrite the "sent-by" field of the Via header
3576 * for outgoing messages with the same interface address as the one in
3577 * the REGISTER request, as long as the request uses the same transport
3578 * instance as the previous REGISTER request.
3579 *
3580 * Default: 1 (yes)
3581 */
3582 pj_bool_t allow_via_rewrite;
3583
3584 /**
3585 * This option controls whether the IP address in SDP should be replaced
3586 * with the IP address found in Via header of the REGISTER response, ONLY
3587 * when STUN and ICE are not used. If the value is FALSE (the original
3588 * behavior), then the local IP address will be used. If TRUE, and when
3589 * STUN and ICE are disabled, then the IP address found in registration
3590 * response will be used.
3591 *
3592 * Default: PJ_FALSE (no)
3593 */
3594 pj_bool_t allow_sdp_nat_rewrite;
3595
3596 /**
3597 * Control the use of SIP outbound feature. SIP outbound is described in
3598 * RFC 5626 to enable proxies or registrar to send inbound requests back
3599 * to UA using the same connection initiated by the UA for its
3600 * registration. This feature is highly useful in NAT-ed deployemtns,
3601 * hence it is enabled by default.
3602 *
3603 * Note: currently SIP outbound can only be used with TCP and TLS
3604 * transports. If UDP is used for the registration, the SIP outbound
3605 * feature will be silently ignored for the account.
3606 *
3607 * Default: PJ_TRUE
3608 */
3609 unsigned use_rfc5626;
3610
3611 /**
3612 * Specify SIP outbound (RFC 5626) instance ID to be used by this
3613 * application. If empty, an instance ID will be generated based on
3614 * the hostname of this agent. If application specifies this parameter, the
3615 * value will look like "<urn:uuid:00000000-0000-1000-8000-AABBCCDDEEFF>"
3616 * without the doublequote.
3617 *
3618 * Default: empty
3619 */
3620 pj_str_t rfc5626_instance_id;
3621
3622 /**
3623 * Specify SIP outbound (RFC 5626) registration ID. The default value
3624 * is empty, which would cause the library to automatically generate
3625 * a suitable value.
3626 *
3627 * Default: empty
3628 */
3629 pj_str_t rfc5626_reg_id;
3630
3631 /**
3632 * Set the interval for periodic keep-alive transmission for this account.
3633 * If this value is zero, keep-alive will be disabled for this account.
3634 * The keep-alive transmission will be sent to the registrar's address,
3635 * after successful registration.
3636 *
3637 * Default: 15 (seconds)
3638 */
3639 unsigned ka_interval;
3640
3641 /**
3642 * Specify the data to be transmitted as keep-alive packets.
3643 *
3644 * Default: CR-LF
3645 */
3646 pj_str_t ka_data;
3647
3648 /**
3649 * Specify whether incoming video should be shown to screen by default.
3650 * This applies to incoming call (INVITE), incoming re-INVITE, and
3651 * incoming UPDATE requests.
3652 *
3653 * Regardless of this setting, application can detect incoming video
3654 * by implementing \a on_call_media_state() callback and enumerating
3655 * the media stream(s) with #pjsua_call_get_info(). Once incoming
3656 * video is recognised, application may retrieve the window associated
3657 * with the incoming video and show or hide it with
3658 * #pjsua_vid_win_set_show().
3659 *
3660 * Default: PJ_FALSE
3661 */
3662 pj_bool_t vid_in_auto_show;
3663
3664 /**
3665 * Specify whether outgoing video should be activated by default when
3666 * making outgoing calls and/or when incoming video is detected. This
3667 * applies to incoming and outgoing calls, incoming re-INVITE, and
3668 * incoming UPDATE. If the setting is non-zero, outgoing video
3669 * transmission will be started as soon as response to these requests
3670 * is sent (or received).
3671 *
3672 * Regardless of the value of this setting, application can start and
3673 * stop outgoing video transmission with #pjsua_call_set_vid_strm().
3674 *
3675 * Default: PJ_FALSE
3676 */
3677 pj_bool_t vid_out_auto_transmit;
3678
3679 /**
3680 * Specify video window's flags. The value is a bitmask combination of
3681 * #pjmedia_vid_dev_wnd_flag.
3682 *
3683 * Default: 0
3684 */
3685 unsigned vid_wnd_flags;
3686
3687 /**
3688 * Specify the default capture device to be used by this account. If
3689 * \a vid_out_auto_transmit is enabled, this device will be used for
3690 * capturing video.
3691 *
3692 * Default: PJMEDIA_VID_DEFAULT_CAPTURE_DEV
3693 */
3694 pjmedia_vid_dev_index vid_cap_dev;
3695
3696 /**
3697 * Specify the default rendering device to be used by this account.
3698 *
3699 * Default: PJMEDIA_VID_DEFAULT_RENDER_DEV
3700 */
3701 pjmedia_vid_dev_index vid_rend_dev;
3702
3703 /**
3704 * Specify the send rate control for video stream.
3705 *
3706 * Default: see #pjmedia_vid_stream_rc_config
3707 */
3708 pjmedia_vid_stream_rc_config vid_stream_rc_cfg;
3709
3710 /**
3711 * Specify the send keyframe config for video stream.
3712 *
3713 * Default: see #pjmedia_vid_stream_sk_config
3714 */
3715 pjmedia_vid_stream_sk_config vid_stream_sk_cfg;
3716
3717 /**
3718 * Media transport config.
3719 */
3720 pjsua_transport_config rtp_cfg;
3721
3722 /**
3723 * Specify NAT64 options.
3724 *
3725 * Default: PJSUA_NAT64_DISABLED
3726 */
3727 pjsua_nat64_opt nat64_opt;
3728
3729 /**
3730 * Specify whether IPv6 should be used on media.
3731 */
3732 pjsua_ipv6_use ipv6_media_use;
3733
3734 /**
3735 * Control the use of STUN for the SIP signaling.
3736 *
3737 * Default: PJSUA_STUN_USE_DEFAULT
3738 */
3739 pjsua_stun_use sip_stun_use;
3740
3741 /**
3742 * Control the use of STUN for the media transports.
3743 *
3744 * Default: PJSUA_STUN_RETRY_ON_FAILURE
3745 */
3746 pjsua_stun_use media_stun_use;
3747
3748 /**
3749 * Control the use of ICE in the account. By default, the settings in the
3750 * \a pjsua_media_config will be used.
3751 *
3752 * Default: PJSUA_ICE_CONFIG_USE_DEFAULT
3753 */
3754 pjsua_ice_config_use ice_cfg_use;
3755
3756 /**
3757 * The custom ICE setting for this account. This setting will only be
3758 * used if \a ice_cfg_use is set to PJSUA_ICE_CONFIG_USE_CUSTOM
3759 */
3760 pjsua_ice_config ice_cfg;
3761
3762 /**
3763 * Control the use of TURN in the account. By default, the settings in the
3764 * \a pjsua_media_config will be used
3765 *
3766 * Default: PJSUA_TURN_CONFIG_USE_DEFAULT
3767 */
3768 pjsua_turn_config_use turn_cfg_use;
3769
3770 /**
3771 * The custom TURN setting for this account. This setting will only be
3772 * used if \a turn_cfg_use is set to PJSUA_TURN_CONFIG_USE_CUSTOM
3773 */
3774 pjsua_turn_config turn_cfg;
3775
3776 /**
3777 * Specify whether secure media transport should be used for this account.
3778 * Valid values are PJMEDIA_SRTP_DISABLED, PJMEDIA_SRTP_OPTIONAL, and
3779 * PJMEDIA_SRTP_MANDATORY.
3780 *
3781 * Default: #PJSUA_DEFAULT_USE_SRTP
3782 */
3783 pjmedia_srtp_use use_srtp;
3784
3785 /**
3786 * Specify whether SRTP requires secure signaling to be used. This option
3787 * is only used when \a use_srtp option above is non-zero.
3788 *
3789 * Valid values are:
3790 * 0: SRTP does not require secure signaling
3791 * 1: SRTP requires secure transport such as TLS
3792 * 2: SRTP requires secure end-to-end transport (SIPS)
3793 *
3794 * Default: #PJSUA_DEFAULT_SRTP_SECURE_SIGNALING
3795 */
3796 int srtp_secure_signaling;
3797
3798 /**
3799 * This setting has been deprecated and will be ignored.
3800 */
3801 pj_bool_t srtp_optional_dup_offer;
3802
3803 /**
3804 * Specify SRTP transport setting. Application can initialize it with
3805 * default values using pjsua_srtp_opt_default().
3806 */
3807 pjsua_srtp_opt srtp_opt;
3808
3809 /**
3810 * Specify interval of auto registration retry upon registration failure,
3811 * in seconds. Set to 0 to disable auto re-registration. Note that
3812 * registration will only be automatically retried for temporal failures
3813 * considered to be recoverable in relatively short term, such as:
3814 * 408 (Request Timeout), 480 (Temporarily Unavailable),
3815 * 500 (Internal Server Error), 502 (Bad Gateway),
3816 * 503 (Service Unavailable), 504 (Server Timeout),
3817 * 6xx (global failure), and failure caused by transport problem.
3818 * For registration retry caused by transport failure, the first retry
3819 * will be done after \a reg_first_retry_interval seconds instead.
3820 * Note that the interval will be randomized slightly by some seconds
3821 * (specified in \a reg_retry_random_interval) to avoid all clients
3822 * re-registering at the same time.
3823 *
3824 * See also \a reg_first_retry_interval setting.
3825 *
3826 * Default: #PJSUA_REG_RETRY_INTERVAL
3827 */
3828 unsigned reg_retry_interval;
3829
3830 /**
3831 * This specifies the interval for the first registration retry. The
3832 * registration retry is explained in \a reg_retry_interval. Note that
3833 * the value here will also be randomized by some seconds (specified
3834 * in \a reg_retry_random_interval) to avoid all clients re-registering
3835 * at the same time.
3836 *
3837 * Default: 0
3838 */
3839 unsigned reg_first_retry_interval;
3840
3841 /**
3842 * This specifies maximum randomized value to be added/substracted
3843 * to/from the registration retry interval specified in \a
3844 * reg_retry_interval and \a reg_first_retry_interval, in second.
3845 * This is useful to avoid all clients re-registering at the same time.
3846 * For example, if the registration retry interval is set to 100 seconds
3847 * and this is set to 10 seconds, the actual registration retry interval
3848 * will be in the range of 90 to 110 seconds.
3849 *
3850 * Default: 10
3851 */
3852 unsigned reg_retry_random_interval;
3853
3854 /**
3855 * Specify whether calls of the configured account should be dropped
3856 * after registration failure and an attempt of re-registration has
3857 * also failed.
3858 *
3859 * Default: PJ_FALSE (disabled)
3860 */
3861 pj_bool_t drop_calls_on_reg_fail;
3862
3863 /**
3864 * Specify how the registration uses the outbound and account proxy
3865 * settings. This controls if and what Route headers will appear in
3866 * the REGISTER request of this account. The value is bitmask combination
3867 * of PJSUA_REG_USE_OUTBOUND_PROXY and PJSUA_REG_USE_ACC_PROXY bits.
3868 * If the value is set to 0, the REGISTER request will not use any proxy
3869 * (i.e. it will not have any Route headers).
3870 *
3871 * Default: 3 (PJSUA_REG_USE_OUTBOUND_PROXY | PJSUA_REG_USE_ACC_PROXY)
3872 */
3873 unsigned reg_use_proxy;
3874
3875#if defined(PJMEDIA_STREAM_ENABLE_KA) && (PJMEDIA_STREAM_ENABLE_KA != 0)
3876 /**
3877 * Specify whether stream keep-alive and NAT hole punching with
3878 * non-codec-VAD mechanism (see @ref PJMEDIA_STREAM_ENABLE_KA) is enabled
3879 * for this account.
3880 *
3881 * Default: PJ_FALSE (disabled)
3882 */
3883 pj_bool_t use_stream_ka;
3884#endif
3885
3886 /**
3887 * Specify how to offer call hold to remote peer. Please see the
3888 * documentation on #pjsua_call_hold_type for more info.
3889 *
3890 * Default: PJSUA_CALL_HOLD_TYPE_DEFAULT
3891 */
3892 pjsua_call_hold_type call_hold_type;
3893
3894
3895 /**
3896 * Specify whether the account should register as soon as it is
3897 * added to the UA. Application can set this to PJ_FALSE and control
3898 * the registration manually with pjsua_acc_set_registration().
3899 *
3900 * Default: PJ_TRUE
3901 */
3902 pj_bool_t register_on_acc_add;
3903
3904 /**
3905 * Specify account configuration specific to IP address change used when
3906 * calling #pjsua_handle_ip_change().
3907 */
3908 pjsua_ip_change_acc_cfg ip_change_cfg;
3909
3910 /**
3911 * Enable RTP and RTCP multiplexing.
3912 */
3913 pj_bool_t enable_rtcp_mux;
3914
3915} pjsua_acc_config;
3916
3917
3918/**
3919 * Initialize ICE config from a media config. If the \a pool argument
3920 * is NULL, a simple memcpy() will be used.
3921 *
3922 * @param pool Memory to duplicate strings.
3923 * @param dst Destination config.
3924 * @param src Source config.
3925 */
3926PJ_DECL(void) pjsua_ice_config_from_media_config(pj_pool_t *pool,
3927 pjsua_ice_config *dst,
3928 const pjsua_media_config *src);
3929
3930/**
3931 * Clone. If the \a pool argument is NULL, a simple memcpy() will be used.
3932 *
3933 * @param pool Memory to duplicate strings.
3934 * @param dst Destination config.
3935 * @param src Source config.
3936 */
3937PJ_DECL(void) pjsua_ice_config_dup( pj_pool_t *pool,
3938 pjsua_ice_config *dst,
3939 const pjsua_ice_config *src);
3940
3941/**
3942 * Initialize TURN config from a media config. If the \a pool argument
3943 * is NULL, a simple memcpy() will be used.
3944 *
3945 * @param pool Memory to duplicate strings.
3946 * @param dst Destination config.
3947 * @param src Source config.
3948 */
3949PJ_DECL(void) pjsua_turn_config_from_media_config(pj_pool_t *pool,
3950 pjsua_turn_config *dst,
3951 const pjsua_media_config *src);
3952
3953/**
3954 * Clone. If the \a pool argument is NULL, a simple memcpy() will be used.
3955 *
3956 * @param pool Memory to duplicate strings.
3957 * @param dst Destination config.
3958 * @param src Source config.
3959 */
3960PJ_DECL(void) pjsua_turn_config_dup(pj_pool_t *pool,
3961 pjsua_turn_config *dst,
3962 const pjsua_turn_config *src);
3963
3964
3965/**
3966 * Call this function to initialize SRTP config with default values.
3967 *
3968 * @param cfg The SRTP config to be initialized.
3969 */
3970PJ_DECL(void) pjsua_srtp_opt_default(pjsua_srtp_opt *cfg);
3971
3972
3973/**
3974 * Call this function to initialize account config with default values.
3975 *
3976 * @param cfg The account config to be initialized.
3977 */
3978PJ_DECL(void) pjsua_acc_config_default(pjsua_acc_config *cfg);
3979
3980
3981/**
3982 * Duplicate account config.
3983 *
3984 * @param pool Pool to be used for duplicating the config.
3985 * @param dst Destination configuration.
3986 * @param src Source configuration.
3987 */
3988PJ_DECL(void) pjsua_acc_config_dup(pj_pool_t *pool,
3989 pjsua_acc_config *dst,
3990 const pjsua_acc_config *src);
3991
3992
3993/**
3994 * Account info. Application can query account info by calling
3995 * #pjsua_acc_get_info().
3996 */
3997typedef struct pjsua_acc_info
3998{
3999 /**
4000 * The account ID.
4001 */
4002 pjsua_acc_id id;
4003
4004 /**
4005 * Flag to indicate whether this is the default account.
4006 */
4007 pj_bool_t is_default;
4008
4009 /**
4010 * Account URI
4011 */
4012 pj_str_t acc_uri;
4013
4014 /**
4015 * Flag to tell whether this account has registration setting
4016 * (reg_uri is not empty).
4017 */
4018 pj_bool_t has_registration;
4019
4020 /**
4021 * An up to date expiration interval for account registration session.
4022 */
4023 int expires;
4024
4025 /**
4026 * Last registration status code. If status code is zero, the account
4027 * is currently not registered. Any other value indicates the SIP
4028 * status code of the registration.
4029 */
4030 pjsip_status_code status;
4031
4032 /**
4033 * Last registration error code. When the status field contains a SIP
4034 * status code that indicates a registration failure, last registration
4035 * error code contains the error code that causes the failure. In any
4036 * other case, its value is zero.
4037 */
4038 pj_status_t reg_last_err;
4039
4040 /**
4041 * String describing the registration status.
4042 */
4043 pj_str_t status_text;
4044
4045 /**
4046 * Presence online status for this account.
4047 */
4048 pj_bool_t online_status;
4049
4050 /**
4051 * Presence online status text.
4052 */
4053 pj_str_t online_status_text;
4054
4055 /**
4056 * Extended RPID online status information.
4057 */
4058 pjrpid_element rpid;
4059
4060 /**
4061 * Buffer that is used internally to store the status text.
4062 */
4063 char buf_[PJ_ERR_MSG_SIZE];
4064
4065} pjsua_acc_info;
4066
4067
4068
4069/**
4070 * Get number of current accounts.
4071 *
4072 * @return Current number of accounts.
4073 */
4074PJ_DECL(unsigned) pjsua_acc_get_count(void);
4075
4076
4077/**
4078 * Check if the specified account ID is valid.
4079 *
4080 * @param acc_id Account ID to check.
4081 *
4082 * @return Non-zero if account ID is valid.
4083 */
4084PJ_DECL(pj_bool_t) pjsua_acc_is_valid(pjsua_acc_id acc_id);
4085
4086
4087/**
4088 * Set default account to be used when incoming and outgoing
4089 * requests doesn't match any accounts.
4090 *
4091 * @param acc_id The account ID to be used as default.
4092 *
4093 * @return PJ_SUCCESS on success.
4094 */
4095PJ_DECL(pj_status_t) pjsua_acc_set_default(pjsua_acc_id acc_id);
4096
4097
4098/**
4099 * Get default account to be used when receiving incoming requests (calls),
4100 * when the destination of the incoming call doesn't match any other
4101 * accounts.
4102 *
4103 * @return The default account ID, or PJSUA_INVALID_ID if no
4104 * default account is configured.
4105 */
4106PJ_DECL(pjsua_acc_id) pjsua_acc_get_default(void);
4107
4108
4109/**
4110 * Add a new account to pjsua. PJSUA must have been initialized (with
4111 * #pjsua_init()) before calling this function. If registration is configured
4112 * for this account, this function would also start the SIP registration
4113 * session with the SIP registrar server. This SIP registration session
4114 * will be maintained internally by the library, and application doesn't
4115 * need to do anything to maintain the registration session.
4116 *
4117 *
4118 * @param acc_cfg Account configuration.
4119 * @param is_default If non-zero, this account will be set as the default
4120 * account. The default account will be used when sending
4121 * outgoing requests (e.g. making call) when no account is
4122 * specified, and when receiving incoming requests when the
4123 * request does not match any accounts. It is recommended
4124 * that default account is set to local/LAN account.
4125 * @param p_acc_id Pointer to receive account ID of the new account.
4126 *
4127 * @return PJ_SUCCESS on success, or the appropriate error code.
4128 */
4129PJ_DECL(pj_status_t) pjsua_acc_add(const pjsua_acc_config *acc_cfg,
4130 pj_bool_t is_default,
4131 pjsua_acc_id *p_acc_id);
4132
4133
4134/**
4135 * Add a local account. A local account is used to identify local endpoint
4136 * instead of a specific user, and for this reason, a transport ID is needed
4137 * to obtain the local address information.
4138 *
4139 * @param tid Transport ID to generate account address.
4140 * @param is_default If non-zero, this account will be set as the default
4141 * account. The default account will be used when sending
4142 * outgoing requests (e.g. making call) when no account is
4143 * specified, and when receiving incoming requests when the
4144 * request does not match any accounts. It is recommended
4145 * that default account is set to local/LAN account.
4146 * @param p_acc_id Pointer to receive account ID of the new account.
4147 *
4148 * @return PJ_SUCCESS on success, or the appropriate error code.
4149 */
4150PJ_DECL(pj_status_t) pjsua_acc_add_local(pjsua_transport_id tid,
4151 pj_bool_t is_default,
4152 pjsua_acc_id *p_acc_id);
4153
4154/**
4155 * Set arbitrary data to be associated with the account.
4156 *
4157 * @param acc_id The account ID.
4158 * @param user_data User/application data.
4159 *
4160 * @return PJ_SUCCESS on success, or the appropriate error code.
4161 */
4162PJ_DECL(pj_status_t) pjsua_acc_set_user_data(pjsua_acc_id acc_id,
4163 void *user_data);
4164
4165
4166/**
4167 * Retrieve arbitrary data associated with the account.
4168 *
4169 * @param acc_id The account ID.
4170 *
4171 * @return The user data. In the case where the account ID is
4172 * not valid, NULL is returned.
4173 */
4174PJ_DECL(void*) pjsua_acc_get_user_data(pjsua_acc_id acc_id);
4175
4176
4177/**
4178 * Delete an account. This will unregister the account from the SIP server,
4179 * if necessary, and terminate server side presence subscriptions associated
4180 * with this account.
4181 *
4182 * @param acc_id Id of the account to be deleted.
4183 *
4184 * @return PJ_SUCCESS on success, or the appropriate error code.
4185 */
4186PJ_DECL(pj_status_t) pjsua_acc_del(pjsua_acc_id acc_id);
4187
4188
4189/**
4190 * Get current config for the account. This will copy current account setting
4191 * to the specified parameter. Note that all pointers in the settings will
4192 * point to the original settings in the account and application must not
4193 * modify the values in any way. Application must also take care that these
4194 * data is only valid until the account is destroyed.
4195 *
4196 * @param acc_id The account ID.
4197 * @param pool Pool to duplicate the config.
4198 * @param acc_cfg Structure to receive the settings.
4199 *
4200 * @return PJ_SUCCESS on success, or the appropriate error code.
4201 */
4202PJ_DECL(pj_status_t) pjsua_acc_get_config(pjsua_acc_id acc_id,
4203 pj_pool_t *pool,
4204 pjsua_acc_config *acc_cfg);
4205
4206
4207/**
4208 * Modify account configuration setting. This function may trigger
4209 * unregistration (of old account setting) and re-registration (of the new
4210 * account setting), e.g: changing account ID, credential, registar, or
4211 * proxy setting.
4212 *
4213 * Note:
4214 * - when the new config triggers unregistration, the pjsua callback
4215 * on_reg_state()/on_reg_state2() for the unregistration will not be called
4216 * and any failure in the unregistration will be ignored, so if application
4217 * needs to be sure about the unregistration status, it should unregister
4218 * manually and wait for the callback before calling this function
4219 * - when the new config triggers re-registration and the re-registration
4220 * fails, the account setting will not be reverted back to the old setting
4221 * and the account will be in unregistered state.
4222 *
4223 * @param acc_id Id of the account to be modified.
4224 * @param acc_cfg New account configuration.
4225 *
4226 * @return PJ_SUCCESS on success, or the appropriate error code.
4227 */
4228PJ_DECL(pj_status_t) pjsua_acc_modify(pjsua_acc_id acc_id,
4229 const pjsua_acc_config *acc_cfg);
4230
4231
4232/**
4233 * Modify account's presence status to be advertised to remote/presence
4234 * subscribers. This would trigger the sending of outgoing NOTIFY request
4235 * if there are server side presence subscription for this account, and/or
4236 * outgoing PUBLISH if presence publication is enabled for this account.
4237 *
4238 * @see pjsua_acc_set_online_status2()
4239 *
4240 * @param acc_id The account ID.
4241 * @param is_online True of false.
4242 *
4243 * @return PJ_SUCCESS on success, or the appropriate error code.
4244 */
4245PJ_DECL(pj_status_t) pjsua_acc_set_online_status(pjsua_acc_id acc_id,
4246 pj_bool_t is_online);
4247
4248/**
4249 * Modify account's presence status to be advertised to remote/presence
4250 * subscribers. This would trigger the sending of outgoing NOTIFY request
4251 * if there are server side presence subscription for this account, and/or
4252 * outgoing PUBLISH if presence publication is enabled for this account.
4253 *
4254 * @see pjsua_acc_set_online_status()
4255 *
4256 * @param acc_id The account ID.
4257 * @param is_online True of false.
4258 * @param pr Extended information in subset of RPID format
4259 * which allows setting custom presence text.
4260 *
4261 * @return PJ_SUCCESS on success, or the appropriate error code.
4262 */
4263PJ_DECL(pj_status_t) pjsua_acc_set_online_status2(pjsua_acc_id acc_id,
4264 pj_bool_t is_online,
4265 const pjrpid_element *pr);
4266
4267/**
4268 * Update registration or perform unregistration. If registration is
4269 * configured for this account, then initial SIP REGISTER will be sent
4270 * when the account is added with #pjsua_acc_add(). Application normally
4271 * only need to call this function if it wants to manually update the
4272 * registration or to unregister from the server.
4273 *
4274 * @param acc_id The account ID.
4275 * @param renew If renew argument is zero, this will start
4276 * unregistration process.
4277 *
4278 * @return PJ_SUCCESS on success, or the appropriate error code.
4279 */
4280PJ_DECL(pj_status_t) pjsua_acc_set_registration(pjsua_acc_id acc_id,
4281 pj_bool_t renew);
4282
4283/**
4284 * Get information about the specified account.
4285 *
4286 * @param acc_id Account identification.
4287 * @param info Pointer to receive account information.
4288 *
4289 * @return PJ_SUCCESS on success, or the appropriate error code.
4290 */
4291PJ_DECL(pj_status_t) pjsua_acc_get_info(pjsua_acc_id acc_id,
4292 pjsua_acc_info *info);
4293
4294
4295/**
4296 * Enumerate all account currently active in the library. This will fill
4297 * the array with the account Ids, and application can then query the
4298 * account information for each id with #pjsua_acc_get_info().
4299 *
4300 * @see pjsua_acc_enum_info().
4301 *
4302 * @param ids Array of account IDs to be initialized.
4303 * @param count In input, specifies the maximum number of elements.
4304 * On return, it contains the actual number of elements.
4305 *
4306 * @return PJ_SUCCESS on success, or the appropriate error code.
4307 */
4308PJ_DECL(pj_status_t) pjsua_enum_accs(pjsua_acc_id ids[],
4309 unsigned *count );
4310
4311
4312/**
4313 * Enumerate account informations.
4314 *
4315 * @param info Array of account infos to be initialized.
4316 * @param count In input, specifies the maximum number of elements.
4317 * On return, it contains the actual number of elements.
4318 *
4319 * @return PJ_SUCCESS on success, or the appropriate error code.
4320 */
4321PJ_DECL(pj_status_t) pjsua_acc_enum_info( pjsua_acc_info info[],
4322 unsigned *count );
4323
4324
4325/**
4326 * This is an internal function to find the most appropriate account to
4327 * used to reach to the specified URL.
4328 *
4329 * @param url The remote URL to reach.
4330 *
4331 * @return Account id.
4332 */
4333PJ_DECL(pjsua_acc_id) pjsua_acc_find_for_outgoing(const pj_str_t *url);
4334
4335
4336/**
4337 * This is an internal function to find the most appropriate account to be
4338 * used to handle incoming calls.
4339 *
4340 * @param rdata The incoming request message.
4341 *
4342 * @return Account id.
4343 */
4344PJ_DECL(pjsua_acc_id) pjsua_acc_find_for_incoming(pjsip_rx_data *rdata);
4345
4346
4347/**
4348 * Create arbitrary requests using the account. Application should only use
4349 * this function to create auxiliary requests outside dialog, such as
4350 * OPTIONS, and use the call or presence API to create dialog related
4351 * requests.
4352 *
4353 * @param acc_id The account ID.
4354 * @param method The SIP method of the request.
4355 * @param target Target URI.
4356 * @param p_tdata Pointer to receive the request.
4357 *
4358 * @return PJ_SUCCESS or the error code.
4359 */
4360PJ_DECL(pj_status_t) pjsua_acc_create_request(pjsua_acc_id acc_id,
4361 const pjsip_method *method,
4362 const pj_str_t *target,
4363 pjsip_tx_data **p_tdata);
4364
4365
4366/**
4367 * Create a suitable Contact header value, based on the specified target URI
4368 * for the specified account.
4369 *
4370 * @param pool Pool to allocate memory for the string.
4371 * @param contact The string where the Contact will be stored.
4372 * @param acc_id Account ID.
4373 * @param uri Destination URI of the request.
4374 *
4375 * @return PJ_SUCCESS on success, other on error.
4376 */
4377PJ_DECL(pj_status_t) pjsua_acc_create_uac_contact( pj_pool_t *pool,
4378 pj_str_t *contact,
4379 pjsua_acc_id acc_id,
4380 const pj_str_t *uri);
4381
4382
4383
4384/**
4385 * Create a suitable Contact header value, based on the information in the
4386 * incoming request.
4387 *
4388 * @param pool Pool to allocate memory for the string.
4389 * @param contact The string where the Contact will be stored.
4390 * @param acc_id Account ID.
4391 * @param rdata Incoming request.
4392 *
4393 * @return PJ_SUCCESS on success, other on error.
4394 */
4395PJ_DECL(pj_status_t) pjsua_acc_create_uas_contact( pj_pool_t *pool,
4396 pj_str_t *contact,
4397 pjsua_acc_id acc_id,
4398 pjsip_rx_data *rdata );
4399
4400
4401/**
4402 * Lock/bind this account to a specific transport/listener. Normally
4403 * application shouldn't need to do this, as transports will be selected
4404 * automatically by the stack according to the destination.
4405 *
4406 * When account is locked/bound to a specific transport, all outgoing
4407 * requests from this account will use the specified transport (this
4408 * includes SIP registration, dialog (call and event subscription), and
4409 * out-of-dialog requests such as MESSAGE).
4410 *
4411 * Note that transport_id may be specified in pjsua_acc_config too.
4412 *
4413 * @param acc_id The account ID.
4414 * @param tp_id The transport ID.
4415 *
4416 * @return PJ_SUCCESS on success.
4417 */
4418PJ_DECL(pj_status_t) pjsua_acc_set_transport(pjsua_acc_id acc_id,
4419 pjsua_transport_id tp_id);
4420
4421
4422/**
4423 * @}
4424 */
4425
4426
4427/*****************************************************************************
4428 * CALLS API
4429 */
4430
4431
4432/**
4433 * @defgroup PJSUA_LIB_CALL PJSUA-API Calls Management
4434 * @ingroup PJSUA_LIB
4435 * @brief Call manipulation.
4436 * @{
4437 */
4438
4439/**
4440 * Maximum simultaneous calls.
4441 */
4442#ifndef PJSUA_MAX_CALLS
4443# define PJSUA_MAX_CALLS 32
4444#endif
4445
4446/**
4447 * Maximum active video windows
4448 */
4449#ifndef PJSUA_MAX_VID_WINS
4450# define PJSUA_MAX_VID_WINS 16
4451#endif
4452
4453/**
4454 * Video window ID.
4455 */
4456typedef int pjsua_vid_win_id;
4457
4458
4459/**
4460 * This enumeration specifies the media status of a call, and it's part
4461 * of pjsua_call_info structure.
4462 */
4463typedef enum pjsua_call_media_status
4464{
4465 /**
4466 * Call currently has no media, or the media is not used.
4467 */
4468 PJSUA_CALL_MEDIA_NONE,
4469
4470 /**
4471 * The media is active
4472 */
4473 PJSUA_CALL_MEDIA_ACTIVE,
4474
4475 /**
4476 * The media is currently put on hold by local endpoint
4477 */
4478 PJSUA_CALL_MEDIA_LOCAL_HOLD,
4479
4480 /**
4481 * The media is currently put on hold by remote endpoint
4482 */
4483 PJSUA_CALL_MEDIA_REMOTE_HOLD,
4484
4485 /**
4486 * The media has reported error (e.g. ICE negotiation)
4487 */
4488 PJSUA_CALL_MEDIA_ERROR
4489
4490} pjsua_call_media_status;
4491
4492
4493/**
4494 * Enumeration of video keyframe request methods. Keyframe request is
4495 * triggered by decoder, usually when the incoming video stream cannot
4496 * be decoded properly due to missing video keyframe.
4497 */
4498typedef enum pjsua_vid_req_keyframe_method
4499{
4500 /**
4501 * Requesting keyframe via SIP INFO message. Note that incoming keyframe
4502 * request via SIP INFO will always be handled even if this flag is unset.
4503 */
4504 PJSUA_VID_REQ_KEYFRAME_SIP_INFO = 1,
4505
4506 /**
4507 * Requesting keyframe via Picture Loss Indication of RTCP feedback.
4508 * This is currently not supported.
4509 */
4510 PJSUA_VID_REQ_KEYFRAME_RTCP_PLI = 2
4511
4512} pjsua_vid_req_keyframe_method;
4513
4514
4515/**
4516 * Call media information.
4517 */
4518typedef struct pjsua_call_media_info
4519{
4520 /** Media index in SDP. */
4521 unsigned index;
4522
4523 /** Media type. */
4524 pjmedia_type type;
4525
4526 /** Media direction. */
4527 pjmedia_dir dir;
4528
4529 /** Call media status. */
4530 pjsua_call_media_status status;
4531
4532 /** The specific media stream info. */
4533 union {
4534 /** Audio stream */
4535 struct {
4536 /** The conference port number for the call. */
4537 pjsua_conf_port_id conf_slot;
4538 } aud;
4539
4540 /** Video stream */
4541 struct {
4542 /**
4543 * The window id for incoming video, if any, or
4544 * PJSUA_INVALID_ID.
4545 */
4546 pjsua_vid_win_id win_in;
4547
4548 /** The video capture device for outgoing transmission,
4549 * if any, or PJMEDIA_VID_INVALID_DEV
4550 */
4551 pjmedia_vid_dev_index cap_dev;
4552
4553 } vid;
4554 } stream;
4555
4556} pjsua_call_media_info;
4557
4558
4559/**
4560 * This structure describes the information and current status of a call.
4561 */
4562typedef struct pjsua_call_info
4563{
4564 /** Call identification. */
4565 pjsua_call_id id;
4566
4567 /** Initial call role (UAC == caller) */
4568 pjsip_role_e role;
4569
4570 /** The account ID where this call belongs. */
4571 pjsua_acc_id acc_id;
4572
4573 /** Local URI */
4574 pj_str_t local_info;
4575
4576 /** Local Contact */
4577 pj_str_t local_contact;
4578
4579 /** Remote URI */
4580 pj_str_t remote_info;
4581
4582 /** Remote contact */
4583 pj_str_t remote_contact;
4584
4585 /** Dialog Call-ID string. */
4586 pj_str_t call_id;
4587
4588 /** Call setting */
4589 pjsua_call_setting setting;
4590
4591 /** Call state */
4592 pjsip_inv_state state;
4593
4594 /** Text describing the state */
4595 pj_str_t state_text;
4596
4597 /** Last status code heard, which can be used as cause code */
4598 pjsip_status_code last_status;
4599
4600 /** The reason phrase describing the status. */
4601 pj_str_t last_status_text;
4602
4603 /** Media status of the first audio stream. */
4604 pjsua_call_media_status media_status;
4605
4606 /** Media direction of the first audio stream. */
4607 pjmedia_dir media_dir;
4608
4609 /** The conference port number for the first audio stream. */
4610 pjsua_conf_port_id conf_slot;
4611
4612 /** Number of active media info in this call. */
4613 unsigned media_cnt;
4614
4615 /** Array of active media information. */
4616 pjsua_call_media_info media[PJMEDIA_MAX_SDP_MEDIA];
4617
4618 /** Number of provisional media info in this call. */
4619 unsigned prov_media_cnt;
4620
4621 /** Array of provisional media information. This contains the media info
4622 * in the provisioning state, that is when the media session is being
4623 * created/updated (SDP offer/answer is on progress).
4624 */
4625 pjsua_call_media_info prov_media[PJMEDIA_MAX_SDP_MEDIA];
4626
4627 /** Up-to-date call connected duration (zero when call is not
4628 * established)
4629 */
4630 pj_time_val connect_duration;
4631
4632 /** Total call duration, including set-up time */
4633 pj_time_val total_duration;
4634
4635 /** Flag if remote was SDP offerer */
4636 pj_bool_t rem_offerer;
4637
4638 /** Number of audio streams offered by remote */
4639 unsigned rem_aud_cnt;
4640
4641 /** Number of video streams offered by remote */
4642 unsigned rem_vid_cnt;
4643
4644 /** Internal */
4645 struct {
4646 char local_info[PJSIP_MAX_URL_SIZE];
4647 char local_contact[PJSIP_MAX_URL_SIZE];
4648 char remote_info[PJSIP_MAX_URL_SIZE];
4649 char remote_contact[PJSIP_MAX_URL_SIZE];
4650 char call_id[128];
4651 char last_status_text[128];
4652 } buf_;
4653
4654} pjsua_call_info;
4655
4656/**
4657 * Flags to be given to various call APIs. More than one flags may be
4658 * specified by bitmasking them.
4659 */
4660typedef enum pjsua_call_flag
4661{
4662 /**
4663 * When the call is being put on hold, specify this flag to unhold it.
4664 * This flag is only valid for #pjsua_call_reinvite() and
4665 * #pjsua_call_update(). Note: for compatibility reason, this flag must
4666 * have value of 1 because previously the unhold option is specified as
4667 * boolean value.
4668 */
4669 PJSUA_CALL_UNHOLD = 1,
4670
4671 /**
4672 * Update the local invite session's contact with the contact URI from
4673 * the account. This flag is only valid for #pjsua_call_set_hold2(),
4674 * #pjsua_call_reinvite() and #pjsua_call_update(). This flag is useful
4675 * in IP address change situation, after the local account's Contact has
4676 * been updated (typically with re-registration) use this flag to update
4677 * the invite session with the new Contact and to inform this new Contact
4678 * to the remote peer with the outgoing re-INVITE or UPDATE.
4679 */
4680 PJSUA_CALL_UPDATE_CONTACT = 2,
4681
4682 /**
4683 * Include SDP "m=" line with port set to zero for each disabled media
4684 * (i.e when aud_cnt or vid_cnt is set to zero). This flag is only valid
4685 * for #pjsua_call_make_call(), #pjsua_call_reinvite(), and
4686 * #pjsua_call_update(). Note that even this flag is applicable in
4687 * #pjsua_call_reinvite() and #pjsua_call_update(), it will only take
4688 * effect when the re-INVITE/UPDATE operation regenerates SDP offer,
4689 * such as changing audio or video count in the call setting.
4690 */
4691 PJSUA_CALL_INCLUDE_DISABLED_MEDIA = 4,
4692
4693 /**
4694 * Do not send SDP when sending INVITE or UPDATE. This flag is only valid
4695 * for #pjsua_call_make_call(), #pjsua_call_reinvite()/reinvite2(), or
4696 * #pjsua_call_update()/update2(). For re-invite/update, specifying
4697 * PJSUA_CALL_UNHOLD will take precedence over this flag.
4698 */
4699 PJSUA_CALL_NO_SDP_OFFER = 8,
4700
4701 /**
4702 * Deinitialize and recreate media, including media transport. This flag
4703 * is useful in IP address change situation, if the media transport
4704 * address (or address family) changes, for example during IPv4/IPv6
4705 * network handover.
4706 * This flag is only valid for #pjsua_call_reinvite()/reinvite2(), or
4707 * #pjsua_call_update()/update2().
4708 *
4709 * Warning: If the re-INVITE/UPDATE fails, the old media will not be
4710 * reverted.
4711 */
4712 PJSUA_CALL_REINIT_MEDIA = 16,
4713
4714 /**
4715 * Update the local invite session's Via with the via address from
4716 * the account. This flag is only valid for #pjsua_call_set_hold2(),
4717 * #pjsua_call_reinvite() and #pjsua_call_update(). Similar to
4718 * the flag PJSUA_CALL_UPDATE_CONTACT above, this flag is useful
4719 * in IP address change situation, after the local account's Via has
4720 * been updated (typically with re-registration).
4721 */
4722 PJSUA_CALL_UPDATE_VIA = 32,
4723
4724 /**
4725 * Update dialog target to URI specified in pjsua_msg_data.target_uri.
4726 * This flag is only valid for pjsua_call_set_hold(),
4727 * pjsua_call_reinvite(), and pjsua_call_update(). This flag can be
4728 * useful in IP address change scenario where IP version has been changed
4729 * and application needs to update target IP address.
4730 */
4731 PJSUA_CALL_UPDATE_TARGET = 64
4732
4733} pjsua_call_flag;
4734
4735
4736/**
4737 * Media stream info.
4738 */
4739typedef struct pjsua_stream_info
4740{
4741 /** Media type of this stream. */
4742 pjmedia_type type;
4743
4744 /** Stream info (union). */
4745 union {
4746 /** Audio stream info */
4747 pjmedia_stream_info aud;
4748
4749 /** Video stream info */
4750 pjmedia_vid_stream_info vid;
4751 } info;
4752
4753} pjsua_stream_info;
4754
4755
4756/**
4757 * Media stream statistic.
4758 */
4759typedef struct pjsua_stream_stat
4760{
4761 /** RTCP statistic. */
4762 pjmedia_rtcp_stat rtcp;
4763
4764 /** Jitter buffer statistic. */
4765 pjmedia_jb_state jbuf;
4766
4767} pjsua_stream_stat;
4768
4769/**
4770 * This enumeration represents video stream operation on a call.
4771 * See also #pjsua_call_vid_strm_op_param for further info.
4772 */
4773typedef enum pjsua_call_vid_strm_op
4774{
4775 /**
4776 * No operation
4777 */
4778 PJSUA_CALL_VID_STRM_NO_OP,
4779
4780 /**
4781 * Add a new video stream. This will add a new m=video line to
4782 * the media, regardless of whether existing video is/are present
4783 * or not. This will cause re-INVITE or UPDATE to be sent to remote
4784 * party.
4785 */
4786 PJSUA_CALL_VID_STRM_ADD,
4787
4788 /**
4789 * Remove/disable an existing video stream. This will
4790 * cause re-INVITE or UPDATE to be sent to remote party.
4791 */
4792 PJSUA_CALL_VID_STRM_REMOVE,
4793
4794 /**
4795 * Change direction of a video stream. This operation can be used
4796 * to activate or deactivate an existing video media. This will
4797 * cause re-INVITE or UPDATE to be sent to remote party.
4798 */
4799 PJSUA_CALL_VID_STRM_CHANGE_DIR,
4800
4801 /**
4802 * Change capture device of a video stream. This will not send
4803 * re-INVITE or UPDATE to remote party.
4804 */
4805 PJSUA_CALL_VID_STRM_CHANGE_CAP_DEV,
4806
4807 /**
4808 * Start transmitting video stream. This will cause previously
4809 * stopped stream to start transmitting again. Note that no
4810 * re-INVITE/UPDATE is to be transmitted to remote since this
4811 * operation only operates on local stream.
4812 */
4813 PJSUA_CALL_VID_STRM_START_TRANSMIT,
4814
4815 /**
4816 * Stop transmitting video stream. This will cause the stream to
4817 * be paused in TX direction, causing it to stop sending any video
4818 * packets. No re-INVITE/UPDATE is to be transmitted to remote
4819 * with this operation.
4820 */
4821 PJSUA_CALL_VID_STRM_STOP_TRANSMIT,
4822
4823 /**
4824 * Send keyframe in the video stream. This will force the stream to
4825 * generate and send video keyframe as soon as possible. No
4826 * re-INVITE/UPDATE is to be transmitted to remote with this operation.
4827 */
4828 PJSUA_CALL_VID_STRM_SEND_KEYFRAME
4829
4830} pjsua_call_vid_strm_op;
4831
4832
4833/**
4834 * Parameters for video stream operation on a call. Application should
4835 * use #pjsua_call_vid_strm_op_param_default() to initialize this structure
4836 * with its default values.
4837 */
4838typedef struct pjsua_call_vid_strm_op_param
4839{
4840 /**
4841 * Specify the media stream index. This can be set to -1 to denote
4842 * the default video stream in the call, which is the first active
4843 * video stream or any first video stream if none is active.
4844 *
4845 * This field is valid for all video stream operations, except
4846 * PJSUA_CALL_VID_STRM_ADD.
4847 *
4848 * Default: -1 (first active video stream, or any first video stream
4849 * if none is active)
4850 */
4851 int med_idx;
4852
4853 /**
4854 * Specify the media stream direction.
4855 *
4856 * This field is valid for the following video stream operations:
4857 * PJSUA_CALL_VID_STRM_ADD and PJSUA_CALL_VID_STRM_CHANGE_DIR.
4858 *
4859 * Default: PJMEDIA_DIR_ENCODING_DECODING
4860 */
4861 pjmedia_dir dir;
4862
4863 /**
4864 * Specify the video capture device ID. This can be set to
4865 * PJMEDIA_VID_DEFAULT_CAPTURE_DEV to specify the default capture
4866 * device as configured in the account.
4867 *
4868 * This field is valid for the following video stream operations:
4869 * PJSUA_CALL_VID_STRM_ADD and PJSUA_CALL_VID_STRM_CHANGE_CAP_DEV.
4870 *
4871 * Default: PJMEDIA_VID_DEFAULT_CAPTURE_DEV.
4872 */
4873 pjmedia_vid_dev_index cap_dev;
4874
4875} pjsua_call_vid_strm_op_param;
4876
4877
4878/**
4879 * Initialize call settings.
4880 *
4881 * @param opt The call setting to be initialized.
4882 */
4883PJ_DECL(void) pjsua_call_setting_default(pjsua_call_setting *opt);
4884
4885
4886/**
4887 * Initialize video stream operation param with default values.
4888 *
4889 * @param param The video stream operation param to be initialized.
4890 */
4891PJ_DECL(void)
4892pjsua_call_vid_strm_op_param_default(pjsua_call_vid_strm_op_param *param);
4893
4894
4895/**
4896 * Get maximum number of calls configured in pjsua.
4897 *
4898 * @return Maximum number of calls configured.
4899 */
4900PJ_DECL(unsigned) pjsua_call_get_max_count(void);
4901
4902/**
4903 * Get number of currently active calls.
4904 *
4905 * @return Number of currently active calls.
4906 */
4907PJ_DECL(unsigned) pjsua_call_get_count(void);
4908
4909/**
4910 * Enumerate all active calls. Application may then query the information and
4911 * state of each call by calling #pjsua_call_get_info().
4912 *
4913 * @param ids Array of account IDs to be initialized.
4914 * @param count In input, specifies the maximum number of elements.
4915 * On return, it contains the actual number of elements.
4916 *
4917 * @return PJ_SUCCESS on success, or the appropriate error code.
4918 */
4919PJ_DECL(pj_status_t) pjsua_enum_calls(pjsua_call_id ids[],
4920 unsigned *count);
4921
4922
4923/**
4924 * Make outgoing call to the specified URI using the specified account.
4925 *
4926 * @param acc_id The account to be used.
4927 * @param dst_uri URI to be put in the To header (normally is the same
4928 * as the target URI).
4929 * @param opt Optional call setting. This should be initialized
4930 * using #pjsua_call_setting_default().
4931 * @param user_data Arbitrary user data to be attached to the call, and
4932 * can be retrieved later.
4933 * @param msg_data Optional headers etc to be added to outgoing INVITE
4934 * request, or NULL if no custom header is desired.
4935 * @param p_call_id Pointer to receive call identification.
4936 *
4937 * @return PJ_SUCCESS on success, or the appropriate error code.
4938 */
4939PJ_DECL(pj_status_t) pjsua_call_make_call(pjsua_acc_id acc_id,
4940 const pj_str_t *dst_uri,
4941 const pjsua_call_setting *opt,
4942 void *user_data,
4943 const pjsua_msg_data *msg_data,
4944 pjsua_call_id *p_call_id);
4945
4946
4947/**
4948 * Check if the specified call has active INVITE session and the INVITE
4949 * session has not been disconnected.
4950 *
4951 * @param call_id Call identification.
4952 *
4953 * @return Non-zero if call is active.
4954 */
4955PJ_DECL(pj_bool_t) pjsua_call_is_active(pjsua_call_id call_id);
4956
4957
4958/**
4959 * Check if call has an active media session.
4960 *
4961 * @param call_id Call identification.
4962 *
4963 * @return Non-zero if yes.
4964 */
4965PJ_DECL(pj_bool_t) pjsua_call_has_media(pjsua_call_id call_id);
4966
4967
4968/**
4969 * Get the conference port identification associated with the call.
4970 *
4971 * @param call_id Call identification.
4972 *
4973 * @return Conference port ID, or PJSUA_INVALID_ID when the
4974 * media has not been established or is not active.
4975 */
4976PJ_DECL(pjsua_conf_port_id) pjsua_call_get_conf_port(pjsua_call_id call_id);
4977
4978/**
4979 * Obtain detail information about the specified call.
4980 *
4981 * @param call_id Call identification.
4982 * @param info Call info to be initialized.
4983 *
4984 * @return PJ_SUCCESS on success, or the appropriate error code.
4985 */
4986PJ_DECL(pj_status_t) pjsua_call_get_info(pjsua_call_id call_id,
4987 pjsua_call_info *info);
4988
4989/**
4990 * Check if remote peer support the specified capability.
4991 *
4992 * @param call_id Call identification.
4993 * @param htype The header type to be checked, which value may be:
4994 * - PJSIP_H_ACCEPT
4995 * - PJSIP_H_ALLOW
4996 * - PJSIP_H_SUPPORTED
4997 * @param hname If htype specifies PJSIP_H_OTHER, then the header
4998 * name must be supplied in this argument. Otherwise the
4999 * value must be set to NULL.
5000 * @param token The capability token to check. For example, if \a
5001 * htype is PJSIP_H_ALLOW, then \a token specifies the
5002 * method names; if \a htype is PJSIP_H_SUPPORTED, then
5003 * \a token specifies the extension names such as
5004 * "100rel".
5005 *
5006 * @return PJSIP_DIALOG_CAP_SUPPORTED if the specified capability
5007 * is explicitly supported, see @pjsip_dialog_cap_status
5008 * for more info.
5009 */
5010PJ_DECL(pjsip_dialog_cap_status) pjsua_call_remote_has_cap(
5011 pjsua_call_id call_id,
5012 int htype,
5013 const pj_str_t *hname,
5014 const pj_str_t *token);
5015
5016/**
5017 * Attach application specific data to the call. Application can then
5018 * inspect this data by calling #pjsua_call_get_user_data().
5019 *
5020 * @param call_id Call identification.
5021 * @param user_data Arbitrary data to be attached to the call.
5022 *
5023 * @return The user data.
5024 */
5025PJ_DECL(pj_status_t) pjsua_call_set_user_data(pjsua_call_id call_id,
5026 void *user_data);
5027
5028
5029/**
5030 * Get user data attached to the call, which has been previously set with
5031 * #pjsua_call_set_user_data().
5032 *
5033 * @param call_id Call identification.
5034 *
5035 * @return The user data.
5036 */
5037PJ_DECL(void*) pjsua_call_get_user_data(pjsua_call_id call_id);
5038
5039
5040/**
5041 * Get the NAT type of remote's endpoint. This is a proprietary feature
5042 * of PJSUA-LIB which sends its NAT type in the SDP when \a nat_type_in_sdp
5043 * is set in #pjsua_config.
5044 *
5045 * This function can only be called after SDP has been received from remote,
5046 * which means for incoming call, this function can be called as soon as
5047 * call is received as long as incoming call contains SDP, and for outgoing
5048 * call, this function can be called only after SDP is received (normally in
5049 * 200/OK response to INVITE). As a general case, application should call
5050 * this function after or in \a on_call_media_state() callback.
5051 *
5052 * @param call_id Call identification.
5053 * @param p_type Pointer to store the NAT type. Application can then
5054 * retrieve the string description of the NAT type
5055 * by calling pj_stun_get_nat_name().
5056 *
5057 * @return PJ_SUCCESS on success.
5058 *
5059 * @see pjsua_get_nat_type(), nat_type_in_sdp
5060 */
5061PJ_DECL(pj_status_t) pjsua_call_get_rem_nat_type(pjsua_call_id call_id,
5062 pj_stun_nat_type *p_type);
5063
5064/**
5065 * Send response to incoming INVITE request. Depending on the status
5066 * code specified as parameter, this function may send provisional
5067 * response, establish the call, or terminate the call. See also
5068 * #pjsua_call_answer2().
5069 *
5070 * @param call_id Incoming call identification.
5071 * @param code Status code, (100-699).
5072 * @param reason Optional reason phrase. If NULL, default text
5073 * will be used.
5074 * @param msg_data Optional list of headers etc to be added to outgoing
5075 * response message. Note that this message data will
5076 * be persistent in all next answers/responses for this
5077 * INVITE request.
5078 *
5079 * @return PJ_SUCCESS on success, or the appropriate error code.
5080 */
5081PJ_DECL(pj_status_t) pjsua_call_answer(pjsua_call_id call_id,
5082 unsigned code,
5083 const pj_str_t *reason,
5084 const pjsua_msg_data *msg_data);
5085
5086
5087/**
5088 * Send response to incoming INVITE request with call setting param.
5089 * Depending on the status code specified as parameter, this function may
5090 * send provisional response, establish the call, or terminate the call.
5091 * Notes about call setting:
5092 * - if call setting is changed in the subsequent call to this function,
5093 * only the first call setting supplied will applied. So normally
5094 * application will not supply call setting before getting confirmation
5095 * from the user.
5096 * - if no call setting is supplied when SDP has to be sent, i.e: answer
5097 * with status code 183 or 2xx, the default call setting will be used,
5098 * check #pjsua_call_setting for its default values.
5099 *
5100 * @param call_id Incoming call identification.
5101 * @param opt Optional call setting.
5102 * @param code Status code, (100-699).
5103 * @param reason Optional reason phrase. If NULL, default text
5104 * will be used.
5105 * @param msg_data Optional list of headers etc to be added to outgoing
5106 * response message. Note that this message data will
5107 * be persistent in all next answers/responses for this
5108 * INVITE request.
5109 *
5110 * @return PJ_SUCCESS on success, or the appropriate error code.
5111 */
5112PJ_DECL(pj_status_t) pjsua_call_answer2(pjsua_call_id call_id,
5113 const pjsua_call_setting *opt,
5114 unsigned code,
5115 const pj_str_t *reason,
5116 const pjsua_msg_data *msg_data);
5117
5118
5119/**
5120 * Hangup call by using method that is appropriate according to the
5121 * call state. This function is different than answering the call with
5122 * 3xx-6xx response (with #pjsua_call_answer()), in that this function
5123 * will hangup the call regardless of the state and role of the call,
5124 * while #pjsua_call_answer() only works with incoming calls on EARLY
5125 * state.
5126 *
5127 * @param call_id Call identification.
5128 * @param code Optional status code to be sent when we're rejecting
5129 * incoming call. If the value is zero, "603/Decline"
5130 * will be sent.
5131 * @param reason Optional reason phrase to be sent when we're rejecting
5132 * incoming call. If NULL, default text will be used.
5133 * @param msg_data Optional list of headers etc to be added to outgoing
5134 * request/response message.
5135 *
5136 * @return PJ_SUCCESS on success, or the appropriate error code.
5137 */
5138PJ_DECL(pj_status_t) pjsua_call_hangup(pjsua_call_id call_id,
5139 unsigned code,
5140 const pj_str_t *reason,
5141 const pjsua_msg_data *msg_data);
5142
5143/**
5144 * Accept or reject redirection response. Application MUST call this function
5145 * after it signaled PJSIP_REDIRECT_PENDING in the \a on_call_redirected()
5146 * callback, to notify the call whether to accept or reject the redirection
5147 * to the current target. Application can use the combination of
5148 * PJSIP_REDIRECT_PENDING command in \a on_call_redirected() callback and
5149 * this function to ask for user permission before redirecting the call.
5150 *
5151 * Note that if the application chooses to reject or stop redirection (by
5152 * using PJSIP_REDIRECT_REJECT or PJSIP_REDIRECT_STOP respectively), the
5153 * call disconnection callback will be called before this function returns.
5154 * And if the application rejects the target, the \a on_call_redirected()
5155 * callback may also be called before this function returns if there is
5156 * another target to try.
5157 *
5158 * @param call_id The call ID.
5159 * @param cmd Redirection operation to be applied to the current
5160 * target. The semantic of this argument is similar
5161 * to the description in the \a on_call_redirected()
5162 * callback, except that the PJSIP_REDIRECT_PENDING is
5163 * not accepted here.
5164 *
5165 * @return PJ_SUCCESS on successful operation.
5166 */
5167PJ_DECL(pj_status_t) pjsua_call_process_redirect(pjsua_call_id call_id,
5168 pjsip_redirect_op cmd);
5169
5170/**
5171 * Put the specified call on hold. This will send re-INVITE with the
5172 * appropriate SDP to inform remote that the call is being put on hold.
5173 * The final status of the request itself will be reported on the
5174 * \a on_call_media_state() callback, which inform the application that
5175 * the media state of the call has changed.
5176 *
5177 * @param call_id Call identification.
5178 * @param msg_data Optional message components to be sent with
5179 * the request.
5180 *
5181 * @return PJ_SUCCESS on success, or the appropriate error code.
5182 */
5183PJ_DECL(pj_status_t) pjsua_call_set_hold(pjsua_call_id call_id,
5184 const pjsua_msg_data *msg_data);
5185
5186/**
5187 * Put the specified call on hold. This will send re-INVITE with the
5188 * appropriate SDP to inform remote that the call is being put on hold.
5189 * The final status of the request itself will be reported on the
5190 * \a on_call_media_state() callback, which inform the application that
5191 * the media state of the call has changed.
5192 *
5193 * @param call_id Call identification.
5194 * @param options Bitmask of pjsua_call_flag constants. Currently, only
5195 * the flag PJSUA_CALL_UPDATE_CONTACT can be used.
5196 * @param msg_data Optional message components to be sent with
5197 * the request.
5198 *
5199 * @return PJ_SUCCESS on success, or the appropriate error code.
5200 */
5201PJ_DECL(pj_status_t) pjsua_call_set_hold2(pjsua_call_id call_id,
5202 unsigned options,
5203 const pjsua_msg_data *msg_data);
5204
5205/**
5206 * Send re-INVITE request or release hold.
5207 * The final status of the request itself will be reported on the
5208 * \a on_call_media_state() callback, which inform the application that
5209 * the media state of the call has changed.
5210 *
5211 * @param call_id Call identification.
5212 * @param options Bitmask of pjsua_call_flag constants. Note that
5213 * for compatibility, specifying PJ_TRUE here is
5214 * equal to specifying PJSUA_CALL_UNHOLD flag.
5215 * @param msg_data Optional message components to be sent with
5216 * the request.
5217 *
5218 * @return PJ_SUCCESS on success, or the appropriate error code.
5219 */
5220PJ_DECL(pj_status_t) pjsua_call_reinvite(pjsua_call_id call_id,
5221 unsigned options,
5222 const pjsua_msg_data *msg_data);
5223
5224
5225/**
5226 * Send re-INVITE request or release hold.
5227 * The final status of the request itself will be reported on the
5228 * \a on_call_media_state() callback, which inform the application that
5229 * the media state of the call has changed.
5230 *
5231 * @param call_id Call identification.
5232 * @param opt Optional call setting, if NULL, the current call
5233 * setting will be used. Note that to release hold
5234 * or update contact or omit SDP offer, this parameter
5235 * cannot be NULL and it must specify appropriate flags,
5236 * e.g: PJSUA_CALL_UNHOLD, PJSUA_CALL_UPDATE_CONTACT,
5237 * PJSUA_CALL_NO_SDP_OFFER.
5238 * @param msg_data Optional message components to be sent with
5239 * the request.
5240 *
5241 * @return PJ_SUCCESS on success, or the appropriate error code.
5242 */
5243PJ_DECL(pj_status_t) pjsua_call_reinvite2(pjsua_call_id call_id,
5244 const pjsua_call_setting *opt,
5245 const pjsua_msg_data *msg_data);
5246
5247
5248/**
5249 * Send UPDATE request.
5250 *
5251 * @param call_id Call identification.
5252 * @param options Bitmask of pjsua_call_flag constants.
5253 * @param msg_data Optional message components to be sent with
5254 * the request.
5255 *
5256 * @return PJ_SUCCESS on success, or the appropriate error code.
5257 */
5258PJ_DECL(pj_status_t) pjsua_call_update(pjsua_call_id call_id,
5259 unsigned options,
5260 const pjsua_msg_data *msg_data);
5261
5262
5263/**
5264 * Send UPDATE request.
5265 *
5266 * @param call_id Call identification.
5267 * @param opt Optional call setting, if NULL, the current call
5268 * setting will be used. Note that to release hold
5269 * or update contact or omit SDP offer, this parameter
5270 * cannot be NULL and it must specify appropriate flags,
5271 * e.g: PJSUA_CALL_UNHOLD, PJSUA_CALL_UPDATE_CONTACT,
5272 * PJSUA_CALL_NO_SDP_OFFER.
5273 * @param msg_data Optional message components to be sent with
5274 * the request.
5275 *
5276 * @return PJ_SUCCESS on success, or the appropriate error code.
5277 */
5278PJ_DECL(pj_status_t) pjsua_call_update2(pjsua_call_id call_id,
5279 const pjsua_call_setting *opt,
5280 const pjsua_msg_data *msg_data);
5281
5282
5283/**
5284 * Initiate call transfer to the specified address. This function will send
5285 * REFER request to instruct remote call party to initiate a new INVITE
5286 * session to the specified destination/target.
5287 *
5288 * If application is interested to monitor the successfulness and
5289 * the progress of the transfer request, it can implement
5290 * \a on_call_transfer_status() callback which will report the progress
5291 * of the call transfer request.
5292 *
5293 * @param call_id The call id to be transferred.
5294 * @param dest URI of new target to be contacted. The URI may be
5295 * in name address or addr-spec format.
5296 * @param msg_data Optional message components to be sent with
5297 * the request.
5298 *
5299 * @return PJ_SUCCESS on success, or the appropriate error code.
5300 */
5301PJ_DECL(pj_status_t) pjsua_call_xfer(pjsua_call_id call_id,
5302 const pj_str_t *dest,
5303 const pjsua_msg_data *msg_data);
5304
5305/**
5306 * Flag to indicate that "Require: replaces" should not be put in the
5307 * outgoing INVITE request caused by REFER request created by
5308 * #pjsua_call_xfer_replaces().
5309 */
5310#define PJSUA_XFER_NO_REQUIRE_REPLACES 1
5311
5312/**
5313 * Initiate attended call transfer. This function will send REFER request
5314 * to instruct remote call party to initiate new INVITE session to the URL
5315 * of \a dest_call_id. The party at \a dest_call_id then should "replace"
5316 * the call with us with the new call from the REFER recipient.
5317 *
5318 * @param call_id The call id to be transferred.
5319 * @param dest_call_id The call id to be replaced.
5320 * @param options Application may specify PJSUA_XFER_NO_REQUIRE_REPLACES
5321 * to suppress the inclusion of "Require: replaces" in
5322 * the outgoing INVITE request created by the REFER
5323 * request.
5324 * @param msg_data Optional message components to be sent with
5325 * the request.
5326 *
5327 * @return PJ_SUCCESS on success, or the appropriate error code.
5328 */
5329PJ_DECL(pj_status_t) pjsua_call_xfer_replaces(pjsua_call_id call_id,
5330 pjsua_call_id dest_call_id,
5331 unsigned options,
5332 const pjsua_msg_data *msg_data);
5333
5334/**
5335 * Send DTMF digits to remote using RFC 2833 payload formats.
5336 *
5337 * @param call_id Call identification.
5338 * @param digits DTMF string digits to be sent as described on RFC 2833
5339 * section 3.10. If PJMEDIA_HAS_DTMF_FLASH is enabled,
5340 * character 'R' is used to represent the
5341 * event type 16 (flash) as stated in RFC 4730.
5342 *
5343 * @return PJ_SUCCESS on success, or the appropriate error code.
5344 */
5345PJ_DECL(pj_status_t) pjsua_call_dial_dtmf(pjsua_call_id call_id,
5346 const pj_str_t *digits);
5347
5348/**
5349 * Send instant messaging inside INVITE session.
5350 *
5351 * @param call_id Call identification.
5352 * @param mime_type Optional MIME type. If NULL, then "text/plain" is
5353 * assumed.
5354 * @param content The message content.
5355 * @param msg_data Optional list of headers etc to be included in outgoing
5356 * request. The body descriptor in the msg_data is
5357 * ignored.
5358 * @param user_data Optional user data, which will be given back when
5359 * the IM callback is called.
5360 *
5361 * @return PJ_SUCCESS on success, or the appropriate error code.
5362 */
5363PJ_DECL(pj_status_t) pjsua_call_send_im( pjsua_call_id call_id,
5364 const pj_str_t *mime_type,
5365 const pj_str_t *content,
5366 const pjsua_msg_data *msg_data,
5367 void *user_data);
5368
5369
5370/**
5371 * Send IM typing indication inside INVITE session.
5372 *
5373 * @param call_id Call identification.
5374 * @param is_typing Non-zero to indicate to remote that local person is
5375 * currently typing an IM.
5376 * @param msg_data Optional list of headers etc to be included in outgoing
5377 * request.
5378 *
5379 * @return PJ_SUCCESS on success, or the appropriate error code.
5380 */
5381PJ_DECL(pj_status_t) pjsua_call_send_typing_ind(pjsua_call_id call_id,
5382 pj_bool_t is_typing,
5383 const pjsua_msg_data*msg_data);
5384
5385/**
5386 * Send arbitrary request with the call. This is useful for example to send
5387 * INFO request. Note that application should not use this function to send
5388 * requests which would change the invite session's state, such as re-INVITE,
5389 * UPDATE, PRACK, and BYE.
5390 *
5391 * @param call_id Call identification.
5392 * @param method SIP method of the request.
5393 * @param msg_data Optional message body and/or list of headers to be
5394 * included in outgoing request.
5395 *
5396 * @return PJ_SUCCESS on success, or the appropriate error code.
5397 */
5398PJ_DECL(pj_status_t) pjsua_call_send_request(pjsua_call_id call_id,
5399 const pj_str_t *method,
5400 const pjsua_msg_data *msg_data);
5401
5402
5403/**
5404 * Terminate all calls. This will initiate #pjsua_call_hangup() for all
5405 * currently active calls.
5406 */
5407PJ_DECL(void) pjsua_call_hangup_all(void);
5408
5409
5410/**
5411 * Dump call and media statistics to string.
5412 *
5413 * @param call_id Call identification.
5414 * @param with_media Non-zero to include media information too.
5415 * @param buffer Buffer where the statistics are to be written to.
5416 * @param maxlen Maximum length of buffer.
5417 * @param indent Spaces for left indentation.
5418 *
5419 * @return PJ_SUCCESS on success.
5420 */
5421PJ_DECL(pj_status_t) pjsua_call_dump(pjsua_call_id call_id,
5422 pj_bool_t with_media,
5423 char *buffer,
5424 unsigned maxlen,
5425 const char *indent);
5426
5427/**
5428 * Get the media stream index of the default video stream in the call.
5429 * Typically this will just retrieve the stream index of the first
5430 * activated video stream in the call. If none is active, it will return
5431 * the first inactive video stream.
5432 *
5433 * @param call_id Call identification.
5434 *
5435 * @return The media stream index or -1 if no video stream
5436 * is present in the call.
5437 */
5438PJ_DECL(int) pjsua_call_get_vid_stream_idx(pjsua_call_id call_id);
5439
5440
5441/**
5442 * Determine if video stream for the specified call is currently running
5443 * (i.e. has been created, started, and not being paused) for the specified
5444 * direction.
5445 *
5446 * @param call_id Call identification.
5447 * @param med_idx Media stream index, or -1 to specify default video
5448 * media.
5449 * @param dir The direction to be checked.
5450 *
5451 * @return PJ_TRUE if stream is currently running for the
5452 * specified direction.
5453 */
5454PJ_DECL(pj_bool_t) pjsua_call_vid_stream_is_running(pjsua_call_id call_id,
5455 int med_idx,
5456 pjmedia_dir dir);
5457
5458/**
5459 * Add, remove, modify, and/or manipulate video media stream for the
5460 * specified call. This may trigger a re-INVITE or UPDATE to be sent
5461 * for the call.
5462 *
5463 * @param call_id Call identification.
5464 * @param op The video stream operation to be performed,
5465 * possible values are #pjsua_call_vid_strm_op.
5466 * @param param The parameters for the video stream operation,
5467 * or NULL for the default parameter values
5468 * (see #pjsua_call_vid_strm_op_param).
5469 *
5470 * @return PJ_SUCCESS on success or the appropriate error.
5471 */
5472PJ_DECL(pj_status_t) pjsua_call_set_vid_strm (
5473 pjsua_call_id call_id,
5474 pjsua_call_vid_strm_op op,
5475 const pjsua_call_vid_strm_op_param *param);
5476
5477
5478/**
5479 * Get media stream info for the specified media index.
5480 *
5481 * @param call_id The call identification.
5482 * @param med_idx Media stream index.
5483 * @param psi To be filled with the stream info.
5484 *
5485 * @return PJ_SUCCESS on success or the appropriate error.
5486 */
5487PJ_DECL(pj_status_t) pjsua_call_get_stream_info(pjsua_call_id call_id,
5488 unsigned med_idx,
5489 pjsua_stream_info *psi);
5490
5491/**
5492 * Get media stream statistic for the specified media index.
5493 *
5494 * @param call_id The call identification.
5495 * @param med_idx Media stream index.
5496 * @param psi To be filled with the stream statistic.
5497 *
5498 * @return PJ_SUCCESS on success or the appropriate error.
5499 */
5500PJ_DECL(pj_status_t) pjsua_call_get_stream_stat(pjsua_call_id call_id,
5501 unsigned med_idx,
5502 pjsua_stream_stat *stat);
5503
5504/**
5505 * Get media transport info for the specified media index.
5506 *
5507 * @param call_id The call identification.
5508 * @param med_idx Media stream index.
5509 * @param t To be filled with the transport info.
5510 *
5511 * @return PJ_SUCCESS on success or the appropriate error.
5512 */
5513PJ_DECL(pj_status_t)
5514pjsua_call_get_med_transport_info(pjsua_call_id call_id,
5515 unsigned med_idx,
5516 pjmedia_transport_info *t);
5517
5518
5519
5520/**
5521 * @}
5522 */
5523
5524
5525/*****************************************************************************
5526 * BUDDY API
5527 */
5528
5529
5530/**
5531 * @defgroup PJSUA_LIB_BUDDY PJSUA-API Buddy, Presence, and Instant Messaging
5532 * @ingroup PJSUA_LIB
5533 * @brief Buddy management, buddy's presence, and instant messaging.
5534 * @{
5535 *
5536 * This section describes PJSUA-APIs related to buddies management,
5537 * presence management, and instant messaging.
5538 */
5539
5540/**
5541 * Max buddies in buddy list.
5542 */
5543#ifndef PJSUA_MAX_BUDDIES
5544# define PJSUA_MAX_BUDDIES 256
5545#endif
5546
5547
5548/**
5549 * This specifies how long the library should wait before retrying failed
5550 * SUBSCRIBE request, and there is no rule to automatically resubscribe
5551 * (for example, no "retry-after" parameter in Subscription-State header).
5552 *
5553 * This also controls the duration before failed PUBLISH request will be
5554 * retried.
5555 *
5556 * Default: 300 seconds
5557 */
5558#ifndef PJSUA_PRES_TIMER
5559# define PJSUA_PRES_TIMER 300
5560#endif
5561
5562
5563/**
5564 * This structure describes buddy configuration when adding a buddy to
5565 * the buddy list with #pjsua_buddy_add(). Application MUST initialize
5566 * the structure with #pjsua_buddy_config_default() to initialize this
5567 * structure with default configuration.
5568 */
5569typedef struct pjsua_buddy_config
5570{
5571 /**
5572 * Buddy URL or name address.
5573 */
5574 pj_str_t uri;
5575
5576 /**
5577 * Specify whether presence subscription should start immediately.
5578 */
5579 pj_bool_t subscribe;
5580
5581 /**
5582 * Specify arbitrary application data to be associated with with
5583 * the buddy object.
5584 */
5585 void *user_data;
5586
5587} pjsua_buddy_config;
5588
5589
5590/**
5591 * This enumeration describes basic buddy's online status.
5592 */
5593typedef enum pjsua_buddy_status
5594{
5595 /**
5596 * Online status is unknown (possibly because no presence subscription
5597 * has been established).
5598 */
5599 PJSUA_BUDDY_STATUS_UNKNOWN,
5600
5601 /**
5602 * Buddy is known to be online.
5603 */
5604 PJSUA_BUDDY_STATUS_ONLINE,
5605
5606 /**
5607 * Buddy is offline.
5608 */
5609 PJSUA_BUDDY_STATUS_OFFLINE,
5610
5611} pjsua_buddy_status;
5612
5613
5614
5615/**
5616 * This structure describes buddy info, which can be retrieved by calling
5617 * #pjsua_buddy_get_info().
5618 */
5619typedef struct pjsua_buddy_info
5620{
5621 /**
5622 * The buddy ID.
5623 */
5624 pjsua_buddy_id id;
5625
5626 /**
5627 * The full URI of the buddy, as specified in the configuration.
5628 */
5629 pj_str_t uri;
5630
5631 /**
5632 * Buddy's Contact, only available when presence subscription has
5633 * been established to the buddy.
5634 */
5635 pj_str_t contact;
5636
5637 /**
5638 * Buddy's online status.
5639 */
5640 pjsua_buddy_status status;
5641
5642 /**
5643 * Text to describe buddy's online status.
5644 */
5645 pj_str_t status_text;
5646
5647 /**
5648 * Flag to indicate that we should monitor the presence information for
5649 * this buddy (normally yes, unless explicitly disabled).
5650 */
5651 pj_bool_t monitor_pres;
5652
5653 /**
5654 * If \a monitor_pres is enabled, this specifies the last state of the
5655 * presence subscription. If presence subscription session is currently
5656 * active, the value will be PJSIP_EVSUB_STATE_ACTIVE. If presence
5657 * subscription request has been rejected, the value will be
5658 * PJSIP_EVSUB_STATE_TERMINATED, and the termination reason will be
5659 * specified in \a sub_term_reason.
5660 */
5661 pjsip_evsub_state sub_state;
5662
5663 /**
5664 * String representation of subscription state.
5665 */
5666 const char *sub_state_name;
5667
5668 /**
5669 * Specifies the last presence subscription termination code. This would
5670 * return the last status of the SUBSCRIBE request. If the subscription
5671 * is terminated with NOTIFY by the server, this value will be set to
5672 * 200, and subscription termination reason will be given in the
5673 * \a sub_term_reason field.
5674 */
5675 unsigned sub_term_code;
5676
5677 /**
5678 * Specifies the last presence subscription termination reason. If
5679 * presence subscription is currently active, the value will be empty.
5680 */
5681 pj_str_t sub_term_reason;
5682
5683 /**
5684 * Extended RPID information about the person.
5685 */
5686 pjrpid_element rpid;
5687
5688 /**
5689 * Extended presence info.
5690 */
5691 pjsip_pres_status pres_status;
5692
5693 /**
5694 * Internal buffer.
5695 */
5696 char buf_[512];
5697
5698} pjsua_buddy_info;
5699
5700
5701/**
5702 * Set default values to the buddy config.
5703 */
5704PJ_DECL(void) pjsua_buddy_config_default(pjsua_buddy_config *cfg);
5705
5706
5707/**
5708 * Get total number of buddies.
5709 *
5710 * @return Number of buddies.
5711 */
5712PJ_DECL(unsigned) pjsua_get_buddy_count(void);
5713
5714
5715/**
5716 * Check if buddy ID is valid.
5717 *
5718 * @param buddy_id Buddy ID to check.
5719 *
5720 * @return Non-zero if buddy ID is valid.
5721 */
5722PJ_DECL(pj_bool_t) pjsua_buddy_is_valid(pjsua_buddy_id buddy_id);
5723
5724
5725/**
5726 * Enumerate all buddy IDs in the buddy list. Application then can use
5727 * #pjsua_buddy_get_info() to get the detail information for each buddy
5728 * id.
5729 *
5730 * @param ids Array of ids to be initialized.
5731 * @param count On input, specifies max elements in the array.
5732 * On return, it contains actual number of elements
5733 * that have been initialized.
5734 *
5735 * @return PJ_SUCCESS on success, or the appropriate error code.
5736 */
5737PJ_DECL(pj_status_t) pjsua_enum_buddies(pjsua_buddy_id ids[],
5738 unsigned *count);
5739
5740/**
5741 * Find the buddy ID with the specified URI.
5742 *
5743 * @param uri The buddy URI.
5744 *
5745 * @return The buddy ID, or PJSUA_INVALID_ID if not found.
5746 */
5747PJ_DECL(pjsua_buddy_id) pjsua_buddy_find(const pj_str_t *uri);
5748
5749
5750/**
5751 * Get detailed buddy info.
5752 *
5753 * @param buddy_id The buddy identification.
5754 * @param info Pointer to receive information about buddy.
5755 *
5756 * @return PJ_SUCCESS on success, or the appropriate error code.
5757 */
5758PJ_DECL(pj_status_t) pjsua_buddy_get_info(pjsua_buddy_id buddy_id,
5759 pjsua_buddy_info *info);
5760
5761/**
5762 * Set the user data associated with the buddy object.
5763 *
5764 * @param buddy_id The buddy identification.
5765 * @param user_data Arbitrary application data to be associated with
5766 * the buddy object.
5767 *
5768 * @return PJ_SUCCESS on success, or the appropriate error code.
5769 */
5770PJ_DECL(pj_status_t) pjsua_buddy_set_user_data(pjsua_buddy_id buddy_id,
5771 void *user_data);
5772
5773
5774/**
5775 * Get the user data associated with the budy object.
5776 *
5777 * @param buddy_id The buddy identification.
5778 *
5779 * @return The application data.
5780 */
5781PJ_DECL(void*) pjsua_buddy_get_user_data(pjsua_buddy_id buddy_id);
5782
5783
5784/**
5785 * Add new buddy to the buddy list. If presence subscription is enabled
5786 * for this buddy, this function will also start the presence subscription
5787 * session immediately.
5788 *
5789 * @param buddy_cfg Buddy configuration.
5790 * @param p_buddy_id Pointer to receive buddy ID.
5791 *
5792 * @return PJ_SUCCESS on success, or the appropriate error code.
5793 */
5794PJ_DECL(pj_status_t) pjsua_buddy_add(const pjsua_buddy_config *buddy_cfg,
5795 pjsua_buddy_id *p_buddy_id);
5796
5797
5798/**
5799 * Delete the specified buddy from the buddy list. Any presence subscription
5800 * to this buddy will be terminated.
5801 *
5802 * @param buddy_id Buddy identification.
5803 *
5804 * @return PJ_SUCCESS on success, or the appropriate error code.
5805 */
5806PJ_DECL(pj_status_t) pjsua_buddy_del(pjsua_buddy_id buddy_id);
5807
5808
5809/**
5810 * Enable/disable buddy's presence monitoring. Once buddy's presence is
5811 * subscribed, application will be informed about buddy's presence status
5812 * changed via \a on_buddy_state() callback.
5813 *
5814 * @param buddy_id Buddy identification.
5815 * @param subscribe Specify non-zero to activate presence subscription to
5816 * the specified buddy.
5817 *
5818 * @return PJ_SUCCESS on success, or the appropriate error code.
5819 */
5820PJ_DECL(pj_status_t) pjsua_buddy_subscribe_pres(pjsua_buddy_id buddy_id,
5821 pj_bool_t subscribe);
5822
5823
5824/**
5825 * Update the presence information for the buddy. Although the library
5826 * periodically refreshes the presence subscription for all buddies, some
5827 * application may want to refresh the buddy's presence subscription
5828 * immediately, and in this case it can use this function to accomplish
5829 * this.
5830 *
5831 * Note that the buddy's presence subscription will only be initiated
5832 * if presence monitoring is enabled for the buddy. See
5833 * #pjsua_buddy_subscribe_pres() for more info. Also if presence subscription
5834 * for the buddy is already active, this function will not do anything.
5835 *
5836 * Once the presence subscription is activated successfully for the buddy,
5837 * application will be notified about the buddy's presence status in the
5838 * on_buddy_state() callback.
5839 *
5840 * @param buddy_id Buddy identification.
5841 *
5842 * @return PJ_SUCCESS on success, or the appropriate error code.
5843 */
5844PJ_DECL(pj_status_t) pjsua_buddy_update_pres(pjsua_buddy_id buddy_id);
5845
5846
5847/**
5848 * Send NOTIFY to inform account presence status or to terminate server
5849 * side presence subscription. If application wants to reject the incoming
5850 * request, it should set the \a state to PJSIP_EVSUB_STATE_TERMINATED.
5851 *
5852 * @param acc_id Account ID.
5853 * @param srv_pres Server presence subscription instance.
5854 * @param state New state to set.
5855 * @param state_str Optionally specify the state string name, if state
5856 * is not "active", "pending", or "terminated".
5857 * @param reason If the new state is PJSIP_EVSUB_STATE_TERMINATED,
5858 * optionally specify the termination reason.
5859 * @param with_body If the new state is PJSIP_EVSUB_STATE_TERMINATED,
5860 * this specifies whether the NOTIFY request should
5861 * contain message body containing account's presence
5862 * information.
5863 * @param msg_data Optional list of headers to be sent with the NOTIFY
5864 * request.
5865 *
5866 * @return PJ_SUCCESS on success.
5867 */
5868PJ_DECL(pj_status_t) pjsua_pres_notify(pjsua_acc_id acc_id,
5869 pjsua_srv_pres *srv_pres,
5870 pjsip_evsub_state state,
5871 const pj_str_t *state_str,
5872 const pj_str_t *reason,
5873 pj_bool_t with_body,
5874 const pjsua_msg_data *msg_data);
5875
5876/**
5877 * Dump presence subscriptions to log.
5878 *
5879 * @param verbose Yes or no.
5880 */
5881PJ_DECL(void) pjsua_pres_dump(pj_bool_t verbose);
5882
5883
5884/**
5885 * The MESSAGE method (defined in pjsua_im.c)
5886 */
5887extern const pjsip_method pjsip_message_method;
5888
5889
5890/**
5891 * The INFO method (defined in pjsua_call.c)
5892 */
5893extern const pjsip_method pjsip_info_method;
5894
5895
5896/**
5897 * Send instant messaging outside dialog, using the specified account for
5898 * route set and authentication.
5899 *
5900 * @param acc_id Account ID to be used to send the request.
5901 * @param to Remote URI.
5902 * @param mime_type Optional MIME type. If NULL, then "text/plain" is
5903 * assumed.
5904 * @param content The message content.
5905 * @param msg_data Optional list of headers etc to be included in outgoing
5906 * request. The body descriptor in the msg_data is
5907 * ignored.
5908 * @param user_data Optional user data, which will be given back when
5909 * the IM callback is called.
5910 *
5911 * @return PJ_SUCCESS on success, or the appropriate error code.
5912 */
5913PJ_DECL(pj_status_t) pjsua_im_send(pjsua_acc_id acc_id,
5914 const pj_str_t *to,
5915 const pj_str_t *mime_type,
5916 const pj_str_t *content,
5917 const pjsua_msg_data *msg_data,
5918 void *user_data);
5919
5920
5921/**
5922 * Send typing indication outside dialog.
5923 *
5924 * @param acc_id Account ID to be used to send the request.
5925 * @param to Remote URI.
5926 * @param is_typing If non-zero, it tells remote person that local person
5927 * is currently composing an IM.
5928 * @param msg_data Optional list of headers etc to be added to outgoing
5929 * request.
5930 *
5931 * @return PJ_SUCCESS on success, or the appropriate error code.
5932 */
5933PJ_DECL(pj_status_t) pjsua_im_typing(pjsua_acc_id acc_id,
5934 const pj_str_t *to,
5935 pj_bool_t is_typing,
5936 const pjsua_msg_data *msg_data);
5937
5938
5939
5940/**
5941 * @}
5942 */
5943
5944
5945/*****************************************************************************
5946 * MEDIA API
5947 */
5948
5949
5950/**
5951 * @defgroup PJSUA_LIB_MEDIA PJSUA-API Media Manipulation
5952 * @ingroup PJSUA_LIB
5953 * @brief Media manipulation.
5954 * @{
5955 *
5956 * PJSUA has rather powerful media features, which are built around the
5957 * PJMEDIA conference bridge. Basically, all media "ports" (such as calls, WAV
5958 * players, WAV playlist, file recorders, sound device, tone generators, etc)
5959 * are terminated in the conference bridge, and application can manipulate
5960 * the interconnection between these terminations freely.
5961 *
5962 * The conference bridge provides powerful switching and mixing functionality
5963 * for application. With the conference bridge, each conference slot (e.g.
5964 * a call) can transmit to multiple destinations, and one destination can
5965 * receive from multiple sources. If more than one media terminations are
5966 * terminated in the same slot, the conference bridge will mix the signal
5967 * automatically.
5968 *
5969 * Application connects one media termination/slot to another by calling
5970 * #pjsua_conf_connect() function. This will establish <b>unidirectional</b>
5971 * media flow from the source termination to the sink termination. To
5972 * establish bidirectional media flow, application wound need to make another
5973 * call to #pjsua_conf_connect(), this time inverting the source and
5974 * destination slots in the parameter.
5975 *
5976 * For example, to stream a WAV file to remote call, application may use
5977 * the following steps:
5978 *
5979 \code
5980
5981 pj_status_t stream_to_call( pjsua_call_id call_id )
5982 {
5983 pjsua_player_id player_id;
5984
5985 status = pjsua_player_create("mysong.wav", 0, &player_id);
5986 if (status != PJ_SUCCESS)
5987 return status;
5988
5989 status = pjsua_conf_connect( pjsua_player_get_conf_port(),
5990 pjsua_call_get_conf_port() );
5991 }
5992 \endcode
5993 *
5994 *
5995 * Other features of PJSUA media:
5996 * - efficient N to M interconnections between media terminations.
5997 * - media termination can be connected to itself to create loopback
5998 * media.
5999 * - the media termination may have different clock rates, and resampling
6000 * will be done automatically by conference bridge.
6001 * - media terminations may also have different frame time; the
6002 * conference bridge will perform the necessary bufferring to adjust
6003 * the difference between terminations.
6004 * - interconnections are removed automatically when media termination
6005 * is removed from the bridge.
6006 * - sound device may be changed even when there are active media
6007 * interconnections.
6008 * - correctly report call's media quality (in #pjsua_call_dump()) from
6009 * RTCP packet exchange.
6010 */
6011
6012/**
6013 * Use PJMEDIA for media? Set this to zero when using third party media
6014 * stack.
6015 */
6016#ifndef PJSUA_MEDIA_HAS_PJMEDIA
6017# define PJSUA_MEDIA_HAS_PJMEDIA 1
6018#endif /* PJSUA_MEDIA_HAS_PJMEDIA */
6019
6020
6021/**
6022 * Specify whether the third party stream has the capability of retrieving
6023 * the stream info, i.e: pjmedia_stream_get_info() and
6024 * pjmedia_vid_stream_get_info(). Currently this capability is required
6025 * by smart media update and call dump.
6026 */
6027#ifndef PJSUA_THIRD_PARTY_STREAM_HAS_GET_INFO
6028# define PJSUA_THIRD_PARTY_STREAM_HAS_GET_INFO 0
6029#endif
6030
6031
6032/**
6033 * Specify whether the third party stream has the capability of retrieving
6034 * the stream statistics, i.e: pjmedia_stream_get_stat() and
6035 * pjmedia_vid_stream_get_stat(). Currently this capability is required
6036 * by call dump.
6037 */
6038#ifndef PJSUA_THIRD_PARTY_STREAM_HAS_GET_STAT
6039# define PJSUA_THIRD_PARTY_STREAM_HAS_GET_STAT 0
6040#endif
6041
6042
6043/**
6044 * Max ports in the conference bridge. This setting is the default value
6045 * for pjsua_media_config.max_media_ports.
6046 */
6047#ifndef PJSUA_MAX_CONF_PORTS
6048# define PJSUA_MAX_CONF_PORTS 254
6049#endif
6050
6051/**
6052 * The default clock rate to be used by the conference bridge. This setting
6053 * is the default value for pjsua_media_config.clock_rate.
6054 */
6055#ifndef PJSUA_DEFAULT_CLOCK_RATE
6056# define PJSUA_DEFAULT_CLOCK_RATE 16000
6057#endif
6058
6059/**
6060 * Default frame length in the conference bridge. This setting
6061 * is the default value for pjsua_media_config.audio_frame_ptime.
6062 */
6063#ifndef PJSUA_DEFAULT_AUDIO_FRAME_PTIME
6064# define PJSUA_DEFAULT_AUDIO_FRAME_PTIME 20
6065#endif
6066
6067
6068/**
6069 * Default codec quality settings. This setting is the default value
6070 * for pjsua_media_config.quality.
6071 */
6072#ifndef PJSUA_DEFAULT_CODEC_QUALITY
6073# define PJSUA_DEFAULT_CODEC_QUALITY 8
6074#endif
6075
6076/**
6077 * Default iLBC mode. This setting is the default value for
6078 * pjsua_media_config.ilbc_mode.
6079 */
6080#ifndef PJSUA_DEFAULT_ILBC_MODE
6081# define PJSUA_DEFAULT_ILBC_MODE 30
6082#endif
6083
6084/**
6085 * The default echo canceller tail length. This setting
6086 * is the default value for pjsua_media_config.ec_tail_len.
6087 */
6088#ifndef PJSUA_DEFAULT_EC_TAIL_LEN
6089# define PJSUA_DEFAULT_EC_TAIL_LEN 200
6090#endif
6091
6092
6093/**
6094 * The maximum file player.
6095 */
6096#ifndef PJSUA_MAX_PLAYERS
6097# define PJSUA_MAX_PLAYERS 32
6098#endif
6099
6100
6101/**
6102 * The maximum file player.
6103 */
6104#ifndef PJSUA_MAX_RECORDERS
6105# define PJSUA_MAX_RECORDERS 32
6106#endif
6107
6108
6109/**
6110 * Enable/disable "c=" line in SDP session level. Set to zero to disable it.
6111 */
6112#ifndef PJSUA_SDP_SESS_HAS_CONN
6113# define PJSUA_SDP_SESS_HAS_CONN 0
6114#endif
6115
6116
6117/**
6118 * Specify the delay needed when restarting the transport/listener.
6119 * e.g: 10 msec on Linux or Android, and 0 on the other platforms.
6120 */
6121#ifndef PJSUA_TRANSPORT_RESTART_DELAY_TIME
6122# define PJSUA_TRANSPORT_RESTART_DELAY_TIME 10
6123#endif
6124
6125
6126/**
6127 * This structure describes media configuration, which will be specified
6128 * when calling #pjsua_init(). Application MUST initialize this structure
6129 * by calling #pjsua_media_config_default().
6130 */
6131struct pjsua_media_config
6132{
6133 /**
6134 * Clock rate to be applied to the conference bridge.
6135 * If value is zero, default clock rate will be used
6136 * (PJSUA_DEFAULT_CLOCK_RATE, which by default is 16KHz).
6137 */
6138 unsigned clock_rate;
6139
6140 /**
6141 * Clock rate to be applied when opening the sound device.
6142 * If value is zero, conference bridge clock rate will be used.
6143 */
6144 unsigned snd_clock_rate;
6145
6146 /**
6147 * Channel count be applied when opening the sound device and
6148 * conference bridge.
6149 */
6150 unsigned channel_count;
6151
6152 /**
6153 * Specify audio frame ptime. The value here will affect the
6154 * samples per frame of both the sound device and the conference
6155 * bridge. Specifying lower ptime will normally reduce the
6156 * latency.
6157 *
6158 * Default value: PJSUA_DEFAULT_AUDIO_FRAME_PTIME
6159 */
6160 unsigned audio_frame_ptime;
6161
6162 /**
6163 * Specify maximum number of media ports to be created in the
6164 * conference bridge. Since all media terminate in the bridge
6165 * (calls, file player, file recorder, etc), the value must be
6166 * large enough to support all of them. However, the larger
6167 * the value, the more computations are performed.
6168 *
6169 * Default value: PJSUA_MAX_CONF_PORTS
6170 */
6171 unsigned max_media_ports;
6172
6173 /**
6174 * Specify whether the media manager should manage its own
6175 * ioqueue for the RTP/RTCP sockets. If yes, ioqueue will be created
6176 * and at least one worker thread will be created too. If no,
6177 * the RTP/RTCP sockets will share the same ioqueue as SIP sockets,
6178 * and no worker thread is needed.
6179 *
6180 * Normally application would say yes here, unless it wants to
6181 * run everything from a single thread.
6182 */
6183 pj_bool_t has_ioqueue;
6184
6185 /**
6186 * Specify the number of worker threads to handle incoming RTP
6187 * packets. A value of one is recommended for most applications.
6188 */
6189 unsigned thread_cnt;
6190
6191 /**
6192 * Media quality, 0-10, according to this table:
6193 * 5-10: resampling use large filter,
6194 * 3-4: resampling use small filter,
6195 * 1-2: resampling use linear.
6196 * The media quality also sets speex codec quality/complexity to the
6197 * number.
6198 *
6199 * Default: 5 (PJSUA_DEFAULT_CODEC_QUALITY).
6200 */
6201 unsigned quality;
6202
6203 /**
6204 * Specify default codec ptime.
6205 *
6206 * Default: 0 (codec specific)
6207 */
6208 unsigned ptime;
6209
6210 /**
6211 * Disable VAD?
6212 *
6213 * Default: 0 (no (meaning VAD is enabled))
6214 */
6215 pj_bool_t no_vad;
6216
6217 /**
6218 * iLBC mode (20 or 30).
6219 *
6220 * Default: 30 (PJSUA_DEFAULT_ILBC_MODE)
6221 */
6222 unsigned ilbc_mode;
6223
6224 /**
6225 * Percentage of RTP packet to drop in TX direction
6226 * (to simulate packet lost).
6227 *
6228 * Default: 0
6229 */
6230 unsigned tx_drop_pct;
6231
6232 /**
6233 * Percentage of RTP packet to drop in RX direction
6234 * (to simulate packet lost).
6235 *
6236 * Default: 0
6237 */
6238 unsigned rx_drop_pct;
6239
6240 /**
6241 * Echo canceller options (see #pjmedia_echo_create())
6242 *
6243 * Default: 0.
6244 */
6245 unsigned ec_options;
6246
6247 /**
6248 * Echo canceller tail length, in miliseconds.
6249 *
6250 * Default: PJSUA_DEFAULT_EC_TAIL_LEN
6251 */
6252 unsigned ec_tail_len;
6253
6254 /**
6255 * Audio capture buffer length, in milliseconds.
6256 *
6257 * Default: PJMEDIA_SND_DEFAULT_REC_LATENCY
6258 */
6259 unsigned snd_rec_latency;
6260
6261 /**
6262 * Audio playback buffer length, in milliseconds.
6263 *
6264 * Default: PJMEDIA_SND_DEFAULT_PLAY_LATENCY
6265 */
6266 unsigned snd_play_latency;
6267
6268 /**
6269 * Jitter buffer initial prefetch delay in msec. The value must be
6270 * between jb_min_pre and jb_max_pre below. If the value is 0,
6271 * prefetching will be disabled.
6272 *
6273 * Default: -1 (to use default stream settings, currently 0)
6274 */
6275 int jb_init;
6276
6277 /**
6278 * Jitter buffer minimum prefetch delay in msec.
6279 *
6280 * Default: -1 (to use default stream settings, currently 60 msec)
6281 */
6282 int jb_min_pre;
6283
6284 /**
6285 * Jitter buffer maximum prefetch delay in msec.
6286 *
6287 * Default: -1 (to use default stream settings, currently 240 msec)
6288 */
6289 int jb_max_pre;
6290
6291 /**
6292 * Set maximum delay that can be accomodated by the jitter buffer msec.
6293 *
6294 * Default: -1 (to use default stream settings, currently 360 msec)
6295 */
6296 int jb_max;
6297
6298 /**
6299 * Enable ICE
6300 */
6301 pj_bool_t enable_ice;
6302
6303 /**
6304 * Set the maximum number of host candidates.
6305 *
6306 * Default: -1 (maximum not set)
6307 */
6308 int ice_max_host_cands;
6309
6310 /**
6311 * ICE session options.
6312 */
6313 pj_ice_sess_options ice_opt;
6314
6315 /**
6316 * Disable RTCP component.
6317 *
6318 * Default: no
6319 */
6320 pj_bool_t ice_no_rtcp;
6321
6322 /**
6323 * Send re-INVITE/UPDATE every after ICE connectivity check regardless
6324 * the default ICE transport address is changed or not. When this is set
6325 * to PJ_FALSE, re-INVITE/UPDATE will be sent only when the default ICE
6326 * transport address is changed.
6327 *
6328 * Default: yes
6329 */
6330 pj_bool_t ice_always_update;
6331
6332 /**
6333 * Enable TURN relay candidate in ICE.
6334 */
6335 pj_bool_t enable_turn;
6336
6337 /**
6338 * Specify TURN domain name or host name, in in "DOMAIN:PORT" or
6339 * "HOST:PORT" format.
6340 */
6341 pj_str_t turn_server;
6342
6343 /**
6344 * Specify the connection type to be used to the TURN server. Valid
6345 * values are PJ_TURN_TP_UDP or PJ_TURN_TP_TCP.
6346 *
6347 * Default: PJ_TURN_TP_UDP
6348 */
6349 pj_turn_tp_type turn_conn_type;
6350
6351 /**
6352 * Specify the credential to authenticate with the TURN server.
6353 */
6354 pj_stun_auth_cred turn_auth_cred;
6355
6356 /**
6357 * Specify idle time of sound device before it is automatically closed,
6358 * in seconds. Use value -1 to disable the auto-close feature of sound
6359 * device
6360 *
6361 * Default : 1
6362 */
6363 int snd_auto_close_time;
6364
6365 /**
6366 * Specify whether built-in/native preview should be used if available.
6367 * In some systems, video input devices have built-in capability to show
6368 * preview window of the device. Using this built-in preview is preferable
6369 * as it consumes less CPU power. If built-in preview is not available,
6370 * the library will perform software rendering of the input. If this
6371 * field is set to PJ_FALSE, software preview will always be used.
6372 *
6373 * Default: PJ_TRUE
6374 */
6375 pj_bool_t vid_preview_enable_native;
6376
6377 /**
6378 * Disable smart media update (ticket #1568). The smart media update
6379 * will check for any changes in the media properties after a successful
6380 * SDP negotiation and the media will only be reinitialized when any
6381 * change is found. When it is disabled, media streams will always be
6382 * reinitialized after a successful SDP negotiation.
6383 *
6384 * Note for third party media, the smart media update requires stream info
6385 * retrieval capability, see #PJSUA_THIRD_PARTY_STREAM_HAS_GET_INFO.
6386 *
6387 * Default: PJ_FALSE
6388 */
6389 pj_bool_t no_smart_media_update;
6390
6391 /**
6392 * Omit RTCP SDES and BYE in outgoing RTCP packet, this setting will be
6393 * applied for both audio and video streams. Note that, when RTCP SDES
6394 * and BYE are set to be omitted, RTCP SDES will still be sent once when
6395 * the stream starts/stops and RTCP BYE will be sent once when the stream
6396 * stops.
6397 *
6398 * Default: PJ_FALSE
6399 */
6400 pj_bool_t no_rtcp_sdes_bye;
6401
6402 /**
6403 * Optional callback for audio frame preview right before queued to
6404 * the speaker.
6405 * Notes:
6406 * - application MUST NOT block or perform long operation in the callback
6407 * as the callback may be executed in sound device thread
6408 * - when using software echo cancellation, application MUST NOT modify
6409 * the audio data from within the callback, otherwise the echo canceller
6410 * will not work properly.
6411 */
6412 void (*on_aud_prev_play_frame)(pjmedia_frame *frame);
6413
6414 /**
6415 * Optional callback for audio frame preview recorded from the microphone
6416 * before being processed by any media component such as software echo
6417 * canceller.
6418 * Notes:
6419 * - application MUST NOT block or perform long operation in the callback
6420 * as the callback may be executed in sound device thread
6421 * - when using software echo cancellation, application MUST NOT modify
6422 * the audio data from within the callback, otherwise the echo canceller
6423 * will not work properly.
6424 */
6425 void (*on_aud_prev_rec_frame)(pjmedia_frame *frame);
6426};
6427
6428
6429/**
6430 * Use this function to initialize media config.
6431 *
6432 * @param cfg The media config to be initialized.
6433 */
6434PJ_DECL(void) pjsua_media_config_default(pjsua_media_config *cfg);
6435
6436
6437/**
6438 * This structure describes codec information, which can be retrieved by
6439 * calling #pjsua_enum_codecs().
6440 */
6441typedef struct pjsua_codec_info
6442{
6443 /**
6444 * Codec unique identification.
6445 */
6446 pj_str_t codec_id;
6447
6448 /**
6449 * Codec priority (integer 0-255).
6450 */
6451 pj_uint8_t priority;
6452
6453 /**
6454 * Codec description.
6455 */
6456 pj_str_t desc;
6457
6458 /**
6459 * Internal buffer.
6460 */
6461 char buf_[64];
6462
6463} pjsua_codec_info;
6464
6465
6466/**
6467 * This structure descibes information about a particular media port that
6468 * has been registered into the conference bridge. Application can query
6469 * this info by calling #pjsua_conf_get_port_info().
6470 */
6471typedef struct pjsua_conf_port_info
6472{
6473 /** Conference port number. */
6474 pjsua_conf_port_id slot_id;
6475
6476 /** Port name. */
6477 pj_str_t name;
6478
6479 /** Format. */
6480 pjmedia_format format;
6481
6482 /** Clock rate. */
6483 unsigned clock_rate;
6484
6485 /** Number of channels. */
6486 unsigned channel_count;
6487
6488 /** Samples per frame */
6489 unsigned samples_per_frame;
6490
6491 /** Bits per sample */
6492 unsigned bits_per_sample;
6493
6494 /** Tx level adjustment. */
6495 float tx_level_adj;
6496
6497 /** Rx level adjustment. */
6498 float rx_level_adj;
6499
6500 /** Number of listeners in the array. */
6501 unsigned listener_cnt;
6502
6503 /** Array of listeners (in other words, ports where this port is
6504 * transmitting to.
6505 */
6506 pjsua_conf_port_id listeners[PJSUA_MAX_CONF_PORTS];
6507
6508} pjsua_conf_port_info;
6509
6510
6511/**
6512 * This structure holds information about custom media transport to
6513 * be registered to pjsua.
6514 */
6515typedef struct pjsua_media_transport
6516{
6517 /**
6518 * Media socket information containing the address information
6519 * of the RTP and RTCP socket.
6520 */
6521 pjmedia_sock_info skinfo;
6522
6523 /**
6524 * The media transport instance.
6525 */
6526 pjmedia_transport *transport;
6527
6528} pjsua_media_transport;
6529
6530
6531/**
6532 * Sound device index constants.
6533 */
6534typedef enum pjsua_snd_dev_id
6535{
6536 /**
6537 * Constant to denote default capture device.
6538 */
6539 PJSUA_SND_DEFAULT_CAPTURE_DEV = PJMEDIA_AUD_DEFAULT_CAPTURE_DEV,
6540
6541 /**
6542 * Constant to denote default playback device.
6543 */
6544 PJSUA_SND_DEFAULT_PLAYBACK_DEV = PJMEDIA_AUD_DEFAULT_PLAYBACK_DEV,
6545
6546 /**
6547 * Constant to denote that no sound device is being used.
6548 */
6549 PJSUA_SND_NO_DEV = PJMEDIA_AUD_INVALID_DEV,
6550
6551 /**
6552 * Constant to denote null sound device.
6553 */
6554 PJSUA_SND_NULL_DEV = -99
6555
6556} pjsua_snd_dev_id;
6557
6558/**
6559 * This enumeration specifies the sound device mode.
6560 */
6561typedef enum pjsua_snd_dev_mode
6562{
6563 /**
6564 * Open sound device without mic (speaker only).
6565 */
6566 PJSUA_SND_DEV_SPEAKER_ONLY = 1,
6567
6568 /**
6569 * Do not open sound device, after setting the sound device.
6570 */
6571 PJSUA_SND_DEV_NO_IMMEDIATE_OPEN = 2
6572
6573} pjsua_snd_dev_mode;
6574
6575
6576/**
6577 * This structure specifies the parameters to set the sound device.
6578 * Use pjsua_snd_dev_param_default() to initialize this structure with
6579 * default values.
6580 */
6581typedef struct pjsua_snd_dev_param
6582{
6583 /*
6584 * Capture dev id.
6585 *
6586 * Default: PJMEDIA_AUD_DEFAULT_CAPTURE_DEV
6587 */
6588 int capture_dev;
6589
6590 /*
6591 * Playback dev id.
6592 *
6593 * Default: PJMEDIA_AUD_DEFAULT_PLAYBACK_DEV
6594 */
6595 int playback_dev;
6596
6597 /*
6598 * Sound device mode, refer to #pjsua_snd_dev_mode.
6599 *
6600 * Default: 0
6601 */
6602 unsigned mode;
6603
6604} pjsua_snd_dev_param;
6605
6606
6607/**
6608 * Initialize pjsua_snd_dev_param with default values.
6609 *
6610 * @param prm The parameter.
6611 */
6612PJ_DECL(void) pjsua_snd_dev_param_default(pjsua_snd_dev_param *prm);
6613
6614
6615/**
6616 * This structure specifies the parameters for conference ports connection.
6617 * Use pjsua_conf_connect_param_default() to initialize this structure with
6618 * default values.
6619 */
6620typedef struct pjsua_conf_connect_param
6621{
6622 /*
6623 * Signal level adjustment from the source to the sink to make it
6624 * louder or quieter. Value 1.0 means no level adjustment,
6625 * while value 0 means to mute the port.
6626 *
6627 * Default: 1.0
6628 */
6629 float level;
6630
6631} pjsua_conf_connect_param;
6632
6633
6634/**
6635 * Initialize pjsua_conf_connect_param with default values.
6636 *
6637 * @param prm The parameter.
6638 */
6639PJ_DECL(void) pjsua_conf_connect_param_default(pjsua_conf_connect_param *prm);
6640
6641
6642/**
6643 * Get maxinum number of conference ports.
6644 *
6645 * @return Maximum number of ports in the conference bridge.
6646 */
6647PJ_DECL(unsigned) pjsua_conf_get_max_ports(void);
6648
6649
6650/**
6651 * Get current number of active ports in the bridge.
6652 *
6653 * @return The number.
6654 */
6655PJ_DECL(unsigned) pjsua_conf_get_active_ports(void);
6656
6657
6658/**
6659 * Enumerate all conference ports.
6660 *
6661 * @param id Array of conference port ID to be initialized.
6662 * @param count On input, specifies max elements in the array.
6663 * On return, it contains actual number of elements
6664 * that have been initialized.
6665 *
6666 * @return PJ_SUCCESS on success, or the appropriate error code.
6667 */
6668PJ_DECL(pj_status_t) pjsua_enum_conf_ports(pjsua_conf_port_id id[],
6669 unsigned *count);
6670
6671
6672/**
6673 * Get information about the specified conference port
6674 *
6675 * @param port_id Port identification.
6676 * @param info Pointer to store the port info.
6677 *
6678 * @return PJ_SUCCESS on success, or the appropriate error code.
6679 */
6680PJ_DECL(pj_status_t) pjsua_conf_get_port_info( pjsua_conf_port_id port_id,
6681 pjsua_conf_port_info *info);
6682
6683
6684/**
6685 * Add arbitrary media port to PJSUA's conference bridge. Application
6686 * can use this function to add the media port that it creates. For
6687 * media ports that are created by PJSUA-LIB (such as calls, file player,
6688 * or file recorder), PJSUA-LIB will automatically add the port to
6689 * the bridge.
6690 *
6691 * @param pool Pool to use.
6692 * @param port Media port to be added to the bridge.
6693 * @param p_id Optional pointer to receive the conference
6694 * slot id.
6695 *
6696 * @return PJ_SUCCESS on success, or the appropriate error code.
6697 */
6698PJ_DECL(pj_status_t) pjsua_conf_add_port(pj_pool_t *pool,
6699 pjmedia_port *port,
6700 pjsua_conf_port_id *p_id);
6701
6702
6703/**
6704 * Remove arbitrary slot from the conference bridge. Application should only
6705 * call this function if it registered the port manually with previous call
6706 * to #pjsua_conf_add_port().
6707 *
6708 * @param port_id The slot id of the port to be removed.
6709 *
6710 * @return PJ_SUCCESS on success, or the appropriate error code.
6711 */
6712PJ_DECL(pj_status_t) pjsua_conf_remove_port(pjsua_conf_port_id port_id);
6713
6714
6715/**
6716 * Establish unidirectional media flow from souce to sink. One source
6717 * may transmit to multiple destinations/sink. And if multiple
6718 * sources are transmitting to the same sink, the media will be mixed
6719 * together. Source and sink may refer to the same ID, effectively
6720 * looping the media.
6721 *
6722 * If bidirectional media flow is desired, application needs to call
6723 * this function twice, with the second one having the arguments
6724 * reversed.
6725 *
6726 * @param source Port ID of the source media/transmitter.
6727 * @param sink Port ID of the destination media/received.
6728 *
6729 * @return PJ_SUCCESS on success, or the appropriate error code.
6730 */
6731PJ_DECL(pj_status_t) pjsua_conf_connect(pjsua_conf_port_id source,
6732 pjsua_conf_port_id sink);
6733
6734/**
6735 * Establish unidirectional media flow from source to sink. One source
6736 * may transmit to multiple destinations/sink. And if multiple
6737 * sources are transmitting to the same sink, the media will be mixed
6738 * together. Source and sink may refer to the same ID, effectively
6739 * looping the media.
6740 *
6741 * Signal level from the source to the sink can be adjusted by making
6742 * it louder or quieter via the parameter param. The level adjustment
6743 * will apply to a specific connection only (i.e. only for the signal
6744 * from the source to the sink), as compared to
6745 * pjsua_conf_adjust_tx_level()/pjsua_conf_adjust_rx_level() which
6746 * applies to all signals from/to that port. The signal adjustment
6747 * will be cumulative, in this following order:
6748 * signal from the source will be adjusted with the level specified
6749 * in pjsua_conf_adjust_rx_level(), then with the level specified
6750 * via this API, and finally with the level specified to the sink's
6751 * pjsua_conf_adjust_tx_level().
6752 *
6753 * If bidirectional media flow is desired, application needs to call
6754 * this function twice, with the second one having the arguments
6755 * reversed.
6756 *
6757 * @param source Port ID of the source media/transmitter.
6758 * @param sink Port ID of the destination media/received.
6759 * @param prm Conference port connection param. If set to
6760 * NULL, default values will be used.
6761 *
6762 * @return PJ_SUCCESS on success, or the appropriate error code.
6763 */
6764PJ_DECL(pj_status_t) pjsua_conf_connect2(pjsua_conf_port_id source,
6765 pjsua_conf_port_id sink,
6766 const pjsua_conf_connect_param *prm);
6767
6768
6769/**
6770 * Disconnect media flow from the source to destination port.
6771 *
6772 * @param source Port ID of the source media/transmitter.
6773 * @param sink Port ID of the destination media/received.
6774 *
6775 * @return PJ_SUCCESS on success, or the appropriate error code.
6776 */
6777PJ_DECL(pj_status_t) pjsua_conf_disconnect(pjsua_conf_port_id source,
6778 pjsua_conf_port_id sink);
6779
6780
6781/**
6782 * Adjust the signal level to be transmitted from the bridge to the
6783 * specified port by making it louder or quieter.
6784 *
6785 * @param slot The conference bridge slot number.
6786 * @param level Signal level adjustment. Value 1.0 means no level
6787 * adjustment, while value 0 means to mute the port.
6788 *
6789 * @return PJ_SUCCESS on success, or the appropriate error code.
6790 */
6791PJ_DECL(pj_status_t) pjsua_conf_adjust_tx_level(pjsua_conf_port_id slot,
6792 float level);
6793
6794/**
6795 * Adjust the signal level to be received from the specified port (to
6796 * the bridge) by making it louder or quieter.
6797 *
6798 * @param slot The conference bridge slot number.
6799 * @param level Signal level adjustment. Value 1.0 means no level
6800 * adjustment, while value 0 means to mute the port.
6801 *
6802 * @return PJ_SUCCESS on success, or the appropriate error code.
6803 */
6804PJ_DECL(pj_status_t) pjsua_conf_adjust_rx_level(pjsua_conf_port_id slot,
6805 float level);
6806
6807/**
6808 * Get last signal level transmitted to or received from the specified port.
6809 * The signal level is an integer value in zero to 255, with zero indicates
6810 * no signal, and 255 indicates the loudest signal level.
6811 *
6812 * @param slot The conference bridge slot number.
6813 * @param tx_level Optional argument to receive the level of signal
6814 * transmitted to the specified port (i.e. the direction
6815 * is from the bridge to the port).
6816 * @param rx_level Optional argument to receive the level of signal
6817 * received from the port (i.e. the direction is from the
6818 * port to the bridge).
6819 *
6820 * @return PJ_SUCCESS on success.
6821 */
6822PJ_DECL(pj_status_t) pjsua_conf_get_signal_level(pjsua_conf_port_id slot,
6823 unsigned *tx_level,
6824 unsigned *rx_level);
6825
6826
6827/*****************************************************************************
6828 * File player and playlist.
6829 */
6830
6831/**
6832 * Create a file player, and automatically add this player to
6833 * the conference bridge.
6834 *
6835 * @param filename The filename to be played. Currently only
6836 * WAV files are supported, and the WAV file MUST be
6837 * formatted as 16bit PCM mono/single channel (any
6838 * clock rate is supported).
6839 * @param options Optional option flag. Application may specify
6840 * PJMEDIA_FILE_NO_LOOP to prevent playback loop.
6841 * @param p_id Pointer to receive player ID.
6842 *
6843 * @return PJ_SUCCESS on success, or the appropriate error code.
6844 */
6845PJ_DECL(pj_status_t) pjsua_player_create(const pj_str_t *filename,
6846 unsigned options,
6847 pjsua_player_id *p_id);
6848
6849
6850/**
6851 * Create a file playlist media port, and automatically add the port
6852 * to the conference bridge.
6853 *
6854 * @param file_names Array of file names to be added to the play list.
6855 * Note that the files must have the same clock rate,
6856 * number of channels, and number of bits per sample.
6857 * @param file_count Number of files in the array.
6858 * @param label Optional label to be set for the media port.
6859 * @param options Optional option flag. Application may specify
6860 * PJMEDIA_FILE_NO_LOOP to prevent looping.
6861 * @param p_id Optional pointer to receive player ID.
6862 *
6863 * @return PJ_SUCCESS on success, or the appropriate error code.
6864 */
6865PJ_DECL(pj_status_t) pjsua_playlist_create(const pj_str_t file_names[],
6866 unsigned file_count,
6867 const pj_str_t *label,
6868 unsigned options,
6869 pjsua_player_id *p_id);
6870
6871/**
6872 * Get conference port ID associated with player or playlist.
6873 *
6874 * @param id The file player ID.
6875 *
6876 * @return Conference port ID associated with this player.
6877 */
6878PJ_DECL(pjsua_conf_port_id) pjsua_player_get_conf_port(pjsua_player_id id);
6879
6880
6881/**
6882 * Get the media port for the player or playlist.
6883 *
6884 * @param id The player ID.
6885 * @param p_port The media port associated with the player.
6886 *
6887 * @return PJ_SUCCESS on success.
6888 */
6889PJ_DECL(pj_status_t) pjsua_player_get_port(pjsua_player_id id,
6890 pjmedia_port **p_port);
6891
6892/**
6893 * Get additional info about the file player. This operation is not valid
6894 * for playlist.
6895 *
6896 * @param port The file player ID.
6897 * @param info The info.
6898 *
6899 * @return PJ_SUCCESS on success or the appropriate error code.
6900 */
6901PJ_DECL(pj_status_t) pjsua_player_get_info(pjsua_player_id id,
6902 pjmedia_wav_player_info *info);
6903
6904
6905/**
6906 * Get playback position. This operation is not valid for playlist.
6907 *
6908 * @param id The file player ID.
6909 *
6910 * @return The current playback position, in samples. On error,
6911 * return the error code as negative value.
6912 */
6913PJ_DECL(pj_ssize_t) pjsua_player_get_pos(pjsua_player_id id);
6914
6915/**
6916 * Set playback position. This operation is not valid for playlist.
6917 *
6918 * @param id The file player ID.
6919 * @param samples The playback position, in samples. Application can
6920 * specify zero to re-start the playback.
6921 *
6922 * @return PJ_SUCCESS on success, or the appropriate error code.
6923 */
6924PJ_DECL(pj_status_t) pjsua_player_set_pos(pjsua_player_id id,
6925 pj_uint32_t samples);
6926
6927/**
6928 * Close the file of playlist, remove the player from the bridge, and free
6929 * resources associated with the file player or playlist.
6930 *
6931 * @param id The file player ID.
6932 *
6933 * @return PJ_SUCCESS on success, or the appropriate error code.
6934 */
6935PJ_DECL(pj_status_t) pjsua_player_destroy(pjsua_player_id id);
6936
6937
6938/*****************************************************************************
6939 * File recorder.
6940 */
6941
6942/**
6943 * Create a file recorder, and automatically connect this recorder to
6944 * the conference bridge. The recorder currently supports recording WAV file.
6945 * The type of the recorder to use is determined by the extension of the file
6946 * (e.g. ".wav").
6947 *
6948 * @param filename Output file name. The function will determine the
6949 * default format to be used based on the file extension.
6950 * Currently ".wav" is supported on all platforms.
6951 * @param enc_type Optionally specify the type of encoder to be used to
6952 * compress the media, if the file can support different
6953 * encodings. This value must be zero for now.
6954 * @param enc_param Optionally specify codec specific parameter to be
6955 * passed to the file writer.
6956 * For .WAV recorder, this value must be NULL.
6957 * @param max_size Maximum file size. Specify zero or -1 to remove size
6958 * limitation. This value must be zero or -1 for now.
6959 * @param options Optional options.
6960 * @param p_id Pointer to receive the recorder instance.
6961 *
6962 * @return PJ_SUCCESS on success, or the appropriate error code.
6963 */
6964PJ_DECL(pj_status_t) pjsua_recorder_create(const pj_str_t *filename,
6965 unsigned enc_type,
6966 void *enc_param,
6967 pj_ssize_t max_size,
6968 unsigned options,
6969 pjsua_recorder_id *p_id);
6970
6971
6972/**
6973 * Get conference port associated with recorder.
6974 *
6975 * @param id The recorder ID.
6976 *
6977 * @return Conference port ID associated with this recorder.
6978 */
6979PJ_DECL(pjsua_conf_port_id) pjsua_recorder_get_conf_port(pjsua_recorder_id id);
6980
6981
6982/**
6983 * Get the media port for the recorder.
6984 *
6985 * @param id The recorder ID.
6986 * @param p_port The media port associated with the recorder.
6987 *
6988 * @return PJ_SUCCESS on success.
6989 */
6990PJ_DECL(pj_status_t) pjsua_recorder_get_port(pjsua_recorder_id id,
6991 pjmedia_port **p_port);
6992
6993
6994/**
6995 * Destroy recorder (this will complete recording).
6996 *
6997 * @param id The recorder ID.
6998 *
6999 * @return PJ_SUCCESS on success, or the appropriate error code.
7000 */
7001PJ_DECL(pj_status_t) pjsua_recorder_destroy(pjsua_recorder_id id);
7002
7003
7004/*****************************************************************************
7005 * Sound devices.
7006 */
7007
7008/**
7009 * Enum all audio devices installed in the system.
7010 *
7011 * @param info Array of info to be initialized.
7012 * @param count On input, specifies max elements in the array.
7013 * On return, it contains actual number of elements
7014 * that have been initialized.
7015 *
7016 * @return PJ_SUCCESS on success, or the appropriate error code.
7017 */
7018PJ_DECL(pj_status_t) pjsua_enum_aud_devs(pjmedia_aud_dev_info info[],
7019 unsigned *count);
7020
7021/**
7022 * Enum all sound devices installed in the system (old API).
7023 *
7024 * @param info Array of info to be initialized.
7025 * @param count On input, specifies max elements in the array.
7026 * On return, it contains actual number of elements
7027 * that have been initialized.
7028 *
7029 * @return PJ_SUCCESS on success, or the appropriate error code.
7030 */
7031PJ_DECL(pj_status_t) pjsua_enum_snd_devs(pjmedia_snd_dev_info info[],
7032 unsigned *count);
7033
7034/**
7035 * Get currently active sound devices. If sound devices has not been created
7036 * (for example when pjsua_start() is not called), it is possible that
7037 * the function returns PJ_SUCCESS with -1 as device IDs.
7038 * See also #pjsua_snd_dev_id constants.
7039 *
7040 * @param capture_dev On return it will be filled with device ID of the
7041 * capture device.
7042 * @param playback_dev On return it will be filled with device ID of the
7043 * device ID of the playback device.
7044 *
7045 * @return PJ_SUCCESS on success, or the appropriate error code.
7046 */
7047PJ_DECL(pj_status_t) pjsua_get_snd_dev(int *capture_dev,
7048 int *playback_dev);
7049
7050
7051/**
7052 * Select or change sound device. Application may call this function at
7053 * any time to replace current sound device.
7054 *
7055 * @param capture_dev Device ID of the capture device.
7056 * @param playback_dev Device ID of the playback device.
7057 *
7058 * @return PJ_SUCCESS on success, or the appropriate error code.
7059 */
7060PJ_DECL(pj_status_t) pjsua_set_snd_dev(int capture_dev,
7061 int playback_dev);
7062
7063/**
7064 * Select or change sound device according to the specified param.
7065 *
7066 * @param snd_param Sound device param.
7067 *
7068 * @return PJ_SUCCESS on success, or the appropriate error code.
7069 */
7070PJ_DECL(pj_status_t) pjsua_set_snd_dev2(pjsua_snd_dev_param *snd_param);
7071
7072
7073/**
7074 * Set pjsua to use null sound device. The null sound device only provides
7075 * the timing needed by the conference bridge, and will not interract with
7076 * any hardware.
7077 *
7078 * @return PJ_SUCCESS on success, or the appropriate error code.
7079 */
7080PJ_DECL(pj_status_t) pjsua_set_null_snd_dev(void);
7081
7082
7083/**
7084 * Disconnect the main conference bridge from any sound devices, and let
7085 * application connect the bridge to it's own sound device/master port.
7086 *
7087 * @return The port interface of the conference bridge,
7088 * so that application can connect this to it's own
7089 * sound device or master port.
7090 */
7091PJ_DECL(pjmedia_port*) pjsua_set_no_snd_dev(void);
7092
7093
7094/**
7095 * Change the echo cancellation settings.
7096 *
7097 * The behavior of this function depends on whether the sound device is
7098 * currently active, and if it is, whether device or software AEC is
7099 * being used.
7100 *
7101 * If the sound device is currently active, and if the device supports AEC,
7102 * this function will forward the change request to the device and it will
7103 * be up to the device on whether support the request. If software AEC is
7104 * being used (the software EC will be used if the device does not support
7105 * AEC), this function will change the software EC settings. In all cases,
7106 * the setting will be saved for future opening of the sound device.
7107 *
7108 * If the sound device is not currently active, this will only change the
7109 * default AEC settings and the setting will be applied next time the
7110 * sound device is opened.
7111 *
7112 * @param tail_ms The tail length, in miliseconds. Set to zero to
7113 * disable AEC.
7114 * @param options Options to be passed to pjmedia_echo_create().
7115 * Normally the value should be zero.
7116 *
7117 * @return PJ_SUCCESS on success.
7118 */
7119PJ_DECL(pj_status_t) pjsua_set_ec(unsigned tail_ms, unsigned options);
7120
7121
7122/**
7123 * Get current echo canceller tail length.
7124 *
7125 * @param p_tail_ms Pointer to receive the tail length, in miliseconds.
7126 * If AEC is disabled, the value will be zero.
7127 *
7128 * @return PJ_SUCCESS on success.
7129 */
7130PJ_DECL(pj_status_t) pjsua_get_ec_tail(unsigned *p_tail_ms);
7131
7132
7133/**
7134 * Check whether the sound device is currently active. The sound device
7135 * may be inactive if the application has set the auto close feature to
7136 * non-zero (the snd_auto_close_time setting in #pjsua_media_config), or
7137 * if null sound device or no sound device has been configured via the
7138 * #pjsua_set_no_snd_dev() function.
7139 */
7140PJ_DECL(pj_bool_t) pjsua_snd_is_active(void);
7141
7142
7143/**
7144 * Configure sound device setting to the sound device being used. If sound
7145 * device is currently active, the function will forward the setting to the
7146 * sound device instance to be applied immediately, if it supports it.
7147 *
7148 * The setting will be saved for future opening of the sound device, if the
7149 * "keep" argument is set to non-zero. If the sound device is currently
7150 * inactive, and the "keep" argument is false, this function will return
7151 * error.
7152 *
7153 * Note that in case the setting is kept for future use, it will be applied
7154 * to any devices, even when application has changed the sound device to be
7155 * used.
7156 *
7157 * Note also that the echo cancellation setting should be set with
7158 * #pjsua_set_ec() API instead.
7159 *
7160 * See also #pjmedia_aud_stream_set_cap() for more information about setting
7161 * an audio device capability.
7162 *
7163 * @param cap The sound device setting to change.
7164 * @param pval Pointer to value. Please see #pjmedia_aud_dev_cap
7165 * documentation about the type of value to be
7166 * supplied for each setting.
7167 * @param keep Specify whether the setting is to be kept for future
7168 * use.
7169 *
7170 * @return PJ_SUCCESS on success or the appropriate error code.
7171 */
7172PJ_DECL(pj_status_t) pjsua_snd_set_setting(pjmedia_aud_dev_cap cap,
7173 const void *pval,
7174 pj_bool_t keep);
7175
7176/**
7177 * Retrieve a sound device setting. If sound device is currently active,
7178 * the function will forward the request to the sound device. If sound device
7179 * is currently inactive, and if application had previously set the setting
7180 * and mark the setting as kept, then that setting will be returned.
7181 * Otherwise, this function will return error.
7182 *
7183 * Note that echo cancellation settings should be retrieved with
7184 * #pjsua_get_ec_tail() API instead.
7185 *
7186 * @param cap The sound device setting to retrieve.
7187 * @param pval Pointer to receive the value.
7188 * Please see #pjmedia_aud_dev_cap documentation about
7189 * the type of value to be supplied for each setting.
7190 *
7191 * @return PJ_SUCCESS on success or the appropriate error code.
7192 */
7193PJ_DECL(pj_status_t) pjsua_snd_get_setting(pjmedia_aud_dev_cap cap,
7194 void *pval);
7195
7196
7197/**
7198 * Opaque type of extra sound device, an additional sound device
7199 * beside the primary sound device (the one instantiated via
7200 * pjsua_set_snd_dev() or pjsua_set_snd_dev2()). This sound device is
7201 * also registered to conference bridge so it can be used as a normal
7202 * conference bridge port, e.g: connect it to/from other ports,
7203 * adjust/check audio level, etc. The conference bridge port ID can be
7204 * queried using pjsua_ext_snd_dev_get_conf_port().
7205 *
7206 * Application may also use this API to improve media clock. Normally
7207 * media clock is driven by sound device in master port, but unfortunately
7208 * some sound devices may produce jittery clock. To improve media clock,
7209 * application can install Null Sound Device (i.e: using
7210 * pjsua_set_null_snd_dev()), which will act as a master port, and instantiate
7211 * the sound device as extra sound device. But note that extra sound device
7212 * will not have auto-close upon idle feature.
7213 */
7214typedef struct pjsua_ext_snd_dev pjsua_ext_snd_dev;
7215
7216
7217/**
7218 * Create an extra sound device and register it to conference bridge.
7219 *
7220 * @param snd_param Sound device port param.
7221 * @param p_snd The extra sound device instance.
7222 *
7223 * @return PJ_SUCCESS on success or the appropriate error code.
7224 */
7225PJ_DECL(pj_status_t) pjsua_ext_snd_dev_create(pjmedia_snd_port_param *param,
7226 pjsua_ext_snd_dev **p_snd);
7227
7228
7229/**
7230 * Destroy an extra sound device and unregister it from conference bridge.
7231 *
7232 * @param p_snd The extra sound device instance.
7233 *
7234 * @return PJ_SUCCESS on success or the appropriate error code.
7235 */
7236PJ_DECL(pj_status_t) pjsua_ext_snd_dev_destroy(pjsua_ext_snd_dev *snd);
7237
7238
7239/**
7240 * Get sound port instance of an extra sound device.
7241 *
7242 * @param snd The extra sound device instance.
7243 *
7244 * @return The sound port instance.
7245 */
7246PJ_DECL(pjmedia_snd_port*) pjsua_ext_snd_dev_get_snd_port(
7247 pjsua_ext_snd_dev *snd);
7248
7249/**
7250 * Get conference port ID of an extra sound device.
7251 *
7252 * @param snd The extra sound device instance.
7253 *
7254 * @return The conference port ID.
7255 */
7256PJ_DECL(pjsua_conf_port_id) pjsua_ext_snd_dev_get_conf_port(
7257 pjsua_ext_snd_dev *snd);
7258
7259
7260/*****************************************************************************
7261 * Codecs.
7262 */
7263
7264/**
7265 * Enum all supported codecs in the system.
7266 *
7267 * @param id Array of ID to be initialized.
7268 * @param count On input, specifies max elements in the array.
7269 * On return, it contains actual number of elements
7270 * that have been initialized.
7271 *
7272 * @return PJ_SUCCESS on success, or the appropriate error code.
7273 */
7274PJ_DECL(pj_status_t) pjsua_enum_codecs( pjsua_codec_info id[],
7275 unsigned *count );
7276
7277
7278/**
7279 * Change codec priority.
7280 *
7281 * @param codec_id Codec ID, which is a string that uniquely identify
7282 * the codec (such as "speex/8000"). Please see pjsua
7283 * manual or pjmedia codec reference for details.
7284 * @param priority Codec priority, 0-255, where zero means to disable
7285 * the codec.
7286 *
7287 * @return PJ_SUCCESS on success, or the appropriate error code.
7288 */
7289PJ_DECL(pj_status_t) pjsua_codec_set_priority( const pj_str_t *codec_id,
7290 pj_uint8_t priority );
7291
7292
7293/**
7294 * Get codec parameters.
7295 *
7296 * @param codec_id Codec ID.
7297 * @param param Structure to receive codec parameters.
7298 *
7299 * @return PJ_SUCCESS on success, or the appropriate error code.
7300 */
7301PJ_DECL(pj_status_t) pjsua_codec_get_param( const pj_str_t *codec_id,
7302 pjmedia_codec_param *param );
7303
7304
7305/**
7306 * Set codec parameters.
7307 *
7308 * @param codec_id Codec ID.
7309 * @param param Codec parameter to set. Set to NULL to reset
7310 * codec parameter to library default settings.
7311 *
7312 * @return PJ_SUCCESS on success, or the appropriate error code.
7313 */
7314PJ_DECL(pj_status_t) pjsua_codec_set_param( const pj_str_t *codec_id,
7315 const pjmedia_codec_param *param);
7316
7317
7318#if DISABLED_FOR_TICKET_1185
7319/**
7320 * Create UDP media transports for all the calls. This function creates
7321 * one UDP media transport for each call.
7322 *
7323 * @param cfg Media transport configuration. The "port" field in the
7324 * configuration is used as the start port to bind the
7325 * sockets.
7326 *
7327 * @return PJ_SUCCESS on success, or the appropriate error code.
7328 */
7329PJ_DECL(pj_status_t)
7330pjsua_media_transports_create(const pjsua_transport_config *cfg);
7331
7332
7333/**
7334 * Register custom media transports to be used by calls. There must
7335 * enough media transports for all calls.
7336 *
7337 * @param tp The media transport array.
7338 * @param count Number of elements in the array. This number MUST
7339 * match the number of maximum calls configured when
7340 * pjsua is created.
7341 * @param auto_delete Flag to indicate whether the transports should be
7342 * destroyed when pjsua is shutdown.
7343 *
7344 * @return PJ_SUCCESS on success, or the appropriate error code.
7345 */
7346PJ_DECL(pj_status_t)
7347pjsua_media_transports_attach( pjsua_media_transport tp[],
7348 unsigned count,
7349 pj_bool_t auto_delete);
7350#endif
7351
7352
7353/* end of MEDIA API */
7354/**
7355 * @}
7356 */
7357
7358
7359/*****************************************************************************
7360 * VIDEO API
7361 */
7362
7363
7364/**
7365 * @defgroup PJSUA_LIB_VIDEO PJSUA-API Video
7366 * @ingroup PJSUA_LIB
7367 * @brief Video support
7368 * @{
7369 */
7370
7371/*
7372 * Video devices API
7373 */
7374
7375/**
7376 * Get the number of video devices installed in the system.
7377 *
7378 * @return The number of devices.
7379 */
7380PJ_DECL(unsigned) pjsua_vid_dev_count(void);
7381
7382/**
7383 * Retrieve the video device info for the specified device index.
7384 *
7385 * @param id The device index.
7386 * @param vdi Device info to be initialized.
7387 *
7388 * @return PJ_SUCCESS on success, or the appropriate error code.
7389 */
7390PJ_DECL(pj_status_t) pjsua_vid_dev_get_info(pjmedia_vid_dev_index id,
7391 pjmedia_vid_dev_info *vdi);
7392
7393/**
7394 * Check whether the video capture device is currently active, i.e. if
7395 * a video preview has been started or there is a video call using
7396 * the device. This function will return PJ_FALSE for video renderer device.
7397 *
7398 * @param id The video device index.
7399 *
7400 * @return PJ_TRUE if active, PJ_FALSE otherwise.
7401 */
7402PJ_DECL(pj_bool_t) pjsua_vid_dev_is_active(pjmedia_vid_dev_index id);
7403
7404/**
7405 * Configure the capability of a video capture device. If the device is
7406 * currently active (i.e. if there is a video call using the device or
7407 * a video preview has been started), the function will forward the setting
7408 * to the video device instance to be applied immediately, if it supports it.
7409 *
7410 * The setting will be saved for future opening of the video device, if the
7411 * "keep" argument is set to non-zero. If the video device is currently
7412 * inactive, and the "keep" argument is false, this function will return
7413 * error.
7414 *
7415 * Note: This function will only works for video capture devices. To
7416 * configure the setting of video renderer device instances, use
7417 * pjsua_vid_win API instead.
7418 *
7419 * Warning: If application refreshes the video device list, it needs to
7420 * manually update the settings to reflect the newly updated video device
7421 * indexes. See #pjmedia_vid_dev_refresh() for more information.
7422 *
7423 * See also #pjmedia_vid_stream_set_cap() for more information about setting
7424 * a video device capability.
7425 *
7426 * @param id The video device index.
7427 * @param cap The video device capability to change.
7428 * @param pval Pointer to value. Please see #pjmedia_vid_dev_cap
7429 * documentation about the type of value to be
7430 * supplied for each setting.
7431 *
7432 * @return PJ_SUCCESS on success or the appropriate error code.
7433 */
7434PJ_DECL(pj_status_t) pjsua_vid_dev_set_setting(pjmedia_vid_dev_index id,
7435 pjmedia_vid_dev_cap cap,
7436 const void *pval,
7437 pj_bool_t keep);
7438
7439/**
7440 * Retrieve the value of a video capture device setting. If the device is
7441 * currently active (i.e. if there is a video call using the device or
7442 * a video preview has been started), the function will forward the request
7443 * to the video device. If video device is currently inactive, and if
7444 * application had previously set the setting and mark the setting as kept,
7445 * then that setting will be returned. Otherwise, this function will return
7446 * error.
7447 * The function only works for video capture device.
7448 *
7449 * @param id The video device index.
7450 * @param cap The video device capability to retrieve.
7451 * @param pval Pointer to receive the value.
7452 * Please see #pjmedia_vid_dev_cap documentation about
7453 * the type of value to be supplied for each setting.
7454 *
7455 * @return PJ_SUCCESS on success or the appropriate error code.
7456 */
7457PJ_DECL(pj_status_t) pjsua_vid_dev_get_setting(pjmedia_vid_dev_index id,
7458 pjmedia_vid_dev_cap cap,
7459 void *pval);
7460
7461/**
7462 * Enum all video devices installed in the system.
7463 *
7464 * @param info Array of info to be initialized.
7465 * @param count On input, specifies max elements in the array.
7466 * On return, it contains actual number of elements
7467 * that have been initialized.
7468 *
7469 * @return PJ_SUCCESS on success, or the appropriate error code.
7470 */
7471PJ_DECL(pj_status_t) pjsua_vid_enum_devs(pjmedia_vid_dev_info info[],
7472 unsigned *count);
7473
7474
7475/*
7476 * Video preview API
7477 */
7478
7479/**
7480 * Parameters for starting video preview with pjsua_vid_preview_start().
7481 * Application should initialize this structure with
7482 * pjsua_vid_preview_param_default().
7483 */
7484typedef struct pjsua_vid_preview_param
7485{
7486 /**
7487 * Device ID for the video renderer to be used for rendering the
7488 * capture stream for preview. This parameter is ignored if native
7489 * preview is being used.
7490 *
7491 * Default: PJMEDIA_VID_DEFAULT_RENDER_DEV
7492 */
7493 pjmedia_vid_dev_index rend_id;
7494
7495 /**
7496 * Show window initially.
7497 *
7498 * Default: PJ_TRUE.
7499 */
7500 pj_bool_t show;
7501
7502 /**
7503 * Window flags. The value is a bitmask combination of
7504 * #pjmedia_vid_dev_wnd_flag.
7505 *
7506 * Default: 0.
7507 */
7508 unsigned wnd_flags;
7509
7510 /**
7511 * Media format. Initialize this with #pjmedia_format_init_video().
7512 * If left unitialized, this parameter will not be used.
7513 */
7514 pjmedia_format format;
7515
7516 /**
7517 * Optional output window to be used to display the video preview.
7518 * This parameter will only be used if the video device supports
7519 * PJMEDIA_VID_DEV_CAP_OUTPUT_WINDOW capability and the capability
7520 * is not read-only.
7521 */
7522 pjmedia_vid_dev_hwnd wnd;
7523
7524} pjsua_vid_preview_param;
7525
7526
7527/**
7528 * Initialize pjsua_vid_preview_param
7529 *
7530 * @param p The parameter to be initialized.
7531 */
7532PJ_DECL(void) pjsua_vid_preview_param_default(pjsua_vid_preview_param *p);
7533
7534/**
7535 * Determine if the specified video input device has built-in native
7536 * preview capability. This is a convenience function that is equal to
7537 * querying device's capability for PJMEDIA_VID_DEV_CAP_INPUT_PREVIEW
7538 * capability.
7539 *
7540 * @param id The capture device ID.
7541 *
7542 * @return PJ_TRUE if it has.
7543 */
7544PJ_DECL(pj_bool_t) pjsua_vid_preview_has_native(pjmedia_vid_dev_index id);
7545
7546/**
7547 * Start video preview window for the specified capture device.
7548 *
7549 * @param id The capture device ID where its preview will be
7550 * started.
7551 * @param p Optional video preview parameters. Specify NULL
7552 * to use default values.
7553 *
7554 * @return PJ_SUCCESS on success, or the appropriate error code.
7555 */
7556PJ_DECL(pj_status_t) pjsua_vid_preview_start(pjmedia_vid_dev_index id,
7557 const pjsua_vid_preview_param *p);
7558
7559/**
7560 * Get the preview window handle associated with the capture device, if any.
7561 *
7562 * @param id The capture device ID.
7563 *
7564 * @return The window ID of the preview window for the
7565 * specified capture device ID, or PJSUA_INVALID_ID if
7566 * preview has not been started for the device.
7567 */
7568PJ_DECL(pjsua_vid_win_id) pjsua_vid_preview_get_win(pjmedia_vid_dev_index id);
7569
7570/**
7571 * Stop video preview.
7572 *
7573 * @param id The capture device ID.
7574 *
7575 * @return PJ_SUCCESS on success, or the appropriate error code.
7576 */
7577PJ_DECL(pj_status_t) pjsua_vid_preview_stop(pjmedia_vid_dev_index id);
7578
7579
7580/*
7581 * Video window manipulation API.
7582 */
7583
7584/**
7585 * This structure describes video window info.
7586 */
7587typedef struct pjsua_vid_win_info
7588{
7589 /**
7590 * Flag to indicate whether this window is a native window,
7591 * such as created by built-in preview device. If this field is
7592 * PJ_TRUE, only the native window handle field of this
7593 * structure is valid.
7594 */
7595 pj_bool_t is_native;
7596
7597 /**
7598 * Native window handle.
7599 */
7600 pjmedia_vid_dev_hwnd hwnd;
7601
7602 /**
7603 * Renderer device ID.
7604 */
7605 pjmedia_vid_dev_index rdr_dev;
7606
7607 /**
7608 * Window show status. The window is hidden if false.
7609 */
7610 pj_bool_t show;
7611
7612 /**
7613 * Window position.
7614 */
7615 pjmedia_coord pos;
7616
7617 /**
7618 * Window size.
7619 */
7620 pjmedia_rect_size size;
7621
7622} pjsua_vid_win_info;
7623
7624
7625/**
7626 * Enumerates all video windows.
7627 *
7628 * @param id Array of window ID to be initialized.
7629 * @param count On input, specifies max elements in the array.
7630 * On return, it contains actual number of elements
7631 * that have been initialized.
7632 *
7633 * @return PJ_SUCCESS on success, or the appropriate error code.
7634 */
7635PJ_DECL(pj_status_t) pjsua_vid_enum_wins(pjsua_vid_win_id wids[],
7636 unsigned *count);
7637
7638
7639/**
7640 * Get window info.
7641 *
7642 * @param wid The video window ID.
7643 * @param wi The video window info to be initialized.
7644 *
7645 * @return PJ_SUCCESS on success, or the appropriate error code.
7646 */
7647PJ_DECL(pj_status_t) pjsua_vid_win_get_info(pjsua_vid_win_id wid,
7648 pjsua_vid_win_info *wi);
7649
7650/**
7651 * Show or hide window. This operation is not valid for native windows
7652 * (pjsua_vid_win_info.is_native=PJ_TRUE), on which native windowing API
7653 * must be used instead.
7654 *
7655 * @param wid The video window ID.
7656 * @param show Set to PJ_TRUE to show the window, PJ_FALSE to
7657 * hide the window.
7658 *
7659 * @return PJ_SUCCESS on success, or the appropriate error code.
7660 */
7661PJ_DECL(pj_status_t) pjsua_vid_win_set_show(pjsua_vid_win_id wid,
7662 pj_bool_t show);
7663
7664/**
7665 * Set video window position. This operation is not valid for native windows
7666 * (pjsua_vid_win_info.is_native=PJ_TRUE), on which native windowing API
7667 * must be used instead.
7668 *
7669 * @param wid The video window ID.
7670 * @param pos The window position.
7671 *
7672 * @return PJ_SUCCESS on success, or the appropriate error code.
7673 */
7674PJ_DECL(pj_status_t) pjsua_vid_win_set_pos(pjsua_vid_win_id wid,
7675 const pjmedia_coord *pos);
7676
7677/**
7678 * Resize window. This operation is not valid for native windows
7679 * (pjsua_vid_win_info.is_native=PJ_TRUE), on which native windowing API
7680 * must be used instead.
7681 *
7682 * @param wid The video window ID.
7683 * @param size The new window size.
7684 *
7685 * @return PJ_SUCCESS on success, or the appropriate error code.
7686 */
7687PJ_DECL(pj_status_t) pjsua_vid_win_set_size(pjsua_vid_win_id wid,
7688 const pjmedia_rect_size *size);
7689
7690/**
7691 * Set output window. This operation is valid only when the underlying
7692 * video device supports PJMEDIA_VIDEO_DEV_CAP_OUTPUT_WINDOW capability AND
7693 * allows the output window to be changed on-the-fly. Currently it is only
7694 * supported on Android.
7695 *
7696 * @param wid The video window ID.
7697 * @param win The new output window.
7698 *
7699 * @return PJ_SUCCESS on success, or the appropriate error code.
7700 */
7701PJ_DECL(pj_status_t) pjsua_vid_win_set_win(pjsua_vid_win_id wid,
7702 const pjmedia_vid_dev_hwnd *win);
7703
7704/**
7705 * Rotate the video window. This function will change the video orientation
7706 * and also possibly the video window size (width and height get swapped).
7707 * This operation is not valid for native windows (pjsua_vid_win_info.is_native
7708 * =PJ_TRUE), on which native windowing API must be used instead.
7709 *
7710 * @param wid The video window ID.
7711 * @param angle The rotation angle in degrees, must be multiple of 90.
7712 * Specify positive value for clockwise rotation or
7713 * negative value for counter-clockwise rotation.
7714 *
7715 * @return PJ_SUCCESS on success, or the appropriate error code.
7716 */
7717PJ_DECL(pj_status_t) pjsua_vid_win_rotate(pjsua_vid_win_id wid,
7718 int angle);
7719
7720
7721/*
7722 * Video codecs API
7723 */
7724
7725/**
7726 * Enum all supported video codecs in the system.
7727 *
7728 * @param id Array of ID to be initialized.
7729 * @param count On input, specifies max elements in the array.
7730 * On return, it contains actual number of elements
7731 * that have been initialized.
7732 *
7733 * @return PJ_SUCCESS on success, or the appropriate error code.
7734 */
7735PJ_DECL(pj_status_t) pjsua_vid_enum_codecs( pjsua_codec_info id[],
7736 unsigned *count );
7737
7738
7739/**
7740 * Change video codec priority.
7741 *
7742 * @param codec_id Codec ID, which is a string that uniquely identify
7743 * the codec (such as "H263/90000"). Please see pjsua
7744 * manual or pjmedia codec reference for details.
7745 * @param priority Codec priority, 0-255, where zero means to disable
7746 * the codec.
7747 *
7748 * @return PJ_SUCCESS on success, or the appropriate error code.
7749 */
7750PJ_DECL(pj_status_t) pjsua_vid_codec_set_priority( const pj_str_t *codec_id,
7751 pj_uint8_t priority );
7752
7753
7754/**
7755 * Get video codec parameters.
7756 *
7757 * @param codec_id Codec ID.
7758 * @param param Structure to receive video codec parameters.
7759 *
7760 * @return PJ_SUCCESS on success, or the appropriate error code.
7761 */
7762PJ_DECL(pj_status_t) pjsua_vid_codec_get_param(
7763 const pj_str_t *codec_id,
7764 pjmedia_vid_codec_param *param);
7765
7766
7767/**
7768 * Set video codec parameters.
7769 *
7770 * @param codec_id Codec ID.
7771 * @param param Codec parameter to set. Set to NULL to reset
7772 * codec parameter to library default settings.
7773 *
7774 * @return PJ_SUCCESS on success, or the appropriate error code.
7775 */
7776PJ_DECL(pj_status_t) pjsua_vid_codec_set_param(
7777 const pj_str_t *codec_id,
7778 const pjmedia_vid_codec_param *param);
7779
7780
7781
7782/* end of VIDEO API */
7783/**
7784 * @}
7785 */
7786
7787
7788/**
7789 * @}
7790 */
7791
7792PJ_END_DECL
7793
7794
7795#endif /* __PJSUA_H__ */