git.sur5r.net Git - openldap/blob - libraries/msdos/winsock/winkit/readme.txt

   1
   2 LDAP (Lightweight Directory Access Protocol) API for Windows/Winsock
   3
   4 The lber and ldap client libraries have been ported to Microsoft Windows
   5 in the form of Windows Dynamic Link libraries called LIBLDAP.DLL (16Bit)
   6 and Ldap32.dll (32Bit).  The LTest program is also provided in both
   7 formats.
   8
   9 A Windows Sockets API (version 1.1 conformant) TCP/IP WINSOCK.DLL or
  10 WSOCK32.DLL is required for the DLL to run.
  11
  12 Our intent is that this "kit" include everything you'll need to make use
  13 of the ldap client API from your 16Bit or 32Bit application.  If you
  14 find something missing or have a suggestion for improvement, send email
  15 to the "bug reporting" address at the bottom of this file.
  16
  17 To use this "kit"
  18
  19     1) Get to a DOS prompt
  20
  21     2) Create the directory you want this to live in (e.g.  \ldap)
  22        and cd into it.  We will refer to that directory simply as
  23        "\ldap" from now on, but it could be anywhere and have any name
  24        you desire.
  25
  26     3) Use "pkunzip -d" to extract the files.  The "-d" is NECESSARY to
  27        preserve the subdirectories and avoid file name collisions.
  28
  29     4) We have included only the files you need to use and test
  30        libldap.dll and ldap32.dll.  If you want the entire distribution,
  31        with source, you can get it from:
  32
  33            ftp://terminator.rs.itd.umich.edu/ldap/ldap-3.3.tar.Z
  34
  35 The following files are included in this distribution:
  36
  37     16Bit binaries and libs
  38         BINARIES/DEBUG/LIBLDAP.DLL
  39         BINARIES/DEBUG/LIBLDAP.LIB
  40         BINARIES/RELEASE/LIBLDAP.DLL
  41         BINARIES/RELEASE/LIBLDAP.LIB
  42
  43         BINARIES/DEBUG/LTEST.EXE
  44
  45     32Bit binaries and libs
  46         BINARIES/DEBUG/LDAP32.DLL
  47         BINARIES/DEBUG/LDAP32.LIB
  48         BINARIES/RELEASE/LDAP32.DLL
  49         BINARIES/RELEASE/LDAP32.LIB
  50
  51         BINARIES/DEBUG/LTEST32.EXE
  52
  53     Include files
  54         INCKIT/MSDOS.H
  55         INCKIT/LBER.H
  56         INCKIT/LDAP.H
  57         INCKIT/PROTO-LD.H
  58         INCKIT/PROTO-LB.H
  59         INCKIT/SRCHPREF.H
  60         INCKIT/DISPTMPL.H
  61
  62     Sample Configuration files
  63         SRCHPREF.CFG
  64         DISPTMPL.CFG
  65         LDFRIEND.CFG
  66         LDFILTER.CFG
  67
  68     Man pages in the form of Windows HLP files
  69         LIBLDAP.HLP     - old format hlp file
  70         LDAP32.HLP      - new format hlp file, both have same content
  71
  72 16Bit versions
  73
  74     Libldap.dll was compiled with KERBEROS, AUTHMAN, WSHELPER, WIN32,
  75     _WINDOWS,& LDAP_REFERRALS defined.  Even if you do not need kerberos
  76     authentication, (see below for more information on kerberos) this
  77     dll should work correctly for you.
  78
  79     LDAP_REFERRALS makes libldap.dll capable of handling referrals
  80     returned by a slapd server.
  81
  82 32Bit versions
  83
  84     The 32Bit version is NOT SAFE for MULTIPLE THREADS at this time.
  85     Not more than one thread per application may make use of the
  86     ldap routines.
  87
  88     Ldap32.dll was compiled with LDAP_REFERRALS defined and is capable
  89     of handling referrals returned by a slapd server.
  90
  91
  92 WRITING APPLICATIONS THAT USE LIBLDAP.DLL or LDAP32.DLL
  93
  94     All of the normal LDAP and LBER calls documented in the help file
  95     should work, except for ldap_perror (this is not supported under
  96     Windows since you will want to use an application-defined dialog;
  97     you can use ldap_err2string to obtain an error string to display in
  98     a message box or dialog).
  99
 100     The man pages are included in this kit in the form of windows HLP files.
 101     The official source man pages are available via the web at:
 102
 103             http://www.umich.edu/ldap/doc/man/
 104
 105     Any memory that you obtain as the result of a call to an LIBLDAP.DLL
 106     routine should NOT be freed by calling the free() routine in your C
 107     library.  Instead, use the the new utility routine ldap_memfree or
 108     the appropriate ldap ...free routine.  This is so the malloc/calloc
 109     and free routines all come from the same library (the one in
 110     libldap) rather than using libldap's malloc/calloc and the calling
 111     program's free.  Microsoft's VC++ 4.0 compiler (in debug mode)
 112     FORCED me to be compulsive about this for the application I used to
 113     test.
 114
 115     To be friendly under Windows, you should use the asynchronous LDAP
 116     calls whenever possible.
 117
 118     One limitation of the current LIBLDAP.DLL is that each X.500 LDAP
 119     result message has to be smaller than 64K bytes.  Ldap32.dll does
 120     NOT have this limitation.
 121
 122     To compile the ldap dlls we define the following preprocessor variables.
 123
 124         WINSOCK, DOS, NEEDPROTOS, NO_USERINTERFACE, KERBEROS
 125
 126     Presumably you don't need KERBEROS.  You may need some/all the others
 127     to take the right path through the include files.  Also note that a
 128     few more preprocessor variables are defined in msdos.h.  This means that
 129     msdos.h must be included before ldap.h or lber.h.
 130
 131
 132 LTest and LTtest32
 133
 134     The LTest.exe and LTest32.exe programs are test interfaces to libldap
 135     and ldap32 respectively.  By default they connect to the host
 136     "truelies".  This host name is contained in a string resource in the
 137     exe file.  You may easily "customize" this to be the name of whatever
 138     server you're using with AppStudio or any Windows resource editor.
 139
 140 Kerberos Information
 141
 142     Libldap.dll was compiled with KERBEROS, AUTHMAN, WSHELPER, &
 143     LDAP_REFERRALS defined.  If you do not need kerberos authentication,
 144     this dll should still work correctly for you.  Libldap.dll
 145     dynamically loads and uses the dlls needed for kerberos
 146     authentication (Authlib.dll, Krbv4win.dll, & WSHelper.dll).  If
 147     Libldap.dll is unable to load the needed dlls, execution continues
 148     without error, but without kerberos authentication capability.
 149
 150     AUTHMAN allows libldap.dll to make use of Authlib.dll (which
 151     requires KrbV4Win.dll & WSHelper.dll) if they are ALL in the "PATH".
 152     If these are not available, kerberos authentication can not succede,
 153     but libldap.dll will execute without error.
 154
 155     WSHELPER means that if WSHelper.dll is in the "PATH", it will be
 156     dynamically loaded and used to do the gethostbyaddr() call required
 157     for kerberos authentication to work.  (This is used because so many
 158     vendor implementations of gethostbyaddr return WRONG results.  We
 159     are working with all vendors we can get to listen to get these
 160     implementations fixed.)  If WSHelper.dll is not in the "PATH"
 161     libldap.dll does not fail to execute correctly.
 162
 163     Ldap32.dll does NOT have the ability to do kerberos authentication
 164     because none of Authlib.dll, krbv4win.dll or wshelper.dll have been
 165     ported to 32Bits at this time.
 166
 167     For further information on using kerberos with the ldap DLLs send
 168     email to ldap-support@umich.edu.
 169
 170 BUG REPORTING
 171
 172     Bug reports should be sent to bug-ldap@umich.edu.
 173
 174
 175 Miscellaneous
 176
 177     Build testing was done on Windows NT workstation 3.51 (build 1057
 178     service pack 2) on an NTFS file system (which supports long
 179     filenames) using Microsoft Visual C++ 1.52c (16 bit) and Visual C++
 180     4.0 (32 bit).
 181
 182 README Last updated 11 January 1996 by Steve Rothwell