git.sur5r.net Git - openldap/blob - libraries/msdos/README.WSA

   1 LDAP MSWindows with WinSock API README
   2
   3 The lber and ldap client libraries have been ported to Microsoft Windows
   4 in the form of a Windows Dynamic Link library called LIBLDAP.DLL and
   5 Ldap32.dll (16 and 32 bit versions respectively).
   6
   7 A Windows Socket API version 1.1 conformant TCP/IP WINSOCK.DLL is
   8 required for the LIBLDAP.DLL to run.  Some patches have been
   9 incorporated that should make it possible to build the LIBLDAP.DLL under
  10 Borland C++ 3.1.  Brief instructions are included later in this file.
  11 (There are no changes to the Borland support in this release.)
  12
  13 This release also include 16 and 32 bit versions of the ltest (&
  14 ltest32) API test programs.  Instructions for building it are in the
  15 second half of this document.  None of the other clients included in the
  16 distribution have been tested under Windows.  The synchronous LDAP
  17 interface is also untested, although it does build okay.
  18
  19 At the very end of this document are some hints for writing applications
  20 that use the LIBLDAP.DLL.
  21
  22 We have also made a windows "kit" available at:
  23
  24    ftp://terminator.rs.itd.umich.edu/ldap/windows/winldap.zip
  25
  26 Our hope is that with this kit, you won't have to compile all this
  27 yourself (unless you want to).  The kit includes:
  28         16 and 32bit dlls
  29         debug and release builds
  30         the LTest utility program
  31         man pages in the form of HLP files (new and old formats)
  32         include files
  33         sample config files
  34
  35 MAKING THE DISTRIBUTION
  36
  37 Build testing was done on Windows NT workstation 3.51 (service patch 2)
  38 (on NTFS which supports long filenames) using Microsoft Visual C++ 1.52c
  39 (16 bit) and Visual C++ 4.0 (32 bit).
  40
  41 To build the LIBLDAP.DLL library under Microsoft Visual C++ 1.52c
  42 (16bit) or Visual C++ 4.0 (32bit):  (search forward in this file for
  43 "Borland" if you are using Borland C++)
  44
  45         1) Untar the ldap distribution somewhere on MSDOS.  You will
  46            need at least the include and libraries subdirectories.
  47            A version of tar that works under MSDOS is a big help for
  48            this step
  49
  50                 tar xf ldap.tar
  51
  52            This will create a directory called ldap or similar that
  53            contains the ldap source distribution.  We will refer to
  54            that directory simply as "\ldap" from now on, but it could
  55            be anywhere and have any name on your system
  56
  57            Note that a lot of empty include files are on this distribution.
  58            This is because some compilers are not smart enough to properly
  59            generate dependencies (i.e. they ignore #ifdefs) so the file needs
  60            to be present, even if not used.
  61
  62         2) cd to the LDAP directory (root of your LDAP area on MSDOS) and
  63            execute the setupwsa batch file.  This will copy a bunch of
  64            files from the ldap\libraries\msdos and
  65            ldap\libraries\msdos\winsock directories to the ldap\include
  66            and ldap\libraries\libldap directories:
  67                 cd \ldap
  68                 libraries\msdos\winsock\setupwsa.bat
  69            Note that a lot of empty include files are copied over... this
  70            is because some compilers are not smart enough to properly
  71            generate dependencies.
  72
  73         3) Create a WINSOCK.LIB import library from the WINSOCK.DEF file.
  74            You can also obtain a pre-built .LIB from ftp.microdyne.com in
  75            /pub/winsock/winsock-1.1/winsock.lib.  To build an import
  76            library using Microsoft's IMPLIB utility:
  77                 cd \ldap\libraries\libldap
  78                 implib winsock.lib winsock.def
  79
  80         4) Now fire up MS Windows and start the Visual C++ Workbench.  Open
  81            the project \ldap\libraries\libldap\libldap.mak or
  82            \ldap\libraries\libldap\ldap32.mak with the appropriate compiler.
  83
  84            Change the project "Include" directory to list the ldap
  85            include directory as well as the standard include directories
  86            (change by using the command found under the
  87            Options...Directories menu in the 16 bit compiler and
  88            Build/Settings in the 32bit compiler).
  89
  90            The preprocessor symbols I have defined are:
  91               WINSOCK, DOS, NEEDPROTOS, NO_USERINTERFACE, KERBEROS I ran
  92            into buffer length limitations when I tried to define more
  93            preprocessor symbols this way.  So all the rest are defined
  94            in msdos.h.  This makes the order of inclusion critical for
  95            msdos.h.
  96
  97
  98          Note: If you are using something other than Visual C++ you will
  99            need to create a makefile or other project file.  It should
 100            include all of the .c files in the liblber and libldap
 101            directories, plus the libraries\libldap\libldap.def (or
 102            libraries\libldap\ldap32.def) module definition file.  It
 103            will need to link in winsock.lib.  You should use the large
 104            memory model.
 105
 106         5) Select Build LIBLDAP.DLL (or Rebuild All) from the Project
 107            menu to build the DLL.  You will see many warnings,
 108            especially from the liblber code.  Our experience is that it
 109            is safe to ignore them.
 110
 111         6) If you want to change what symbols are defined (for example
 112            WSHELPER, or LDAP_DEBUG), change them in msdos.h and
 113            recompile.  LDAP_DEBUG now works in the windows environment.
 114            The comments in msdos.h explain what the various options are.
 115
 116 You should now have a functional LIBLDAP (or ldap32) dynamic link
 117 library.  If you wish to build a version of ltest for MSWindows to test
 118 it, follow these next steps.
 119
 120         1) Copy the libldap test.c and LIBLDAP.DLL import library files
 121            to the Windows ltest directory.  Under DOS:
 122               cd \ldap
 123               copy libraries\libldap\test.c libraries\msdos\winsock\ltest
 124               copy libraries\libldap\libldap.lib libraries\msdos\winsock\ltest
 125
 126         2) Open the project \ldap\libraries\msdos\winsock\ltest\ltest.mak
 127            (or ltest32.mdp) under the Microsoft Visual C++ Workbench.
 128            Change the project include directory to list the
 129            \ldap\include directory as well as the standard include
 130            directories.
 131
 132         3) Edit the string resource IDS_LDAP_HOST_NAME in ltest.rc (or
 133            ltest32.rc) and change the string "truelies" to the name of
 134            the LDAP server host you would like to test against.
 135
 136            Since this is a string resource, it may also be edited in the
 137            DLL with AppStudio.  So you can change it without having to
 138            recompile.
 139
 140         4) Build the project.  If you are not using Visual C++, you will
 141            need to create a makefile or other project file, and then
 142            build.  The project should include all of the .c files in
 143            the ldap\libraries\msdos\winsock\ltest directory and the
 144            ltest.def module definition file.  You will need to link in
 145            libldap.lib and winsock.lib (import libraries).
 146
 147 You should now have a functional ltest application.  It is ugly, but it
 148 is useful for testing purposes.  It doesn't try very hard to be a pretty
 149 MS Windows application.
 150
 151
 152 To build the LIBLDAP.DLL library under Borland C++ 3.1:
 153
 154         Note: No changes have been made wrt Borland compiler in this release.
 155
 156         1) Untar the ldap distribution somewhere on MSDOS.  You will
 157            need at least the include and libaries subdirectories.
 158            A version of tar that works under MSDOS is a big help for
 159            this step:
 160                 tar xf ldap.tar
 161
 162            This will create a directory called ldap or similar that
 163            contains the ldap source distribution.  We will refer to
 164            that directory simply as "\ldap" from now on, but it could
 165            be anywhere and have any name on your system
 166
 167         2) cd to the LDAP directory (root of your LDAP area on MSDOS) and
 168            execute the setupwsa batch file.  This will copy a bunch of
 169            files from the ldap\libraries\msdos and ldap\libraries\msdos\winsock
 170            directories to the ldap\include and ldap\libraries\libldap
 171            directories:
 172                 cd \ldap
 173                 libraries\msdos\winsock\setupwsa.bat
 174
 175         3) Start Borland C++ and create a new project here named
 176             libraries\libldap\libldap.prj and add all .c files in
 177             the libraries\liblber and libraries/libldap directories
 178             except open.c and test.c.  Also add libldap.def and
 179             the winsock.lib.
 180
 181         4) Configure the project:
 182             Set include directories to have ..\..\include in them
 183             Set these #defines: NO_USERINTERFACE;DOS;NEEDPROTOS;WIN31;BC31
 184             Switch case-sensitive link/exports off
 185             Include the runtime library statically, and 'none' of the others
 186
 187         5) Do Build All
 188
 189
 190 WRITING APPLICATIONS THAT USE LIBLDAP.DLL
 191
 192     All of the normal LDAP and LBER calls documented in the man pages
 193     (contained in the ldap\doc\man directory) should work, except for
 194     ldap_perror (this is not supported under Windows since you will
 195     want to use an application-defined dialog; you can use ldap_err2string
 196     to obtain an error string to display in a message box or dialog).
 197     The LIBLDAP.DEF file has a complete list of available routines.
 198
 199     Any memory that you obtain as the result of a call to an LIBLDAP.DLL
 200     routine should NOT be freed by calling the free() routine in your
 201     C library.  Instead, use the the new utility routine ldap_memfree.
 202     This is so the malloc/calloc and free routines all come from the same
 203     library (the one in libldap) rather than using libldap's malloc/calloc
 204     and the calling program's free.  The 32bit compiler (in debug mode)
 205     FORCED me to be compulsive about this for the application I used to test.
 206
 207     To be friendly under Windows, you should use the asynchronous LDAP
 208     calls whenever possible.
 209
 210     One limitation of the current LIBLDAP.DLL is that each X.500 LDAP
 211     result message has to be smaller than 64K bytes.  Ldap32.dll does
 212     NOT have this limitation.
 213
 214     To compile the dlls we define the following preprocessor variables.
 215
 216         WINSOCK, DOS, NEEDPROTOS, NO_USERINTERFACE, KERBEROS
 217
 218     Presumably you don't need KERBEROS.  You may need some/all the
 219     others to take the right path through the include files.  Also note
 220     that a few more preprocessor variables are defined in msdos.h.  This
 221     means that msdos.h must be included before ldap.h or lber.h.
 222
 223
 224 BUG REPORTING
 225
 226     Bug reports should be sent to bug-ldap@umich.edu.
 227
 228 README Last updated 13 January 1996 by Steve Rothwell