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