2 @setfilename excorporate.info
3 @settitle Excorporate Manual
7 * Excorporate: (excorporate). Exchange Web Services integration for Emacs.
11 Copyright @copyright{} 2016 Free Software Foundation, Inc.
14 Permission is granted to copy, distribute and/or modify this document
15 under the terms of the GNU Free Documentation License, Version 1.2 or
16 any later version published by the Free Software Foundation; with no
17 Invariant Sections, with the Front-Cover, or Back-Cover Texts. A copy of
18 the license is included in the section entitled ``GNU Free Documentation
19 License'' in the Emacs manual.
21 This document is part of a collection distributed under the GNU Free
22 Documentation License. If you want to distribute this document
23 separately from the collection, you can do so by adding a copy of the
24 license to the document, as described in section 6 of the license.
26 All Emacs Lisp code contained in this document may be used, distributed,
27 and modified without restriction.
32 @title Excorporate Manual
33 @author Thomas Fitzsimmons
41 @top Excorporate Manual
43 Excorporate provides Exchange Web Services (EWS) support for Emacs.
45 If the Exchange server you access is configured to provide EWS
46 support, then there's a 76% chance that Excorporate will enable you to
47 retrieve your calendar entries from the comfort of Emacs.
49 The 24% failure rate is because accessing -- in particular,
50 authenticating against -- an Exchange server can be challenging.
52 Known to fail are Kerberos/GSSAPI authentication and accessing the
53 server through a proxy
54 (@uref{https://debbugs.gnu.org/cgi/bugreport.cgi?bug=10}).
56 Patches are welcome to enable more of these access scenarios.
59 * Installation:: Getting and installing @code{excorporate}.
60 * Configuration:: Configuring @code{excorporate}.
61 * Usage:: Using @code{excorporate}.
62 * Troubleshooting:: Debugging why a connection failed
63 * Reporting Bugs:: Reporting bugs
69 Excorporate works on Emacs versions >= 24.1.
72 Install @code{excorporate} from the GNU ELPA repository:
74 @code{M-x package-install RET excorporate}
77 @chapter Configuration
80 Ideally you won't need to configure Excorporate at all. On friendly
81 Exchange setups, Excorporate can discover the EWS URL automatically.
86 @code{M-x excorporate}
89 which will prompt you for the Exchange account email address. Follow
90 the prompts and if all goes well, you'll see a message in the
91 minibuffer or in *Messages* saying that the connection is ready.
94 If autodiscovery runs out of URLs to try, then customize
95 @code{excorporate-configuration}:
97 @code{M-x customize-variable RET excorporate-configuration}
100 From the value menu select ``Skip autodiscovery''. This allows you to
101 enter the Exchange account email address and the EWS URL directly.
102 The EWS URL is of the form
103 @code{https://mail.gnu.org/ews/exchange.asmx}.
106 After saving the configuration, try @code{M-x excorporate} again.
109 If that doesn't work, then you're probably out of luck, or you'll have
110 to start a troubleshooting deep dive (@pxref{Troubleshooting}).
116 Excorporate binds `e' in @code{*Calendar*} buffers. Open the calendar
122 move the cursor to the date you want to see meetings for, and press
123 `e'. This will show the meetings in a temporary read-only Org Mode
124 buffer named @code{*Excorporate*}.
126 @node Troubleshooting
127 @chapter Troubleshooting
130 First, you'll want to double-check that the Exchange server you're
131 trying to access provides EWS support. If it doesn't, Excorporate
132 can't do anything for you. Before asking your Exchange administrator,
133 check intranet wikis and so forth; other users of non-standard clients
134 may have already found the EWS URL. This is called the ``EWS
135 endpoint''. I can be as simple as something like:
137 @code{https://mail.gnu.org/ews/exchange.asmx}
140 First you need to make sure you can access the endpoint.
143 For Exchange Web Services (EWS) which Excorporate uses, you'll have to
144 determine the EWS endpoint for your Exchange account, call it
145 @code{ews-url}. It is usually something like:
147 https://<mail host name>/ews/exchange.asmx
150 Excorporate calculates the WSDL URL, call it @code{wsdl-url}, by
151 replacing the endpoint's last path element with ``Services.wsdl'':
153 https://<mail host name>/ews/Services.wsdl
156 Before even attempting Excorporate, you have to make these succeed:
160 (url-retrieve-synchronously ews-url)
165 When this works, you'll see web page text in *Messages*, containing a
166 message about having created a service.
170 (url-retrieve-synchronously wsdl-url)
175 When this works, it will show a bunch of WSDL (XML) in *Messages*.
178 Debug the above URL retrievals with (setq url-debug t), and with this
182 diff --git a/lisp/url/url-http.el b/lisp/url/url-http.el
183 index d49e527..0f1c8ae 100644
184 --- a/lisp/url/url-http.el
185 +++ b/lisp/url/url-http.el
186 @@ -869,6 +869,7 @@ url-http-parse-headers
187 (url-handle-content-transfer-encoding))
188 (url-http-debug "Finished parsing HTTP headers: %S" success)
190 + (url-http-debug "Response: %s" (buffer-string))
191 (goto-char (point-min))
197 (Beware that HTTP responses are out-of-order with this patch.)
200 Once you're sure the above steps are working, try @code{M-x
204 The buffer @code{*fsm-debug*} shows @code{excorporate} state
205 transitions and should provide details of where things went wrong.
208 Also check @code{*Messages*} for anything obvious.
211 If you suspect something wrong with accessing the EWS URL, try setting
212 @code{url-debug} to t and retry @code{M-x excorporate}, then check the
213 @code{*URL-DEBUG*} buffer for output.
216 If you suspect NTLM authentication is failing, as a long shot, you
217 might try setting @code{ntlm-compatibility-level} to 0 and retrying
218 @code{M-x excorporate}.
221 Excorporate's dependencies implement the tricky elements of
222 asynchronous Exchange access: a state machine (@code{fsm}), TLS
223 negotiation (@code{gnutls}), NTLM authentication (@code{ntlm} and
224 @code{url-http-ntlm}) and SOAP communication (@code{soap-client}).
227 @chapter Reporting Bugs
230 To report a bug, use @code{M-x report-emacs-bug}, and put Excorporate
231 somewhere in the subject.