LDapper 1.2.2 - by Carl W. Bell

Copyright © 1997-1999 Baylor University
LDAP SDK Copyright © 1990 Regents of the University of Michigan.

Disclaimer: Although LDapper seems to work fine, it is distributed "as is". Use at your own risk.

LDapper is a simple LDAP (Lightweight Directory Access Protocol) client for finding e-mail addresses. You can look up people by name and/or department. Once you have a list of people, you can copy/paste or drag addresses into a new e-mail message. Depending on your e-mail client, you may be able to automagically add them to a new message by selecting the "Mail To:" command in the LDAP menu or by clicking the e-mail button. Try it and see if it works. It does with Mail Drop. (Go figure... :-)

For more information on LDAP, see Innosoft's LDAP World:

<http://www3.innosoft.com/ldapworld/index.html>

and University of Michigan LDAP:

<http://www.umich.edu/~dirsvcs/ldap/index.html>

Special thanx go to One Click Systems, makers of ClickMail Central Directory (an LDAP server for the Macintosh) for their assistance as I added international character support to LDapper:

<http://www.oneclick.com/>

Directories

You will need to set up at least one directory before you can do a search. (This can be the "Internet Config Default" directory - see below.) Open up preferences and click the add (+) button. If you hold down the option key while clicking the add button, a copy of the current directory will be added. Then specify the directory's name (which can be whatever you want, but must be unique), the LDAP server's IP address, and an optional (but sometimes not so optional) search base. You can also specify an IP port if it is different from the normal LDAP port (389). Click the edit (pencil) or delete (trashcan) buttons to edit and delete directories. The first directory in the list is one that corresponds to the default Internet Config directory. You cannot delete this directory or edit its LDAP server, port, or search base within LDapper. The directories list is automatically sorted by name when the preferences file is first read at startup and right before it is written to disk when quitting LDapper.

At Baylor, you will want to enter one or more of the following:

Directory: Baylor Directory
LDAP Server: ldap.baylor.edu
Search base: o=Baylor University, c=US

Directory: Baylor Directory (Students)
LDAP Server: ldap.baylor.edu
Search base: ou=Students, ou=People, o=Baylor University, c=US

Directory: Baylor Directory (Faculty & Staff)
LDAP Server: ldap.baylor.edu
Search base: ou=Faculty and Staff, ou=People, o=Baylor University, c=US

Note that Baylor runs two LDAP servers, one on the standard port 389, and one on port 390. Because the 390 server contains information that is not considered "public" information, e.g., home addresses and phone numbers, it is only accessible on the Baylor network. E-mail addresses are available on both servers so you can use the default port without any problems.

You can also specify some of the default attributes that LDapper uses. While editing the directory, click the "Attributes" tab. These attributes (and default values) include Last Name (sn), Full Name (cn), Department (ou), and E-mail Address (mail). You can also specify the value for the objectClass attribute (person) used to restrict searches to people. Unless you know that you need to change these, you should leave these set to the defaults. To reset the values to their defaults, click the "Defaults" button. The attributes panel is where you specify the encoding to use for international characters such as ö or ñ. The default encoding is "No Encoding" (just plain MacRoman/ASCII characters). For many users this should be fine since most of the information will be in ASCII anyway. One major benefit of not encoding is that searches will be faster. If you know that you need to use international characters, you will probably want to use the UTF-8 (Unicode) encoding. UTF-8 is required for LDAPv3 but is commonly used in LDAPv2 systems (which is what LDapper supports). Note that in order to use UTF-8, you must have Apple's Text Encoding Converter extension installed on your Mac. LDapper will allow you to specify UTF-8 without TEC installed but will fall back to "No encoding". LDapper also supports ISO-Latin-1 and Mac-Latin-1 encodings. These use internal tables to convert characters so the Text Encoding Converter is not required (although TEC was used to generate the tables themselves). The last encoding T.61 is actually the official encoding method for LDAPv2 but is not supported by LDapper and so the menu item is disabled.

