/usr/share/gtk-doc/html/telepathy-spec/Connection.html is in telepathy-specification 0.27.3-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 | <?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd" "">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<title>Connection — Telepathy D-Bus Interface Specification</title>
<link rel="stylesheet" href="style.css" type="text/css"/>
<link rel="shortcut icon" type="image/png" media="all" href="favicon.png" />
<script src="jquery.min.js"></script>
<script src="magic.js"></script>
</head>
<body>
<div class="header">
<h1>Interface <abbr title='org.freedesktop.Telepathy.Connection'>Connection</abbr></h1>
<a href="index.html">Interface Index</a>
(<a href="interfaces.html">Compact</a>)
| <a href="#summary">Summary</a>
| <a href="#description">Description</a>
| <a href="#methods">Methods</a>
| <a href="#signals">Signals</a>
| <a href="#properties">Properties</a>
| <a href="#contact-attributes">Contact Attributes</a>
| <a href="#types">Types</a>
</div>
<div class="main">
<div class="summary">
<a name="summary"></a>
<h3>Methods</h3>
<table class="summary">
<tr>
<td><a href="Connection.html#Method:Connect">Connect</a></td>
<td>()</td>
<td>→</td>
<td>nothing</td>
<td>
</td>
</tr>
<tr>
<td><a href="Connection.html#Method:Disconnect">Disconnect</a></td>
<td>()</td>
<td>→</td>
<td>nothing</td>
<td>
</td>
</tr>
<tr>
<td><a href="Connection.html#Method:GetInterfaces">GetInterfaces</a></td>
<td>()</td>
<td>→</td>
<td>as: Interfaces</td>
<td>
</td>
</tr>
<tr>
<td><a href="Connection.html#Method:GetProtocol">GetProtocol</a></td>
<td>()</td>
<td>→</td>
<td>s: Protocol</td>
<td>
</td>
</tr>
<tr class="deprecated">
<td><a href="Connection.html#Method:GetSelfHandle">GetSelfHandle</a></td>
<td>()</td>
<td>→</td>
<td>u: Self_Handle</td>
<td>
(deprecated)
</td>
</tr>
<tr>
<td><a href="Connection.html#Method:GetStatus">GetStatus</a></td>
<td>()</td>
<td>→</td>
<td>u: Status</td>
<td>
</td>
</tr>
<tr>
<td><a href="Connection.html#Method:HoldHandles">HoldHandles</a></td>
<td>(u: Handle_Type, au: Handles)</td>
<td>→</td>
<td>nothing</td>
<td>
</td>
</tr>
<tr>
<td><a href="Connection.html#Method:InspectHandles">InspectHandles</a></td>
<td>(u: Handle_Type, au: Handles)</td>
<td>→</td>
<td>as: Identifiers</td>
<td>
</td>
</tr>
<tr class="deprecated">
<td><a href="Connection.html#Method:ListChannels">ListChannels</a></td>
<td>()</td>
<td>→</td>
<td>a(osuu): Channel_Info</td>
<td>
(deprecated)
</td>
</tr>
<tr>
<td><a href="Connection.html#Method:ReleaseHandles">ReleaseHandles</a></td>
<td>(u: Handle_Type, au: Handles)</td>
<td>→</td>
<td>nothing</td>
<td>
</td>
</tr>
<tr class="deprecated">
<td><a href="Connection.html#Method:RequestChannel">RequestChannel</a></td>
<td>(s: Type, u: Handle_Type, u: Handle, b: Suppress_Handler)</td>
<td>→</td>
<td>o: Object_Path</td>
<td>
(deprecated)
</td>
</tr>
<tr>
<td><a href="Connection.html#Method:RequestHandles">RequestHandles</a></td>
<td>(u: Handle_Type, as: Identifiers)</td>
<td>→</td>
<td>au: Handles</td>
<td>
</td>
</tr>
<tr>
<td><a href="Connection.html#Method:AddClientInterest">AddClientInterest</a></td>
<td>(as: Tokens)</td>
<td>→</td>
<td>nothing</td>
<td>
</td>
</tr>
<tr>
<td><a href="Connection.html#Method:RemoveClientInterest">RemoveClientInterest</a></td>
<td>(as: Tokens)</td>
<td>→</td>
<td>nothing</td>
<td>
</td>
</tr>
</table>
<h3>Signals</h3>
<table class="summary">
<tr class="deprecated">
<td><a href="Connection.html#Signal:SelfHandleChanged">SelfHandleChanged</a></td>
<td>(u: Self_Handle)</td>
<td>
(deprecated)
</td>
</tr>
<tr>
<td><a href="Connection.html#Signal:SelfContactChanged">SelfContactChanged</a></td>
<td>(u: Self_Handle, s: Self_ID)</td>
<td>
</td>
</tr>
<tr class="deprecated">
<td><a href="Connection.html#Signal:NewChannel">NewChannel</a></td>
<td>(o: Object_Path, s: Channel_Type, u: Handle_Type, u: Handle, b: Suppress_Handler)</td>
<td>
(deprecated)
</td>
</tr>
<tr>
<td><a href="Connection.html#Signal:ConnectionError">ConnectionError</a></td>
<td>(s: Error, a{sv}: Details)</td>
<td>
</td>
</tr>
<tr>
<td><a href="Connection.html#Signal:StatusChanged">StatusChanged</a></td>
<td>(u: Status, u: Reason)</td>
<td>
</td>
</tr>
</table>
<h3>Properties</h3>
<table class="summary">
<tr>
<td><a href="Connection.html#Property:Interfaces">Interfaces</a></td>
<td>
as
(<a href="generic-types.html#Simple-Type:DBus_Interface" title="Array of Simple Type DBus_Interface">DBus_Interface_List</a>)
</td>
<td>Read only</td>
<td></td>
<td>
</td>
</tr>
<tr>
<td><a href="Connection.html#Property:SelfHandle">SelfHandle</a></td>
<td>
u
(<a href="Connection.html#Simple-Type:Contact_Handle" title="Simple Type Contact_Handle">Contact_Handle</a>)
</td>
<td>Read only</td>
<td></td>
<td>
</td>
</tr>
<tr>
<td><a href="Connection.html#Property:SelfID">SelfID</a></td>
<td>
s
</td>
<td>Read only</td>
<td></td>
<td>
</td>
</tr>
<tr>
<td><a href="Connection.html#Property:Status">Status</a></td>
<td>
u
(<a href="Connection.html#Enum:Connection_Status" title="Enum Connection_Status">Connection_Status</a>)
</td>
<td>Read only</td>
<td></td>
<td>
</td>
</tr>
<tr>
<td><a href="Connection.html#Property:HasImmortalHandles">HasImmortalHandles</a></td>
<td>
b
</td>
<td>Read only</td>
<td></td>
<td>
</td>
</tr>
</table>
<h3>Contact Attributes</h3>
<table class="summary">
<tr class="contact-attribute">
<td><a href="Connection.html#Contact-Attribute:contact-id">org.freedesktop.Telepathy.Connection/contact-id</a></td>
<td>
s
</td>
</tr>
</table>
<h3>Types</h3>
<table class="summary">
<tr>
<td><a href="Connection.html#Simple-Type:Handle">Handle</a></td>
<td>Simple Type</td>
<td>u</td>
<td>
</td>
</tr>
<tr>
<td><a href="Connection.html#Simple-Type:Contact_Handle">Contact_Handle</a></td>
<td>Simple Type</td>
<td>u</td>
<td>
</td>
</tr>
<tr>
<td><a href="Connection.html#Simple-Type:Room_Handle">Room_Handle</a></td>
<td>Simple Type</td>
<td>u</td>
<td>
</td>
</tr>
<tr class="deprecated">
<td><a href="Connection.html#Simple-Type:List_Handle">List_Handle</a></td>
<td>Simple Type</td>
<td>u</td>
<td>
(deprecated)
</td>
</tr>
<tr class="deprecated">
<td><a href="Connection.html#Simple-Type:Group_Handle">Group_Handle</a></td>
<td>Simple Type</td>
<td>u</td>
<td>
(deprecated)
</td>
</tr>
<tr>
<td><a href="Connection.html#Enum:Handle_Type">Handle_Type</a></td>
<td>Enum</td>
<td>u</td>
<td>
</td>
</tr>
<tr>
<td><a href="Connection.html#Enum:Connection_Status">Connection_Status</a></td>
<td>Enum</td>
<td>u</td>
<td>
</td>
</tr>
<tr>
<td><a href="Connection.html#Enum:Connection_Status_Reason">Connection_Status_Reason</a></td>
<td>Enum</td>
<td>u</td>
<td>
</td>
</tr>
<tr class="deprecated">
<td><a href="Connection.html#Struct:Channel_Info">Channel_Info</a></td>
<td>Struct</td>
<td>(osuu)</td>
<td>
(deprecated)
</td>
</tr>
</table>
</div>
<div class="annotation changed"><span class="version">Changed in 0.17.10. </span>Previously, the account part of
Connection bus names/object paths was allowed to have more than one
component (i.e. contain dots or slashes), resulting in Connection
bus names and object paths with more than 7 components. We now restrict
Connection bus names/object paths to have exactly 7
components.</div>
<div class="annotation changed"><span class="version">Changed in 0.17.23. </span>The Requests and Contacts interfaces
are now mandatory. Their functionality will be merged into the main
Connection interface at some point in future.</div>
<div class="requires">
Objects implementing this interface must also implement:
<ul>
<li><a href="Connection_Interface_Requests.html" title="Interface org.freedesktop.Telepathy.Connection.Interface.Requests">org.freedesktop.Telepathy.Connection.Interface.Requests</a></li>
<li><a href="Connection_Interface_Contacts.html" title="Interface org.freedesktop.Telepathy.Connection.Interface.Contacts">org.freedesktop.Telepathy.Connection.Interface.Contacts</a></li>
</ul>
</div>
<a name="description"></a>
<h3>Description</h3>
<div class="docstring" xmlns="http://www.w3.org/1999/xhtml">
<p>This models a connection to a single user account on a communication
service. Its basic capability is to provide the facility to request and
receive channels of differing types (such as text channels or streaming
media channels) which are used to carry out further communication.</p>
<p>In order to allow Connection objects to be discovered by new clients,
the object path and well-known bus name MUST be of the form
<code>/org/freedesktop/Telepathy/Connection/cmname/proto/account</code>
and
<code>org.freedesktop.Telepathy.Connection.cmname.proto.account</code>
where:</p>
<ul>
<li><em>cmname</em> is the same
<a href="Connection_Manager.html#Simple-Type:Connection_Manager_Name">Connection_Manager_Name</a> that appears
in the connection manager's object path and well-known bus name</li>
<li><em>proto</em> is the <a href="Connection_Manager.html#Simple-Type:Protocol">Protocol</a> name as seen in
<a href="Connection_Manager.html#Method:ListProtocols" namespace="org.freedesktop.Telepathy.ConnectionManager" title="Method org.freedesktop.Telepathy.ConnectionManager.ListProtocols">ListProtocols</a>,
but with "-" replaced with "_" to get a valid
object path/bus name</li>
<li><em>account</em> is some non-empty sequence of ASCII letters,
digits and underscores not starting with a digit</li>
</ul>
<p><em>account</em> SHOULD be formed such that any valid distinct
connection instance on this protocol has a distinct name. This
might be formed by including the server name followed by the user
name (escaped via some suitable mechanism like telepathy-glib's
tp_escape_as_identifier() function to preserve uniqueness); on
protocols where connecting multiple times is permissable, a
per-connection identifier might be necessary to ensure
uniqueness.</p>
<p>Clients MAY parse the object path to determine the connection
manager name and the protocol, but MUST NOT attempt to parse the
<em>account</em> part. Connection managers MAY use any unique string
for this part.</p>
<p>As well as the methods and signatures below, arbitrary interfaces may be
provided by the Connection object to represent extra connection-wide
functionality, such as the Connection.Interface.SimplePresence for
receiving and
reporting presence information, and Connection.Interface.Aliasing for
connections where contacts may set and change an alias for themselves.
These interfaces can be discovered using the
<a href="Connection.html#Method:GetInterfaces" title="Method org.freedesktop.Telepathy.Connection.GetInterfaces">GetInterfaces</a> method.</p>
<p>Contacts, rooms, and server-stored lists (such as subscribed contacts,
block lists, or allow lists) on a service are all represented by
immutable <em>handles</em>, which are unsigned non-zero integers which are
valid only for the lifetime of the connection object, and are used
throughout the protocol where these entities are represented, allowing
simple testing of equality within clients.</p>
<p>Zero as a handle value is sometimes used as a "null" value to mean
the absence of a contact, room, etc.</p>
<p>Handles have per-type uniqueness, meaning that
every (handle type, handle number) tuple is guaranteed to be unique within
a connection and that a handle alone (without its type) is meaningless or
ambiguous. Connection manager implementations should reference count these
handles to determine if they are in use either by any active clients or any
open channels, and may deallocate them when this ceases to be true. Clients
may request handles of a given type and identifier with the
<a href="Connection.html#Method:RequestHandles" title="Method org.freedesktop.Telepathy.Connection.RequestHandles">RequestHandles</a> method, inspect the entity
identifier with the <a href="Connection.html#Method:InspectHandles" title="Method org.freedesktop.Telepathy.Connection.InspectHandles">InspectHandles</a>
method, keep handles from being released with
<a href="Connection.html#Method:HoldHandles" title="Method org.freedesktop.Telepathy.Connection.HoldHandles">HoldHandles</a>, and notify that they are no
longer storing handles with
<a href="Connection.html#Method:ReleaseHandles" title="Method org.freedesktop.Telepathy.Connection.ReleaseHandles">ReleaseHandles</a>.</p>
</div>
<div class="outset methods method">
<a name="methods"></a>
<h1>Methods</h1>
<div class="inset method">
<a name="Method:Connect"></a>
<span class="permalink">(<a href="Connection.html#Method:Connect">Permalink</a>)</span>
<h2>Connect () → nothing</h2>
<div class="docstring" xmlns="http://www.w3.org/1999/xhtml">
<p>Request that the connection be established. This will be done
asynchronously and errors will be returned by emitting
<a href="Connection.html#Signal:StatusChanged" title="Signal org.freedesktop.Telepathy.Connection.StatusChanged">StatusChanged</a> signals.</p>
<p>Calling this method on a Connection that is already connecting
or connected is allowed, and has no effect.</p>
</div>
</div>
<div class="inset method">
<a name="Method:Disconnect"></a>
<span class="permalink">(<a href="Connection.html#Method:Disconnect">Permalink</a>)</span>
<h2>Disconnect () → nothing</h2>
<div class="docstring">
Request that the connection be closed. This closes the connection if
it's not already in DISCONNECTED state, and destroys the connection
object.
</div>
</div>
<div class="inset method">
<a name="Method:GetInterfaces"></a>
<span class="permalink">(<a href="Connection.html#Method:GetInterfaces">Permalink</a>)</span>
<h2>GetInterfaces () → as: Interfaces</h2>
<div class="indent">
<h3>Returns</h3>
<ul>
<li>
Interfaces — as
(<a href="generic-types.html#Simple-Type:DBus_Interface" title="Array of Simple Type DBus_Interface">DBus_Interface_List</a>)
</li>
<div class="docstring">
The value of the <a href="Connection.html#Property:Interfaces" title="Property org.freedesktop.Telepathy.Connection.Interfaces">Interfaces</a> property
</div>
</ul>
</div>
<div class="docstring" xmlns="http://www.w3.org/1999/xhtml">
<p>Returns the set of optional interfaces supported by this
connection. See <a href="Connection.html#Property:Interfaces" title="Property org.freedesktop.Telepathy.Connection.Interfaces">Interfaces</a> for more
details.</p>
</div>
<hr/>
<div class="indent">
<h3>Possible Errors</h3>
<ul>
<li><a href="errors.html#Error:Disconnected" title="Error org.freedesktop.Telepathy.Error.Disconnected">Disconnected</a></li>
<div class="docstring">
Before version 0.17.8 calling GetInterfaces while
on a connection that is not yet CONNECTED wasn't allowed. If a
CM returns this error, its list of interfaces should be regarded
as empty until it becomes CONNECTED.
</div>
</ul>
</div>
</div>
<div class="inset method">
<a name="Method:GetProtocol"></a>
<span class="permalink">(<a href="Connection.html#Method:GetProtocol">Permalink</a>)</span>
<h2>GetProtocol () → s: Protocol</h2>
<div class="indent">
<h3>Returns</h3>
<ul>
<li>
Protocol — s
(<a href="Connection_Manager.html#Simple-Type:Protocol" title="Simple Type Protocol">Protocol</a>)
</li>
<div class="docstring">
A string identifier for the protocol
</div>
</ul>
</div>
<div class="docstring">
Get the protocol this connection is using.
</div>
</div>
<div class="inset method">
<a name="Method:GetSelfHandle"></a>
<span class="permalink">(<a href="Connection.html#Method:GetSelfHandle">Permalink</a>)</span>
<h2>GetSelfHandle () → u: Self_Handle</h2>
<div class="annotation deprecated"><span class="version">Deprecated since 0.17.10. </span>Use GetAll to get the
SelfHandle property (and all other Connection properties)
instead.</div>
<div class="indent">
<h3>Returns</h3>
<ul>
<li>
Self_Handle — u
(<a href="Connection.html#Simple-Type:Contact_Handle" title="Simple Type Contact_Handle">Contact_Handle</a>)
</li>
<div class="docstring">
The value of the <a href="Connection.html#Property:SelfHandle" title="Property org.freedesktop.Telepathy.Connection.SelfHandle">SelfHandle</a> property
</div>
</ul>
</div>
<div class="docstring">
Returns the value of the SelfHandle property. Change notification
is via the SelfHandleChanged signal.
</div>
<hr/>
<div class="indent">
<h3>Possible Errors</h3>
<ul>
<li><a href="errors.html#Error:Disconnected" title="Error org.freedesktop.Telepathy.Error.Disconnected">Disconnected</a></li>
<div class="docstring">
The connection is not currently connected and cannot be used.
This error may also be raised when operations are performed on a
Connection for which
<a href="Connection.html#Signal:StatusChanged" namespace="org.freedesktop.Telepathy.Connection" title="Signal org.freedesktop.Telepathy.Connection.StatusChanged">StatusChanged</a>
has signalled status Disconnected for reason None.
<div class="rationale"><h5>Rationale:</h5><div>
The second usage corresponds to None in the
<a href="Connection.html#Enum:Connection_Status_Reason">Connection_Status_Reason</a> enum; if a better reason
is available, the corresponding error should be used instead.
</div></div>
</div>
</ul>
</div>
</div>
<div class="inset method">
<a name="Method:GetStatus"></a>
<span class="permalink">(<a href="Connection.html#Method:GetStatus">Permalink</a>)</span>
<h2>GetStatus () → u: Status</h2>
<div class="indent">
<h3>Returns</h3>
<ul>
<li>
Status — u
(<a href="Connection.html#Enum:Connection_Status" title="Enum Connection_Status">Connection_Status</a>)
</li>
<div class="docstring">
The value of the <a href="Connection.html#Property:Status" title="Property org.freedesktop.Telepathy.Connection.Status">Status</a> property
</div>
</ul>
</div>
<div class="docstring">
Get the current status as defined in the
<a href="Connection.html#Signal:StatusChanged" title="Signal org.freedesktop.Telepathy.Connection.StatusChanged">StatusChanged</a> signal.
</div>
</div>
<div class="inset method">
<a name="Method:HoldHandles"></a>
<span class="permalink">(<a href="Connection.html#Method:HoldHandles">Permalink</a>)</span>
<h2>HoldHandles (u: Handle_Type, au: Handles) → nothing</h2>
<div class="annotation changed"><span class="version">Changed in 0.21.6. </span>If
<a href="Connection.html#Property:HasImmortalHandles" title="Property org.freedesktop.Telepathy.Connection.HasImmortalHandles">HasImmortalHandles</a> is true,
this method no longer does anything.</div>
<div class="indent">
<h3>Parameters</h3>
<ul>
<li>
Handle_Type — u
(<a href="Connection.html#Enum:Handle_Type" title="Enum Handle_Type">Handle_Type</a>)
</li>
<div class="docstring">
The type of handle to be held
</div>
<li>
Handles — au
(<a href="Connection.html#Simple-Type:Handle" title="Array of Simple Type Handle">Handle_List</a>)
</li>
<div class="docstring">
A array of integer handles to hold
</div>
</ul>
</div>
<div class="docstring" xmlns="http://www.w3.org/1999/xhtml">
<p>If <a href="Connection.html#Property:HasImmortalHandles" title="Property org.freedesktop.Telepathy.Connection.HasImmortalHandles">HasImmortalHandles</a> is true,
which SHOULD always be the case in this version of telepathy-spec,
this method does nothing and returns successfully, unless
the given handle type or any of the given handles is invalid.</p>
<p>In older connection managers, this method
notifies the connection manger that your client is holding a copy
of handles which may not be in use in any existing channel or
list, and were not obtained by using the
<a href="Connection.html#Method:RequestHandles" title="Method org.freedesktop.Telepathy.Connection.RequestHandles">RequestHandles</a> method. For
example, a handle observed in an emitted signal, or displayed
somewhere in the UI that is not associated with a channel. The
connection manager must not deallocate a handle where any clients
have used this method to indicate it is in use until the
<a href="Connection.html#Method:ReleaseHandles" title="Method org.freedesktop.Telepathy.Connection.ReleaseHandles">ReleaseHandles</a>
method is called, or the clients disappear from the bus.</p>
<p>Note that HoldHandles is idempotent - calling it multiple times
is equivalent to calling it once. If a handle is "referenced" by
several components which share a D-Bus unique name, the client
should perform reference counting internally, and only call
ReleaseHandles when none of the cooperating components need the
handle any longer.</p>
</div>
<hr/>
<div class="indent">
<h3>Possible Errors</h3>
<ul>
<li><a href="errors.html#Error:Disconnected" title="Error org.freedesktop.Telepathy.Error.Disconnected">Disconnected</a></li>
<div class="docstring">
The connection is not currently connected and cannot be used.
This error may also be raised when operations are performed on a
Connection for which
<a href="Connection.html#Signal:StatusChanged" namespace="org.freedesktop.Telepathy.Connection" title="Signal org.freedesktop.Telepathy.Connection.StatusChanged">StatusChanged</a>
has signalled status Disconnected for reason None.
<div class="rationale"><h5>Rationale:</h5><div>
The second usage corresponds to None in the
<a href="Connection.html#Enum:Connection_Status_Reason">Connection_Status_Reason</a> enum; if a better reason
is available, the corresponding error should be used instead.
</div></div>
</div>
<li><a href="errors.html#Error:Invalid Argument" title="Error org.freedesktop.Telepathy.Error.InvalidArgument">Invalid Argument</a></li>
<div class="docstring">
The handle type is invalid
</div>
<li><a href="errors.html#Error:Invalid Handle" title="Error org.freedesktop.Telepathy.Error.InvalidHandle">Invalid Handle</a></li>
<div class="docstring">
One of the given handles is not valid
</div>
</ul>
</div>
</div>
<div class="inset method">
<a name="Method:InspectHandles"></a>
<span class="permalink">(<a href="Connection.html#Method:InspectHandles">Permalink</a>)</span>
<h2>InspectHandles (u: Handle_Type, au: Handles) → as: Identifiers</h2>
<div class="indent">
<h3>Parameters</h3>
<ul>
<li>
Handle_Type — u
(<a href="Connection.html#Enum:Handle_Type" title="Enum Handle_Type">Handle_Type</a>)
</li>
<div class="docstring">
The type of handle to be inspected
</div>
<li>
Handles — au
(<a href="Connection.html#Simple-Type:Handle" title="Array of Simple Type Handle">Handle_List</a>)
</li>
<div class="docstring">
An array of integer handles of this type
</div>
</ul>
</div>
<div class="indent">
<h3>Returns</h3>
<ul>
<li>
Identifiers — as
</li>
<div class="docstring">
An array of identifiers corresponding to the given handles, in the same order.
</div>
</ul>
</div>
<div class="docstring">
Return a string representation for a number of handles of a given
type.
</div>
<hr/>
<div class="indent">
<h3>Possible Errors</h3>
<ul>
<li><a href="errors.html#Error:Disconnected" title="Error org.freedesktop.Telepathy.Error.Disconnected">Disconnected</a></li>
<div class="docstring">
The connection is not currently connected and cannot be used.
This error may also be raised when operations are performed on a
Connection for which
<a href="Connection.html#Signal:StatusChanged" namespace="org.freedesktop.Telepathy.Connection" title="Signal org.freedesktop.Telepathy.Connection.StatusChanged">StatusChanged</a>
has signalled status Disconnected for reason None.
<div class="rationale"><h5>Rationale:</h5><div>
The second usage corresponds to None in the
<a href="Connection.html#Enum:Connection_Status_Reason">Connection_Status_Reason</a> enum; if a better reason
is available, the corresponding error should be used instead.
</div></div>
</div>
<li><a href="errors.html#Error:Invalid Argument" title="Error org.freedesktop.Telepathy.Error.InvalidArgument">Invalid Argument</a></li>
<div class="docstring">
The handle type is invalid
</div>
<li><a href="errors.html#Error:Invalid Handle" title="Error org.freedesktop.Telepathy.Error.InvalidHandle">Invalid Handle</a></li>
<div class="docstring">
One of the given handles is not valid
</div>
</ul>
</div>
</div>
<div class="inset method">
<a name="Method:ListChannels"></a>
<span class="permalink">(<a href="Connection.html#Method:ListChannels">Permalink</a>)</span>
<h2>ListChannels () → a(osuu): Channel_Info</h2>
<div class="annotation deprecated"><span class="version">Deprecated since 0.17.23. </span>Use the
<a href="Connection_Interface_Requests.html#Property:Channels" namespace="org.freedesktop.Telepathy.Connection.Interface" title="Property org.freedesktop.Telepathy.Connection.Interface.Requests.Channels">Requests.Channels</a>
property instead.
</div>
<div class="indent">
<h3>Returns</h3>
<ul>
<li>
Channel_Info — a(osuu)
(<a href="Connection.html#Struct:Channel_Info" title="Array of Struct Channel_Info">Channel_Info_List</a>)
</li>
<div class="docstring">
An array of structs representing channels.
</div>
</ul>
</div>
<div class="docstring">
List all the channels which currently exist on this connection.
</div>
<hr/>
<div class="indent">
<h3>Possible Errors</h3>
<ul>
<li><a href="errors.html#Error:Disconnected" title="Error org.freedesktop.Telepathy.Error.Disconnected">Disconnected</a></li>
<div class="docstring">
The connection is not currently connected and cannot be used.
This error may also be raised when operations are performed on a
Connection for which
<a href="Connection.html#Signal:StatusChanged" namespace="org.freedesktop.Telepathy.Connection" title="Signal org.freedesktop.Telepathy.Connection.StatusChanged">StatusChanged</a>
has signalled status Disconnected for reason None.
<div class="rationale"><h5>Rationale:</h5><div>
The second usage corresponds to None in the
<a href="Connection.html#Enum:Connection_Status_Reason">Connection_Status_Reason</a> enum; if a better reason
is available, the corresponding error should be used instead.
</div></div>
</div>
</ul>
</div>
</div>
<div class="inset method">
<a name="Method:ReleaseHandles"></a>
<span class="permalink">(<a href="Connection.html#Method:ReleaseHandles">Permalink</a>)</span>
<h2>ReleaseHandles (u: Handle_Type, au: Handles) → nothing</h2>
<div class="annotation changed"><span class="version">Changed in 0.21.6. </span>If
<a href="Connection.html#Property:HasImmortalHandles" title="Property org.freedesktop.Telepathy.Connection.HasImmortalHandles">HasImmortalHandles</a> is true,
this method no longer does anything.</div>
<div class="indent">
<h3>Parameters</h3>
<ul>
<li>
Handle_Type — u
(<a href="Connection.html#Enum:Handle_Type" title="Enum Handle_Type">Handle_Type</a>)
</li>
<div class="docstring">
An integer handle type (as defined in RequestHandle)
</div>
<li>
Handles — au
(<a href="Connection.html#Simple-Type:Handle" title="Array of Simple Type Handle">Handle_List</a>)
</li>
<div class="docstring">
An array of integer handles being held by the client
</div>
</ul>
</div>
<div class="docstring">
<p>If <a href="Connection.html#Property:HasImmortalHandles" title="Property org.freedesktop.Telepathy.Connection.HasImmortalHandles">HasImmortalHandles</a> is true,
which SHOULD always be the case in this version of telepathy-spec,
this method does nothing and returns successfully, unless
the given handle type or any of the given handles is invalid.</p>
<p>In older connection managers, this method
explicitly notifies the connection manager that your client is no
longer holding any references to the given handles, and that they
may be deallocated if they are not held by any other clients or
referenced by any existing channels. See
<a href="Connection.html#Method:HoldHandles" title="Method org.freedesktop.Telepathy.Connection.HoldHandles">HoldHandles</a> for notes.</p>
</div>
<hr/>
<div class="indent">
<h3>Possible Errors</h3>
<ul>
<li><a href="errors.html#Error:Disconnected" title="Error org.freedesktop.Telepathy.Error.Disconnected">Disconnected</a></li>
<div class="docstring">
The connection is not currently connected and cannot be used.
This error may also be raised when operations are performed on a
Connection for which
<a href="Connection.html#Signal:StatusChanged" namespace="org.freedesktop.Telepathy.Connection" title="Signal org.freedesktop.Telepathy.Connection.StatusChanged">StatusChanged</a>
has signalled status Disconnected for reason None.
<div class="rationale"><h5>Rationale:</h5><div>
The second usage corresponds to None in the
<a href="Connection.html#Enum:Connection_Status_Reason">Connection_Status_Reason</a> enum; if a better reason
is available, the corresponding error should be used instead.
</div></div>
</div>
<li><a href="errors.html#Error:Invalid Argument" title="Error org.freedesktop.Telepathy.Error.InvalidArgument">Invalid Argument</a></li>
<div class="docstring">
The handle type is invalid
</div>
<li><a href="errors.html#Error:Invalid Handle" title="Error org.freedesktop.Telepathy.Error.InvalidHandle">Invalid Handle</a></li>
<div class="docstring">
One of the given handles is not valid
</div>
</ul>
</div>
</div>
<div class="inset method">
<a name="Method:RequestChannel"></a>
<span class="permalink">(<a href="Connection.html#Method:RequestChannel">Permalink</a>)</span>
<h2>RequestChannel (s: Type, u: Handle_Type, u: Handle, b: Suppress_Handler) → o: Object_Path</h2>
<div class="annotation deprecated"><span class="version">Deprecated since 0.17.23. </span>Use
<a href="Connection_Interface_Requests.html#Method:CreateChannel" namespace="org.freedesktop.Telepathy.Connection.Interface" title="Method org.freedesktop.Telepathy.Connection.Interface.Requests.CreateChannel">Requests.CreateChannel</a>
or <a href="Connection_Interface_Requests.html#Method:EnsureChannel" namespace="org.freedesktop.Telepathy.Connection.Interface" title="Method org.freedesktop.Telepathy.Connection.Interface.Requests.EnsureChannel">Requests.EnsureChannel</a>
instead. Connection managers MAY implement RequestChannel by
raising NotImplemented, or implement fewer types of channel via
this API.</div>
<div class="indent">
<h3>Parameters</h3>
<ul>
<li>
Type — s
(<a href="generic-types.html#Simple-Type:DBus_Interface" title="Simple Type DBus_Interface">DBus_Interface</a>)
</li>
<div class="docstring">
A D-Bus interface name representing base channel type
</div>
<li>
Handle_Type — u
(<a href="Connection.html#Enum:Handle_Type" title="Enum Handle_Type">Handle_Type</a>)
</li>
<div class="docstring">
An integer representing the handle type, or Handle_Type_None if
no handle is specified
</div>
<li>
Handle — u
(<a href="Connection.html#Simple-Type:Handle" title="Simple Type Handle">Handle</a>)
</li>
<div class="docstring">
A nonzero integer handle representing a contact, room, list etc.
according to handle_type, or zero if the handle_type is
Handle_Type_None
</div>
<li>
Suppress_Handler — b
</li>
<div class="docstring">
<p>Clients SHOULD always set this to true.</p>
<div class="rationale"><h5>Rationale:</h5><div>
<p>The historical meaning was that clients that did not
intend to take responsibility for displaying the channel to
the user could set this to FALSE, in which case the channel
dispatcher would launch an appropriate channel handler.</p>
<p>However, clients whose functionality relies on having a
working channel dispatcher should obtain that functionality by
calling methods on the channel dispatcher, so that they will
get an appropriate error if the channel dispatcher is missing
or not working.</p>
<p>The channel dispatcher itself should set this to true too,
so that it will ignore the
<a href="Connection.html#Signal:NewChannel" title="Signal org.freedesktop.Telepathy.Connection.NewChannel">NewChannel</a> signal that results
from the creation of the channel. It can then dispatch the
channel returned from this method to an
appropriate handler.</p>
<p>So, there is no sensible use-case for setting this to false,
and setting it to false can result in unhandled channels (in
the case where clients assume that a channel dispatcher is
present, but it isn't).</p>
</div></div>
</div>
</ul>
</div>
<div class="indent">
<h3>Returns</h3>
<ul>
<li>
Object_Path — o
</li>
<div class="docstring">
The D-Bus object path for the channel created or retrieved
</div>
</ul>
</div>
<div class="docstring" xmlns="http://www.w3.org/1999/xhtml">
<p>Request a channel satisfying the specified type and communicating
with the contact, room, list etc. indicated by the given
handle_type and handle. The handle_type and handle may both be
zero to request the creation of a new, empty channel, which may
or may not be possible, depending on the protocol and channel
type.</p>
<p>On success, the returned channel will always be of the requested
type (i.e. implement the requested channel-type interface).</p>
<p>If a new, empty channel is requested, on success the returned
channel will always be an "anonymous" channel for which the type
and handle are both zero.</p>
<p>If a channel to a contact, room etc. is requested, on success, the
returned channel may either be a new or existing channel to
the requested entity (i.e. its
<a href="Channel.html#Property:TargetHandleType" namespace="org.freedesktop.Telepathy.Channel" title="Property org.freedesktop.Telepathy.Channel.TargetHandleType">TargetHandleType</a>
and <a href="Channel.html#Property:TargetHandle" namespace="org.freedesktop.Telepathy.Channel" title="Property org.freedesktop.Telepathy.Channel.TargetHandle">TargetHandle</a>
properties are the
requested handle type and handle), or a newly created "anonymous"
channel associated with the requested handle in some
implementation-specific way.</p>
<p>For example, for a contact handle, the returned channel
might be "anonymous", but implement the groups interface and have
the requested contact already present among the members.</p>
<p>If the request cannot be satisfied, an error is raised and no
channel is created.</p>
</div>
<hr/>
<div class="indent">
<h3>Possible Errors</h3>
<ul>
<li><a href="errors.html#Error:Disconnected" title="Error org.freedesktop.Telepathy.Error.Disconnected">Disconnected</a></li>
<div class="docstring">
The connection is not currently connected and cannot be used.
This error may also be raised when operations are performed on a
Connection for which
<a href="Connection.html#Signal:StatusChanged" namespace="org.freedesktop.Telepathy.Connection" title="Signal org.freedesktop.Telepathy.Connection.StatusChanged">StatusChanged</a>
has signalled status Disconnected for reason None.
<div class="rationale"><h5>Rationale:</h5><div>
The second usage corresponds to None in the
<a href="Connection.html#Enum:Connection_Status_Reason">Connection_Status_Reason</a> enum; if a better reason
is available, the corresponding error should be used instead.
</div></div>
</div>
<li><a href="errors.html#Error:Network Error" title="Error org.freedesktop.Telepathy.Error.NetworkError">Network Error</a></li>
<div class="docstring">
Raised when there is an error reading from or writing to the network.
</div>
<li><a href="errors.html#Error:Not Implemented" title="Error org.freedesktop.Telepathy.Error.NotImplemented">Not Implemented</a></li>
<div class="docstring">
Unknown channel type
</div>
<li><a href="errors.html#Error:Invalid Handle" title="Error org.freedesktop.Telepathy.Error.InvalidHandle">Invalid Handle</a></li>
<div class="docstring">
The given handle does not exist or cannot be created
</div>
<li><a href="errors.html#Error:Not Available" title="Error org.freedesktop.Telepathy.Error.NotAvailable">Not Available</a></li>
<div class="docstring">
The requested channel type cannot be created with the given handle
</div>
<li><a href="errors.html#Error:Not Capable" title="Error org.freedesktop.Telepathy.Error.NotCapable">Not Capable</a></li>
<div class="docstring">
The requested channel cannot be created because contact doesn't
have the required capabilities.
</div>
<li><a href="errors.html#Error:Channel.Banned" title="Error org.freedesktop.Telepathy.Error.Channel.Banned">Channel.Banned</a></li>
<div class="docstring">
You are banned from the channel.
</div>
<li><a href="errors.html#Error:Channel.Full" title="Error org.freedesktop.Telepathy.Error.Channel.Full">Channel.Full</a></li>
<div class="docstring">
The channel is full.
</div>
<li><a href="errors.html#Error:Channel.Invite Only" title="Error org.freedesktop.Telepathy.Error.Channel.InviteOnly">Channel.Invite Only</a></li>
<div class="docstring">
The requested channel is invite-only.
</div>
</ul>
</div>
</div>
<div class="inset method">
<a name="Method:RequestHandles"></a>
<span class="permalink">(<a href="Connection.html#Method:RequestHandles">Permalink</a>)</span>
<h2>RequestHandles (u: Handle_Type, as: Identifiers) → au: Handles</h2>
<div class="annotation changed"><span class="version">Changed in 0.21.6. </span>If
<a href="Connection.html#Property:HasImmortalHandles" title="Property org.freedesktop.Telepathy.Connection.HasImmortalHandles">HasImmortalHandles</a> is true,
this method no longer has its reference-counting effect.</div>
<div class="indent">
<h3>Parameters</h3>
<ul>
<li>
Handle_Type — u
(<a href="Connection.html#Enum:Handle_Type" title="Enum Handle_Type">Handle_Type</a>)
</li>
<div class="docstring">
The type of handle required
</div>
<li>
Identifiers — as
</li>
<div class="docstring">
An array of identifiers of entities to request handles for
</div>
</ul>
</div>
<div class="indent">
<h3>Returns</h3>
<ul>
<li>
Handles — au
(<a href="Connection.html#Simple-Type:Handle" title="Array of Simple Type Handle">Handle_List</a>)
</li>
<div class="docstring">
An array of integer handle numbers in the same order as the given identifiers.
</div>
</ul>
</div>
<div class="docstring" xmlns="http://www.w3.org/1999/xhtml">
<p>Request several handles from the connection manager which represent a
number of contacts, rooms or server-stored lists on the service.</p>
<p>If <a href="Connection.html#Property:HasImmortalHandles" title="Property org.freedesktop.Telepathy.Connection.HasImmortalHandles">HasImmortalHandles</a> is true,
which SHOULD always be the case in this version of telepathy-spec,
the handles remain valid until the connection disconnects.</p>
<p>The implementation of this method in older connection managers
must record that these handles are in use by the
client who invokes this method, and must not deallocate the handles
until the client disconnects from the bus or calls the
<a href="Connection.html#Method:ReleaseHandles" title="Method org.freedesktop.Telepathy.Connection.ReleaseHandles">ReleaseHandles</a>
method. Where the identifier refers to an entity that already has a
handle in this connection manager, this handle should be returned
instead. The handle number 0 must not be returned by the connection
manager.</p>
</div>
<hr/>
<div class="indent">
<h3>Possible Errors</h3>
<ul>
<li><a href="errors.html#Error:Disconnected" title="Error org.freedesktop.Telepathy.Error.Disconnected">Disconnected</a></li>
<div class="docstring">
The connection is not currently connected and cannot be used.
This error may also be raised when operations are performed on a
Connection for which
<a href="Connection.html#Signal:StatusChanged" namespace="org.freedesktop.Telepathy.Connection" title="Signal org.freedesktop.Telepathy.Connection.StatusChanged">StatusChanged</a>
has signalled status Disconnected for reason None.
<div class="rationale"><h5>Rationale:</h5><div>
The second usage corresponds to None in the
<a href="Connection.html#Enum:Connection_Status_Reason">Connection_Status_Reason</a> enum; if a better reason
is available, the corresponding error should be used instead.
</div></div>
</div>
<li><a href="errors.html#Error:Invalid Handle" title="Error org.freedesktop.Telepathy.Error.InvalidHandle">Invalid Handle</a></li>
<div class="docstring">
The given identifier does not identify a valid entity of the given
type.
<div class="rationale"><h5>Rationale:</h5><div>
For instance, an XMPP connection would raise this error for
identifiers with type Handle_Type_Room that do not contain
exactly one '@' character, that contain spaces, and so on.
</div></div>
</div>
<li><a href="errors.html#Error:Not Implemented" title="Error org.freedesktop.Telepathy.Error.NotImplemented">Not Implemented</a></li>
<div class="docstring">
The given handle type is not valid, or is not implemented on this
connection.
<div class="rationale"><h5>Rationale:</h5><div>
For instance, a connection to a protocol that doesn't have
chat rooms would raise this error for room handles, and all CMs
would raise this error for Handle_Type_None.
</div></div>
</div>
</ul>
</div>
</div>
<div class="inset method">
<a name="Method:AddClientInterest"></a>
<span class="permalink">(<a href="Connection.html#Method:AddClientInterest">Permalink</a>)</span>
<h2>AddClientInterest (as: Tokens) → nothing</h2>
<div class="annotation added"><span class="version">Added in 0.21.3. </span></div>
<div class="indent">
<h3>Parameters</h3>
<ul>
<li>
Tokens — as
</li>
<div class="docstring" xmlns="http://www.w3.org/1999/xhtml">
<p>Interfaces or parts of interfaces in which to register an
interest, represented by either a
<a href="generic-types.html#Simple-Type:DBus_Interface">DBus_Interface</a>, or a string prefixed with a
<a href="generic-types.html#Simple-Type:DBus_Interface">DBus_Interface</a>.</p>
<p>If the Connection does not support one of these tokens, this
is not considered to be an error; the unsupported token is
simply ignored.</p>
</div>
</ul>
</div>
<div class="docstring" xmlns="http://www.w3.org/1999/xhtml">
<p>Register a client's interest in notifications related to one or
more interfaces.</p>
<p>Groups of notifications are identified by a token which is either
a D-Bus interface name, or a string that starts with a D-Bus
interface name. The meaning of each token is given by that D-Bus
interface, which MUST define it in its documentation.</p>
<div class="rationale"><h5>Rationale:</h5><div>
<p>Initially, all interests are in entire interface, but allowing
other strings allows subscription to part of an interface; for
instance, an interest in ...MailNotification/count could track
the number of messages without caring about their detailed
content.</p>
</div></div>
<p>For each token with which this method interacts, the
Connection tracks an "interest count" (like a reference count) for
each unique bus name that has called this method. When a client
calls this method, for each token, the interest count for its
unique bus name is incremented; when
<a href="Connection.html#Method:RemoveClientInterest" title="Method org.freedesktop.Telepathy.Connection.RemoveClientInterest">RemoveClientInterest</a> is called,
all interest counts for that unique bus name are decremented.
If the unique bus name leaves the bus (for instance, if the
client crashes or exits), all interest counts for that unique bus
name are set to zero.</p>
<p>The Connection can then use these reference counts to
avoid subscribing to protocol-level notifications unless at least
one client has a non-zero interest count for the relevant
token.</p>
<div class="rationale"><h5>Rationale:</h5><div>
<p>This method exists to reduce memory and network overhead when
there is no active subscription.</p>
<p>One situation where this is useful is <a href="Connection_Interface_Location.html" namespace="org.freedesktop.Telepathy.Connection.Interface" title="Interface org.freedesktop.Telepathy.Connection.Interface.Location">Location</a>: on XMPP, location updates are received
over PEP. If the Connection advertises the
<code>geoloc+notify</code> capability, it will be sent location
updates for all contacts. To avoid consuming resources for this,
the connection should avoid advertising that capability until
a client has expressed an interest in contacts' locations.</p>
<p>Another example of a protocol that benefits from this method is
the Google XMPP Mail Notification extension, which can be used
to implement <a href="Connection_Interface_Mail_Notification.html#Client-Interest:org.freedesktop.Telepathy.Connection.Interface.MailNotification" namespace="org.freedesktop.Telepathy.Connection.Interface" title="Client Interest org.freedesktop.Telepathy.Connection.Interface.MailNotification">MailNotification</a>. In this protocol, the CM
receives a notification that something has changed, but to get
more information, the CM must request this information. Knowing
that nobody is currently interested in this information, the CM
can avoid generating useless network traffic. Similarly, the CM
may free the list of unread messages to reduce memory overhead.</p>
</div></div>
<p>If this method is called for an interface that might require
protocol-level subscription, but the connection cannot set up
that subscription yet (for instance because the
<a href="Connection.html#Property:Status" title="Property org.freedesktop.Telepathy.Connection.Status">Status</a> is not Connected yet), the
Connection MUST remember the client's interest, and attempt to
subscribe to the appropriate protocol feature when this becomes
possible.</p>
<p>Clients MAY ignore any errors raised by this method; it is intended
to be called with the reply ignored.</p>
<div class="rationale"><h5>Rationale:</h5><div>
<p>The only reason it could fail is if it's unimplemented, in which
case the only thing the client can usefully do is to proceed as if
it had succeeded.</p>
</div></div>
</div>
</div>
<div class="inset method">
<a name="Method:RemoveClientInterest"></a>
<span class="permalink">(<a href="Connection.html#Method:RemoveClientInterest">Permalink</a>)</span>
<h2>RemoveClientInterest (as: Tokens) → nothing</h2>
<div class="annotation added"><span class="version">Added in 0.21.3. </span></div>
<div class="indent">
<h3>Parameters</h3>
<ul>
<li>
Tokens — as
</li>
<div class="docstring" xmlns="http://www.w3.org/1999/xhtml">
<p>Interfaces or parts of interfaces that were previously passed to
<a href="Connection.html#Method:AddClientInterest" title="Method org.freedesktop.Telepathy.Connection.AddClientInterest">AddClientInterest</a>.</p>
</div>
</ul>
</div>
<div class="docstring" xmlns="http://www.w3.org/1999/xhtml">
<p>Release an interest registered using
<a href="Connection.html#Method:AddClientInterest" title="Method org.freedesktop.Telepathy.Connection.AddClientInterest">AddClientInterest</a>. See that
method's documentation for details.</p>
<p>Clients MAY ignore any errors raised by this method; it is intended
to be called with the reply ignored.</p>
<div class="rationale"><h5>Rationale:</h5><div>
<p>The only reasons it could fail are if it's unimplemented, or if
the client's reference-counting is wrong and it has tried to
remove a client interest that it did not add. In both cases,
there's nothing the client could do about it.</p>
</div></div>
</div>
</div>
</div>
<div class="outset signals signal">
<a name="signals"></a>
<h1>Signals</h1>
<div class="inset signal">
<a name="Signal:SelfHandleChanged"></a>
<span class="permalink">(<a href="Connection.html#Signal:SelfHandleChanged">Permalink</a>)</span>
<h2>SelfHandleChanged (u: Self_Handle)</h2>
<div class="annotation added"><span class="version">Added in 0.17.10. </span>Clients MAY assume that if the
SelfHandle property exists, this signal will be emitted when
necessary.</div>
<div class="annotation deprecated"><span class="version">Deprecated since 0.27.2. </span>Use SelfContactChanged to get the
new SelfID at the same time</div>
<div class="indent">
<h3>Parameters</h3>
<ul>
<li>
Self_Handle — u
(<a href="Connection.html#Simple-Type:Contact_Handle" title="Simple Type Contact_Handle">Contact_Handle</a>)
</li>
<div class="docstring">
The new value of the SelfHandle property.
</div>
</ul>
</div>
<div class="docstring">
Emitted whenever the <a href="Connection.html#Property:SelfHandle" title="Property org.freedesktop.Telepathy.Connection.SelfHandle">SelfHandle</a> property
changes. If the connection
is not yet in the CONNECTED state, this signal is not guaranteed
to be emitted.
</div>
</div>
<div class="inset signal">
<a name="Signal:SelfContactChanged"></a>
<span class="permalink">(<a href="Connection.html#Signal:SelfContactChanged">Permalink</a>)</span>
<h2>SelfContactChanged (u: Self_Handle, s: Self_ID)</h2>
<div class="annotation added"><span class="version">Added in 0.27.2. </span>Clients MAY assume that if the
SelfHandle and SelfID property exists, this signal will be emitted when
necessary.</div>
<div class="indent">
<h3>Parameters</h3>
<ul>
<li>
Self_Handle — u
(<a href="Connection.html#Simple-Type:Contact_Handle" title="Simple Type Contact_Handle">Contact_Handle</a>)
</li>
<div class="docstring">
The new value of the SelfHandle property.
</div>
<li>
Self_ID — s
</li>
<div class="docstring">
The new value of the SelfID property.
</div>
</ul>
</div>
<div class="docstring">
Emitted whenever the <a href="Connection.html#Property:SelfHandle" title="Property org.freedesktop.Telepathy.Connection.SelfHandle">SelfHandle</a> and
<a href="Connection.html#Property:SelfID" title="Property org.freedesktop.Telepathy.Connection.SelfID">SelfID</a> property
changes. If the connection
is not yet in the CONNECTED state, this signal is not guaranteed
to be emitted.
</div>
</div>
<div class="inset signal">
<a name="Signal:NewChannel"></a>
<span class="permalink">(<a href="Connection.html#Signal:NewChannel">Permalink</a>)</span>
<h2>NewChannel (o: Object_Path, s: Channel_Type, u: Handle_Type, u: Handle, b: Suppress_Handler)</h2>
<div class="annotation deprecated"><span class="version">Deprecated since 0.17.23. </span>Connection managers MUST still
emit this signal, but clients SHOULD listen for the <a href="Connection_Interface_Requests.html#Signal:NewChannels" namespace="org.freedesktop.Telepathy.Connection.Interface" title="Signal org.freedesktop.Telepathy.Connection.Interface.Requests.NewChannels">Requests.NewChannels</a>
signal instead.
</div>
<div class="indent">
<h3>Parameters</h3>
<ul>
<li>
Object_Path — o
</li>
<div class="docstring">
A D-Bus object path for the channel object on this service
</div>
<li>
Channel_Type — s
(<a href="generic-types.html#Simple-Type:DBus_Interface" title="Simple Type DBus_Interface">DBus_Interface</a>)
</li>
<div class="docstring">
A D-Bus interface name representing the channel type
</div>
<li>
Handle_Type — u
(<a href="Connection.html#Enum:Handle_Type" title="Enum Handle_Type">Handle_Type</a>)
</li>
<div class="docstring">
An integer representing the type of handle this channel
communicates with, or Handle_Type_None if no handle is specified
</div>
<li>
Handle — u
(<a href="Connection.html#Simple-Type:Handle" title="Simple Type Handle">Handle</a>)
</li>
<div class="docstring">
A handle indicating the specific contact, room or list this
channel communicates with, or zero if no handle is specified
</div>
<li>
Suppress_Handler — b
</li>
<div class="docstring" xmlns="http://www.w3.org/1999/xhtml">
<p>If true, the channel was requested by a client that intends to
present it to the user itself (i.e. it passed suppress_handler=TRUE
to the <a href="Connection.html#Method:RequestChannel" title="Method org.freedesktop.Telepathy.Connection.RequestChannel">RequestChannel</a> method), so no
other handler should be
launched. Clients MAY assume that channels where this is true
were created by a user request.</p>
<p>If false, either the channel was created due to incoming
information from the service, or the channel was requested by
a local client that does not intend to handle the channel itself
(this usage is deprecated).</p>
<p>Clients MUST NOT assume that only incoming channels will have
this flag set to false.</p>
</div>
</ul>
</div>
<div class="docstring">
Emitted when a new Channel object is created, either through user
request or incoming information from the service.
</div>
</div>
<div class="inset signal">
<a name="Signal:ConnectionError"></a>
<span class="permalink">(<a href="Connection.html#Signal:ConnectionError">Permalink</a>)</span>
<h2>ConnectionError (s: Error, a{sv}: Details)</h2>
<div class="indent">
<h3>Parameters</h3>
<ul>
<li>
Error — s
(<a href="generic-types.html#Simple-Type:DBus_Error_Name" title="Simple Type DBus_Error_Name">DBus_Error_Name</a>)
</li>
<div class="docstring">
The name of a D-Bus error describing the error that occurred,
which may correspond to a
<a href="Connection.html#Enum:Connection_Status_Reason">Connection_Status_Reason</a>, or may be a more
specific Telepathy error
(such as
<code>org.freedesktop.Telepathy.Error.ConnectionRefused</code>
for Connection_Status_Reason_Network_Error)
or a protocol-specific or connection-manager-specific error in a
suitable namespace.
<div class="rationale"><h5>Rationale:</h5><div>
For instance, a SIP connection manager could signal
"402 Payment Required" as an error in a
connection-manager-specific namespace, or a link-local
XMPP implementation that used Avahi could provide the error
given to it by the avahi-daemon.
</div></div>
</div>
<li>
Details — a{sv}
(<a href="generic-types.html#Mapping:String_Variant_Map" title="Mapping String_Variant_Map">String_Variant_Map</a>)
</li>
<div class="docstring" xmlns="http://www.w3.org/1999/xhtml">
<p>Additional information about the error, which may include
the following well-known keys:</p>
<dl>
<dt>debug-message (s)</dt>
<dd>Debugging information on the change, corresponding to the
message part of a D-Bus error message, which SHOULD NOT be
displayed to users under normal circumstances</dd>
<dt>server-message (s)</dt>
<dd>A human-readable message from the server explaining what
happened. This may be in the user's native language, or in the
server operator's native language, or even in Lojban.</dd>
<dt>user-requested (b), expected-hostname (s), certificate-hostname (s)</dt>
<dd>The same details defined in <a href="Authentication_TLS_Certificate.html#Struct:TLS_Certificate_Rejection">TLS_Certificate_Rejection</a>.</dd>
</dl>
</div>
</ul>
</div>
<div class="docstring" xmlns="http://www.w3.org/1999/xhtml">
<p>Emitted when an error occurs that renders this connection unusable.
</p>
<p>Whenever this signal is emitted, it MUST immediately be followed by
a <a href="Connection.html#Signal:StatusChanged" title="Signal org.freedesktop.Telepathy.Connection.StatusChanged">StatusChanged</a> signal with status
Connection_Status_Disconnected and an appropriate reason
code.</p>
<p>Connection managers SHOULD emit this signal on disconnection, but
need not do so. Clients MUST support connection managers that emit
StatusChanged(Disconnected, ...) without first emitting
ConnectionError.</p>
<div class="rationale"><h5>Rationale:</h5><div>
<p>This signal provides additional information about the reason
for disconnection. The reason for connection is always
straightforward - it was requested - so it does not need further
explanation. However, on errors, it can be useful to provide
additional information.</p>
<p>The <a href="Connection.html#Enum:Connection_Status_Reason">Connection_Status_Reason</a> is not given
here, since it will be signalled in
<a href="Connection.html#Signal:StatusChanged" title="Signal org.freedesktop.Telepathy.Connection.StatusChanged">StatusChanged</a>. A reasonable client
implementation would be to store the information given by this
signal until StatusChanged is received, at which point the
information given by this signal can be used to supplement the
StatusChanged signal.</p>
</div></div>
</div>
</div>
<div class="inset signal">
<a name="Signal:StatusChanged"></a>
<span class="permalink">(<a href="Connection.html#Signal:StatusChanged">Permalink</a>)</span>
<h2>StatusChanged (u: Status, u: Reason)</h2>
<div class="indent">
<h3>Parameters</h3>
<ul>
<li>
Status — u
(<a href="Connection.html#Enum:Connection_Status" title="Enum Connection_Status">Connection_Status</a>)
</li>
<div class="docstring">
An integer indicating the new status, as defined by ConnectionStatus
</div>
<li>
Reason — u
(<a href="Connection.html#Enum:Connection_Status_Reason" title="Enum Connection_Status_Reason">Connection_Status_Reason</a>)
</li>
<div class="docstring">
An integer indicating the reason for the status change, as defined
by ConnectionStatusReason
</div>
</ul>
</div>
<div class="docstring">
Emitted when the status of the connection changes. All states and
reasons have numerical values, as defined in ConnectionStatus
and ConnectionStatusReason.
</div>
</div>
</div>
<div class="outset properties property">
<a name="properties"></a>
<h1>Properties</h1>
<div>
Accessed using the <a
href="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties">org.freedesktop.DBus.Properties</a>
interface.
</div>
<div class="inset property">
<a name="Property:Interfaces"></a>
<span class="permalink">(<a href="Connection.html#Property:Interfaces">Permalink</a>)</span>
<h2>
Interfaces — as
(<a href="generic-types.html#Simple-Type:DBus_Interface" title="Array of Simple Type DBus_Interface">DBus_Interface_List</a>)
</h2>
<div class="access">Read only</div>
<div class="annotation added"><span class="version">Added in 0.19.2. </span>Clients SHOULD fall back
to calling <a href="Connection.html#Method:GetInterfaces" title="Method org.freedesktop.Telepathy.Connection.GetInterfaces">GetInterfaces</a> if this
property is not supported.</div>
<div class="docstring" xmlns="http://www.w3.org/1999/xhtml">
<p>The set of optional interfaces supported by this connection.
Before the connection status changes to CONNECTED,
this property may change at any time, but it is guaranteed that
interfaces will only be added, not removed. After the connection
status changes to CONNECTED, this property cannot
change further.</p>
<p>There is no explicit change notification; reasonable behaviour
for a client would be to retrieve the interfaces list once
initially, and once more when it becomes CONNECTED.</p>
<div class="rationale"><h5>Rationale:</h5><div>
<p>In some connection managers, certain capabilities of a connection
are known to be implemented for all connections (e.g. support
for SimplePresence), and some interfaces (like SimplePresence) can
even be used before connecting. Other capabilities may
or may not exist, depending on server functionality; by the time
the connection goes CONNECTED, the connection manager is expected
to have evaluated the server's functionality and enabled any extra
interfaces for the remainder of the Connection's lifetime.</p>
</div></div>
</div>
</div>
<div class="inset property">
<a name="Property:SelfHandle"></a>
<span class="permalink">(<a href="Connection.html#Property:SelfHandle">Permalink</a>)</span>
<h2>
SelfHandle — u
(<a href="Connection.html#Simple-Type:Contact_Handle" title="Simple Type Contact_Handle">Contact_Handle</a>)
</h2>
<div class="access">Read only</div>
<div class="annotation added"><span class="version">Added in 0.17.10. </span>For compatibility with older
versions, clients should fall back to calling the
<a href="Connection.html#Method:GetSelfHandle" title="Method org.freedesktop.Telepathy.Connection.GetSelfHandle">GetSelfHandle</a>
method.</div>
<div class="docstring">
The handle which represents the user on this connection, which will
remain valid for the lifetime of this connection, or until a change
in the user's identifier is signalled by the
<a href="Connection.html#Signal:SelfContactChanged" title="Signal org.freedesktop.Telepathy.Connection.SelfContactChanged">SelfContactChanged</a> signal.
If the connection is not yet in the CONNECTED state, the value of
this property MAY be zero.
</div>
</div>
<div class="inset property">
<a name="Property:SelfID"></a>
<span class="permalink">(<a href="Connection.html#Property:SelfID">Permalink</a>)</span>
<h2>
SelfID — s
</h2>
<div class="access">Read only</div>
<div class="annotation added"><span class="version">Added in 0.27.2. </span></div>
<div class="docstring">
The identifier which represents the user on this connection, which will
remain valid for the lifetime of this connection, or until a change
in the user's identifier is signalled by the
<a href="Connection.html#Signal:SelfContactChanged" title="Signal org.freedesktop.Telepathy.Connection.SelfContactChanged">SelfContactChanged</a> signal.
If the connection is not yet in the CONNECTED state, the value of
this property MAY be empty string.
</div>
</div>
<div class="inset property">
<a name="Property:Status"></a>
<span class="permalink">(<a href="Connection.html#Property:Status">Permalink</a>)</span>
<h2>
Status — u
(<a href="Connection.html#Enum:Connection_Status" title="Enum Connection_Status">Connection_Status</a>)
</h2>
<div class="access">Read only</div>
<div class="annotation added"><span class="version">Added in 0.19.2. </span>Clients SHOULD fall back
to calling <a href="Connection.html#Method:GetStatus" title="Method org.freedesktop.Telepathy.Connection.GetStatus">GetStatus</a> if this
property is not supported.</div>
<div class="docstring" xmlns="http://www.w3.org/1999/xhtml">
<p>The current status of the connection. Change notification is via
the <a href="Connection.html#Signal:StatusChanged" title="Signal org.freedesktop.Telepathy.Connection.StatusChanged">StatusChanged</a> signal.</p>
<p>If retrieval of property succeeds and yields the value Disconnected,
this indicates that the connection has not yet been established.
If connection has been attempted and failed, the Connection object
SHOULD be removed from the bus entirely, meaning that retrieval of
this property SHOULD fail.</p>
</div>
</div>
<div class="inset property">
<a name="Property:HasImmortalHandles"></a>
<span class="permalink">(<a href="Connection.html#Property:HasImmortalHandles">Permalink</a>)</span>
<h2>
HasImmortalHandles — b
</h2>
<div class="access">Read only</div>
<div class="annotation added"><span class="version">Added in 0.21.6. </span></div>
<div class="docstring" xmlns="http://www.w3.org/1999/xhtml">
<p>True if handles last for the whole lifetime of the Connection.
This SHOULD be the case in all connection managers, but clients
MUST interoperate with older connection managers
(which reference-count handles).</p>
</div>
</div>
</div>
<div class="outset contact-attributes">
<a name="contact-attributes"></a>
<h1>Contact Attributes</h1>
<div>
Attributes that a contact can have, accessed with the
org.freedesktop.Telepathy.Connection.Interface.Contacts interface.
</div>
<div class="inset contact-attribute">
<a name="Contact-Attribute:contact-id"></a>
<span class="permalink">(<a href="Connection.html#Contact-Attribute:contact-id">Permalink</a>)</span>
<h2>
org.freedesktop.Telepathy.Connection/contact-id — s
</h2>
<div class="docstring" xmlns="http://www.w3.org/1999/xhtml">
<p>The same string that would be returned by
<a href="Connection.html#Method:InspectHandles" title="Method org.freedesktop.Telepathy.Connection.InspectHandles">InspectHandles</a>. As a special case,
this is always present in the result of <a href="Connection_Interface_Contacts.html#Method:GetContactAttributes" namespace="org.freedesktop.Telepathy.Connection.Interface.Contacts" title="Method org.freedesktop.Telepathy.Connection.Interface.Contacts.GetContactAttributes">GetContactAttributes</a>,
whether it was explicitly requested or not.</p>
</div>
</div>
</div>
<div class="outset types type">
<a name="types"></a>
<h1>Types</h1>
<div class="inset type">
<a name="Simple-Type:Handle"></a>
<span class="permalink">Simple Type (<a href="Connection.html#Simple-Type:Handle">Permalink</a>)</span>
<h2>
Handle — u
</h2>
<div class="docstring">An unsigned 32-bit integer representing a
handle</div>
</div>
<div class="inset type">
<a name="Simple-Type:Contact_Handle"></a>
<span class="permalink">Simple Type (<a href="Connection.html#Simple-Type:Contact_Handle">Permalink</a>)</span>
<h2>
Contact_Handle — u
</h2>
<div class="docstring">An unsigned 32-bit integer representing a handle of type
Handle_Type_Contact</div>
</div>
<div class="inset type">
<a name="Simple-Type:Room_Handle"></a>
<span class="permalink">Simple Type (<a href="Connection.html#Simple-Type:Room_Handle">Permalink</a>)</span>
<h2>
Room_Handle — u
</h2>
<div class="docstring">An unsigned 32-bit integer representing a handle of type
Handle_Type_Room</div>
</div>
<div class="inset type">
<a name="Simple-Type:List_Handle"></a>
<span class="permalink">Simple Type (<a href="Connection.html#Simple-Type:List_Handle">Permalink</a>)</span>
<h2>
List_Handle — u
</h2>
<div class="annotation deprecated"><span class="version">Deprecated since 0.25.0. </span>Replaced by <a href="Connection_Interface_Contact_List.html" namespace="org.freedesktop.Telepathy" title="Interface org.freedesktop.Telepathy.Connection.Interface.ContactList">Connection.Interface.ContactList</a>
</div>
<div class="docstring">An unsigned 32-bit integer representing a handle of type
Handle_Type_List</div>
</div>
<div class="inset type">
<a name="Simple-Type:Group_Handle"></a>
<span class="permalink">Simple Type (<a href="Connection.html#Simple-Type:Group_Handle">Permalink</a>)</span>
<h2>
Group_Handle — u
</h2>
<div class="annotation deprecated"><span class="version">Deprecated since 0.25.0. </span>Replaced by <a href="Connection_Interface_Contact_List.html" namespace="org.freedesktop.Telepathy" title="Interface org.freedesktop.Telepathy.Connection.Interface.ContactList">Connection.Interface.ContactList</a>
</div>
<div class="docstring">An unsigned 32-bit integer representing a handle of type
Handle_Type_Group</div>
</div>
<div class="inset type">
<a name="Enum:Handle_Type"></a>
<span class="permalink">Enum (<a href="Connection.html#Enum:Handle_Type">Permalink</a>)</span>
<h2>
Handle_Type — u
</h2>
<ul>
<li>None (0)</li>
<div class="docstring">
A "null" handle type used to indicate the absence of a handle.
When a handle type and a handle appear as a pair, if the handle
type is zero, the handle must also be zero.
</div><li>Contact (1)</li>
<div class="docstring">
A contact
</div><li>Room (2)</li>
<div class="docstring">
A chat room
</div><li>List (3)</li>
<div class="annotation deprecated"><span class="version">Deprecated since 0.25.0. </span>Replaced by <a href="Connection_Interface_Contact_List.html" namespace="org.freedesktop.Telepathy" title="Interface org.freedesktop.Telepathy.Connection.Interface.ContactList">Connection.Interface.ContactList</a>
</div><div class="docstring">
A server-generated contact list (see Channel.Interface.Group)
</div><li>Group (4)</li>
<div class="annotation deprecated"><span class="version">Deprecated since 0.25.0. </span>Replaced by <a href="Connection_Interface_Contact_List.html" namespace="org.freedesktop.Telepathy" title="Interface org.freedesktop.Telepathy.Connection.Interface.ContactList">Connection.Interface.ContactList</a>
</div><div class="docstring">
A user-defined contact list (see Channel.Interface.Group)
</div></ul>
</div>
<div class="inset type">
<a name="Enum:Connection_Status"></a>
<span class="permalink">Enum (<a href="Connection.html#Enum:Connection_Status">Permalink</a>)</span>
<h2>
Connection_Status — u
</h2>
<ul>
<li>Connected (0)</li>
<div class="docstring">
The connection is fully connected and all methods are available.
</div><li>Connecting (1)</li>
<div class="docstring">
<a href="Connection.html#Method:Connect" title="Method org.freedesktop.Telepathy.Connection.Connect">Connect</a> has been called but the
connection has not yet been established. Some methods may fail
until the connection has been established.
</div><li>Disconnected (2)</li>
<div class="docstring">
If this is retrieved from <a href="Connection.html#Method:GetStatus" title="Method org.freedesktop.Telepathy.Connection.GetStatus">GetStatus</a> or
<a href="Connection.html#Property:Status" title="Property org.freedesktop.Telepathy.Connection.Status">Status</a>, it indicates that connection
has not yet been attempted. If seen in a
<a href="Connection.html#Signal:StatusChanged" title="Signal org.freedesktop.Telepathy.Connection.StatusChanged">StatusChanged</a> signal, it indicates
that the connection has failed; the Connection object SHOULD be
removed from D-Bus immediately, and all subsequent method calls
SHOULD fail.
</div></ul>
</div>
<div class="inset type">
<a name="Enum:Connection_Status_Reason"></a>
<span class="permalink">Enum (<a href="Connection.html#Enum:Connection_Status_Reason">Permalink</a>)</span>
<h2>
Connection_Status_Reason — u
</h2>
<div class="docstring" xmlns="http://www.w3.org/1999/xhtml">
<p>A reason why the status of the connection changed. Apart from
Requested, the values of this enumeration only make sense as
reasons why the status changed to Disconnected.</p>
</div>
<ul>
<li>None_Specified (0)</li>
<div class="docstring" xmlns="http://www.w3.org/1999/xhtml">
<p>There is no reason set for this state change. Unknown status
reasons SHOULD be treated like this reason.</p>
<p>When disconnected for this reason, the equivalent D-Bus error is
<code>org.freedesktop.Telepathy.Error.<a href="errors.html#Error:Disconnected" title="org.freedesktop.Telepathy.Error.Disconnected">Disconnected</a></code>.</p>
</div><li>Requested (1)</li>
<div class="docstring" xmlns="http://www.w3.org/1999/xhtml">
<p>The change is in response to a user request. Changes to the
Connecting or Connected status SHOULD always indicate this reason;
changes to the Disconnected status SHOULD indicate this reason
if and only if the disconnection was requested by the user.</p>
<p>When disconnected for this reason, the equivalent D-Bus error is
<code>org.freedesktop.Telepathy.Error.Cancelled</code>.</p>
</div><li>Network_Error (2)</li>
<div class="docstring" xmlns="http://www.w3.org/1999/xhtml">
<p>There was an error sending or receiving on the network socket.</p>
<p>When the status changes from Connecting to Disconnected for this
reason, the equivalent D-Bus error is either
<code>org.freedesktop.Telepathy.Error.NetworkError</code>,
<code>org.freedesktop.Telepathy.Error.ConnectionRefused</code>,
<code>org.freedesktop.Telepathy.Error.ConnectionFailed</code>
or some more specific error.</p>
<p>When the status changes from Connected to Disconnected for this
reason, the equivalent D-Bus error is either
<code>org.freedesktop.Telepathy.Error.NetworkError</code>,
<code>org.freedesktop.Telepathy.Error.ConnectionLost</code>
or some more specific error.</p>
</div><li>Authentication_Failed (3)</li>
<div class="docstring" xmlns="http://www.w3.org/1999/xhtml">
<p>The username or password was invalid.</p>
<p>When disconnected for this reason, the equivalent D-Bus error is
<code>org.freedesktop.Telepathy.Error.AuthenticationFailed</code>.
</p>
</div><li>Encryption_Error (4)</li>
<div class="docstring" xmlns="http://www.w3.org/1999/xhtml">
<p>There was an error negotiating SSL on this connection, or
encryption was unavailable and require-encryption was set when the
connection was created.</p>
<p>When disconnected for this reason, the equivalent D-Bus error is
<code>org.freedesktop.Telepathy.Error.EncryptionNotAvailable</code>
if encryption was not available at all, or
<code>org.freedesktop.Telepathy.Error.EncryptionError</code>
if encryption failed.</p>
</div><li>Name_In_Use (5)</li>
<div class="docstring" xmlns="http://www.w3.org/1999/xhtml">
<p>In general, this reason indicates that the requested account
name or other identification could not be used due to conflict
with another connection. It can be divided into three cases:</p>
<ul>
<li>If the status change is from Connecting to Disconnected
and the 'register' parameter to RequestConnection was present
and true, the requested account could not be created on the
server because it already exists.
The equivalent D-Bus error is
<code>org.freedesktop.Telepathy.Error.RegistrationExists</code>.
</li>
<li>If the status change is from Connecting to Disconnected
but the 'register' parameter is absent or false, the connection
manager could not connect to the specified account because
a connection to that account already exists.
The equivalent D-Bus error is
<code>org.freedesktop.Telepathy.Error.AlreadyConnected</code>.
<div class="rationale"><h5>Rationale:</h5><div>
In some protocols, like XMPP (when connecting with the same
JID and resource as an existing connection), the existing
connection "wins" and the new one fails to connect.
</div></div>
</li>
<li>If the status change is from Connected to Disconnected,
the existing connection was automatically disconnected because
a new connection to the same account (perhaps from a different
client or location) was established.
The equivalent D-Bus error is
<code>org.freedesktop.Telepathy.Error.ConnectionReplaced</code>.
<div class="rationale"><h5>Rationale:</h5><div>
In some protocols, like MSNP (when connecting twice with the
same Passport), the new connection "wins" and the
existing one is automatically disconnected.
</div></div>
</li>
</ul>
</div><li>Cert_Not_Provided (6)</li>
<div class="docstring" xmlns="http://www.w3.org/1999/xhtml">
<p>The server did not provide a SSL certificate.</p>
<p>When disconnected for this reason, the equivalent D-Bus error is
<code>org.freedesktop.Telepathy.Error.Cert.NotProvided</code>.
</p>
</div><li>Cert_Untrusted (7)</li>
<div class="docstring" xmlns="http://www.w3.org/1999/xhtml">
<p>The server's SSL certificate is signed by an untrusted certifying
authority. This error SHOULD NOT be used to represent a self-signed
certificate: use the more specific Cert_Self_Signed reason for
that.</p>
<p>When disconnected for this reason, the equivalent D-Bus error is
<code>org.freedesktop.Telepathy.Error.Cert.Untrusted</code>.
</p>
</div><li>Cert_Expired (8)</li>
<div class="docstring" xmlns="http://www.w3.org/1999/xhtml">
<p>The server's SSL certificate has expired.</p>
<p>When disconnected for this reason, the equivalent D-Bus error is
<code>org.freedesktop.Telepathy.Error.Cert.Expired</code>.
</p>
</div><li>Cert_Not_Activated (9)</li>
<div class="docstring" xmlns="http://www.w3.org/1999/xhtml">
<p>The server's SSL certificate is not yet valid.</p>
<p>When disconnected for this reason, the equivalent D-Bus error is
<code>org.freedesktop.Telepathy.Error.Cert.NotActivated</code>.
</p>
</div><li>Cert_Hostname_Mismatch (10)</li>
<div class="docstring" xmlns="http://www.w3.org/1999/xhtml">
<p>The server's SSL certificate did not match its hostname.</p>
<p>When disconnected for this reason, the equivalent D-Bus error is
<code>org.freedesktop.Telepathy.Error.Cert.HostnameMismatch</code>.
</p>
</div><li>Cert_Fingerprint_Mismatch (11)</li>
<div class="docstring" xmlns="http://www.w3.org/1999/xhtml">
<p>The server's SSL certificate does not have the expected
fingerprint.</p>
<p>When disconnected for this reason, the equivalent D-Bus error is
<code>org.freedesktop.Telepathy.Error.Cert.FingerprintMismatch</code>.
</p>
</div><li>Cert_Self_Signed (12)</li>
<div class="docstring" xmlns="http://www.w3.org/1999/xhtml">
<p>The server's SSL certificate is self-signed.</p>
<p>When disconnected for this reason, the equivalent D-Bus error is
<code>org.freedesktop.Telepathy.Error.Cert.SelfSigned</code>.
</p>
</div><li>Cert_Other_Error (13)</li>
<div class="docstring" xmlns="http://www.w3.org/1999/xhtml">
<p>There was some other error validating the server's SSL
certificate.</p>
<p>When disconnected for this reason, the equivalent D-Bus error is
<code>org.freedesktop.Telepathy.Error.Cert.Invalid</code>.
</p>
</div><li>Cert_Revoked (14)</li>
<div class="docstring" xmlns="http://www.w3.org/1999/xhtml">
<p>The server's SSL certificate has been revoked.</p>
<p>When disconnected for this reason, the equivalent D-Bus error is
<code>org.freedesktop.Telepathy.Error.Cert.Revoked</code>.
</p>
</div><li>Cert_Insecure (15)</li>
<div class="docstring" xmlns="http://www.w3.org/1999/xhtml">
<p>The server's SSL certificate uses an insecure algorithm,
or is cryptographically weak.</p>
<p>When disconnected for this reason, the equivalent D-Bus error is
<code>org.freedesktop.Telepathy.Error.Cert.Insecure</code>.
</p>
</div><li>Cert_Limit_Exceeded (16)</li>
<div class="docstring" xmlns="http://www.w3.org/1999/xhtml">
<p>The length in bytes of the server certificate, or the depth of the
sever certificate chain exceed the limits imposed by the crypto
library.</p>
<p>When disconnected for this reason, the equivalent D-Bus error is
<code>org.freedesktop.Telepathy.Error.Cert.LimitExceeded</code>
</p>
</div></ul>
</div>
<div class="inset type">
<a name="Struct:Channel_Info"></a>
<span class="permalink">Struct (<a href="Connection.html#Struct:Channel_Info">Permalink</a>)</span>
<h2>
Channel_Info — (osuu)
</h2>
<div class="annotation deprecated"><span class="version">Deprecated since 0.17.23. </span></div>
<div class="docstring">A struct representing a channel, as returned by
ListChannels on the Connection interface.</div>
<ul>
<li>Channel — o</li>
<div class="docstring">The object path of the channel, which is on the
same bus name as the connection</div><li>Channel_Type — s (<a href="generic-types.html#Simple-Type:DBus_Interface" title="Simple Type DBus_Interface">DBus_Interface</a>)</li>
<div class="docstring">The channel's type</div><li>Handle_Type — u (<a href="Connection.html#Enum:Handle_Type" title="Enum Handle_Type">Handle_Type</a>)</li>
<div class="docstring">The type of the handle that the channel communicates
with, or Handle_Type_None if there is no associated
handle</div><li>Handle — u (<a href="Connection.html#Simple-Type:Handle" title="Simple Type Handle">Handle</a>)</li>
<div class="docstring">The handle that the channel communicates with,
or 0 if there is no associated handle</div></ul>
</div>
</div>
</div>
</body>
</html>
|