This section will help you upgrade an application written using a previous version of the SocketTools Library Edition. In most cases, the modifications required will be minimal and may only require a few edits and recompiling the program. However, it is recommended that you review this entire document so that you understand what changes were made and how those changes can be implemented in your software.

Supported Platforms

SocketTools 7.2 is supported on Windows XP, Windows Server 2003, Windows Vista, Windows 7 and Windows Server 2008. There have been a significant number of internal changes in the core networking code used by the SocketTools libraries which take advantage of features that are specific to those platforms. Earlier versions of the operating system, including Windows 95, Windows 98, Windows Me, Windows NT 4.0 and Windows 2000 are no longer supported by Microsoft and are not compatible with SocketTools.

Windows 7 and Windows Server 2008

The SocketTools 7.2 Library Edition has been specifically designed for full compatibility with the Windows 7 and Windows Server 2008 operating systems. Developers who are redistributing applications which target these platforms should upgrade to the current version of SocketTools to ensure compatibility. It is strongly recommended that you review the Windows 7 section of the Microsoft website and familiarize yourself with the changes in the operating system and specifically how the User Account Control (UAC) system works.

Development Tools

As standard Windows dynamic link libraries, the SocketTools 7.2 libraries may be used with virtually any programming language that can call exported functions in a DLL, either by name or by ordinal. Import libraries are provided for Visual C++ in both x86 and x64 COFF format, and for Borland's C++ compiler in OMF format. Other languages should use the convention appropriate for calling an exported function, such as the Declare statement in Visual Basic. Note that while the libraries may be used with the .NET languages, it is recommended that you use the SocketTools .NET Edition if you are creating applications for the .NET Framework.

If you are developing on the Windows Vista or Windows 7 platforms, Microsoft only supports Visual Studio 2005 and later versions. Earlier versions of Visual Studio are unsupported and may require that you use those development tools with elevated privileges. If you are using Visual Studio 6.0 or Visual Studio .NET 2003 and cannot upgrade to the current version of Visual Studio, Microsoft recommends that you continue to develop on the Windows XP platform. Applications built on Windows XP can be installed on Windows Vista, and Vista fully supports both the Visual Basic 6.0 runtime and .NET 1.1 Framework. It is recommended that you download the current service packs available for Visual Studio .NET 2003 and Visual Studio 2005 from Microsoft. Additionally, if you are using Visual Studio 2005 it is recommended that you download the current Windows SDK which targets the Windows Vista, Windows 7 and Windows Server 2008 platforms.

SocketTools Header Files

In earlier versions of SocketTools, there were a number of different header files which were included by cstools.h. For example, there were different header files for constants, function prototypes and so on. In SocketTools 5.0 and earlier versions, the function prototypes and C++ class definitions were in separate include files. With SocketTools 7.2, all of the library constants, functions and C++ classes are in a single header file named cstools7.h. The error codes are defined in a separate header file named cserror7.h, which is automatically included by cstools7.h. There are three special macros which C++ developers can use to control certain behavior:

CSTOOLS_NO_LIBRARIES

Visual C++ and Borland C++ supports a pragma which can be used to automatically specify the names of libraries that the compiler should attempt to link with in order to resolve function calls. By default, it is not necessary to explicitly specify the names of the SocketTools import libraries to link to. However, if you wish to explicitly link to specific import libraries, then define this macro prior to including the cstools7.h header files.

CSTOOLS_NO_NAMESPACE

When compiling a C++ application, the SocketTools functions are defined in a namespace called SocketTools. This prevents the possibility of conflicts with functions of the same name that may be used in other libraries. If you prefer the functions to be defined in the global namespace instead, then define this macro prior to including the cstools7.h header file.

CSTOOLS_NO_CLASSES

When compiling a C++ application, class wrappers for the SocketTools API are automatically included by default. Defining this macro prevents this, and only the API function prototypes will be declared. It is important to note that this only affects programs written using C++. The class wrappers will not be included for standard C programs, regardless if this macro is defined or not.

