view release on metacpan or  search on metacpan

zlib/win32/DLL_FAQ.txt  view on Meta::CPAN

  - Although exporting symbols by ordinal is a little faster, it
    is risky.  Any single glitch in the maintenance or use of the
    DEF file that contains the ordinals can result in incompatible
    builds and frustrating crashes.  Simply put, the benefits of
    exporting symbols by ordinal do not justify the risks.

    Technically, it should be possible to maintain ordinals in
    the DEF file, and still export the symbols by name.  Ordinals
    exist in every DLL, and even if the dynamic linking performed
    at the DLL startup is searching for names, ordinals serve as
    hints, for a faster name lookup.  However, if the DEF file
    contains ordinals, the Microsoft linker automatically builds
    an implib that will cause the executables linked to it to use
    those ordinals, and not the names.  It is interesting to
    notice that the GNU linker for Win32 does not suffer from this
    problem.

    It is possible to avoid the DEF file if the exported symbols
    are accompanied by a "__declspec(dllexport)" attribute in the
    source files.  You can do this in zlib by predefining the
    ZLIB_DLL macro.


 6. I see that the ZLIB1.DLL functions use the "C" (CDECL) calling
    convention.  Why not use the STDCALL convention?
    STDCALL is the standard convention in Win32, and I need it in
    my Visual Basic project!

    (For readability, we use CDECL to refer to the convention
     triggered by the "__cdecl" keyword, STDCALL to refer to
     the convention triggered by "__stdcall", and FASTCALL to
     refer to the convention triggered by "__fastcall".)

  - Most of the native Windows API functions (without varargs) use
    indeed the WINAPI convention (which translates to STDCALL in
    Win32), but the standard C functions use CDECL.  If a user
    application is intrinsically tied to the Windows API (e.g.
    it calls native Windows API functions such as CreateFile()),
    sometimes it makes sense to decorate its own functions with
    WINAPI.  But if ANSI C or POSIX portability is a goal (e.g.
    it calls standard C functions such as fopen()), it is not a
    sound decision to request the inclusion of <windows.h>, or to
    use non-ANSI constructs, for the sole purpose to make the user
    functions STDCALL-able.

    The functionality offered by zlib is not in the category of
    "Windows functionality", but is more like "C functionality".

    Technically, STDCALL is not bad; in fact, it is slightly
    faster than CDECL, and it works with variable-argument
    functions, just like CDECL.  It is unfortunate that, in spite
    of using STDCALL in the Windows API, it is not the default
    convention used by the C compilers that run under Windows.
    The roots of the problem reside deep inside the unsafety of
    the K&R-style function prototypes, where the argument types
    are not specified; but that is another story for another day.

    The remaining fact is that CDECL is the default convention.
    Even if an explicit convention is hard-coded into the function
    prototypes inside C headers, problems may appear.  The
    necessity to expose the convention in users' callbacks is one
    of these problems.

    The calling convention issues are also important when using
    zlib in other programming languages.  Some of them, like Ada
    (GNAT) and Fortran (GNU G77), have C bindings implemented
    initially on Unix, and relying on the C calling convention.
    On the other hand, the pre- .NET versions of Microsoft Visual
    Basic require STDCALL, while Borland Delphi prefers, although
    it does not require, FASTCALL.

    In fairness to all possible uses of zlib outside the C
    programming language, we choose the default "C" convention.
    Anyone interested in different bindings or conventions is
    encouraged to maintain specialized projects.  The "contrib/"
    directory from the zlib distribution already holds a couple
    of foreign bindings, such as Ada, C++, and Delphi.


 7. I need a DLL for my Visual Basic project.  What can I do?

  - Define the ZLIB_WINAPI macro before including "zlib.h", when
    building both the DLL and the user application (except that
    you don't need to define anything when using the DLL in Visual
    Basic).  The ZLIB_WINAPI macro will switch on the WINAPI
    (STDCALL) convention.  The name of this DLL must be different
    than the official ZLIB1.DLL.

    Gilles Vollant has contributed a build named ZLIBWAPI.DLL,
    with the ZLIB_WINAPI macro turned on, and with the minizip
    functionality built in.  For more information, please read
    the notes inside "contrib/vstudio/readme.txt", found in the
    zlib distribution.


 8. I need to use zlib in my Microsoft .NET project.  What can I
    do?

  - Henrik Ravn has contributed a .NET wrapper around zlib.  Look
    into contrib/dotzlib/, inside the zlib distribution.


 9. If my application uses ZLIB1.DLL, should I link it to
    MSVCRT.DLL?  Why?

  - It is not required, but it is recommended to link your
    application to MSVCRT.DLL, if it uses ZLIB1.DLL.

    The executables (.EXE, .DLL, etc.) that are involved in the
    same process and are using the C run-time library (i.e. they
    are calling standard C functions), must link to the same
    library.  There are several libraries in the Win32 system:
    CRTDLL.DLL, MSVCRT.DLL, the static C libraries, etc.
    Since ZLIB1.DLL is linked to MSVCRT.DLL, the executables that
    depend on it should also be linked to MSVCRT.DLL.


10. Why are you saying that ZLIB1.DLL and my application should
    be linked to the same C run-time (CRT) library?  I linked my
    application and my DLLs to different C libraries (e.g. my
    application to a static library, and my DLLs to MSVCRT.DLL),