README

   1 Introduction
   2 ============
   3
   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:
   7
   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)
  14
  15 With this plugin you should be able to replace your Microsoft Office
  16 Communicator client with Pidgin/Adium/Miranda/Telepathy.
  17
  18
  19 Features
  20 ========
  21
  22 The plugin has support for
  23
  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
  40
  41 The plugin has backends for
  42
  43     * Pidgin/Finch (libpurple)
  44     * Adium (libpurple)
  45     * Miranda
  46     * Telepathy (under development)
  47
  48
  49 Advantages over Office Communicator products
  50 ============================================
  51
  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
  63
  64
  65 Support
  66 =======
  67
  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.
  71
  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:
  74
  75     https://sourceforge.net/p/sipe/wiki/How%20to%20setup%20an%20account/
  76
  77 If you encounter problems then please make sure to check out the Frequently
  78 Asked Question page:
  79
  80     https://sourceforge.net/p/sipe/faq/
  81
  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:
  84
  85     http://sourceforge.net/p/sipe/discussion/
  86
  87 If you think that you have found a bug in SIPE then please report it to the
  88 SIPE bug tracker:
  89
  90     https://sourceforge.net/p/sipe/bugs/
  91
  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.
  96
  97 New or missing features can be requested here:
  98
  99     https://sourceforge.net/p/sipe/feature-requests/
 100
 101
 102 Localization
 103 ============
 104
 105 SIPE has already been localized for several languages. You can help to
 106 translate SIPE to your native language at Transifex:
 107
 108     https://www.transifex.com/stefanb/pidgin-sipe/
 109
 110 The service offers a convenient web editor.
 111
 112
 113 D-Bus support (libpurple backend only)
 114 ======================================
 115
 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:
 119
 120     Function              Description
 121
 122     SipeCallPhoneNumber(aId, phone_number)
 123                           Same as "Call a phone number" menu
 124
 125     SipeJoinConferenceWithOrganizerAndId(aId, organizer_email, meeting_id)
 126                           Same as "Organizer email" and "Meeting ID" in the
 127                           dialog opened by "Join scheduled conference..."
 128
 129     SipeJoinConferenceWithUri(aId, uri)
 130                           Same as "Meeting location" in the dialog opened by
 131                           "Join scheduled conference..."
 132
 133     SipeRepublishCalendar(aId)
 134                           Same as "Republish Calendar" menu
 135
 136     SipeResetStatus(aId)
 137                           Same as "Reset status" menu
 138
 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.
 142
 143 Example script code (without error checks to keep it simple):
 144
 145 Perl:
 146
 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... );
 154
 155 Python:
 156
 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... );
 164
 165
 166 Installing from a distribution repository
 167 =========================================
 168
 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.
 173
 174 Once you have SIPE installed and are connected to your account you can check
 175 from the following Pidgin menu
 176
 177         Accounts -> <SIPE Account> -> About SIPE plugin...
 178
 179 which optional features have been enabled in your SIPE build.
 180
 181
 182 Do It Yourself I: compiling against "pidgin" package
 183 ====================================================
 184
 185 NOTE: for instructions how to setup a build environment on Windows to
 186       compile the Windows Pidgin plugin, please read:
 187
 188         https://developer.pidgin.im/wiki/BuildingWinPidgin
 189
 190 NOTE: for instructions how to cross-compile the Windows Pidgin plugin on
 191       Linux, please read:
 192
 193         contrib/mingw-cross-compile/README.txt
 194
 195 NOTE: for instructions how to compile the SIPEAdiumPlugin on Mac OS X,
 196       please read:
 197
 198         src/adium/README.adium
 199
 200
 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
 205
 206         libpurple-dev
 207         libpurple-devel
 208
 209 For the compilation you'll need to install a C compiler and some of the
 210 following packages
 211
 212         libtool
 213         intltool
 214
 215         pkg-config
 216         libglib2.0-dev
 217         libxml2-dev
 218         libgmime-2.6-dev  (optional)
 219
 220         pkgconfig
 221         libglib2-devel
 222         libxml2-devel
 223         gettext-devel
 224         gmime-devel       (optional)
 225
 226 You have to choose between NSS or OpenSSL for the crypto backend. You'll
 227 need one of the following packages
 228
 229         for NSS:
 230         libnss3-dev
 231         nss-devel
 232         mozilla-nss-devel
 233
 234         for OpenSSL:
 235         libssl-dev
 236         openssl-devel
 237
 238 If you want to enable Kerberos authentication support then you'll need one
 239 of the following packages
 240
 241         libkrb5-dev
 242         krb5-devel
 243
 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
 247
 248         gssntlmssp-devel
 249
 250 If you want to enable the D-Bus support then you'll need one of the
 251 following packages
 252
 253         libdbus-1-dev
 254         dbus-devel
 255
 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!
 259
 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)
 265
 266         farstream02-devel
 267         gstreamer1-devel
 268         gstreamer1-plugins-base-devel
 269         libnice-devel                 (>= 0.1.13)
 270         libpurple-devel               (>= 2.10.12)
 271
 272 Now you should be able to compile the source code with
 273
 274         ./configure --prefix=/usr
 275         make
 276
 277 If you get errors then you are missing some required package. After
 278 successful compilation you can install SIPE with:
 279
 280         su -c "make install"
 281
 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
 285
 286         autoconf
 287         automake
 288         flex
 289
 290 Now you should be able to regenerate the files with
 291
 292         autopoint --force
 293         AUTOPOINT="intltoolize --copy --force --automake" \
 294                 autoreconf --force --install
 295
 296 After that go back to the configure step above.
 297
 298
 299 Do It Yourself II: compiling against self-compiled pidgin
 300 =========================================================
 301
 302 If you have compiled pidgin from source code yourself then you'll have to
 303 specify the correct installation path in configure. Usually pidgin is
 304 installed in /usr/local so the following command should work
 305
 306         ./configure --prefix=/usr/local
 307
 308 The rest of the steps are the same as in the previous section.
 309
 310
 311 Do It Yourself III: building from git checkout
 312 ==============================================
 313
 314 Building from a git checkout is meant for project maintainers, i.e. you
 315 need to generate the configure script first:
 316
 317         ./autogen.sh
 318
 319 The rest of the steps are the same as in the previous sections.
 320
 321 To clean all artifacts and reset the source tree to pristine condition use
 322
 323         make maintainer-clean
 324
 325 If you just want to quickly run a one-shot build from a git checkout then
 326 you can use the following helper script which executes all necessary steps
 327 in the correct order:
 328
 329         ./git-build.sh
 330
 331
 332 Contributing code
 333 =================
 334
 335 If you want to contribute to the SIPE project please have a look at
 336
 337     http://sipe.sourceforge.net/git/
 338
 339 Some of the instructions are unfortunately out-dated. If in doubt then
 340 *ASK* from the current maintainers before committing!
 341
 342 Please also have a look at the Pidgin coding style guide
 343
 344     https://developer.pidgin.im/wiki/StyleGuide