=======================================================================
                Net::LDAPapi Module v1.21 for PERL5
             Clayton Donley, <donley@cig.mcel.mot.com>
=======================================================================

COPYRIGHT
=========

   Copyright (c) 1997 Clayton Donley. All rights reserved.
   This program is free software; you can redistribute it and/or
   modify it under the same terms as Perl itself.


INTRODUCTION
============

   This PERL5 module was designed to interface with the LDAP API provided
by the Netscape LDAP SDK.  I have also gotten most of the functions to
work using the University of Michigan SDK.

   This is my first attempt at a Perl5 module.  It was initially done
so that I could take advantage of CGI and other libraries to make quick
Web based applications for manipulating an LDAP directory.  I later
expanded it to include most of the API calls.


REQUIREMENTS
============

   This package requries a C compiler, Perl5 (of course), and either the
University of Michigan or Netscape LDAP headers and library files.  The
Netscape version is recommended and is available from the following URL:

      http://developer.netscape.com/one/directory/downloads.html

   This PERL module was mostly tested under Solaris 2.5+ and PERL 5.003.  I
am interested in knowing any incompatabilities, as I'll probably be using
it on other platforms in the near future anyway.


INSTALLATION
============

   After extracting the archive, simply type the following:

      $ perl5 Makefile.PL
      $ make

   Edit the file test.pl to contain your LDAP server, BASEDN, and filter
string.  Next type:

      $ make test

   It should complete all of its tests with no problems.  To install the
module you will likely need to become root and type:

      # make install

   That's it.  You can now 'use Net::LDAPapi' and make LDAP calls within your
PERL5 scripts with ease.


EXAMPLES
========

   There exists three examples in the 'examples' directory.  I'll probably
include a full-featured LDAP Maintenance CGI at some point in the near
future.  The current examples are:

      o ldapwalk.pl - This script demonstrates the use of Asynchronous LDAP
         calls to return all the attributes and values for entries matching
         a filter specified on the command line.  Simply change the variables
         at the start of the file to match your environment.

      o testwrite.pl - This script demonstrates using synchronous Add, Modify,
         and Delete calls to manage an LDAP server.  You need update access
         to an LDAP server to run this example.  Once again, simply change
         the variables at the top of the file.

      o www-ldap.pl - This script uses both this module and the CGI.pm
         module available on the Internet.  It allows users to authenticate
         and modify their own information.  You can easily customize this
         program, or learn from it and write your own CGIs.  The BIND
         and WEB_AUTHENTICATE subroutines would be especially useful in
         incorporating LDAP authentication into your own CGI scripts, even
         if the script has nothing to do with LDAP otherwise.

   In addition, the test.pl program in the top level directory shows some
of the basic synchronous search functionality.


LDAP API SUPPORT
================

   The following is a list of LDAP API calls supported by this API.  You can
find more information on each one in the man page generated when you make
the module.

   Calls marked with (*) are only available using the Netscape SDK.

		ldap_abandon
		ldap_add
		ldap_add_s
		ldap_bind
		ldap_bind_s
		ldap_compare
		ldap_compare_s
		ldap_count_entries
		ldap_delete
		ldap_delete_s
		ldap_dn2ufn
		ldap_err2string
		ldap_explode_dn (*)
		ldap_explode_rdn (*)
		ldap_explode_dns (*)
		ldap_first_attribute
		ldap_first_entry
		ldap_get_dn
		ldap_getmsgid (*)
		ldap_get_lderrno (*)
		ldap_get_option (*)
		ldap_get_values
		ldap_init
		ldap_msgfree (*)
		ldap_modify
		ldap_modify_s
		ldap_modrdn2
		ldap_modrdn2_s
		ldap_next_attribute
		ldap_next_entry
		ldap_open
		ldap_perror
		ldap_result
		ldap_result2error
		ldap_search
		ldap_search_s
		ldap_search_st
		ldap_set_option (*)
		ldap_simple_bind
		ldap_simple_bind_s
		ldap_unbind

FEEDBACK
========

I'm looking for any feedback regarding this package or how you use this
package.  If you've got other good examples or such, please send them my
way and I'll include them.

BUGS
====

ldap_init doesn't seem to work with University of Michigan's API.  Always
returns unable to connect to server errors.  Use ldap_open instead for now.

Lots of compile warnings about 'const char *" definitions when compiling
under University of Michigan.  I'll clean this later, but it should work
for now.

Memory management is better than the original version, but may need some
more work.

Need to get test and compile with other LDAP SDK's.  You should be able to
get most of this to work, outside some of the options setting without any
modifications.

I really want to get Binary updates working, as I look forward to allowing
people to upload their JPEG images of themselves and etc...

--
Clayton Donley
Motorola (China) Electronics, Ltd.
Beijing, China
email: donley@cig.mcel.mot.com