SocketTools C++ Class Wrappers

The C++ class wrappers for the SocketTools libraries have been moved from a separate file into the cstools7.h header file, and are now automatically included whenever a C++ program is compiled. The classes have been designed for compatibility with a variety of C++ compilers; however, there are certain features which are only available if the application is compiled using the Microsoft Foundation Classes (MFC). For example, if an application is built using MFC, each class is derived from CObject and there are additional overloaded methods implemented which support the use of objects like CString. If the application is built without using MFC, or a different C++ compiler is used, those methods will not be available.

Upgrading From Version 6.0

If you are upgrading from SocketTools 6.0 most applications will be source-compatible with version 7.1 and will not require significant changes to your existing code. The only requirement is to include the new header files and link to the new version of the import libraries. Note that the library file names have changed, as have the export function ordinals. This means that the new libraries are not binary compatible and are not drop-in replacements for the version 6.0 libraries. If you have declared functions by ordinal in your application (something that is not commonly done), those values have changed and must be updated. If you have declared the exported functions by name, you will be able to reference the new libraries using the same values.

For developers who are using the SocketWrench API or the Domain Name Service API, you may need to make some additional changes to your source code. Because SocketTools 7.2 supports both IPv4 and IPv6 network connections, some functions had to be modified to support the different types of addresses. In particular, those functions which used a 32-bit unsigned integer (DWORD) to store an IP address were changed to use an INTERNET_ADDRESS structure which can accommodate both types of addresses.

The following lists the changes that developers should be aware of when migrating from earlier versions:

• The name of the primary header file is cstools7.h and there is no longer a separate header file for function prototypes, constants and C++ class definitions. The cserror7.h header file defines the error code values, and csrtkey7.h defines the runtime license key for this version of SocketTools.
• SocketTools requires Windows XP or later and uses the Windows Sockets 2.2 API. When using C or C++, the cstools7.h header file should be included before windows.h to ensure that the compiler does not try to include the deprecated Windows Sockets 1.1 header file. Failure to do so can result in compiler warnings about duplicated macros and function prototypes.
• The name for each of the DLLs and import libraries has been changed with the new version. Applications written using previous versions of SocketTools must be updated to use the new file names.
• Some constant values have changed. This will not impact applications that used the defined macros, but may impact any application which uses hard-coded numeric values, rather than constants or macros.
• The InetGetAddress and InetFormatAddress functions have changed to use the new INTERNET_ADDRESS structure, as have several other related functions. If your application stores an IP address as a 32-bit integer value, you will need to modify that code. It is generally recommended that you store IP addresses in their string format, and you should allocate at least 40 characters for the string. That will be large enough to handle both IPv4 and IPv6 addresses.
• Most of the networking APIs have a new option to force the library to establish an IPv6 network connection. By default, the libraries will still give preference to using IPv4 by default, since it is still the dominant version of the protocol in use today. It is important to note, however, that if you force your application to use only an IPv6 connection, your program may not work on many end-user systems.

Applications which continue to use the SocketTools 6.0 libraries can be installed side-by-side with the version 7.1 libraries. It is recommended that you redistribute the libraries in the same folder as your application executable, rather than a shared system folder such as C:\Windows\System32. While it would be possible to use 6.0 libraries and earlier versions in the same application, they would have to be loaded dynamically because the function names used in the two versions are the same.

The runtime license key has also changed for Version 7.2, which will require you to define the new key in your application when calling the library's initialization function. As with previous versions of SocketTools, you can use the License Manager utility to generate a new header file which contains the runtime key you should use. The version 6.0 runtime key is not valid for the Version 7.2 libraries and an error will be returned if an invalid runtime key is specified.

Library File Names

The file names of the dynamic link libraries and import libraries have changed with the new version. The following table lists the new names.

Copyright © 2012 Catalyst Development Corporation. All rights reserved.