[elpa] master 9ce646f 11/11: Excorporate: Document API usage in manual

[Thomas Fitzsimmons]

branch: master
commit 9ce646f13a61bba8203d89cecbc85af8e4691d92
Author: Thomas Fitzsimmons <fitzsim@fitzsim.org>
Commit: Thomas Fitzsimmons <fitzsim@fitzsim.org>

    Excorporate: Document API usage in manual
    
    * packages/excorporate/excorporate.texi
    (Reporting Bugs): Make first chapter.  Simplify reporting
    instructions.
    (API Usage): New chapter.  packages/excorporate/excorporate.info:
    Regenerate.
---
 packages/excorporate/excorporate.info | 149 +++++++++++++++++++++++++++++-----
 packages/excorporate/excorporate.texi | 135 ++++++++++++++++++++++++++++--
 2 files changed, 259 insertions(+), 25 deletions(-)

diff --git a/packages/excorporate/excorporate.info 
b/packages/excorporate/excorporate.info
index 05f24f6..b99ff67 100644
--- a/packages/excorporate/excorporate.info
+++ b/packages/excorporate/excorporate.info
@@ -24,7 +24,7 @@ START-INFO-DIR-ENTRY
 END-INFO-DIR-ENTRY
 
 
-File: excorporate.info,  Node: Top,  Next: Installation,  Up: (dir)
+File: excorporate.info,  Node: Top,  Next: Reporting Bugs,  Up: (dir)
 
 Excorporate Manual
 ******************
@@ -50,16 +50,27 @@ welcome, as are patches to enable more of these access 
scenarios.  See
 
 * Menu:
 
+* Reporting Bugs::              How to report bugs in Excorporate
 * Installation::                Getting and installing 'excorporate'.
 * Configuration::               Configuring 'excorporate'.
 * Usage::                       Using 'excorporate'.
 * Troubleshooting::             Debugging why a connection failed
-* Reporting Bugs::              Reporting bugs
+* API Usage::                   Using the API provided by 'excorporate'.
 
 
-File: excorporate.info,  Node: Installation,  Next: Configuration,  Prev: Top, 
 Up: Top
+File: excorporate.info,  Node: Reporting Bugs,  Next: Installation,  Prev: 
Top,  Up: Top
 
-1 Installation
+1 Reporting Bugs
+****************
+
+To report a bug, send an email to 'bug-gnu-emacs@gnu.org' using your
+favourite email program.  Put "Excorporate" somewhere in the subject
+line, for example: "Excorporate: Failed to authenticate".
+
+
+File: excorporate.info,  Node: Installation,  Next: Configuration,  Prev: 
Reporting Bugs,  Up: Top
+
+2 Installation
 **************
 
 Excorporate works on Emacs versions >= 24.1.
@@ -71,7 +82,7 @@ Install 'excorporate' from the GNU ELPA repository:
 
 File: excorporate.info,  Node: Configuration,  Next: Usage,  Prev: 
Installation,  Up: Top
 
-2 Configuration
+3 Configuration
 ***************
 
 Ideally you won't need to configure Excorporate beyond providing your
@@ -101,7 +112,7 @@ Troubleshooting::.
 
 File: excorporate.info,  Node: Usage,  Next: Troubleshooting,  Prev: 
Configuration,  Up: Top
 
-3 Usage
+4 Usage
 *******
 
 Excorporate can put entries it retrieves into the Emacs Diary, and use
@@ -150,9 +161,9 @@ Excorporate) will retrieve your meetings and display your 
diary so that
 you see the day's events first thing in the morning.
 
 
-File: excorporate.info,  Node: Troubleshooting,  Next: Reporting Bugs,  Prev: 
Usage,  Up: Top
+File: excorporate.info,  Node: Troubleshooting,  Next: API Usage,  Prev: 
Usage,  Up: Top
 
-4 Troubleshooting
+5 Troubleshooting
 *****************
 
 First, you'll want to double-check that the Exchange server you're
@@ -230,23 +241,121 @@ NTLM authentication ('ntlm' and 'url-http-ntlm') and 
SOAP communication
 ('soap-client').
 
 
