pjs/directory/c-sdk/ldap/examples

#
# ***** BEGIN LICENSE BLOCK *****
# Version: MPL 1.1/GPL 2.0/LGPL 2.1
# 
# The contents of this file are subject to the Mozilla Public License Version 
# 1.1 (the "License"); you may not use this file except in compliance with 
# the License. You may obtain a copy of the License at 
# http://www.mozilla.org/MPL/
# 
# Software distributed under the License is distributed on an "AS IS" basis,
# WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
# for the specific language governing rights and limitations under the
# License.
# 
# The Original Code is Mozilla Communicator client code.
# 
# The Initial Developer of the Original Code is
# Netscape Communications Corporation.
# Portions created by the Initial Developer are Copyright (C) 1998-1999
# the Initial Developer. All Rights Reserved.
# 
# Contributor(s):
# 
# Alternatively, the contents of this file may be used under the terms of
# either of the GNU General Public License Version 2 or later (the "GPL"),
# or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
# in which case the provisions of the GPL or the LGPL are applicable instead
# of those above. If you wish to allow use of your version of this file only
# under the terms of either the GPL or the LGPL, and not to allow others to
# use your version of this file under the terms of the MPL, indicate your
# decision by deleting the provisions above and replace them with the notice
# and other provisions required by the GPL or the LGPL. If you do not delete
# the provisions above, a recipient may use your version of this file under
# the terms of any one of the MPL, the GPL or the LGPL.
# 
# ***** END LICENSE BLOCK ***** 

                  Directory SDK Examples
                  ----------------------

This directory contains some sample LDAP code to help you understand
how to use the Directory SDK.  These examples are designed to work against
the sample data contained in the Netscape Directory Server 4.x
distribution.  If you want to run these samples, you will need to have
a working LDAP server running, and the sample "example.com" data
loaded.

-------------------
Synchronous samples
-------------------
These samples use the synchronous LDAP calls.  These calls are more
straightforward to use, and it's suggested you look at these examples
first.  These calls will block the calling process until all results
have been returned, so they are probably not appropriate for use in a
client with a graphical user interface which relies an an event loop.
However, they're fine for command-line clients and CGI programs.

search.c
--------
Shows how to use ldap_search_s() to search for all entries which have
an attribute value which exactly matches what you're searching for.  In
this example, all entries with the surname (last name) "Jensen" are
retrieved and displayed.

csearch.c
---------
Like search.c, but enables an in-memory cache.

ssnoauth.c
----------
Like search.c, but the search is done over SSL.

ssearch.c
---------
Like ssnoauth.c, but with certificate based authentication thrown in.

srvrsort.c
----------
Shows how to use server side sorting in conjunction with the
ldap_search_ext_s() function.

rdentry.c
---------
Shows how to use ldap_search_s() to retrieve a particular entry from the
directory.  In this example, the entry:
	uid=bjensen,ou=People,dc=example,dc=com
is retrieved and displayed.

getattrs.c
----------
Just like read.c, but retrieves specific attributes from an entry.

compare.c
---------
Show how to use ldap_compare_s(), which allows you to test if a particular
value is contained in an attribute of an entry.

modattrs.c
----------
Shows how to use ldap_modify_s() to replace and add to values in an attribute.

modrdn.c
--------
Shows how to use ldap_modrdn2_s() to change the relative distinguished name
(rdn) of an entry.

getfilt.c
---------
Shows how to use the ldap_getfilter family of routines, which help generate
LDAP filters based on an arbitrary search string provided by a user.

crtfilt.c
---------
Shows how to use the ldap_create_filter() function to generate LDAP filters.



---------------------
Asynchronous examples
---------------------
These examples use the asynchronous LDAP calls.  The general idea is that
you begin an operation, and then periodically poll to see if any results
have been returned.

asearch.c
---------
Initiates a search for entries, and polls for results, printing them as
they arrive.

nsprio.c
--------
Like asearch.c but using the prldap routines to incorporate NSPR.

add.c
------
Add an entry to the directory.

del.c
------
Delete an entry from the directory.

psearch.c
---------
Shows how to use the Persistent Search LDAPv3 protocol extension to
monitor a directory server for changes.

ppolicy.c
---------
Attempt to bind to the directory, and report back any password expiration
information received.  This demonstrates how clients can process password
policy information that is optionally returned by Netscape Directory Server
3.0 and later.



-------------------
Additional examples
-------------------
The Macintosh or Windows versions of the Directory SDK also include
sample project files.  A sample CodeWarrior project file is included
in the macintosh directory.  

Sample Visual C++ makefiles for a Windows application (winldap) are 
included in the windows directory. The Win32 version of the makefile
is named winldap.mak; the Win16 version of the makefile is named LDAP16.MAK.

If you want to fix up the additional examples and recontribute them back
to mozilla they will gladly be accepted :-)