purple: update to latest 3.x.x plugin interfaces
[siplcs.git] / README
blob6c84bdccf83604d468a06d9f37ca20c9d6dfe2e7
1 Introduction
2 ============
4 SIPE is a third-party plugin for the Pidgin/Adium/Miranda/Telepathy
5 multi-protocol instant messaging clients/frameworks. It implements the
6 extended version of SIP/SIMPLE used by various products:
8     * Skype for Business
9     * Microsoft Office 365
10     * Microsoft Business Productivity Online Suite (BPOS)
11     * Microsoft Lync Server
12     * Microsoft Office Communications Server (OCS 2007/2007 R2)
13     * Microsoft Live Communications Server (LCS 2003/2005)
15 With this plugin you should be able to replace your Microsoft Office
16 Communicator client with Pidgin/Adium/Miranda/Telepathy.
19 Features
20 ========
22 The plugin has support for
24     * Instant Messaging (IM)
25     * Multiparty chat (OCS 2005) or conference (OCS 2007+)
26     * Group chat (Lync 2010) or Persistent chat (Lync 2013) - [MS-XCCOSIP]
27     * Enhanced presence
28     * Calendar integration with Exchange 2007+ (can be disabled)
29     * Contact details information - company, phones, photo, web site, etc.
30     * Unified Contact Store (Lync 2013) - [MS-OXWSCOS]
31     * Contact search - [MS-PRES] and [MS-DLX] methods supported
32     * Encrypted file transfer (OCS2007: send & receive, Lync: receive only)
33     * Voice & Video calls
34     * Call initiation through PBX
35     * NTLMv2, Kerberos & TLS-DSK authentication methods
36     * Single Sign-On (depends on OS and authentication method)
37     * Automatic SSL/TLS protection for SIP/HTTP connections
38     * Crypto implementation using NSS or OpenSSL
39     * Localization
41 The plugin has backends for
43     * Pidgin/Finch (libpurple)
44     * Adium (libpurple)
45     * Miranda
46     * Telepathy (under development)
49 Advantages over Office Communicator products
50 ============================================
52     * Available on broader range of platforms: Linux, *BSD, Maemo, OSX,
53       commercial UNIX, Windows.
54     * Ability to simultaneously connect to several Office Communicator
55       accounts in addition to public IM network accounts like MSN, AOL,
56       Yahoo. For example one account is in vendor company and another is
57       in client company.
58     * Keeps history of communications in environments without Outlook. For
59       example in companies where Lotus Notes is deployed as a default
60       groupware client instead of Outlook.
61     * Lotus Notes/Domino calendar integration. Unique to SIPE.
62     * Open development model, open source product. License is GPL-2.0-or-later
65 Support
66 =======
68 The Pidgin or Adium projects do not support third-party plugins! Please do
69 not ask questions about SIPE in their forums or report SIPE problems to their
70 bug trackers.
72 If you set up your Office Communicator/Lync account with SIPE for the first
73 time then please make sure to read this page:
75     https://sourceforge.net/p/sipe/wiki/How%20to%20setup%20an%20account/
77 If you encounter problems then please make sure to check out the Frequently
78 Asked Question page:
80     https://sourceforge.net/p/sipe/faq/
82 If you still have problems then please check the support forum if another
83 user encountered the same problem and maybe solved it already:
85     http://sourceforge.net/p/sipe/discussion/
87 If you think that you have found a bug in SIPE then please report it to the
88 SIPE bug tracker:
90     https://sourceforge.net/p/sipe/bugs/
92 The SIPE project kindly requests that you do not ignore the instructions that
93 appear at the head of the "Create Ticket" page. These instructions are there
94 for a reason and if you ignore them then you will only cause unnecessary work
95 for the project and yourself. Please do not report missing features as bugs.
97 New or missing features can be requested here:
99     https://sourceforge.net/p/sipe/feature-requests/
102 Localization
103 ============
105 SIPE has already been localized for several languages. You can help to
106 translate SIPE to your native language at Transifex:
108     https://www.transifex.com/stefanb/pidgin-sipe/
110 The service offers a convenient web editor.
113 D-Bus support (libpurple backend only)
114 ======================================
116 If libpurple and SIPE have been compiled with D-Bus support and the D-Bus
117 backend has been successfully initialized at libpurple start, then SIPE
118 extends the libpurple D-Bus interface with the following APIs:
120     Function              Description
122     SipeCallPhoneNumber(aId, phone_number)
123                           Same as "Call a phone number" menu
125     SipeJoinConferenceWithOrganizerAndId(aId, organizer_email, meeting_id)
126                           Same as "Organizer email" and "Meeting ID" in the
127                           dialog opened by "Join scheduled conference..."
129     SipeJoinConferenceWithUri(aId, uri)
130                           Same as "Meeting location" in the dialog opened by
131                           "Join scheduled conference..."
133     SipeRepublishCalendar(aId)
134                           Same as "Republish Calendar" menu
136     SipeResetStatus(aId)
137                           Same as "Reset status" menu
139 To use the APIs from a script you'll need a D-Bus object for the libpurple
140 interface and a valid & connected account ID as first parameter. An invalid
141 account ID will cause SIPE to silently ignore the D-Bus invocation.
143 Example script code (without error checks to keep it simple):
145 Perl:
147     use Net::DBus;
148     my $bus       = Net::DBus->session;
149     my $service   = $bus->get_service('im.pidgin.purple.PurpleService');
150     my $purple    = $service->get_object('/im/pidgin/purple/PurpleObject',
151                                          'im.pidgin.purple.PurpleInterface');
152     my $accountId = $purple->PurpleAccountsFind($accountName, 'prpl-sipe');
153     $purple->SipeXYZ($accountId, parameters... );
155 Python:
157     import dbus
158     bus       = dbus.SessionBus()
159     object    = bus.get_object("im.pidgin.purple.PurpleService",
160                                "/im/pidgin/purple/PurpleObject")
161     purple    = dbus.Interface(object, "im.pidgin.purple.PurpleInterface")
162     accountId = purple.PurpleAccountsFind($accountName, 'prpl-sipe')
163     purple.SipeXYZ(accountId, parameters... );
166 Installing from a distribution repository
167 =========================================
169 Many Open Source OS distributions have a ready-made package "pidgin-sipe".
170 Before trying to compile it from the source code yourself you should try
171 to install this package with the standard installation method provided by
172 your OS.
174 Once you have SIPE installed and are connected to your account you can check
175 from the following Pidgin menu
177         Accounts -> <SIPE Account> -> About SIPE plugin...
179 which optional features have been enabled in your SIPE build.
182 Do It Yourself I: compiling against "pidgin" package
183 ====================================================
185 NOTE: for instructions how to setup a build environment on Windows to
186       compile the Windows Pidgin plugin, please read:
188         https://developer.pidgin.im/wiki/BuildingWinPidgin
190 NOTE: for instructions how to cross-compile the Windows Pidgin plugin on
191       Linux, please read:
193         contrib/mingw-cross-compile/README.txt
195 NOTE: for instructions how to compile the SIPEAdiumPlugin on Mac OS X,
196       please read:
198         src/adium/README.adium
201 If you already have installed the "pidgin" package from your distribution
202 repository and want compile SIPE from source code yourself, then you need to
203 install the necessary headers first. Depending on your distribution you'll
204 need to install one of the following packages
206         libpurple-dev
207         libpurple-devel
209 For the compilation you'll need to install a C compiler and some of the
210 following packages
212         libtool
213         intltool
215         pkg-config
216         libglib2.0-dev
217         libxml2-dev
218         libgmime-2.6-dev  (optional)
220         pkgconfig
221         libglib2-devel
222         libxml2-devel
223         gettext-devel
224         gmime-devel       (optional)
226 You have to choose between NSS or OpenSSL for the crypto backend. You'll
227 need one of the following packages
229         for NSS:
230         libnss3-dev
231         nss-devel
232         mozilla-nss-devel
234         for OpenSSL:
235         libssl-dev
236         openssl-devel
238 If you want to enable Kerberos authentication support then you'll need one
239 of the following packages
241         libkrb5-dev
242         krb5-devel
244 If you additionally want to disable the internal NTLM implementation and
245 authenticate with NTLM via GSSAPI then you'll need one of the following
246 packages
248         gssntlmssp-devel
250 If you want to enable the D-Bus support then you'll need one of the
251 following packages
253         libdbus-1-dev
254         dbus-devel
256 If you want to enable Voice & Video features then you'll need some of the
257 following packages. You need to install the same version of the GStreamer
258 development packages which where used to compile Pidgin!
260         libfarstream-0.2-dev
261         libgstreamer1.0-dev
262         libgstreamer-plugins-base1.0-dev
263         libnice-dev                   (>= 0.1.13)
264         libpurple-dev                 (>= 2.10.12)
266         farstream02-devel
267         gstreamer1-devel
268         gstreamer1-plugins-base-devel
269         libnice-devel                 (>= 0.1.13)
270         libpurple-devel               (>= 2.10.12)
272 Now you should be able to compile the source code with
274         ./configure --prefix=/usr
275         make
277 If you get errors then you are missing some required package. After
278 successful compilation you can install SIPE with:
280         su -c "make install"
282 If you get errors from configure or libtool about version conflicts then
283 you need to regenerate the autoconf files. You'll need these additional
284 packages
286         autoconf
287         automake
288         flex
290 Now you should be able to regenerate the files with
292         autoreconf --verbose --install --force
294 After that go back to the configure step above.
297 Do It Yourself II: compiling against self-compiled pidgin
298 =========================================================
300 If you have compiled pidgin from source code yourself then you'll have to
301 specify the correct installation path in configure. Usually pidgin is
302 installed in /usr/local so the following command should work
304         ./configure --prefix=/usr/local
306 The rest of the steps are the same as in the previous section.