3 @setfilename ../../info/eudc.info
4 @settitle Emacs Unified Directory Client (EUDC) Manual
12 This file documents EUDC version 1.40.0.
14 EUDC is the Emacs Unified Directory Client, a common interface to
15 directory servers and contact information.
17 Copyright @copyright{} 1998, 2000--2015 Free Software Foundation, Inc.
20 Permission is granted to copy, distribute and/or modify this document
21 under the terms of the GNU Free Documentation License, Version 1.3 or
22 any later version published by the Free Software Foundation; with no
23 Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'',
24 and with the Back-Cover Texts as in (a) below. A copy of the license
25 is included in the section entitled ``GNU Free Documentation License''.
27 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
28 modify this GNU manual.''
32 @dircategory Emacs network features
34 * EUDC: (eudc). Emacs client for directory servers (LDAP, BBDB).
41 @subtitle The Emacs Unified Directory Client
42 @author by Oscar Figueiredo
54 @top Emacs Unified Directory Client
60 * Overview:: Summary of EUDC features
61 * Installation:: How to install EUDC
62 * Usage:: The various usage possibilities explained
63 * Credits:: Who's done what
64 * GNU Free Documentation License:: The license for this documentation.
75 EUDC, the @dfn{Emacs Unified Directory Client}, provides a common user
76 interface to access directory servers using different directory
79 Currently supported back-ends are:
83 LDAP, Lightweight Directory Access Protocol
85 BBDB, Big Brother's Insidious Database
88 The main features of the EUDC interface are:
92 Queries using a customizable form
94 Inline query expansion (for instance you can expand a name
95 to an email address in a mail message buffer using a server as an
98 Multiple servers can be tried in turn until a match is found for an
101 Fast minibuffer queries for email addresses and phone numbers
103 Interface to BBDB to let you insert server records into your own BBDB database
104 (@pxref{Top,,BBDB,bbdb,BBDB Manual})
108 * LDAP:: What is LDAP ?
109 * BBDB:: What is BBDB ?
117 LDAP, @dfn{the Lightweight Directory Access Protocol}, is a communication
118 protocol for directory applications defined in RFC 1777.
120 Quoted from RFC 1777:
123 [LDAP] is designed to provide access to the X.500 Directory while not
124 incurring the resource requirements of the Directory Access Protocol
125 (DAP). This protocol is specifically targeted at simple management
126 applications and browser applications that provide simple read/write
127 interactive access to the X.500 Directory, and is intended to be a
128 complement to the DAP itself.
131 LDAP servers usually store (but are not limited to) information about
132 people such as their name, phone number, email address, office
133 location, etc@enddots{} More information about LDAP can be found at
134 @url{http://www.openldap.org/}.
136 EUDC requires external support to access LDAP directory servers
137 (@pxref{LDAP Configuration})
143 BBDB is the @dfn{Big Brother's Insidious Database}, a package for Emacs
144 originally written by Jamie Zawinski which provides rolodex-like
145 database functionality featuring tight integration with the Emacs mail
148 It is often used as an enhanced email address book.
150 EUDC considers BBDB as a directory server back end just like LDAP,
151 though BBDB has no client/server protocol and thus always resides
152 locally on your machine. The point in this is not to offer an
153 alternate way to query your BBDB database (BBDB itself provides much
154 more flexible ways to do that), but rather to offer an interface to
155 your local directory that is consistent with the interface to external
156 LDAP directories. This is particularly interesting when performing
157 queries on multiple servers.
159 EUDC also offers a means to insert results from directory queries into
160 your own local BBDB (@pxref{Creating BBDB Records})
163 @chapter Installation
165 Add the following to your @file{.emacs} init file:
169 This will install EUDC at startup.
171 After installing EUDC you will find (the next time you launch Emacs) a
172 new @code{Directory Search} submenu in the @samp{Tools} menu that will
173 give you access to EUDC.
175 You may also find it useful to add the following to your @file{.emacs}
176 initialization file to add a shortcut for email address expansion in
177 email composition buffers (@pxref{Inline Query Expansion})
182 '(define-key message-mode-map [(control ?c) (tab)] 'eudc-expand-inline))
185 '(define-key mail-mode-map [(control ?c) (tab)] 'eudc-expand-inline))
189 * LDAP Configuration:: EUDC needs external support for LDAP
192 @node LDAP Configuration
193 @section LDAP Configuration
195 LDAP support is added by means of @file{ldap.el}, which is part of
196 Emacs. @file{ldap.el} needs an external program called
197 @command{ldapsearch}, available as part of OpenLDAP
198 (@url{http://www.openldap.org/}). The configurations in this section
199 were tested with OpenLDAP 2.4.23.
201 Most servers use LDAP-over-SSL these days; the examples here reflect
202 that. The other possibilities are:
204 @vindex ldap-host-parameters-alist
205 @vindex ldap-ldapsearch-args
209 Servers that do not require authentication or that do not encrypt
210 authentication traffic.
212 Include @code{auth simple} in @code{ldap-host-parameters-alist}, which
213 causes the @code{-x} option to be passed to @command{ldapsearch}.
216 Servers that require SASL authentication.
218 Pass any required extra options to @command{ldapsearch} using
219 @code{ldap-ldapsearch-args}.
222 The following examples use a base of
223 @code{ou=people,dc=gnu,dc=org} and the host name
224 @code{ldap.gnu.org}, a server that supports LDAP-over-SSL (the
225 @code{ldaps} protocol, with default port @code{636}) and which
226 requires authentication by the user @code{emacsuser} with password
229 These configurations are meant to be self-contained; that is, each
230 provides everything required for sensible TAB-completion of email
231 fields. BBDB lookups are attempted first; if a matching BBDB entry is
232 found then EUDC will not attempt any LDAP lookups.
234 Wildcard LDAP lookups are supported using the @code{*} character. For
235 example, attempting to TAB-complete the following:
242 will return all LDAP entries with surnames that begin with
243 @code{Smith}. In every LDAP query it makes, EUDC implicitly appends
244 the wildcard character to the end of the last word.
247 * Emacs-only Configuration:: Configure with @file{.emacs}
248 * External Configuration:: Configure with @file{/etc/openldap/ldap.conf}
249 * Troubleshooting:: Debug @command{ldapsearch} failures
252 @node Emacs-only Configuration
253 @subsection Emacs-only Configuration
255 Emacs can pass most required configuration options via the
256 @command{ldapsearch} command-line. One exception is certificate
257 configuration for LDAP-over-SSL, which must be specified in
258 @file{/etc/openldap/ldap.conf}. On systems that provide such
259 certificates as part of the @code{OpenLDAP} installation, this can be
260 as simple as one line:
263 TLS_CACERTDIR /etc/openldap/certs
266 In @file{.emacs}, these expressions suffice to configure EUDC for
269 @vindex message-mode-map
270 @findex eudc-expand-inline
271 @vindex eudc-server-hotlist
272 @vindex ldap-host-parameters-alist
274 (eval-after-load "message"
275 '(define-key message-mode-map (kbd "TAB") 'eudc-expand-inline))
276 (customize-set-variable 'eudc-server-hotlist
278 ("ldaps://ldap.gnu.org" . ldap)))
279 (customize-set-variable 'ldap-host-parameters-alist
280 '(("ldaps://ldap.gnu.org"
281 base "ou=people,dc=gnu,dc=org"
282 binddn "gnu\\emacsuser"
283 passwd ldap-password-read)))
286 @findex ldap-password-read
288 @vindex password-cache
289 @vindex password-cache-expiry
290 @findex password-reset
291 Specifying the function @code{ldap-password-read} for @code{passwd}
292 will cause Emacs to prompt interactively for the password. The
293 password will then be validated and cached, unless
294 @code{password-cache} is nil. You can customize
295 @code{password-cache-expiry} to control the duration for which the
296 password is cached. If you want to clear the cache, call
297 @code{password-reset}.
299 @node External Configuration
300 @subsection External Configuration
302 Your system may already be configured for a default LDAP server. For
303 example, @file{/etc/openldap/ldap.conf} might contain:
306 BASE ou=people,dc=gnu,dc=org
307 URI ldaps://ldap.gnu.org
308 TLS_CACERTDIR /etc/openldap/certs
311 @cindex bind distinguished name
313 Authentication requires a password, and a @dfn{bind distinguished name
314 (binddn)} representing the user, in this case,
315 @code{gnu\emacsuser}. These can be specified in
316 @file{~/.authinfo.gpg} with the following line:
319 machine ldaps://ldap.gnu.org binddn gnu\emacsuser password s3cr3t
322 Then in the @file{.emacs} init file, these expressions suffice to
323 configure EUDC for LDAP:
325 @vindex message-mode-map
326 @findex eudc-expand-inline
327 @vindex eudc-server-hotlist
328 @vindex ldap-host-parameters-alist
330 (eval-after-load "message"
331 '(define-key message-mode-map (kbd "TAB") 'eudc-expand-inline))
332 (customize-set-variable 'eudc-server-hotlist
334 ("ldaps://ldap.gnu.org" . ldap)))
335 (customize-set-variable 'ldap-host-parameters-alist
336 '(("ldaps://ldap.gnu.org"
340 For this example where we only care about one server, the server name
341 can be omitted in @file{~/.authinfo.gpg} and @file{.emacs}, in which
342 case @command{ldapsearch} defaults to the host name in
343 @file{/etc/openldap/ldap.conf}.
345 The @file{~/.authinfo.gpg} line becomes:
348 binddn gnu\emacsuser password s3cr3t
352 and the @file{.emacs} expressions become:
354 @vindex message-mode-map
355 @findex eudc-expand-inline
356 @vindex eudc-server-hotlist
357 @vindex ldap-host-parameters-alist
359 (eval-after-load "message"
360 '(define-key message-mode-map (kbd "TAB") 'eudc-expand-inline))
361 (customize-set-variable 'eudc-server-hotlist
362 '(("" . bbdb) ("" . ldap)))
363 (customize-set-variable 'ldap-host-parameters-alist
364 '(("" auth-source t)))
367 @node Troubleshooting
368 @subsection Troubleshooting
370 If @command{ldapsearch} exits with an error, you'll see a message like
371 this in the @code{*Messages*} buffer (all on one line):
374 ldap-search-internal: Failed ldapsearch invocation:
375 ldapsearch "-Hldaps://ldap.gnu.org" "-bou=people,dc=gnu,dc=org"
376 "-Dgnu\emacsuser" "-W" "-LL" "-tt" "(&(mail=name*))"
377 "givenname" "sn" "mail"
380 The @command{ldapsearch} command is formatted such that it can be
381 copied and pasted into a terminal. Set the @command{ldapsearch} debug
382 level to 5 by appending @code{-d 5} to the command line.
387 This chapter describes the usage of EUDC@. Most functions and
388 customization options are available through the @samp{Directory Search}
389 submenu of the @samp{Tools} submenu.
392 * Querying Servers:: How queries are performed and handled
393 * Query Form:: How to use and customize the query form
394 * Display of Query Results:: Controlling how query results are presented
395 * Inline Query Expansion:: How to use and customize inline queries
396 * The Server Hotlist:: How to use and manage the server hotlist
397 * Multi-server Queries:: How to query multiple servers successively
398 * Creating BBDB Records:: How to insert query results into your BBDB
399 * Server/Protocol Locals:: Customizing on a per server/protocol basis
403 @node Querying Servers
404 @section Querying Servers
406 EUDC's basic functionality is to let you query a directory server and
407 return the results back to you. There are several things you may want
408 to customize in this process.
412 * Selecting a Server:: The first thing to do
413 * Return Attributes:: Configuring what the server should return
414 * Duplicate Attributes:: What to do when records have duplicate attributes
417 @node Selecting a Server
418 @subsection Selecting a Server
420 Before doing any query you will need to set the directory server. You
421 need to specify the name of the host machine running the server software
422 and the protocol to use. If you do not set the server in any fashion,
423 EUDC will ask you for one when you make your first query.
425 You can set the server by selecting one from your hotlist of servers
426 (@pxref{The Server Hotlist}) available in the @samp{Server} submenu or
427 by selecting @samp{New Server} in that same menu.
429 LDAP servers generally require some configuration before you can perform
430 queries on them. In particular, the @dfn{search base} must be
431 configured. If the server you select has no configured search base then
432 EUDC will propose you to configure it at this point. A customization
433 buffer will be displayed where you can edit the search base and other
434 parameters for the server.
437 The name or IP address of the remote directory server. A TCP port number
438 may be specified by appending a colon and a number to the name of the
439 server. You will not need this unless your server runs on a port other
440 than the default (which depends on the protocol).
441 If the directory server resides on your own computer (which is the case
442 if you use the BBDB back end) then @samp{localhost} is a reasonable value but
443 it will be ignored anyway.
446 @defvar eudc-protocol
447 The directory protocol to use to query the server. Currently supported
448 protocols in this version of EUDC are @code{ldap} and @code{bbdb}.
451 @deffn Command eudc-set-server
452 This command accessible from @samp{New Server} submenu lets you specify a
453 new directory server and protocol.
456 @node Return Attributes
457 @subsection Return Attributes
459 Directory servers may be configured to return a default set of
460 attributes for each record matching a query if the query specifies none.
461 The variable @code{eudc-default-return-attributes} controls the return
462 attributes you want to see, if different from the server defaults.
464 @defvar eudc-default-return-attributes
465 A list of the default attributes to extract from directory entries. If
466 set to the symbol @code{all} then all available attributes are
467 returned. A value of @code{nil}, the default, means to return the
468 default attributes as configured in the server.
471 The server may return several matching records to a query. Some of the
472 records may however not contain all the attributes you requested. You can
473 discard those records.
475 @defopt eudc-strict-return-matches
476 If non-@code{nil}, entries that do not contain all the requested return
477 attributes are ignored. Default is @code{t}.
480 @node Duplicate Attributes
481 @subsection Duplicate Attributes
483 Directory standards may authorize different instances of the same
484 attribute in a record. For instance the record of a person may contain
485 several email fields containing different email addresses, in which
486 case EUDC will consider the attribute duplicated.
488 EUDC has several methods to deal with duplicated attributes. The
489 available methods are:
493 Makes a list with the different values of the duplicate attribute. The
494 record is returned with only one instance of the attribute with a list
495 of all the different values as a value. This is the default method that
496 is used to handle duplicate fields for which no other method has been
499 Discards all the duplicate values of the field keeping only the first
502 Concatenates the different values using a newline as a separator. The
503 record keeps only one instance of the field the value of which is a
504 single multi-line string.
506 Duplicates the whole record into as many instances as there are different
507 values for the field. This is the default for the email field. Thus a
508 record containing 3 different email addresses is duplicated into three
509 different records each having a single email address. This is
510 particularly useful in combination with @code{select} as the method to
511 handle multiple matches in inline expansion queries (@pxref{Inline Query
512 Expansion}) because you are presented with the 3 addresses in a
516 Because a method may not be applicable to all fields, the variable
517 @code{eudc-duplicate-attribute-handling-method} lets you specify either a
518 default method for all fields or a method for each individual field.
520 @defvar eudc-duplicate-attribute-handling-method
521 A method to handle entries containing duplicate attributes. This is
522 either an alist of elements @code{(@var{attr} . @var{method})}, or a symbol
523 @var{method}. The alist form of the variable associates a method to an
524 individual attribute name; the second form specifies a method applicable
525 to all attribute names. Available methods are: @code{list},
526 @code{first}, @code{concat}, and @code{duplicate} (see above). The default is
535 The simplest way to query your directory server is to use the query
536 form. You display the query form with the @samp{Query with Form} menu
537 item or by invoking the command @kbd{M-x eudc-query-form}. The attribute
538 names presented in this form are defined by the
539 @code{eudc-query-form-attributes} variable (unless a non-@code{nil}
540 argument is supplied to @code{eudc-query-form}).
542 Since the different directory protocols to which EUDC interfaces may
543 use different names for equivalent attributes, EUDC defines its own set
544 of attribute names and a mapping between these names and their
545 protocol-specific equivalent through the variable
546 @code{eudc-protocol-attributes-translation-alist}. Names currently
547 defined by EUDC are @code{name}, @code{firstname}, @code{email} and
550 @defvar eudc-query-form-attributes
551 @findex eudc-get-attribute-list
552 A list of attributes presented in the query form. Attribute names in
553 this list should be either EUDC attribute names or valid attribute
554 names. You can get a list of valid attribute names for the current
555 protocol with the @samp{List Valid Attribute Names} menu item or the
556 @kbd{M-x eudc-get-attribute-list} command. Defaults to @code{name},
557 @code{email} and @code{phone}.
560 @deffn Command eudc-query-form get-fields-from-server
561 Display a form to query the directory server. If given a non-@code{nil}
562 argument the function first queries the server for the existing fields
563 and displays a corresponding form. Not all protocols may support a
564 non-@code{nil} argument here.
567 Since the names of the fields may not be explicit enough or adapted to
568 be directly displayed as prompt strings in the form, the variable
569 @code{eudc-user-attribute-names-alist} lets you define more explicit
570 names for directory attribute names. This variable is ignored if
571 @code{eudc-use-raw-directory-names} is non-@code{nil}.
573 @defvar eudc-user-attribute-names-alist
574 This is an alist of user-defined names for the directory attributes used in
575 query/response forms. Prompt strings for attributes that are not in this
576 alist are derived by splitting the attribute name at underscores and
577 capitalizing the individual words.
580 @defvar eudc-use-raw-directory-names
581 If non-@code{nil}, use attributes names as defined in the directory.
582 Otherwise, directory query/response forms display the user attribute
583 names defined in @code{eudc-user-attribute-names-alist}.
586 @node Display of Query Results
587 @section Display of Query Results
589 Upon successful completion of a form query, EUDC will display a buffer
590 containing the results of the query.
592 The fields that are returned for each record
593 are controlled by @code{eudc-default-return-attributes} (@pxref{Return
596 The display of each individual field can be performed by an arbitrary
597 function which allows specific processing for binary values, such as
598 images or audio samples, as well as values with semantics, such as
601 @defvar eudc-attribute-display-method-alist
602 An alist specifying methods to display attribute values. Each member of
603 the list is of the form @code{(@var{name} . @var{func})} where
604 @var{name} is a lowercased string naming a directory attribute
605 (translated according to @code{eudc-user-attribute-names-alist} if
606 @code{eudc-use-raw-directory-names} is non-@code{nil}) and @var{func} a
607 function that will be passed the corresponding attribute values for
611 This variable has protocol-local definitions (see @pxref{Server/Protocol
612 Locals}). For instance, it is defined as follows for LDAP:
615 (eudc-protocol-set 'eudc-attribute-display-method-alist
616 '(("jpegphoto" . eudc-display-jpeg-inline)
617 ("labeledurl" . eudc-display-url)
618 ("audio" . eudc-display-sound)
619 ("labeledurl" . eudc-display-url)
620 ("url" . eudc-display-url))
624 EUDC provides a set of built-in functions to display binary value types:
626 @defun eudc-display-generic-binary data
627 Display a button for unidentified binary @var{data}.
630 @defun eudc-display-url url
631 Display URL and make it clickable.
634 @defun eudc-display-sound data
635 Display a button to play the sound @var{data}.
638 @defun eudc-display-jpeg-inline data
639 Display the JPEG @var{data} inline at point if possible.
642 @defun eudc-display-jpeg-as-button data
643 Display a button for the JPEG @var{data}.
646 Right-clicking on a binary value button pops up a contextual menu with
647 options to process the value. Among these are saving the attribute
648 value to a file or sending it to an external viewer command. External
649 viewers should expect the value on their standard input and should
650 display it or perform arbitrary processing on it. Messages sent to
651 standard output are discarded. External viewers are listed in the
652 variable @code{eudc-external-viewers} which you can customize.
654 @defvar eudc-external-viewers
655 This is a list of viewer program specifications. Each specification is
656 a list whose first element is a string naming the viewer for unique
657 identification, the second element is the executable program which
658 should be invoked and the following elements are arguments that should
659 be passed to the program.
663 @node Inline Query Expansion
664 @section Inline Query Expansion
666 Inline query expansion is a powerful method to get completion from your
667 directory server. The most common usage is for expanding names to email
668 addresses in mail message buffers. The expansion is performed by the
669 command @kbd{M-x eudc-expand-inline} which is available from the
670 @samp{Expand Inline Query} menu item but can also be conveniently
671 bound to a key shortcut (@pxref{Installation}). The operation is
672 controlled by the variables @code{eudc-inline-expansion-format},
673 @code{eudc-inline-query-format},
674 @code{eudc-expanding-overwrites-query} and
675 @code{eudc-multiple-match-handling-method}.
677 If the query fails for a server, other servers may be tried successively
678 until one of them finds a match (@pxref{Multi-server Queries}).
680 @deffn Command eudc-expand-inline replace-p
681 Query the server and expand the query string before point. The query
682 string consists of the buffer substring from the point back to the
683 preceding comma, colon or beginning of
684 line. @code{eudc-inline-query-format} controls how individual words
685 are mapped onto directory attribute names. After querying the server
686 for the given string, the expansion specified by
687 @code{eudc-inline-expansion-format} is inserted in the buffer at
688 point. If @var{replace-p} is @code{t} then this expansion replaces the
689 query string in the buffer. If @code{eudc-expanding-overwrites-query}
690 is non-@code{nil} then the meaning of @var{replace-p} is negated.
693 @defvar eudc-inline-query-format
694 Format of an inline expansion query.
695 This is actually a list of @var{format}s. A @var{format} is a list of
696 one or more EUDC attribute names. A @var{format} applies if it contains
697 as many attributes as individual words in the inline query string. If
698 several @var{format}s apply then they are tried in order until a match
699 is found. If @code{nil} all the words will be mapped onto the default
700 server/protocol attribute name (generally @code{name}).
702 For instance, use the following
704 (setq eudc-inline-query-format '((name)
709 to indicate that single word expansion queries are to be considered as
710 surnames and if no match is found then they should be tried as first
711 names. Inline queries consisting of two words are considered as
712 consisting of a first name followed by a surname. If the query consists
713 of more than two words, then the first one is considered as the first
714 name and the remaining words are all considered as surname constituents.
716 @var{format}s are in fact not limited to EUDC attribute names, you can
717 use server or protocol specific names in them. It may be safer if you
718 do so, to set the variable @code{eudc-inline-query-format} in a protocol
719 or server local fashion (see @pxref{Server/Protocol Locals}).
721 For instance you could use the following to match up to three words
722 against the @code{cn} attribute of LDAP servers:
724 (eudc-protocol-set 'eudc-inline-query-format
732 @defvar eudc-inline-expansion-format
733 This variable lets you control exactly what is inserted into the buffer
734 upon an inline expansion request. It is a list whose first element is a
735 string passed to @code{format}. Remaining elements are symbols
736 corresponding to directory attribute names. The corresponding attribute
737 values are passed as additional arguments to @code{format}. Default is
738 @code{("%s" email)} but you may want to consider a value like @code{("%s
742 @defvar eudc-multiple-match-handling-method
743 This variable controls what to do when multiple entries match a query
744 for an inline expansion. Possible values are:
747 The first match is considered as being the only one, the others are
750 A selection buffer pops up where you can choose a particular match. This
751 is the default value of the variable.
753 The expansion uses all records successively
755 An error is signaled. The expansion aborts.
758 Default is @code{select}
763 @node The Server Hotlist
764 @section The Server Hotlist
766 EUDC lets you maintain a list of frequently used servers so that you
767 can easily switch from one to another. This hotlist appears in the
768 @samp{Server} submenu. You select a server in this list by clicking on
769 its name. You can add the current server to the list with the command
770 @kbd{M-x eudc-bookmark-current-server}. The list is contained in the variable
771 @code{eudc-server-hotlist} which is stored in and retrieved from the file
772 designated by @code{eudc-options-file}. EUDC also provides a facility to
773 edit the hotlist interactively (@pxref{The Hotlist Edit Buffer}).
775 The hotlist is also used to make queries on multiple servers
776 successively (@pxref{Multi-server Queries}). The order in which the
777 servers are tried is the order they appear in the hotlist, therefore it
778 is important to sort the hotlist appropriately.
780 @deffn Command eudc-bookmark-server server
781 Add @var{server} to the hotlist of servers
784 @deffn Command eudc-bookmark-current-server
785 Add the current server to the hotlist of servers
788 @defvar eudc-options-file
789 The name of a file where EUDC stores its internal variables
790 (the hotlist and the current server). EUDC will try to load
791 that file upon initialization so, if you choose a file name
792 different from the defaults @file{~/.eudc-options}, be sure to set this
793 variable to the appropriate value @emph{before} EUDC is itself
798 * The Hotlist Edit Buffer:: An interactive hotlist editing facility
801 @node The Hotlist Edit Buffer
802 @subsection The Hotlist Edit Buffer
804 The hotlist edit buffer offers a means to manage a list of frequently
805 used servers. Commands are available in the context pop-up menu
806 generally bound to the right mouse button. Those commands also have
807 equivalent key bindings.
809 @deffn Command eudc-hotlist-add-server
811 Add a new server to the hotlist on the line after point
814 @deffn Command eudc-hotlist-delete-server
816 Delete the server on the line point is on
819 @deffn Command eudc-hotlist-select-server
821 Select the server the point is on as the current directory server for
825 @deffn Command eudc-hotlist-transpose-servers
827 Bubble up the server the point is on to the top of the list
830 @deffn Command eudc-hotlist-quit-edit
832 Save the changes and quit the hotlist edit buffer. Use @kbd{x} or
833 @kbd{M-x kill-buffer} to exit without saving.
837 @node Multi-server Queries
838 @section Multi-server Queries
840 When using inline query expansion (@pxref{Inline Query Expansion}), EUDC
841 can try to query successively a sequence of directory servers until one
842 of them successfully finds a match for the query.
844 @defvar eudc-inline-expansion-servers
845 This variable controls which servers are tried and in which order when
846 trying to perform an inline query. Possible values are:
849 Only the current directory server is tried
851 The servers in the hotlist are tried in order until one finds a match
852 for the query or @code{eudc-max-servers-to-query} is reached
853 @item server-then-hotlist
854 The current server then the servers in the hotlist are tried in the
855 order they appear in the hotlist until one of them finds a match or
856 @code{eudc-max-servers-to-query} is reached. This is the default.
860 @defvar eudc-max-servers-to-query
861 This variable indicates the maximum number of servers to query when
862 performing a multi-server query. The default, @code{nil}, indicates
863 that all available servers should be tried.
868 @node Creating BBDB Records
869 @section Creating BBDB Records
871 @findex eudc-insert-record-at-point-into-bbdb
872 @findex eudc-try-bbdb-insert
873 With EUDC, you can automatically create BBDB records
874 (@pxref{Top,,BBDB,bbdb,BBDB Manual}) from records you get from a
875 directory server. You do this by moving point to the appropriate
876 record in a query result display buffer and invoking the command
877 @kbd{M-x eudc-insert-record-at-point-into-bbdb} with the
878 keyboard binding @kbd{b}@footnote{This key binding does not actually
879 call @code{eudc-insert-record-at-point-into-bbdb} but uses
880 @code{eudc-try-bbdb-insert} instead.}, or with the menu. EUDC
881 cannot update an existing BBDB record and will signal an error if you
882 try to insert a record matching an existing one.
884 @findex eudc-batch-export-records-to-bbdb
885 It is also possible to export to BBDB the whole batch of records
886 contained in the directory query result with the command
887 @kbd{M-x eudc-batch-export-records-to-bbdb}.
889 Because directory systems may not enforce a strict record format, local
890 server installations may use different attribute names and have
891 different ways to organize the information. Furthermore BBDB has its own
892 record structure. For these reasons converting a record from its
893 external directory format to the BBDB format is a highly customizable
896 @defvar eudc-bbdb-conversion-alist
897 The value of this variable should be a symbol naming an alist defining a
898 mapping between BBDB field names onto directory attribute names records.
899 This is a protocol-local variable and is initialized upon protocol
900 switch (@pxref{Server/Protocol Locals}). The alist is made of cells of the
901 form @code{(@var{bbdb-field} . @var{spec-or-list})}.
902 @var{bbdb-field} is the name of a field
903 that must be defined in your BBDB environment (standard field names are
904 @code{name}, @code{company}, @code{net}, @code{phone}, @code{address}
906 @var{spec-or-list} is either a single mapping specification or a list of
907 mapping specifications. Lists of mapping specifications are valid for
908 the @code{phone} and @code{address} BBDB fields only. @var{spec}s are
909 actually s-expressions which are evaluated as follows:
915 evaluates to the symbol value. Symbols corresponding to directory
916 attribute names present in the record evaluate to the value of the field
919 is evaluated as a function. The argument list may contain attribute
920 names which evaluate to the corresponding values in the record. The form
921 evaluation should return something appropriate for the particular
922 @var{bbdb-field} (see @code{bbdb-create-internal}).
923 @code{eudc-bbdbify-phone} and @code{eudc-bbdbify-address} are provided as
924 convenience functions to parse phones and addresses.
928 @defun eudc-bbdbify-phone phone location
929 This is a convenience function provided for use in
930 @code{eudc-bbdb-conversion-alist}. It parses @var{phone} into a vector
931 compatible with @code{bbdb-create-internal}. @var{phone} is either a string
932 supposedly containing a phone number or a list of such strings which are
933 concatenated. @var{location} is used as the phone location for BBDB.
936 @defun eudc-bbdbify-address addr location
937 This is a convenience function provided for use in
938 @code{eudc-bbdb-conversion-alist}. It parses @var{addr} into a vector
939 compatible with @code{bbdb-create-internal}. @var{addr} should be an
940 address string of no more than four lines or a list of lines. The last
941 line is searched for the zip code, city and state name. @var{location}
942 is used as the phone location for BBDB.
945 Note that only a subset of the attributes you selected with
946 @code{eudc-default-return-attributes} and that are actually displayed may
947 actually be inserted as part of the newly created BBDB record.
950 @node Server/Protocol Locals
951 @section Server/Protocol Locals
953 EUDC can be customized independently for each server or directory
954 protocol. All variables can be given local bindings that are activated
955 when a particular server and/or protocol becomes active. This is much
956 like buffer-local bindings but on a per server or per protocol basis.
959 * Manipulating local bindings:: Functions to set and query local bindings
962 @node Manipulating local bindings
963 @subsection Manipulating local bindings
965 EUDC offers functions that let you set and query variables on a per
966 server or per protocol basis.
968 The following predicates allow you to test the existence of
969 server/protocol local bindings for a particular variable.
971 @defun eudc-server-local-variable-p var
972 Return non-@code{nil} if @var{var} has server-local bindings
975 @defun eudc-protocol-local-variable-p var
976 Return non-@code{nil} if @var{var} has protocol-local bindings
979 The following functions allow you to set the value of a variable with
980 various degrees of locality.
982 @defun eudc-default-set var val
983 Set the EUDC default value of @var{var} to @var{val}.
984 The current binding of @var{var} (if local to the current server or
985 protocol) is not changed.
988 @defun eudc-protocol-set var val &optional protocol
989 Set the binding of @var{var} local to @var{protocol} to @var{val}. If
990 omitted, @var{protocol} defaults to the current value of
991 @code{eudc-protocol}. The current binding of @var{var} is changed only
992 if @var{protocol} is omitted.
995 @defun eudc-server-set var val &optional server
996 Set the binding of @var{var} local to @var{server} to @var{val}. If
997 omitted, @var{server} defaults to the current value of
998 @code{eudc-server}. The current binding of @var{var} is changed only if
999 @var{server} is omitted.
1002 @defun eudc-set var val
1003 Set the most local (server, protocol or default) binding of @var{var} to
1004 @var{val}. The current binding of @var{var} is also set to @var{val}.
1007 The following variables allow you to query the various bindings of a
1008 variable (local or non-local).
1010 @defun eudc-variable-default-value var
1011 Return the default binding of @var{var} (outside of a particular server
1012 or protocol local binding).
1013 Return @code{unbound} if @var{var} has no EUDC default value.
1016 @defun eudc-variable-protocol-value var &optional protocol
1017 Return the value of @var{var} local to @var{protocol}. Return
1018 @code{unbound} if @var{var} has no value local to @var{protocol}.
1019 @var{protocol} defaults to @code{eudc-protocol}.
1022 @defun eudc-variable-server-value var [server]
1023 Return the value of @var{var} local to @var{server}.
1024 Return @code{unbound} if @var{var} has no value local to @var{server}.
1025 @var{server} defaults to @code{eudc-server}.
1028 Changing a protocol-local or server-local value of a variable has no
1029 effect on its current value. The following command is used to
1030 synchronize the current values of variables with their local values
1031 given the current @code{eudc-server} and @code{eudc-protocol}:
1033 @defun eudc-update-local-variables
1034 Update all EUDC variables according to their local settings.
1042 EUDC was written by Oscar Figueiredo based on @file{ph.el} by the
1045 Thanks to Soren Dayton for his suggestions, his enthusiasm and his help
1046 in testing and proofreading the code and docs of @file{ph.el}.
1048 @node GNU Free Documentation License
1049 @appendix GNU Free Documentation License
1050 @include doclicense.texi