diff --git a/doc/misc/eudc.texi b/doc/misc/eudc.texi index 66867cbc58..0cea3126a0 100644 --- a/doc/misc/eudc.texi +++ b/doc/misc/eudc.texi @@ -85,6 +85,8 @@ LDAP, Lightweight Directory Access Protocol CCSO PH/QI @item BBDB, Big Brother's Insidious Database +@item +macOS Contacts @end itemize The main features of the EUDC interface are: @@ -110,6 +112,7 @@ Interface to BBDB to let you insert server records into your own BBDB database * LDAP:: What is LDAP ? * CCSO PH/QI:: What is CCSO, PH, QI ? * BBDB:: What is BBDB ? +* macOS Contacts:: What is macOS Contacts ? @end menu @@ -186,6 +189,31 @@ performing queries on multiple servers. EUDC also offers a means to insert results from directory queries into your own local BBDB (@pxref{Creating BBDB Records}) + +@node macOS Contacts +@section macOS Contacts + +@url{https://support.apple.com/guide/contacts/welcome/mac,, macOS +Contacts} is the rolodex-like application that ships with the macOS +operating system@footnote{Apple have changed the names of their +operating system and some applications over time. macOS used to be +called Mac OS X in the past, and the Contacts application was +previously called Address Book.}. It is tightly integrated with the +other Apple applications (Mail, Calendar, etc.), and can synchronise +contacts information between Apple devices via CardDAV servers (such +as e.g. iCloud). + +EUDC considers macOS Contacts as a directory server back end just like +LDAP or PH/QI servers, though the macOS Contacts application always +resides locally on your machine. The point in this is not to offer an +alternate way to query your macOS Contacts database (the macOS +Contacts application itself provides much more flexible ways to do +that), but rather to offer an interface to your local directory that +is consistent with the interface to external directories (LDAP, +PH/QI). This is particularly interesting when performing queries on +multiple servers. + + @node Installation @chapter Installation @@ -214,6 +242,7 @@ email composition buffers (@pxref{Inline Query Expansion}) @menu * LDAP Configuration:: EUDC needs external support for LDAP +* macOS Contacts Configuration:: Enable the macOS Contacts backend @end menu @node LDAP Configuration @@ -339,6 +368,42 @@ and the @file{.emacs} expressions become: (customize-set-variable 'ldap-host-parameters-alist '(("" auth-source t))) @end lisp + +@node macOS Contacts Configuration +@section macOS Contacts Configuration + +macOS Contacts support is added by means of @file{eudcb-mab.el}, or +@file{eudcb-macos-contacts.el} which are part of Emacs. + +@file{eudcb-mab.el} reverse engineers the format of the database file +used by the macOS Contacts app, and accesses its contents directly. +While this may promise some performance advantages, it comes at the +cost of using an undocumented interface. Hence, users of +@file{eudcb-mab.el} are recommended to double check the compatibility +of @file{eudcb-mab.el} before upgrading to a new version of macOS. +@file{eudcb-mab.el} is retained for backwards compatibility with +existing configurations, and may be removed in a future release. + +@file{eudcb-macos-contacts.el} uses the public scripting interfaces +offered by the Contacts app via the macOS +@url{https://developer.apple.com/library/archive/documentation/AppleScript/Conceptual/AppleScriptX/Concepts/osa.html,, +Open Scripting Architecture (OSA)}. To accomplish this, +@file{eudcb-macos-contacts.el} uses an external command line utility +named +@url{https://developer.apple.com/library/archive/documentation/OpenSource/Conceptual/ShellScripting/AdvancedTechniques/AdvancedTechniques.html#//apple_ref/doc/uid/TP40004268-TP40003521-SW44,, +osascript}, which is included with all macOS versions since 10.0 +(which was released 2001). @file{eudcb-macos-contacts.el} is hence +recommended for all new configurations. + +To enable a macOS Contacts backend, first `require' the respective +library to load it, and then set the `eudc-server' to localhost in +your init file: +@lisp +(require 'eudcb-macos-contacts) +(eudc-macos-contacts-set-server "localhost") +@end lisp + + @node Usage @chapter Usage