Computer Networks and Internets API Library Written by Michael H. Evangelista (michael@powerof.to) Please send bug reports to netbook@cs.purdue.edu. For the latest revision of this software please visit http://www.netbook.cs.purdue.edu. --------------------- What is the CNAI API? --------------------- The CNAI API is a library of functions that simplify the creation of application programs that use TCP by hiding many of the details. The CNAP API library includes routines to wait for TCP connections and connect to servers. It also includes utilities to convert hostnames to IP addresses and service names to port numbers. -------------------------------------------------- Where is the documentation for the CNAI API calls? -------------------------------------------------- The CNAI API is documented in chapter 3 of Computer Networks and Internets, 4th edition by Douglas E. Comer, Prentice-Hall, 2003. ------------------------------------------- On what platforms can the CNAI API be used? ------------------------------------------- The CNAI API has been tested under: * Linux 2.2.12-20/x86 * Solaris 5.6/SPARC * Solaris 5.6/x86 * Windows NT 4.0/x86 * Windows 2000 Professional. * WIndows XP The CNAI API should operate properly on other Win32 platforms (e.g., Windows 98, Windows ME). The Unix versions should be easily ported to any system supporting Berkeley Sockets and POSIX mutexes. --------------------------------------------------------------------- How do I compile the CNAI API library under Unix (Linux and Solaris)? --------------------------------------------------------------------- The compilation of the CNAI API library and included applications is the same under Solaris and Linux (see below for differences in the Makefile). Before using the enclosed Makefiles, ensure that the utilities 'ld' (linker) and 'gcc' (Gnu C Compiler) are in your path, or modify the Makefile so that the complete paths to these utilities are specified. * To build the CNAI API library (cnaiapi.o): 1) enter the appropriate compile directory (either compile_linux or compile_solaris). 2) issue the command 'make cnaiapi.o'. After compilation, the file cnaiapi.o will be in the compile directory. * To build the included applications: 1) enter the appropriate compile directory (either compile_linux or compile_solaris). 2) issue the command 'make apps' to build all the applications or 'make ' to build just one. Because the applications depend on cnaiapi.o it will be built if it has not already. After compilation the application programs will be in the compile directory. ---------------------------------------------------------------- What are the differences between the Solaris and Linux Makfiles? ---------------------------------------------------------------- * They include the preprocessor definition of SOLARIS and LINUX respectively. * The Solaris Makefile links applications with the libraries socket, nsl, and pthread. ---------------------------------------------------------- How do I use the CNAI API library to build my own programs under Solaris and Linux? ---------------------------------------------------------- To integrate the CNAI API library into your own programs you must: * have cnaiapi.o available (see 'How do I compile...?') * #include cnaiapi.h in each of your C program files that use CNAI API library calls. Ensure that your C compiler can find cnaiapi.h when you compile your C files. There are two ways to do this: 1) use the directive '#include ' and use the -I option to tell the compiler where to look for .h files 2) use the directive '#include "cnaiapi.h"' and place cnaiapi.h in the same directory as your C files * link cnaiapi.o into your program. Do this by including cnaiapi.o in the list of files you pass to your compiler. * link to the socket, nsl, and pthread libraries if using Solaris. Do this by including '-lsocket -lnsl -lpthread' in your compiler options. ---------------------------------------------------- How do I compile the CNAI API Library under Windows? ---------------------------------------------------- Two ways to compile the CNAI API library under Windows have been tested: * MinGW * Microsoft Visual C++ ----------------------------------------------- How do I compile the CNAI API code under MinGW? ----------------------------------------------- MinGW is a "minimal port of gcc (Gnu C Compiler) to Windows". You can obtain the MinGW code from http://www.mingw.org. Follow the directions for installation included with the MinGW distribution. Once you have installed MinGW, be sure to add the MinGW "bin" directory to your PATH. Simply run mingw32-make from the make-mingw directory to compile the library modules and the example programs. The executable programs files will be named with a ".exe" extension; for example, webserver.exe. These executable files can be run from the Windows command line; for example, "C:> webserver" ------------------------------------------------------------- How do I compile the CNAI API code unde Microsoft Visual C++? ------------------------------------------------------------- To compile the CNAI API library for Windows you must have Microsoft Visual C++ 6.0 or higher. * To build only the CNAI API library: 1) Open the Visual C++ workspace file, 'compile_win32\Computer Networks and Internets\Computer Networks and Internets.DSW'. 2) From the 'Build' menu choose 'Set Active Configuration...' 3) From the list choose 'API_Library - Win32 Release' and click 'OK'. 4) From the 'Build' menu choose 'Build cnaiapi.lib'. After compilation, the file 'cnaiapi.lib' will be in the folder 'compile_win32\Computer Networks and Internets\Api_Library\Release'. * To build the included applications: 1) Build 'cnaiapi.lib' as described above. 2) From the 'Build' menu choose 'Batch Build' 3) Check the applications that you want built and also 'API_Library - Win32 Release' if it has not already been built. 4) Click 'Build'. Visual C++ will build each application. When complete, the .exe file for each application will be in the directory 'compile_win32\Computer Networks and Internets\\Release'. * To run the included applications. 1) Open a DOS prompt window. Because the included applications require command line arguments, they cannot be run by double-clicking their icons. 2) Change to the the directory where the application exists as described in step 4 above. 3) Type the application's name followed by the arguments required by the application. ------------------------------------------------------------------------- How do I use the CNAI API library to build my own programs under Windows? ------------------------------------------------------------------------- * have cnaiapi.lib available (see 'How do I compile...?') * #include cnaiapi.h in each of your C program files that use CNAI API library calls. Ensure that Visual C++ can find cnaiapi.h and cnaiapi_win32.h when you compile your C files. There are two ways to do this: 1) Use the directive '#include ' and tell Visual C++ where to look for .h files. You can tell Visual C++ where to look for .h files by setting the 'Additional Include Directories' field in Project Menu->Project Settings->C/C++ Tab->Preprocessor Category. 2) Use the directive '#include "cnaiapi.h"' and place cnaiapi.h and cnaiapi_win32.h in the same directory as your C files. * link cnaiapi.o into your program. Do this by including 'cnaiapi.lib' in the list of 'Object/Library Modules' under Project Menu->Project Settings->Link Tab->General Category. You may tell Visual C++ where to find the file 'cnaiapi.o' by setting the Additional Library Path in the Input Category of the same settings window. * link to the WinSock 2 library. Do this by including 'ws2_32.lib' in the Object/Library Modules list described above. -------------------------------------------------------------- Do I need to explicitly call WSAStartup to initialize WinSock? -------------------------------------------------------------- No. The CNAI API library does this for you the first time you invoke one of its routines. --------------------------------------------------------- Is the CNAI API safe to use with multi-threaded programs? --------------------------------------------------------- Yes. The CNAI API has mutexes around all non-MT-safe calls (e.g., gethostbyname, getservbyname). To simplify the process of creating application programs that use TCP for beginners, all CNAI API library calls invoke cnaiapi_init first to ensure that the library has initialized. Doing so creates a race condition in multi-threaded programs in which multiple threads invoke routines from the CNAI API. If your program is multi-threaded you must explicitly call cnaiapi_init before spawning any threads to avoid this race condition. See api/cnaiapi_init.c for details.