-File: excorporate.info,  Node: Reporting Bugs,  Prev: Troubleshooting,  Up: Top
-
-5 Reporting Bugs
-****************
-
-To report a bug, use 'M-x report-emacs-bug', and put Excorporate
-somewhere in the subject.
+File: excorporate.info,  Node: API Usage,  Prev: Troubleshooting,  Up: Top
+
+6 API Usage
+***********
+
+Here are some examples of using the API (application programming
+interface) provided by Excorporate.
+
+Not all of Excorporate's functionality is exposed as interactive
+functions.  Here is an example of creating a meeting to which
+hacker2@gnu.org is invited, using a non-interactive function provided by
+Excorporate:
+
+     (exco-calendar-item-meeting-create
+      (car exco--connection-identifiers)
+      "Test meeting 1"
+      "Hi,\n\nThis is a test meeting 1.\n\nRegards.\n"
+      (encode-time 0 15 14 23 09 2020)
+      (encode-time 0 0  15 23 09 2020)
+      "Online only"
+      '("hacker2@gnu.org") nil
+      (lambda (identifier response)
+        (message "%S: %S" identifier response)))
+     => ("hacker1@gnu.org" . "https://mail.gnu.org/EWS/Exchange.asmx";): 
(((ResponseMessages (CreateItemResponseMessage (ResponseClass . "Success") 
(ResponseCode . "NoError") (Items (CalendarItem (ItemId (Id . "A[...]A==") 
(ChangeKey . "D[...]M"))))))))
+
+The callback is run asychronously after the server responds, so as not
+to block Emacs, and the result is what is printed in the '*Messages*'
+buffer.  This example assumes the user has already run 'M-x excorporate'
+to create a connection.  '(car exco--connection-identifiers)' is a hack
+that uses the first-established connection.  Excorporate fully supports
+connecting to multiple different servers though (see
+'exco-connection-iterate') so published code that uses the Excorporate
+API should not assume just one connection.
+
+There is lots of server-side functionality that Excorporate does not
+provide high-level non-interactive functions for.  Using that
+functionality is still possible with the low-level 'exco-operate' and
+'exco-operate-synchronously' functions.
+
+For example, evaluating this form produces lots of details about the
+meeting represented by the ItemId form, including tidbits like the list
+of invitees and how they've responded (accepted, declined, tentatively
+accepted, unknown).  You can find ItemId forms to experiment with in the
+PROPERTIES drawer of calendar entries in the interactive Org buffer.
+
+     (exco-operate-synchronously
+       (car exco--connection-identifiers)
+       "GetItem"
+       '(((ItemShape (BaseShape . "AllProperties"))
+          (ItemIds (ItemId (Id . "A[...]A==") (ChangeKey . "D[...]d"))))
+         nil nil nil nil nil nil))
+     => (((ResponseMessages (GetItemResponseMessage (ResponseClass . 
"Success") (ResponseCode . "NoError") (Items (CalendarItem ...))))))
+
+Note that this function is synchronous.  This is nice for experimenting
+with, for example, in an IELM REPL, but published code should mostly use
+the asynchronous calls to avoid blocking Emacs during server operations.
+
+Here is a more complicated example that asynchronously queries the
+server for availability overlap for hacker1@gnu.org and hacker2@gnu.org,
+in the Eastern Time Zone.
+
+     (exco-operate
+      (car exco--connection-identifiers)
+      "GetUserAvailability"
+      '(((TimeZone
+          (Bias . 300)
+          (StandardTime
+           (Bias . 0)
+           (Time . "02:00:00")
+           (DayOrder . 1)
+           (Month . 11)
+           (DayOfWeek . "Sunday"))
+          (DaylightTime
+           (Bias . -60)
+           (Time . "02:00:00")
+           (DayOrder . 2)
+           (Month . 3)
+           (DayOfWeek . "Sunday")))
+         (MailboxDataArray
+          (MailboxData
+           (Email
+            (Address . "hacker1@gnu.org"))
+           (AttendeeType . "Required")
+           (ExcludeConflicts . nil))
+          (MailboxData
+           (Email
+            (Address . "hacker2@gnu.org"))
+           (AttendeeType . "Required")
+           (ExcludeConflicts . nil)))
+         (FreeBusyViewOptions
+          (TimeWindow
+           (StartTime . "2020-09-25T00:00:00Z")
+           (EndTime . "2020-09-25T23:59:00Z"))
+          (MergedFreeBusyIntervalInMinutes . 60)
+          (RequestedView "DetailedMerged")))
+        nil nil nil)
+      (lambda (identifier response)
+        (message "%S: %S" identifier response)))
+     => ("hacker1@gnu.org" . "https://mail.gnu.org/EWS/Exchange.asmx";): 
(((FreeBusyResponseArray (FreeBusyResponse ... ) ...)))
+
+Feel free to submit new functions in excorporate.el and the backends
+that you think others would find useful.  Functions in excorporate.el
+have always kept/must always keep the same interface so that they stay
+backward compatible.
 
 
 
 Tag Table:
 Node: Top1103
