4 @settitle Emacs Unified Directory Client (EUDC) Manual
15 * EUDC: (eudc). A client for directory servers (LDAP, PH)
18 This file documents EUDC v1.32
20 EUDC is part of XEmacs.
22 EUDC is the Emacs Unified Directory Client, a common interface to
23 directory servers using various protocols such as LDAP or the CCSO white
24 pages directory system (PH/QI)
26 Copyright @copyright{} 1998, 2000 Free Software Foundation, Inc.
28 Permission is granted to make and distribute verbatim
29 copies of this manual provided the copyright notice and
30 this permission notice are preserved on all copies.
33 Permission is granted to process this file through TeX
34 and print the results, provided the printed document
35 carries a copying permission notice identical to this
36 one except for the removal of this paragraph (this
37 paragraph not being relevant to the printed manual).
40 Permission is granted to copy and distribute modified
41 versions of this manual under the conditions for
42 verbatim copying and the terms of the ``GNU General
43 Public License'', and provided that the entire
44 resulting derived work is distributed under the terms
45 of a permission notice identical to this one.
47 Permission is granted to copy and distribute
48 translations of this manual into another language,
49 under the above conditions for modified versions,
50 except that this permission notice may be stated in a
51 translation approved by the Free Software Foundation.
56 @subtitle The Emacs Unified Directory Client
57 @author by Oscar Figueiredo
62 Copyright @copyright{} 1998, 2000 Free Software Foundation, Inc.
64 Permission is granted to make and distribute verbatim
65 copies of this manual provided the copyright notice and
66 this permission notice are preserved on all copies.
69 Permission is granted to process this file through TeX
70 and print the results, provided the printed document
71 carries a copying permission notice identical to this
72 one except for the removal of this paragraph (this
73 paragraph not being relevant to the printed manual).
77 Permission is granted to copy and distribute modified
78 versions of this manual under the conditions for
79 verbatim copying and the terms of the ``GNU General
80 Public License'', and provided that the entire
81 resulting derived work is distributed under the terms
82 of a permission notice identical to this one.
84 Permission is granted to copy and distribute
85 translations of this manual into another language,
86 under the above conditions for modified versions,
87 except that this permission notice may be stated in a
88 translation approved by the Free Software Foundation.
92 @node Top, Overview, (dir), (dir)
93 @comment node-name, next, previous, up
96 This manual documents EUDC v1.32, the Emacs Unified Directory Client.
98 A common interface to directory servers using various protocols such as
99 LDAP or the CCSO white pages directory system (PH/QI)
104 * Overview:: Summary of EUDC features
105 * Installation:: How to install EUDC
106 * Usage:: The various usage possibilities explained
107 * Credits:: Who's done what
115 @node Overview, Installation, Top, Top
116 @comment node-name, next, previous, up
119 EUDC, the Emacs Unified Directory Client, provides a common user
120 interface to access directory servers using different directory
123 Currently supported back-ends are:
127 LDAP, Lightweight Directory Access Protocol
131 BBDB, Big Brother's Insiduous Database
134 The main features of the EUDC interface are:
138 Queries using a customizable form
140 Inline query expansion (for instance you can expand a name
141 to an email address in a mail message buffer using a server as an
144 Multiple servers can automatically be tried in turn
146 Fast minibuffer queries for email addresses and phone numbers
148 Interface to BBDB to let you insert server records into your own BBDB database
149 (@pxref{Top,,BBDB,bbdb,BBDB Manual})
153 * LDAP:: What is LDAP ?
154 * CCSO PH/QI:: What is CCSO, PH, QI ?
155 * BBDB:: What is BBDB ?
160 @node LDAP, CCSO PH/QI, Overview, Overview
161 @comment node-name, next, previous, up
164 LDAP, Lightweight Directory Access Protocol, is a communication
165 protocol for directory applications defined in RFC 1777.
167 Quoted from RFC 1777:
170 [LDAP] is designed to provide access to the X.500 Directory while not
171 incurring the resource requirements of the Directory Access Protocol
172 (DAP). This protocol is specifically targeted at simple management
173 applications and browser applications that provide simple read/write
174 interactive access to the X.500 Directory, and is intended to be a
175 complement to the DAP itself.
178 LDAP servers usually store (but are not limited to) information about
179 people such as their name, phone number, email address, office
180 location, etc@enddots{} More information about LDAP can be found at
181 @url{http://www.openldap.org/}
183 EUDC requires external support to access LDAP directory servers
184 (@pxref{LDAP Requirements})
187 @node CCSO PH/QI, BBDB, LDAP, Overview
188 @comment node-name, next, previous, up
191 The Central Computing Services Office (CCSO) of the University of
192 Illinois at Urbana Champaign (UIUC) created and freely distributes a
193 directory system that is currently in use in more than 300 organizations
194 around the world. The system records information about people such as
195 their address, phone number, email, academic information or any other
196 details it was configured to.
198 The system consists of two parts: a database server traditionally called
199 @samp{qi} and a command-line client called @samp{ph}.
200 @url{ftp://uiarchive.cso.uiuc.edu/pub/packages/ph} is the main
201 distribution site. @url{http://www.uiuc.edu/cgi-bin/ph/lookup?Query=.}
202 provides a listing of the active @samp{qi} servers.
204 The original command-line @samp{ph} client that comes with the
205 @samp{ph/qi} distribution provides additional features like the
206 possibility to communicate with the server in login-mode which makes it
207 possible to change records in the database. This is not implemented in
211 @node BBDB, , CCSO PH/QI, Overview
212 @comment node-name, next, previous, up
215 BBDB is the Big Brother's Insiduous Database, a package for Emacs
216 originally written by Jamie Zawinski which provides rolodex-like
217 database functionality featuring tight integration with the Emacs mail
220 It is often used as an enhanced email address book.
222 EUDC considers BBDB as a directory server backend just like LDAP or
223 PH/QI servers though BBDB has no client/server protocol and thus always
224 resides locally on your machine. The point in this is not to offer an
225 alternate way to query your BBDB database (BBDB itself provides much
226 more flexible ways to do that) but rather to offer an interface to your
227 local directory that is consistent with the interface to external
228 directories (LDAP, PH/QI). This is particularly interesting when
229 performing queries on multiple servers.
231 EUDC also offers a means to insert results from directory queries into
232 your own local BBDB (@pxref{Creating BBDB Records})
234 @node Installation, Usage, Overview, Top
235 @comment node-name, next, previous, up
236 @chapter Installation
238 EUDC is distributed as an XEmacs package. Follow the rules for the
239 installation of XEmacs packages (@pxref{Packages,,XEmacs
240 Packages,xemacs,XEmacs Manual}).
242 After installing EUDC you will find (the next time you launch XEmacs) a
243 new @samp{Directory Search} submenu in the @samp{Tools} menu that will
244 give you access to EUDC.
246 You may also find it useful to add the following to your @file{.emacs}
247 initialization file to add a shortcut for email address expansion in
248 email composition buffers (@pxref{Inline Query Expansion})
253 '(define-key message-mode-map [(control ?c) (tab)] 'eudc-expand-inline))
256 '(define-key mail-mode-map [(control ?c) (tab)] 'eudc-expand-inline))
260 * LDAP Requirements:: EUDC needs external support for LDAP
263 @node LDAP Requirements, , Installation, Installation
264 @comment node-name, next, previous, up
265 @section LDAP Requirements
267 For EUDC to be able to query LDAP servers, LDAP support must be compiled
268 into the XEmacs binary otherwise you will get that error message:
269 @samp{Cannot open load file: ldap}
271 LDAP support is automatically compiled in when you build XEmacs provided
272 appropriate LDAP libraries are installed on your system. As of this
273 writing you can use either (URLs are subject to change):
278 (@url{http://www.openldap.org/})
280 University of Michigan's LDAP Client software
281 (@url{http://www.umich.edu/~dirsvcs/ldap/})
285 @node Usage, Credits, Installation, Top
286 @comment node-name, next, previous, up
289 This chapter describes the usage of EUDC. Most functions and
290 customization options are available through the @samp{Directory Search}
291 submenu of the @samp{Tools} submenu.
294 * Querying Servers:: How queries are performed and handled
295 * Query Form:: How to use and customize the query form
296 * Display of Query Results:: Controlling how query results are presented
297 * Inline Query Expansion:: How to use and customize inline queries
298 * The Server Hotlist:: How to use and manage the server hotlist
299 * Multi-server Queries:: How to query multiple servers successively
300 * Creating BBDB Records:: How to insert query results into your BBDB
301 * Server/Protocol Locals:: Customizing on a per server/protocol basis
305 @node Querying Servers, Query Form, Usage, Usage
306 @comment node-name, next, previous, up
307 @section Querying Servers
309 EUDC's basic functionality is to let you query a directory server and
310 return the results back to you. There are several things you may want
311 to customize in this process.
315 * Selecting a Server:: The first thing to do
316 * Return Attributes:: Configuring what the server should return
317 * Duplicate Attributes:: What to do when records have duplicate attributes
320 @node Selecting a Server, Return Attributes, Querying Servers, Querying Servers
321 @subsection Selecting a Server
323 Before doing any query you will need to set the directory server. You
324 need to specify the name of the host machine running the server software
325 and the protocol to use. If you do not set the server in any fashion,
326 EUDC will ask you for one when you make your first query.
328 You can set the server by selecting one from your hotlist of servers
329 (@pxref{The Server Hotlist}) available in the @samp{Server} submenu or
330 by selecting @samp{New Server} in that same menu.
332 LDAP servers generally require some configuration before you can perform
333 queries on them. In particular, the @dfn{search base} must be
334 configured. If the server you select has no configured search base then
335 EUDC will propose you to configure it at this point. A customization
336 buffer will be displayed where you can edit the search base and other
337 parameters for the server.
340 The name or IP address of the remote directory server. A TCP port number
341 may be specified by appending a colon and a number to the name of the
342 server. You will not need this unless your server runs on a port other
343 than the default (which depends on the protocol).
344 If the directory server resides on your own computer (which is the case
345 if you use the BBDB backend) then `localhost' is a reasonable value but
346 it will be ignored anyway.
349 @defvar eudc-protocol
350 The directory protocol to use to query the server. Currently supported
351 protocols in this version of EUDC are @code{ph}, @code{ldap} and @code{bbdb}.
354 @deffn Command eudc-set-server
355 This command accessible from @samp{Server} submenu lets you specify a
356 new directory server and protocol.
359 @node Return Attributes, Duplicate Attributes, Selecting a Server, Querying Servers
360 @subsection Return Attributes
362 Directory servers may be configured to return a default set of
363 attributes for each record matching a query if the query specifies none.
364 The variable @code{eudc-default-return-attributes} controls the return
365 attributes you want to see, if different from the server defaults.
367 @defvar eudc-default-return-attributes
368 A list of the default attributes to extract from directory entries. If
369 set to the symbol @code{all} then all available attributes are
370 returned. A value of @code{nil}, the default, means to return the
371 default attributes as configured in the server.
374 The server may return several matching records to a query. Some of the
375 records may however not contain all the attributes you requested. You can
376 discard those records.
378 @defopt eudc-strict-return-matches
379 If non-@code{nil}, entries that do not contain all the requested return
380 attributes are ignored. Default is @code{t}.
383 @node Duplicate Attributes, , Return Attributes, Querying Servers
384 @subsection Duplicate Attributes
386 Directory standards may authorize different instances of the same
387 attribute in a record. For instance the record of a person may contain
388 several email fields containing different email addresses. When using
389 a QI directory server this is difficult to distinguish from attributes
390 having multi-line values such as the postal address that may contain a
391 line for the street and another one for the zip code and city name. In
392 both cases, EUDC will consider the attribute duplicated.
394 EUDC has several methods to deal with duplicated attributes. The
395 available methods are:
399 Makes a list with the different values of the duplicate attribute. The
400 record is returned with only one instance of the attribute with a list
401 of all the different values as a value. This is the default method that
402 is used to handle duplicate fields for which no other method has been
405 Discards all the duplicate values of the field keeping only the first
408 Concatenates the different values using a newline as a separator. The
409 record keeps only one instance of the field the value of which is a
410 single multi-line string.
412 Duplicates the whole record into as many instances as there are
413 different values for the field. This is the default for the email
414 field. Thus a record containing 3 different email addresses is
415 duplicated into three different records each having a single email
416 address. This is particularly useful in combination with @code{select}
417 as the method to handle multiple matches in inline expansion queries
418 (@pxref{Inline Query Expansion}) because you are presented with the 3
419 addresses in a selection buffer
422 Because a method may not be applicable to all fields, the variable
423 @code{eudc-duplicate-attribute-handling-method} lets you specify either a
424 default method for all fields or a method for each individual field.
426 @defvar eudc-duplicate-attribute-handling-method
427 A method to handle entries containing duplicate attributes. This is
428 either an alist @code{(@var{attr} . @var{method})} or a symbol
429 @var{method}. The alist form of the variable associates a method to an
430 individual attribute name, the second form specifies a method applicable
431 to all attribute names. Available methods are: @code{list},
432 @code{first}, @code{concat}, @code{duplicate} (see above). Defaults to
438 @node Query Form, Display of Query Results, Querying Servers, Usage
439 @comment node-name, next, previous, up
442 The simplest way to query your directory server is to use the query
443 form. You display the query form with the @samp{Query with Form} menu
444 item or by invoking the command @kbd{M-x eudc-query-form}. The attribute
445 names presented in this form are defined by the
446 @code{eudc-query-form-attributes} variable (unless a non-@code{nil}
447 argument is supplied to @code{eudc-query-form}).
449 Since the different directory protocols to which EUDC interfaces may
450 use different names for equivalent attributes, EUDC defines its own set
451 of attribute names and a mapping between these names and their
452 protocol-specific equivalent through the variable
453 @code{eudc-protocol-attributes-translation-alist}. Names currently
454 defined by EUDC are @code{name}, @code{firstname}, @code{email} and
457 @defvar eudc-query-form-attributes
458 A list of attributes presented in the query form. Attribute names in
459 this list should be either EUDC attribute names or valid attribute
460 names. You can get a list of valid attribute names for the current
461 protocol with the @samp{List Valid Attribute Names} menu item or the
462 @kbd{M-x eudc-get-attribute-list} command. Defaults to @code{name},
463 @code{email} and @code{phone}.
466 @deffn Command eudc-query-form get-fields-from-server
467 Display a form to query the directory server. If given a non-@code{nil}
468 argument the function first queries the server for the existing fields
469 and displays a corresponding form. Not all protocols may support a
470 non-@code{nil} argument here.
473 Since the names of the fields may not be explicit enough or adapted to
474 be directly displayed as prompt strings in the form, the variable
475 @code{eudc-user-attribute-names-alist} lets you define more explicit
476 names for directory attribute names. This variable is ignored if
477 @code{eudc-use-raw-directory-names} is non-@code{nil}.
479 @defvar eudc-user-attribute-names-alist
480 This is an alist of user-defined names for the directory attributes used in
481 query/response forms. Prompt strings for attributes that are not in this
482 alist are derived by splitting the attribute name at underscores and
483 capitalizing the individual words.
486 @defvar eudc-use-raw-directory-names
487 If non-@code{nil}, use attributes names as defined in the directory.
488 Otherwise, directory query/response forms display the user attribute
489 names defined in @code{eudc-user-attribute-names-alist}.
492 @node Display of Query Results, Inline Query Expansion, Query Form, Usage
493 @comment node-name, next, previous, up
494 @section Display of Query Results
496 Upon successful completion of a form query, EUDC will display a buffer
497 containing the results of the query.
499 The fields that are returned for each record
500 are controlled by @code{eudc-default-return-attributes} (@pxref{Return
503 The display of each individual field can be performed by an arbitrary
504 function which allows specific processing for binary values like images
505 or audio samples as well as values with computer semantics like URLs.
507 @defvar eudc-attribute-display-method-alist
508 An alist specifying methods to display attribute values. Each member of
509 the list is of the form @code{(@var{name} . @var{func})} where
510 @var{name} is a lowercased string naming a directory attribute
511 (translated according to @code{eudc-user-attribute-names-alist} if
512 @code{eudc-use-raw-directory-names} is non-@code{nil}) and @var{func} a
513 function that will be passed the corresponding attribute values for
517 This variable has protocol-local definitions (see @pxref{Server/Protocol
518 Locals}). For instance, it is defined as follows for LDAP:
521 (eudc-protocol-set 'eudc-attribute-display-method-alist
522 '(("jpegphoto" . eudc-display-jpeg-inline)
523 ("labeledurl" . eudc-display-url)
524 ("audio" . eudc-display-sound)
525 ("labeledurl" . eudc-display-url)
526 ("url" . eudc-display-url))
530 EUDC provides a set of built-in functions to display binary value types:
532 @defun eudc-display-generic-binary data
533 Display a button for unidentified binary @var{data}.
536 @defun eudc-display-url url
537 Display URL and make it clickable.
540 @defun eudc-display-sound data
541 Display a button to play the sound @var{data}.
544 @defun eudc-display-jpeg-inline data
545 Display the JPEG @var{data} inline at point if possible.
548 @defun eudc-display-jpeg-as-button data
549 Display a button for the JPEG @var{data}.
552 Right-clicking on a binary value button pops up a contextual menu with
553 options to process the value. Among these are saving the attribute
554 value to a file or sending it to an external viewer command. External
555 viewers should expect the value on their standard input and should
556 display it or perform arbitrary processing on it. Messages sent to
557 standard output are discarded. External viewers are listed in the
558 variable @code{eudc-external-viewers} which you can customize.
560 @defvar eudc-external-viewers
561 This is a list of viewer program specifications. Each specification is
562 a list whose first element is a string naming the viewer for unique
563 identification, the second element is the executable program which
564 should be invoked and the following elements are arguments that should
565 be passed to the program.
569 @node Inline Query Expansion, The Server Hotlist, Display of Query Results, Usage
570 @comment node-name, next, previous, up
571 @section Inline Query Expansion
573 Inline query expansion is a powerful method to get completion from your
574 directory server. The most common usage is for expanding names to email
575 addresses in mail message buffers. The expansion is performed by the
576 command @kbd{M-x eudc-expand-inline} which is available from the
577 @samp{Directory Search} menu but can also be conveniently bound to a key
578 shortcut (@pxref{Installation}) The operation is controlled by the
579 variables @code{eudc-inline-expansion-format},
580 @code{eudc-inline-query-format},
581 @code{eudc-expanding-overwrites-query} and
582 @code{eudc-multiple-match-handling-method}.
584 If the query fails for a server, other servers may be tried successively
585 until one of them finds a match (@pxref{Multi-server Queries}).
587 @deffn Command eudc-expand-inline replace-p
588 Query the server and expand the query string before point. The query
589 string consists of the buffer substring from the point back to the
590 preceding comma, colon or beginning of
591 line. @code{eudc-inline-query-format} controls how individual words
592 are mapped onto directory attribute names. After querying the server
593 for the given string, the expansion specified by
594 @code{eudc-inline-expansion-format} is inserted in the buffer at
595 point. If @var{replace-p} is @code{t} then this expansion replaces the
596 query string in the buffer. If @code{eudc-expanding-overwrites-query}
597 is non-@code{nil} then the meaning of @var{replace-p} is negated.
600 @defvar eudc-inline-query-format
601 Format of an inline expansion query.
602 This is actually a list of @var{format}s. A @var{format} is a list of
603 one or more EUDC attribute names. A @var{format} applies if it contains
604 as many attributes as individual words in the inline query string. If
605 several @var{format}s apply then they are tried in order until a match
606 is found. If @code{nil} all the words will be mapped onto the default
607 server/protocol attribute name (generally @code{name}).
609 For instance, use the following
611 (setq eudc-inline-query-format '((name)
615 to indicate that single word expansion queries are to be considered as
616 surnames and if no match is found then they should be tried as first
617 names. Inline queries consisting of two words are considered as
618 consisting of a first name followed by a surname. If the query consists
619 of more than two words, then the first one is considered as the first
620 name and the remaining words are all considered as surname constituents.
622 @var{format}s are in fact not limited to EUDC attribute names, you can
623 use server or protocol specific names in them. If you do so it is
624 highly recommended to set the variable @code{eudc-inline-query-format}
625 in a protocol or server local fashion (see @pxref{Server/Protocol
628 For instance you could use the following to match up to three words
629 against the @code{cn} attribute of LDAP servers:
631 (eudc-protocol-set 'eudc-inline-query-format
639 @defvar eudc-inline-expansion-format
640 This variable lets you control exactly what is inserted into the buffer
641 upon an inline expansion request. It is a list whose first element is a
642 string passed to @code{format}. Remaining elements are symbols
643 corresponding to directory attribute names. The corresponding attribute
644 values are passed as additional arguments to @code{format}. Default is
645 @code{("%s" email)} but you may want to consider a value like @code{("%s
649 @defvar eudc-multiple-match-handling-method
650 This variable controls what to do when multiple entries match a query
651 for an inline expansion. Possible values are:
654 The first match is considered as being the only one, the others are
657 A selection buffer pops up where you can choose a particular match. This
658 is the default value of the variable.
660 The expansion uses all records successively
662 An error is signaled. The expansion aborts.
666 Defaults to @code{select}
671 @node The Server Hotlist, Multi-server Queries, Inline Query Expansion, Usage
672 @comment node-name, next, previous, up
673 @section The Server Hotlist
675 EUDC lets you maintain a list of frequently used servers so that you
676 can easily switch from one to another. This hotlist appears in the
677 @samp{Server} submenu. You select a server in this list by clicking on
678 its name. You can add the current server to the list with the command
679 @kbd{M-x eudc-bookmark-current-server}. The list is contained in the variable
680 @code{eudc-server-hotlist} which is stored in and retrieved from the file
681 designated by @code{eudc-options-file}. EUDC also provides a facility to
682 edit the hotlist interactively (@pxref{The Hotlist Edit Buffer}).
684 The hotlist is also used to make queries on multiple servers
685 successively (@pxref{Multi-server Queries}). The order in which the
686 servers are tried is the order they appear in the hotlist, therefore it
687 is important to sort the hotlist appropriately.
689 @deffn Command eudc-bookmark-server server
690 Add @var{server} to the hotlist of servers
693 @deffn Command eudc-bookmark-current-server
694 Add the current server to the hotlist of servers
697 @defvar eudc-options-file
698 The name of a file where EUDC stores its internal variables
699 (the hotlist and the current server). EUDC will try to load
700 that file upon initialization so, if you choose a file name
701 different from the defaults @file{~/.eudc-options}, be sure to set this
702 variable to the appropriate value @emph{before} EUDC is itself
707 * The Hotlist Edit Buffer:: An interactive hotlist editing facility
710 @node The Hotlist Edit Buffer, , The Server Hotlist, The Server Hotlist
711 @comment node-name, next, previous, up
712 @subsection The Hotlist Edit Buffer
714 The hotlist edit buffer offers a means to manage a list of frequently
715 used servers. Commands are available in the context pop-up menu
716 generally bound to the right mouse button. Those commands also have
717 equivalent keybindings.
719 @deffn Command eudc-hotlist-add-server
721 Add a new server to the hotlist on the line after point
724 @deffn Command eudc-hotlist-delete-server
726 Delete the server on the line point is on
729 @deffn Command eudc-hotlist-select-server
731 Select the server the point is on as the current directory server for
735 @deffn Command eudc-hotlist-transpose-servers
737 Bubble up the server the point is on to the top of the list
740 @deffn Command eudc-hotlist-quit-edit
742 Save the changes and quit the hotlist edit buffer. Use @kbd{x} or
743 @kbd{M-x kill-buffer} to exit without saving.
747 @node Multi-server Queries, Creating BBDB Records, The Server Hotlist, Usage
748 @comment node-name, next, previous, up
749 @section Multi-server Queries
751 When performing inline or form queries, EUDC can try to contact a
752 sequence of directory servers. When performing form queries EUDC tries
753 all the servers specified by the variable @code{eudc-multi-query-policy}
754 and displays all the matching records. When performing inline expansion
755 queries however, EUDC stops trying different servers as soon as a match
756 has been found on one of them.
758 @defvar eudc-multi-query-policy
759 This variable the policy for querying multiple servers. Possible values are:
762 Only the current directory server is tried
764 Up to @code{eudc-max-servers-to-query} servers in the hotlist are tried
766 @item server-then-hotlist
767 The current server then Up to @code{eudc-max-servers-to-query}-1 servers
768 in the hotlist are tried. This is the default.
772 @defvar eudc-max-servers-to-query
773 This variable indicates the maximum number of servers to query when
774 performing a multi-server query. The default, @code{nil}, indicates
775 that all available servers should be tried.
780 @node Creating BBDB Records, Server/Protocol Locals, Multi-server Queries, Usage
781 @comment node-name, next, previous, up
782 @section Creating BBDB Records
784 With EUDC, you can automatically create BBDB records
785 (@pxref{Top,,BBDB,bbdb,BBDB Manual}) from records you get from a
786 directory server. You do this by moving point to the appropriate
787 record in a query result display buffer and invoking the command
788 @kbd{M-x eudc-insert-record-at-point-into-bbdb} with the
789 keyboard binding @kbd{b} @footnote{This keybinding does not actually
790 call @code{eudc-insert-record-at-point-into-bbdb} but uses
791 @code{eudc-try-bbdb-insert} instead.}, or with the menu. EUDC
792 cannot update an existing BBDB record and will signal an error if you
793 try to insert a record matching an existing one.
795 It is also possible to export to BBDB the whole batch of records
796 contained in the directory query result with the command
797 @kbd{M-x eudc-batch-export-records-to-bbdb}.
799 Because directory systems may not enforce a strict record format, local
800 server installations may use different attribute names and have
801 different ways to organize the information. Furthermore BBDB has its own
802 record structure. For these reasons converting a record from its
803 external directory format to the BBDB format is a highly customizable
806 @defvar eudc-bbdb-conversion-alist
807 The value of this variable should be a symbol naming an alist defining a
808 mapping between BBDB field names onto directory attribute names records.
809 This is a protocol-local variable and is initialized upon protocol
810 switch (@pxref{Server/Protocol Locals}) The alist is made of cells of the
811 form @code{(@var{bbdb-field} . @var{spec-or-list})}.
812 @var{bbdb-field} is the name of a field
813 that must be defined in your BBDB environment (standard field names are
814 @code{name}, @code{company}, @code{net}, @code{phone}, @code{address}
816 @var{spec-or-list} is either a single mapping specification or a list of
817 mapping specifications. Lists of mapping specifications are valid for
818 the @code{phone} and @code{address} BBDB fields only. @var{spec}s are
819 actually s-expressions which are evaluated as follows:
825 evaluates to the symbol value. Symbols corresponding to directory
826 attribute names present in the record evaluate to the value of the field
829 is evaluated as a function. The argument list may contain attribute
830 names which evaluate to the corresponding values in the record. The form
831 evaluation should return something appropriate for the particular
832 @var{bbdb-field} (see @code{bbdb-create-internal}).
833 @code{eudc-bbdbify-phone} and @code{eudc-bbdbify-address} are provided as
834 convenience functions to parse phones and addresses.
838 The default value of the PH-specific value of that variable is
839 @code{eudc-ph-bbdb-conversion-alist}:
844 (address . (eudc-bbdbify-address address "Address"))
845 (phone . ((eudc-bbdbify-phone phone "Phone")
846 (eudc-bbdbify-phone office_phone "Office Phone"))))
853 the @code{name} field of the BBDB record gets its value
854 from the @code{name} attribute of the directory record
856 the @code{net} field of the BBDB record gets its value
857 from the @code{email} attribute of the directory record
859 the @code{address} field of the BBDB record is obtained by parsing the
860 @code{address} attribute of the directory record with the function
861 @code{eudc-bbdbify-address}
863 two @code{phone} fields are created (when possible) in the BBDB record.
864 The first one has @cite{Phone} for location and its value is obtained by
865 parsing the @code{phone} attribute of the PH/QI record with the function
866 @code{eudc-bbdbify-phone}. The second one has @cite{Office Phone} for location
867 its value is obtained by parsing the @code{office_phone} attribute of the
868 PH/QI record with the function @code{eudc-bbdbify-phone}.
871 @defun eudc-bbdbify-phone phone location
872 This is a convenience function provided for use in
873 @code{eudc-bbdb-conversion-alist}. It parses @var{phone} into a vector
874 compatible with @code{bbdb-create-internal}. @var{phone} is either a string
875 supposedly containing a phone number or a list of such strings which are
876 concatenated. @var{location} is used as the phone location for BBDB.
879 @defun eudc-bbdbify-address addr location
880 This is a convenience function provided for use in
881 @code{eudc-bbdb-conversion-alist}. It parses @var{addr} into a vector
882 compatible with @code{bbdb-create-internal}. @var{addr} should be an
883 address string of no more than four lines or a list of lines. The last
884 line is searched for the zip code, city and state name. @var{location}
885 is used as the phone location for BBDB.
888 Note that only a subset of the attributes you selected with
889 @code{eudc-default-return-attributes} and that are actually displayed may
890 actually be inserted as part of the newly created BBDB record.
893 @node Server/Protocol Locals, , Creating BBDB Records, Usage
894 @comment node-name, next, previous, up
895 @section Server/Protocol Locals
897 EUDC can be customized independently for each server or directory
898 protocol. All variables can be given local bindings that are activated
899 when a particular server and/or protocol becomes active. This is much
900 like buffer-local bindings but on a per server or per protocol basis.
903 * Manipulating local bindings:: Functions to set and query local bindings
906 @node Manipulating local bindings, , Server/Protocol Locals, Server/Protocol Locals
907 @comment node-name, next, previous, up
908 @subsection Manipulating local bindings
910 EUDC offers functions that let you set and query variables on a per
911 server or per protocol basis.
913 The following predicates allow you to test the existence of
914 server/protocol local bindings for a particular variable.
916 @defun eudc-server-local-variable-p var
917 Return non-@code{nil} if @var{var} has server-local bindings
920 @defun eudc-protocol-local-variable-p var
921 Return non-@code{nil} if @var{var} has protocol-local bindings
924 The following functions allow you to set the value of a variable with
925 various degrees of localness.
927 @defun eudc-default-set var val
928 Set the EUDC default value of @var{var} to @var{val}.
929 The current binding of @var{var} (if local to the current server or
930 protocol) is not changed.
933 @defun eudc-protocol-set var val &optional protocol
934 Set the binding of @var{var} local to @var{protocol} to @var{val}. If
935 omitted, @var{protocol} defaults to the current value of
936 @code{eudc-protocol}. The current binding of @var{var} is changed only
937 if @var{protocol} is omitted.
940 @defun eudc-server-set var val &optional server
941 Set the binding of @var{var} local to @var{server} to @var{val}. If
942 omitted, @var{server} defaults to the current value of
943 @code{eudc-server}. The current binding of @var{var} is changed only if
944 @var{server} is omitted.
947 @defun eudc-set var val
948 Set the most local (server, protocol or default) binding of @var{var} to
949 @var{val}. The current binding of @var{var} is also set to @var{val}.
952 The following variables allow you to query the various bindings of a
953 variable (local or non-local).
955 @defun eudc-variable-default-value var
956 Return the default binding of @var{var} (outside of a particular server
957 or protocol local binding).
958 Return @code{unbound} if @var{var} has no EUDC default value.
961 @defun eudc-variable-protocol-value var &optional protocol
962 Return the value of @var{var} local to @var{protocol}. Return
963 @code{unbound} if @var{var} has no value local to @var{protocol}.
964 @var{protocol} defaults to @code{eudc-protocol}.
967 @defun eudc-variable-server-value var &optional server
968 Return the value of @var{var} local to @var{server}. Return
969 @code{unbound} if @var{var} has no value local to @var{server}.
970 @var{server} defaults to @code{eudc-server}.
974 Changing a protocol-local or server-local value of a variable has no
975 effect on its current value. The following command is used to
976 synchronize the current values of variables with their local values
977 given the current @code{eudc-server} and @code{eudc-protocol}:
979 @defun eudc-update-local-variables
980 Update all EUDC variables according to their local settings.
985 @node Credits, Variables Index, Usage, Top
986 @comment node-name, next, previous, up
989 EUDC was written by Oscar Figueiredo based on @file{ph.el} by the
992 Thanks to Soren Dayton for his suggestions, his enthusiasm and his help
993 in testing and proofreading the code and docs of @file{ph.el}.
995 @node Variables Index, , Credits, Top
996 @comment node-name, next, previous, up
997 @unnumbered Variables Index