README
1Licq D-Bus Interface plugin
2===========================
3
4DESCRIPTION
5
6This plugin adds support for remote monitoring and control of Licq via D-Bus.
7Signals are sent for incoming messages, contact list and basic user information
8can be queried and status can be changed.
9
10The name org.licq is registered on the session bus.
11
12
13QUICK INSTALLATION
14
15Dependencies for D-Bus plugin:
16- Licq, including dependencies needed to build Licq
17- libdbus 1.0.0 or later
18
19Build and install:
20# mkdir build && cd build
21# cmake ..
22# make
23# make install
24
25The plugin will be called "dbus" and has no parameters or configuration file.
26
27
28METHOD CALLS
29
30Get Licq version:
31# dbus-send --type=method_call --dest=org.licq /org/licq/Core org.licq.Core.GetVersion
32
33Terminate Licq:
34# dbus-send --type=method_call --dest=org.licq /org/licq/Core org.licq.Core.Shutdown
35
36Get list of accounts:
37Returns an array of object paths for each account.
38# dbus-send --print-reply --type=method_call --dest=org.licq /org/licq/ContactList org.licq.ContactList.GetAccounts
39
40Get list of contacts for an account:
41Returns an array of objects paths for each contact.
42# dbus-send --print-reply --type=method_call --dest=org.licq /org/licq/ContactList/ICQ/12345678 org.licq.Account.GetContacts
43
44Get current status for an account or contact:
45Returns bitmask of status flags and a user readable string. Note that the
46string may be translated and should not be relied on in code logic.
47For bitmask values, see StatusFlags in include/licq/contactlist/user.h.
48# dbus-send --print-reply --type=method_call --dest=org.licq /org/licq/ContactList/ICQ/12345678 org.licq.Account.GetStatus
49# dbus-send --print-reply --type=method_call --dest=org.licq /org/licq/ContactList/ICQ/12345678/87654321 org.licq.Contact.GetStatus
50
51Get basic information for an account or contact:
52Returns four strings: Alias, first name, last name, and email.
53# dbus-send --print-reply --type=method_call --dest=org.licq /org/licq/ContactList/ICQ/12345678 org.licq.Account.GetName
54# dbus-send --print-reply --type=method_call --dest=org.licq /org/licq/ContactList/ICQ/12345678/87654321 org.licq.Contact.GetName
55
56Set current status for an account:
57# dbus-send --type=method_call --dest=org.licq /org/licq/ContactList/ICQ/12345678 org.licq.Account.SetStatus string:away
58# dbus-send --type=method_call --dest=org.licq /org/licq/ContactList/ICQ/12345678 org.licq.Account.SetStatus uint32:1024
59
60
61SIGNALS
62
63Receiving signals:
64# dbus-monitor "type='signal',sender='org.licq'"
65
66Signals are emitted for status changes, received messages, and the number of
67unread messages.
68Object paths and interfaces are the same as for the method calls above.
69
70The following methods are used in signals:
71Status - Emitted for accounts and contacts when status changes.
72 Parameters are bitmask status and string as for GetStatus
73 above
74NumUnread - Emitted for ContactList with a single unsigned parameter
75 telling the current number of unread events.
76NumUnread - Emitted for accounts and contacts. One unsigned parameter
77 tells the current number of unread events for the contact.
78 A second string parameter with the contact's display name is
79 also included for convenience.
80ReceivedEvent - Emitted for accounts and contacts when an event is received
81 Two string parameters contains the event message and the
82 contact's display name.
83Started - Emitted for Core when Licq has registered with D-Bus.
84Shutdown - Emitted for Core when Licq is about to terminate.
85
86
87ENCODING
88
89All strings are encoded as UTF-8.
90However, user ids of accounts and contacts that contains characters other than
91[0-9A-Za-z] must be converted when used in object paths by replacing each byte
92with an underscore followed by two hex digits. (This is similair to how % is
93used in URIs.) For example, the MSN account test@example.com can be accessed
94using the following object path: /org/licq/ContactList/MSN/test_40example_2Ecom
95