-Node: Installation2305
-Node: Configuration2568
-Node: Usage3588
-Node: Troubleshooting5677
-Node: Reporting Bugs8550
+Node: Reporting Bugs2399
+Node: Installation2723
+Node: Configuration2997
+Node: Usage4017
+Node: Troubleshooting6106
+Node: API Usage8974
 
 End Tag Table
 
diff --git a/packages/excorporate/excorporate.texi 
b/packages/excorporate/excorporate.texi
index 8db33d9..d335191 100644
--- a/packages/excorporate/excorporate.texi
+++ b/packages/excorporate/excorporate.texi
@@ -60,13 +60,22 @@ welcome, as are patches to enable more of these access 
scenarios.  See
 @pxref{Reporting Bugs}.
 
 @menu
+* Reporting Bugs::              How to report bugs in Excorporate
 * Installation::                Getting and installing @code{excorporate}.
 * Configuration::               Configuring @code{excorporate}.
 * Usage::                       Using @code{excorporate}.
 * Troubleshooting::             Debugging why a connection failed
-* Reporting Bugs::              Reporting bugs
+* API Usage::                   Using the API provided by @code{excorporate}.
 @end menu
 
+@node Reporting Bugs
+@chapter Reporting Bugs
+
+@noindent
+To report a bug, send an email to @code{bug-gnu-emacs@@gnu.org} using
+your favourite email program.  Put ``Excorporate'' somewhere in the
+subject line, for example: ``Excorporate: Failed to authenticate''.
+
 @node Installation
 @chapter Installation
 
@@ -266,11 +275,127 @@ asynchronous Exchange access: a state machine 
(@code{fsm}), TLS
 negotiation (@code{gnutls}), NTLM authentication (@code{ntlm} and
 @code{url-http-ntlm}) and SOAP communication (@code{soap-client}).
 
