ldap/readme.txt

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