Some information is only available if you identify yourself to the LDAP server. For example, the server may be set up to only allow people at your site to view home address and phone number information; anonymous users will not be able to retrieve these attributes. You can set your credentials by clicking the "Authentication" tab. Enter your identification (possibly your "distinguished name", e.g., "cn=Rocket Squirrel, o=Wossamotta University, c=US") and an optional password. If you leave the password field blank, LDapper will identify you but you will probably have the same access as if you were anonymous. Note that although you may be authenticated, you cannot use LDapper to change information on the server.

Searching

Select the New command in the File menu to open a new search window with initial settings as specified in Preferences. You can change several of the settings, e.g., the directory, types of searches, before doing a search.

To do a search, enter some text in the name and/or department field, then click the Find button (or select the Find command in the LDAP menu, or press return). Use the popup menu to choose between "Last Name:" (LDAP's sn) and "Full Name" (LDAP's cn) searches. The department is really organizational unit (LDAP's ou) although this can be changed to another attribute by editing the directory in preferences. You can choose the search types for names and departments with the popup menus in a search window. The choices are: is, is similar to, contains, starts with, ends with.

If the first character in the name field is an open parenthesis '(', LDapper will assume that that is a "real" LDAP search filter and will just pass it onto the the server. [I'm not going to try to explain search filters. You either know how to specify one or you don't. LDapper always does a subtree search - you cannot specify base-object or one-level searches.] Hold down the option key when clicking the search button to see the search filter that will be sent to the server.

You can specify the maximum number of responses you want to receive from the LDAP server. The default is 100. Set this to 0 to designate no limit (but you may run out of memory). Also note that there may be a limit set by the server. You can also specify how long to wait for a response before timing out. Set this to 0 to wait forever. (Maybe not such a good idea.) The default is 30 seconds. The default max hits and time limits are set in preferences but you can also change the values without changing the defaults in their corresponding fields in the search window.

There are a few other options that can be set before doing a search. The "Clear List Before New Search" checkbox specifies whether or not all of the addresses in the list are removed so that all of the entries in the list will be matches to the current search and not old matches. The "Fetch Full Attributes" checkbox specifies whether or not all attributes are fetched in the initial search rather than the set of minimal attributes. Enabling this may slow down searches if there are a lot of matches or you are on a slower connection. The "Discard Responses Without E-mail" checkbox specifies whether or not responses that are missing e-mail addresses are ignored. If this is not enabled, entries in the list without e-mail addresses will show "n/a" instead. You will not be able to include any of these (non-)addresses when performing a "mailto". The "Search For People Only" checkbox specifies whether or not LDapper should limit a search to only people, i.e., those entries with an objectClass value of "person". (This can be modified in preferences when editing a directory.) For example, if you do a search for people in a department that contains "Marketing", the server may return responses for the departments themselves. These three options are persistent and are saved to the preference file.

LDapper will connect to the server when you first do a search, but will not close the connection until the window is closed, a different directory is specified, the preferences are modified, or the number of seconds specified in the internal IDLEDISCONNECTSECONDS preference mentioned below have passed since the last search.

You can save the search criteria to a file by selecting the "Save" (or "Save As") commands in the File menu. Information saved in the file includes the current directory, last/full name search, type of name search (from the popup menu), the name to search for, type of department search, and the department to search for. Select the "Open..." command from the File menu to open the file and apply it to a new window. Saving and opening files will use Navigation Services, if available. If you encounter problems with this, hold down the option key and select the commands to use the old style Standard File dialogs. Because Navigation Services is sometimes slow, there is a preference that will permanently disable it so you don't have to hold down the option key each time. Note that doing this may cause problems on newer versions of the OS that require Navigations Services.

The Address List and Info Field

When you click the Find button or select the Find command from the LDAP menu, a search query is sent to the server. As entries are added to the address list, you can cancel the operation by pressing cmd-period. If there are no matches to your search, or more matches than the "Max # Hits" preference, LDapper will let you know. The search requests only a minimal set of attributes for matching responses (name, email, and dept) unless the "Fetch All Attributes" option is enabled. As mentioned above, entries without an e-mail address will show "n/a" in the list. If an entry doesn't have a name (cn), but does have a department (ou), then the list will show the department name. Entries without names or departments will show "n/a". To remove entries from the list, select them, then hit delete or choose the Clear command from the Edit menu.

To specify how the address list is sorted, click in the address list's "Name" or "E-Mail" column header. You can change the width of the columns by clicking the line between the column headers and dragging. To switch between ascending and descending sorts, click the sort button above the list's scroll bar. LDapper will remember the way that the address list is sorted and the with of the columns between sessions.

Choose the "Show/Hide Info" menu to show/hide detailed information about the selected address. This information is not fetched until it is actually needed, in other words, when you select an entry in the list. If you switch directories or modify the current directory in preferences, LDapper will not fetch the info for any of the addresses that are already in the list although it will for addresses found in subsequent searches. The list of "full" attributes is stored in an internal resource in LDapper, but you can specify other attributes if you are familiar with ResEdit. (See below.)

You can modify the size of the address list and info field by clicking on the line between the two and dragging the mouse. The size is saved between sessions. (Sometimes, especially when zooming the window, the sizes of the list and field may jump unexpectedly. This is a known bug caused by the way LDapper handles sizing of the window. Just resize the list/field again.) If you ever need to reset the window, the address list, and info field, to their default positions, hold down the option key while opening a new window.

Copying/Dragging Addresses

Click one or more entries in the address list to select them. Then you can copy/paste or drag them to your e-mail application. Entries without e-mail addresses will not be included. Different e-mail applications handle copying (and dragging) of addresses differently. You will need to experiment with some settings to see what works best with your e-mail application.

If the "Separate With Commas" preference is enabled, addresses will be separated with commas, e.g.,

rocky@wossamotta.edu,bullwinkle@wossamotta.edu

If it is disabled they will be separated with carriage returns, e.g.,

rocky@wossamotta.edu
bullwinkle@wossamotta.edu

If the "Include Personal Names" preference is enabled, then you'll get

"Rocket J. Squirrel" <rocky@wossamotta.edu>,"Bullwinkle J. Moose" <bullwinkle@wossamotta.edu>

or

"Rocket J. Squirrel" <rocky@wossamotta.edu>
"Bullwinkle J. Moose" <bullwinkle@wossamotta.edu>

Exporting

You can export addresses by choosing an item in the "Export Addresses" menu. The items in the menu correspond to export plug-in files found in a folder called "LDapper Plug-ins". This folder must be located in the same folder as LDapper, in the Extensions folder, in the Application Support folder, or the System folder. The actual format of the exported addresses or info depends on the plug-in itself. Plug-ins can be either 68K or native PPC. Both types will be used by the native PPC version of LDapper but only the 68K plug-ins will be used by the 68K version, even if running on a PPC Mac. Plug-ins have or should have a unique internal signature. If there are multiple plug-ins installed with the same signature, LDapper will use the first one, except in the case where one plug-in is 68K and the other is native PPC, the native PPC plug-in will be used (in the PPC version of LDapper).

Plug-ins distributed with LDapper include:

AddressName

address (name)
address (name)
address
address (name)
etc.

NameAddress

name <address>
address
name <address>
name <address>
etc.

PseudoLDIF

dn: the dn
attr: value
attr: value
attr: value
attr: value

dn: the dn
attr: value
attr: value
attr: value
attr: value

etc.

Palm(TM) Desktop

This plug-in writes a file that can be imported into the 3Com® Palm(TM) Desktop organizer software's contact list. When importing, be sure to choose Fields: "Contacts" and Delimiters: "Palm Desktop". This plug-in is highly dependent on the format of the response from the LDAP server, e.g., for parsing addresses. There are two versions distributed with LDapper - one that is configured to work with the server at Baylor and one that is more generic. It is possible to modify it for other sites using ResEdit. (See the "Palm Desktop Read Me" file for more details.) Note that this has only been tested with MacPac v2 and may not work other versions.

If you need a different format you can write your own plug-in. Plug-in docs (more or less) as well as source code for some of the above plug-ins are available here. Contact Carl Bell at the address below if you want more info.

"Mail To:"

LDapper can automagically create a new e-mail message pre-addressed with selected addresses if your e-mail application supports this. This works the same way as if you had clicked on a "mailto:" URL in a web page so any program that can be set up as a mailto URL helper should work. You first must specify which e-mail application you want to use in the preferences dialog. (The default application is Mail Drop...) Note that both the application's creator, e.g., 'MDrp' for Mail Drop, and an alias to the application is saved in the preference file. What this means is that normally LDapper will use the alias to get the application, but if for some reason that doesn't work, it will try to convert the application's creator back into the application, and it may find a different copy. If the "Use Internet Config" preference is enabled, LDapper will simply pass off the address to IC and let it handle it although if you don't have an e-mail helper set, nothing will happen. Select one or more entries in the address list, then click the "Mail To:" button or select the "Mail To:" command in the LDAP menu to send the address(es) to your e-mail application. Double-clicking an address or pressing return/enter while the address list is active will do the same thing.

Note that sending addresses to your e-mail application in this manner will not include personal names. If you want personal names, you must use copy/paste or drag and drop instead. Also, some applications require a trailing null at the end of each address, while some others will only work if there isn't one there. There is a preference to include this or not. Try an address and if it doesn't seem to work, toggle this preference. Finally, there is no way to include multiple addresses in a single mailto so LDapper must send a separate mailto for each address. Most applications create a new message for each mailto. Some applications, including Mail Drop, will create a new message (if the front window is not already a new message) only for the first one, and subsequent mailtos will be added to that message. If the latter is what you prefer, you should let the vendor or developer of your e-mail application know.

Internal Defaults

Lab managers can can specify initial defaults for various preferences. These are stored inside of LDapper in a 'TEXT' resource (ID 10000). Because the LDapper Preferences file is really a text file, you can copy and paste the entries into the TEXT resource. The order of the pref entries is irrelevant. Important: There must be a return after the last entry in the TEXT resource.

LDapper's default preferences are:

Admin prefs not written to pref file

CANSAVEPREFS=T
DONTLAUNCHASHARE=T
DEFAULTBROWSER=MOSS
IDLEDISCONNECTSECONDS=120

Normal prefs

FULLDIRECTORY=see below
MAXHITS=100
TIMELIMIT=30
CLEARLIST=T
FETCHFULLATTRS=F
DISCARDNONEMAIL=T
DEFAULTNAMESEARCH=3
DEFAULTDEPTSEARCH=4
EMAILAPP=MDrp
EMAILAPPALIAS=see below
USEINTERNETCONFIG=F
SEPARATEWITHCOMMAS=T
INCLUDEPERSONALNAMES=T
LASTNAMESEARCH=T
SHOWINFO=F
PEOPLEONLY=T
SORTBYNAME=T
ASCENDINGORDER=T
NAMECOLUMNWIDTH=180
USENAVSERVICES=T
TRAILINGNULL=F
LDAPWINDOWBOUNDS=see below
LDAPWINDOWSPLIT=see below

You only need to add entries to the TEXT resource if you want something different than the above defaults. Add the CANSAVEPREFS pref and set it to F for lab environments but make sure you add at least one DIRECTORY entry in the TEXT resource or make sure that USEINTERNETCONFIG is T and that the LDAP server/search base is set in Internet Config.

Boolean (true/false) values should be either T or F. Integer values are just the number. The default searches types are:

1 - is
2 - is similar to
3 - contains
4 - starts with
5 - ends with

No directory is specified by default, but the entry looks like:

FULLDIRECTORY=dirName<tab>ldap.server.address[:port]<tab>searchbase
<tab>personAttr<tab>lastNameAttr<tab>fullNameAttr<tab>deptAttr<tab>mailAttr
<tab>id<tab>password

Note that the line break after the searchbase and mailAttr is only to make this readable. The FULLDIRECTORY entry must be on one line. Older versions of LDapper used a shortened version of this (DIRECTORY) that did not include the attributes or authentication info. This is no longer supported.

It is probably easiest to set up directories in the preferences dialog and then copy/paste them from the prefs file into the 'TEXT' resource. You can leave the ID and password blank. The password is encrypted and encoded so you can't type it in beforehand anyway.

The EMAILAPPALIAS is an alias record ("hexified") of the chosen e-mail helper application. If missing, or if the alias cannot be resolved, LDapper will search the hard disks for the application whose signature is specified in EMAILAPP.

LDapper will sometimes search the Mac's hard disks for an application, e.g., the e-mail application or a web browser. Normally, mounted AppleShare volumes are ignored so that LDapper won't try to launch (and more importantly, save an alias to) a program that resides on a remote server. To have LDapper include AppleShare volumes, add a DONTLAUNCHASHARE=F entry.

As mentioned above, LDapper also can launch a web browser after checking for a newer version. If the "Use Internet Config" option is enabled, LDapper will just use it. If not, it will search for and use Netscape Navigator and Microsoft Internet Explorer in that order. If you want to force it to use IE or have a different browser, add a DEFAULTBROWSER=???? entry. Replace the ?'s with the signature of your browser (MSIE for Explorer).

The IDLEDISCONNECTSECONDS specifies how long (in seconds) that LDapper will keep the connection to the server open after doing the last search. If you are doing several searches, it is more efficient to use the same connection rather than open and close a new connection for each search. This setting will avoid accidentally leaving connections open for extended periods of time. The default is 120 seconds (2 minutes).

LDapper will save the current search window size and position as well as the location of the "splitter" between the address list and info field. If you want to use something different than the default, e.g., because you have a larger monitor, set the window how you want it and copy the LDAPWINDOWBOUNDS and LDAPWINDOWSPLIT preferences to the internal prefs. (Do not modify the WIND or PPob resources.) Of course, this won't be useful unless the CANSAVEPREFS value is F.

LDapper no longer requests all available attributes for the Info field but instead uses a specific list stored internally in STR# resource 5000. The default attributes are:

cn mobile
ou multiLineDescription
mail nameSuffix
sn notice
affiliationCode o
businessCategory objectClass
c onVacation
classification organizationalStatus
classStanding otherMailbox
departmentName pager
departmentNumber personalTitle
description physicalDeliveryOfficeName
destinationIndicator pid
drink postalAddress
employeeNumber postalCode
employeeType postOfficeBox
facsimileTelephoneNumber preferredDeliveryMethod
givenname registeredAddress
homePhone roomNumber
homePostalAddress secretary
initials seeAlso
internationalISDNNumber st
jobTitle streetAddress
krbName telephoneNumber
l title
labeledURI uid
labeledURL universityID
mailPreferenceOption userClass
manager userPassword
memberOfGroup vacationMessage

These cannot be modified within LDapper, so if you want to include additional attributes, or possibly want a reduced list, you can use ResEdit to modify this resource. A better solution would be to create a resource file with the same name as your directory (replace any ':' characters with '-') and give it a creator 'LDpr' and file type 'Dire'. Add a STR# 5000 resource with the attributes you want to use and store the file in your LDapper Plug-ins folder. The attributes file will have the same icon as a plug-in.

AppleScript Support

As of version 1.2, LDapper has some basic AppleScript support. See LDapper's dictionary for the gory details and if you have any problems with it, let me know.

A few notes on AppleScript:

* The "search", "mailto", "disconnect", and "update info" terms are specific to a window. If you tell the application to search, you'll get a "did not understand" error. Instead, use the window as the command's direct object or just tell the window to do it:

search window 1

or

if (count of window) = 0 then make new window
set search name of window 1 to "Smith"
tell window 1 search
set theAddress to address 1 of window 1

or

set theWindow to window 1
tell theWindow
set search name to "Smith"
search
update info index 1
set theAddress to address 1
end tell

* If you get an address, e.g., set theAddress to address 1 of window 1, you'll get a record that contains the full info (if available) as a list of attribute value pairs and not the text. To get the text, get the "full info text" property explicitly, e.g., set theText to full info text of theAddress.

* To get a list of all addresses, use "get every address of window 1".

* LDapper is not meant to be a general purpose LDAP client, but rather a way to get e-mail addresses. But remember that if you set the search name to a string that begins with "(", LDapper will use that as a search filter. It was stated above that LDapper always does a subtree search but in fact you can change the search scope with AppleScript to "base", "one level" and "subtree". You can also change the search base to something other than the default search base for the directory. (Both of these are properties of the window.)

* You cannot get or access an address while a search is in progress, even if the address has already been received from the server. Some other commands are disabled as well. Instead, wait until the search is done by checking the "search in progress" property:

tell window 1
do search
repeat while search in progress
-- do nothing
end repeat
set theEmail to email address of address 1
end tell

* Preferences are considered properties of the application and window objects and changing the properties via AppleScript will change the prefs as stored in the preferences file.

* If you export addresses while AppleScript recording, you will get both a "using plugin name" and "using plugin type". You should then edit the script to use one or the other but not both.

Release Notes:

The release notes have been moved to a separate document because when they are included here, the file is too large to open with SimpleText.

Contact Info:

If you have any questions, comments, (constructive) criticism, or bug reports, you can contact me at the address(es) below.

-cb

Carl_Bell@baylor.edu
Carl Bell's Web Page <http://www.baylor.edu/~Carl_Bell/>
Stuff I've Written <http://www.baylor.edu/~Carl_Bell/stuff.html>

Snail Mail:

Carl W. Bell
Information Technology Center
Baylor University
P.O. Box 97268
Waco, TX 76798-7268

Phone:

(254) 710-4065

The Fine Print

Baylor's Fine Print:

This software, data and/or documentation contain trade secrets and confidential information which are proprietary to Baylor University. Their use or disclosure in whole or in part without the express written permission of Baylor University is prohibited.

This software, data and/or documentation are also unpublished works protected under the copyright laws of the United States of America. If these works become published, the following notice shall apply:

Copyright © 1997-1999 Baylor University
All Rights Reserved

The name of Baylor University may not be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE, DATA AND/OR DOCUMENTATION ARE PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

When permission has been granted to make copies of this software, data and/or documentation, the above notices must be retained on all copies.

Permission is hereby granted for non-commercial use and distribution of LDapper.

UMich LDAP SDK's Fine Print

Copyright (c) 1990 Regents of the University of Michigan.
All rights reserved.

Redistribution and use in source and binary forms are permitted provided that this notice is preserved and that due credit is given to the University of Michigan at Ann Arbor. The name of the University may not be used to endorse or promote products derived from this software without specific prior written permission. This software is provided ``as is'' without express or implied warranty.

3Com's Fine Print

Copyright © 1999 3Com Corporation. All rights reserved. 3Com is a registered trademark of 3Com Corporation or its subsidiaries. Palm is a trademark of 3Com Corporation or its subsidiaries. All other company and product names may be trademarks of their respective companies with which they are associated.


Original file name: LDapper - Read Me - converted on Sunday, 19 September 1999, 00:32

This page was created using TextToHTML. TextToHTML is a free software for Macintosh and is (c) 1995,1996 by Kris Coppieters