-@node Reporting Bugs
-@chapter Reporting Bugs
+@node API Usage
+@chapter API Usage
+
+@noindent
+Here are some examples of using the API (application programming
+interface) provided by Excorporate.
+
+@noindent
+Not all of Excorporate's functionality is exposed as interactive
+functions.  Here is an example of creating a meeting to which
+hacker2@@gnu.org is invited, using a non-interactive function provided by
+Excorporate:
+
+@example
+@group
+(exco-calendar-item-meeting-create
+ (car exco--connection-identifiers)
+ "Test meeting 1"
+ "Hi,\n\nThis is a test meeting 1.\n\nRegards.\n"
+ (encode-time 0 15 14 23 09 2020)
+ (encode-time 0 0  15 23 09 2020)
+ "Online only"
+ '("hacker2@@gnu.org") nil
+ (lambda (identifier response)
+   (message "%S: %S" identifier response)))
+@result{} ("hacker1@@gnu.org" . "https://mail.gnu.org/EWS/Exchange.asmx";): 
(((ResponseMessages (CreateItemResponseMessage (ResponseClass . "Success") 
(ResponseCode . "NoError") (Items (CalendarItem (ItemId (Id . "A[...]A==") 
(ChangeKey . "D[...]M"))))))))
+@end group
+@end example
+
+@noindent
+The callback is run asychronously after the server responds, so as not
+to block Emacs, and the result is what is printed in the
+@code{*Messages*} buffer.  This example assumes the user has already run
+@kbd{M-x excorporate} to create a connection.  @code{(car
+exco--connection-identifiers)} is a hack that uses the first-established
+connection.  Excorporate fully supports connecting to multiple different
+servers though (see @code{exco-connection-iterate}) so published code
+that uses the Excorporate API should not assume just one connection.
+
+@noindent
+There is lots of server-side functionality that Excorporate does not
+provide high-level non-interactive functions for.  Using that
+functionality is still possible with the low-level @code{exco-operate}
+and @code{exco-operate-synchronously} functions.
+
+@noindent
+For example, evaluating this form produces lots of details about the
+meeting represented by the ItemId form, including tidbits like the list
+of invitees and how they've responded (accepted, declined, tentatively
+accepted, unknown).  You can find ItemId forms to experiment with in the
+PROPERTIES drawer of calendar entries in the interactive Org buffer.
+
+@example
+@group
+(exco-operate-synchronously
+  (car exco--connection-identifiers)
+  "GetItem"
+  '(((ItemShape (BaseShape . "AllProperties"))
+     (ItemIds (ItemId (Id . "A[...]A==") (ChangeKey . "D[...]d"))))
+    nil nil nil nil nil nil))
+@result{} (((ResponseMessages (GetItemResponseMessage (ResponseClass . 
"Success") (ResponseCode . "NoError") (Items (CalendarItem ...))))))
+@end group
+@end example
+
+@noindent
+Note that this function is synchronous.  This is nice for experimenting
+with, for example, in an IELM REPL, but published code should mostly use
+the asynchronous calls to avoid blocking Emacs during server operations.
+
+@noindent
+Here is a more complicated example that asynchronously queries the
+server for availability overlap for hacker1@@gnu.org and hacker2@@gnu.org,
+in the Eastern Time Zone.
+
+@example
+@group
+(exco-operate
+ (car exco--connection-identifiers)
+ "GetUserAvailability"
+ '(((TimeZone
+     (Bias . 300)
+     (StandardTime
+      (Bias . 0)
+      (Time . "02:00:00")
+      (DayOrder . 1)
+      (Month . 11)
+      (DayOfWeek . "Sunday"))
+     (DaylightTime
+      (Bias . -60)
+      (Time . "02:00:00")
+      (DayOrder . 2)
+      (Month . 3)
+      (DayOfWeek . "Sunday")))
+    (MailboxDataArray
+     (MailboxData
+      (Email
+       (Address . "hacker1@@gnu.org"))
+      (AttendeeType . "Required")
+      (ExcludeConflicts . nil))
+     (MailboxData
+      (Email
+       (Address . "hacker2@@gnu.org"))
+      (AttendeeType . "Required")
+      (ExcludeConflicts . nil)))
+    (FreeBusyViewOptions
+     (TimeWindow
+      (StartTime . "2020-09-25T00:00:00Z")
+      (EndTime . "2020-09-25T23:59:00Z"))
+     (MergedFreeBusyIntervalInMinutes . 60)
+     (RequestedView "DetailedMerged")))
+   nil nil nil)
+ (lambda (identifier response)
+   (message "%S: %S" identifier response)))
+@result{} ("hacker1@@gnu.org" . "https://mail.gnu.org/EWS/Exchange.asmx";): 
(((FreeBusyResponseArray (FreeBusyResponse ... ) ...)))
+@end group
+@end example
 
 @noindent
-To report a bug, use @code{M-x report-emacs-bug}, and put Excorporate
-somewhere in the subject.
+Feel free to submit new functions in excorporate.el and the backends
+that you think others would find useful.  Functions in excorporate.el
+have always kept/must always keep the same interface so that they stay
+backward compatible.
 
 @bye