code.delx.au - gnu-emacs-elpa/blob - packages/excorporate/excorporate.info

   1 This is excorporate.info, produced by makeinfo version 6.0 from
   2 excorporate.texi.
   3
   4 Copyright (C) 2016 Free Software Foundation, Inc.
   5
   6      Permission is granted to copy, distribute and/or modify this
   7      document under the terms of the GNU Free Documentation License,
   8      Version 1.2 or any later version published by the Free Software
   9      Foundation; with no Invariant Sections, with the Front-Cover, or
  10      Back-Cover Texts.  A copy of the license is included in the section
  11      entitled "GNU Free Documentation License" in the Emacs manual.
  12
  13      This document is part of a collection distributed under the GNU
  14      Free Documentation License.  If you want to distribute this
  15      document separately from the collection, you can do so by adding a
  16      copy of the license to the document, as described in section 6 of
  17      the license.
  18
  19      All Emacs Lisp code contained in this document may be used,
  20      distributed, and modified without restriction.
  21 INFO-DIR-SECTION Emacs
  22 START-INFO-DIR-ENTRY
  23 * Excorporate: (excorporate).  Exchange Web Services integration for Emacs.
  24 END-INFO-DIR-ENTRY
  25
  26 \1f
  27 File: excorporate.info,  Node: Top,  Next: Installation,  Up: (dir)
  28
  29 Excorporate Manual
  30 ******************
  31
  32 Excorporate provides Exchange Web Services (EWS) support for Emacs.
  33
  34    If the Exchange server you access is configured to provide EWS
  35 support, then there's a 76% chance that Excorporate will enable you to
  36 retrieve your calendar entries from the comfort of Emacs.
  37
  38    The 24% failure rate is because accessing - in particular,
  39 authenticating against - an Exchange server can be challenging.
  40
  41    Known to fail are Kerberos/GSSAPI authentication and accessing the
  42 server through a proxy
  43 (<https://debbugs.gnu.org/cgi/bugreport.cgi?bug=10>).
  44
  45    Patches are welcome to enable more of these access scenarios.
  46
  47 * Menu:
  48
  49 * Installation::                Getting and installing 'excorporate'.
  50 * Configuration::               Configuring 'excorporate'.
  51 * Usage::                       Using 'excorporate'.
  52 * Troubleshooting::             Debugging why a connection failed
  53 * Reporting Bugs::              Reporting bugs
  54
  55 \1f
  56 File: excorporate.info,  Node: Installation,  Next: Configuration,  Prev: Top,  Up: Top
  57
  58 1 Installation
  59 **************
  60
  61 Excorporate works on Emacs versions >= 24.1.
  62
  63 Install 'excorporate' from the GNU ELPA repository:
  64
  65    'M-x package-install RET excorporate'
  66
  67 \1f
  68 File: excorporate.info,  Node: Configuration,  Next: Usage,  Prev: Installation,  Up: Top
  69
  70 2 Configuration
  71 ***************
  72
  73 Ideally you won't need to configure Excorporate at all.  On friendly
  74 Exchange setups, Excorporate can discover the EWS URL automatically.
  75
  76 First try:
  77
  78    'M-x excorporate'
  79
  80 which will prompt you for the Exchange account email address.  Follow
  81 the prompts and if all goes well, you'll see a message in the minibuffer
  82 or in *Messages* saying that the connection is ready.
  83
  84 If autodiscovery runs out of URLs to try, then customize
  85 'excorporate-configuration':
  86
  87    'M-x customize-variable RET excorporate-configuration'
  88
  89 From the value menu select "Skip autodiscovery".  This allows you to
  90 enter the Exchange account email address and the EWS URL directly.  The
  91 EWS URL is of the form 'https://mail.gnu.org/ews/exchange.asmx'.
  92
  93 After saving the configuration, try 'M-x excorporate' again.
  94
  95 If that doesn't work, then you're probably out of luck, or you'll have
  96 to start a troubleshooting deep dive (*note Troubleshooting::).
  97
  98 \1f
  99 File: excorporate.info,  Node: Usage,  Next: Troubleshooting,  Prev: Configuration,  Up: Top
 100
 101 3 Usage
 102 *******
 103
 104 Excorporate binds 'e' in '*Calendar*' buffers.  Open the calendar with:
 105
 106    'M-x calendar'
 107
 108 move the cursor to the date you want to see meetings for, and press 'e'.
 109 This will show the meetings in a temporary read-only Org Mode buffer
 110 named '*Excorporate*'.
 111
 112 \1f
 113 File: excorporate.info,  Node: Troubleshooting,  Next: Reporting Bugs,  Prev: Usage,  Up: Top
 114
 115 4 Troubleshooting
 116 *****************
 117
 118 First, you'll want to double-check that the Exchange server you're
 119 trying to access provides EWS support.  If it doesn't, Excorporate can't
 120 do anything for you.  Before asking your Exchange administrator, check
 121 intranet wikis and so forth; other users of non-standard clients may
 122 have already found the EWS URL. This is called the "EWS endpoint".  I
 123 can be as simple as something like:
 124
 125    'https://mail.gnu.org/ews/exchange.asmx'
 126
 127 First you need to make sure you can access the endpoint.
 128
 129 For Exchange Web Services (EWS) which Excorporate uses, you'll have to
 130 determine the EWS endpoint for your Exchange account, call it 'ews-url'.
 131 It is usually something like:
 132
 133    https://<mail host name>/ews/exchange.asmx
 134
 135 Excorporate calculates the WSDL URL, call it 'wsdl-url', by replacing
 136 the endpoint's last path element with "Services.wsdl":
 137
 138    https://<mail host name>/ews/Services.wsdl
 139
 140 Before even attempting Excorporate, you have to make these succeed:
 141
 142      (with-current-buffer
 143       (url-retrieve-synchronously ews-url)
 144       (buffer-string))
 145
 146 When this works, you'll see web page text in *Messages*, containing a
 147 message about having created a service.
 148
 149      (with-current-buffer
 150       (url-retrieve-synchronously wsdl-url)
 151       (buffer-string))
 152
 153 When this works, it will show a bunch of WSDL (XML) in *Messages*.
 154
 155 Debug the above URL retrievals with (setq url-debug t), and with this
 156 patch:
 157
 158      diff --git a/lisp/url/url-http.el b/lisp/url/url-http.el
 159      index d49e527..0f1c8ae 100644
 160      --- a/lisp/url/url-http.el
 161      +++ b/lisp/url/url-http.el
 162      @ -869,6 +869,7 @ url-http-parse-headers
 163             (url-handle-content-transfer-encoding))
 164           (url-http-debug "Finished parsing HTTP headers: %S" success)
 165           (widen)
 166      +    (url-http-debug "Response: %s" (buffer-string))
 167           (goto-char (point-min))
 168           success))
 169
 170
 171 (Beware that HTTP responses are out-of-order with this patch.)
 172
 173 Once you're sure the above steps are working, try 'M-x excorporate'.
 174
 175 The buffer '*fsm-debug*' shows 'excorporate' state transitions and
 176 should provide details of where things went wrong.
 177
 178 Also check '*Messages*' for anything obvious.
 179
 180 If you suspect something wrong with accessing the EWS URL, try setting
 181 'url-debug' to t and retry 'M-x excorporate', then check the
 182 '*URL-DEBUG*' buffer for output.
 183
 184 If you suspect NTLM authentication is failing, as a long shot, you might
 185 try setting 'ntlm-compatibility-level' to 0 and retrying 'M-x
 186 excorporate'.
 187
 188 Excorporate's dependencies implement the tricky elements of asynchronous
 189 Exchange access: a state machine ('fsm'), TLS negotiation ('gnutls'),
 190 NTLM authentication ('ntlm' and 'url-http-ntlm') and SOAP communication
 191 ('soap-client').
 192
 193 \1f
 194 File: excorporate.info,  Node: Reporting Bugs,  Prev: Troubleshooting,  Up: Top
 195
 196 5 Reporting Bugs
 197 ****************
 198
 199 To report a bug, use 'M-x report-emacs-bug', and put Excorporate
 200 somewhere in the subject.
 201
 202
 203 \1f
 204 Tag Table:
 205 Node: Top\7f1103
 206 Node: Installation\7f2124
 207 Node: Configuration\7f2387
 208 Node: Usage\7f3435
 209 Node: Troubleshooting\7f3806
 210 Node: Reporting Bugs\7f6649
 211 \1f
 212 End Tag Table