C/C++

Getting Started

There are just a few steps needed to use the ETH32 API from the C or C++ language. First you must copy the eth32.h header file from the API distribution files into your project's source code directory (unless you have already copied the header into your system's or compiler's header directory). There is a slightly different header file for Windows and Linux, so be sure to copy the correct one. Then, simply include the file at the top of any code module that uses functions from the API, as follows:

       #include "eth32.h"
       

The only other special step is ensuring that your application is correctly linked with the ETH32 API library when your application is compiled. This varies depending on the compiler and the platform which you are using.

Microsoft Visual Studio C/C++ (Unmanaged)

These instructions apply to MS Visual Studio 4-6 as well as Visual Studio .NET when compiling unmanaged C++ applications (project type of Win32 Project). The term unmanaged means that the code is not using the .NET framework and garbage collection system. If you are using managed C++.NET, please see the instructions in the section for .NET languages.

In order for your application to link successfully, the compiler must be instructed to link with the eth32api.lib file. The purpose of the eth32api.lib file is to inform the compiler and linker of which functions are included in the eth32api.dll file. After your program is built (compiled and linked), your resulting application is not dependent on the eth32api.lib file, only on the eth32api.dll file.

For Visual Studio 4-6:

For Visual Studio .NET Unmanaged (Win32) Projects:

Borland C/C++ Compilers

Borland C/C++ compilers also must have a .lib file in order to link successfully. However, the eth32api.lib file is in Microsoft (COFF) format and must be converted to the Borland format (OMF). A file is included in the API distribution that has already been converted to the OMF format and is named beth32api.lib

For your reference, the eth32api.lib file was converted to the beth32api.lib file with Borland's COFF2OMF utility using the command:

        COFF2OMF -lib:ca eth32api.lib beth32api.lib
        

GNU C/C++ Compiler (GCC) on Linux

In order for your application to link successfully, the compiler must be instructed to link with the libeth32 library. Both shared and static versions of the library are provided in the distribution. We recommend using the shared library because it allows your applications to benefit from future updates of the library without recompiling each application. Note that before using the shared library, it must be installed in one of the system library directories (typically /usr/lib). This is already done if you have successfully run the Linux installation script.

Because the ETH32 API is multithreaded, you must compile your applications with the -pthread compiler flag. This is always necessary, even if your application doesn't directly create its own threads. Note that if you forget to include this flag, your application may work, but will exhibit strange behavior or crash in certain situations. If you ever notice this happening, please double check that you included the -pthread flag.

The compiler command for using the shared library will be similar to:

        gcc -pthread myfile.c -leth32
        

When using the static library, copy the libeth32.a file into your source code directory and use a compiler command similar to:

        gcc -pthread myfile.c libeth32.a
        

The shared library may also be used with the dlopen() and related functions, although most people will have no need to do so. If you do, though, please observe these points: