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.

Developer's Guide

SocketTools 6.0 includes a new Developer's Guide that we recommend all developers review. It covers a variety of general programming topics, such as application design, event handling and secure connections. There's also a section with information that is specific to a number of programming languages besides C++, such as C# and Visual Basic.

Supported Platforms

SocketTools 6.0 is supported on Windows 2000, Windows XP, Windows Server 2003, Windows Vista 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 3.51 and Windows NT 4.0 are no longer supported by Microsoft and are not compatible with SocketTools.

Windows Vista

The SocketTools 6.0 Library Edition has been specifically designed for full compatibility with the Windows Vista 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 Vista 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 6.0 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 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 platform or later versions of Windows, Microsoft only supports Visual Studio 2005 and Visual Studio 2008. 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 Visual Studio 2008, Microsoft recommends that you continue to develop on the Windows XP or Windows 2000 platform. Applications built on those platforms 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 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 4.0 and 5.0, the function prototypes and C++ class definitions were in separate include files. With SocketTools 6.0, all of the library constants, functions and C++ classes are in a single header file named cstools6.h. The error codes are defined in a separate header file named cserror6.h, which is automatically included by cstools6.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 cstools6.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 cstools6.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 cstools6.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 4.0 or 5.0

If you are upgrading from SocketTools 4.0 or 5.0 most applications will be source-compatible with version 6.0 and will not require 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 4.0 or 5.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.

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

• The name of the primary header file is cstools6.h and there is no longer a separate header file for function prototypes, constants and C++ class definitions. The cserror6.h header file defines the error code values, and csrtkey6.h defines the runtime license key for this version of SocketTools.
• SocketTools requires Windows 2000 or later and uses the Windows Sockets 2.2 API. When using C or C++, the cstools6.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.
• Support for SFTP has been integrated into the FTP library and is available to developers who have a Secure Edition license. In most cases, all the application needs to do is connect on port 22 to establish an SFTP connection.
• The FtpAsyncConnect and FtpConnect functions have had parameters added to them to specify the username and password. In most cases, it is no longer necessary to call the FtpLogin function to authenticate the client session.
• The InetAsyncListen and InetListen functions have been changed so that the local address is specified as a string in dot-notation rather than as an unsigned 32-bit integer.

Applications which continue to use the SocketTools 4.0 or 5.0 libraries can be installed side-by-side with the version 6.0 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 6.0, 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 4.0 or 5.0 runtime keys are not valid for the version 6.0 libraries and an error will be returned if an invalid runtime key is specified.

Upgrading From Version 3.0

If you are upgrading from SocketTools 3.0 or earlier, there are a number of common changes that were made throughout the libraries. This section will list those changes and how they impact existing applications.

Error Codes

The error codes have been completely re-implemented and they are now shared across all of the libraries rather than having different errors duplicated as they were in previous versions. The errors are now also much more detailed, so that instead of generic errors such as ERROR_HTTP_READ, which were a catch-all for a variety of conditions, functions will return specific errors like ST_ERROR_CONNECTION_RESET which indicate the exact reason for the failure. Another change with error reporting is that the error values themselves are now unsigned 32-bit integers and use the standard Windows error facility. This means that standard Windows functions like GetLastError, SetLastError and FormatMessage can be used with our error values, as well as the internal API functions we provide for error handling.

Connection Functions

Those libraries which have functions for establishing a connection, such as FtpConnect and HttpConnect, have been modified so that there are additional parameters that must be specified. In most cases they have an additional "options" parameter which can be used to specify connection options. In some cases there are reserved parameters which must always be specified as zero values. Using the extended version of a connection function, such as FtpConnectEx, is no longer necessary. A change to how you call the library's connection function is typically the most common modification that you will need to make to update your software. There are still the asynchronous variants, such as FtpAsyncConnect, which enable an application to create an asynchronous (non-blocking) connection to a server.

Data Exchange

A number of the functions in the previous versions of SocketTools enabled applications to easily store data in local files or the system clipboard. For example, if the MIME library was used to create an e-mail message, the application would need to save the message to a local, temporary file or copy it to the system clipboard in order to use the SMTP library to deliver the message. The disadvantages to this was that using a temporary file incurred additional overhead, and using the system clipboard would cause anything that the user previously placed there to be overwritten. In SocketTools 6.0, functions have been added and modified which permit the application to pass the address of a memory buffer directly between functions. Now, instead of using a temporary file or the clipboard, the application could copy the message into a buffer in memory and then pass the address of that buffer to the SMTP library for delivery. Although the ability to store and access data in files or the clipboard has been retained, it is recommended that developers update their applications to take advantage of the ability to use memory buffers instead. The functions which have been added or modified are: FtpGetData, FtpPutData, HttpGetData, HttpPostData, HttpPutData, MimeExportMessageEx, MimeImportMessageEx, NntpGetArticle, NntpPostArticle, PopGetMessage, SmtpAppendMessage and SmtpSendMessage.

Event Handling

Events are a mechanism used by the library to notify an application when a certain action takes place. For example, when an asynchronous network connection is established, a "connect" event is generated which notifies the program that the connection has been made. Events are used in both synchronous (blocking) and asynchronous (non-blocking) applications, however they are used in different ways. Asynchronous events are always related to some network event and each of the libraries share the same basic set of asynchronous event notifications which are similar to the events generated by the Windows Sockets API. Events are generated when a connection is made, when data arrives and can be read, when data can be written, and when the remote host closes its connection.

There are also events which are generated by the libraries when a timeout occurs, or when a blocking operation is canceled. In addition, there is a second group of events which are not network related and are designed to provide some status information back to the program. For example, the FTP_EVENT_COMMAND event is generated whenever a command sent to the server has been processed. And during the process of downloading or uploading a file, the FTP_EVENT_PROGRESS event will be periodically fired. This effectively gives control back to the program for a period of time during the transfer, and enables it to obtain information about the client status and present it to a user. For example, the FtpGetTransferStatus function could be called whenever the FTP_EVENT_PROGRESS event is generated; the information returned could then be used to update a progress bar so that the user knows how much of the transfer has completed.

There are several common functions which are used to manage event handling for a library. The DisableEvents function is used to disable event handling and return the client connection to a blocking state. The EnableEvents function is used to enable event notifications. The FreezeEvents function is used to suspend or resume event handling by the application, and the RegisterEvent function is used to register a function which is called whenever an event occurs. Refer to the documentation for more information about the specific functions for the library that you are using.

Security Functions

There are several new functions in the Secure Library Edition to handle certificates. Each of the connection functions, such as FtpConnect, now have a parameter which specifies a pointer to an SECURITYCREDENTIALS structure. This is a structure which is used to specify information about the client, such as the name of a certificate store and the common name for a certificate to use when establishing a secure connection. C/C++ programmers can populate this structure with the information needed, however other programming languages such as Visual Basic are not capable of easily creating this data structure. To address that issue, there are two new functions called CreateSecurityCredentials and DeleteSecurityCredentials, specific to each library. They can be used to create a pointer to the structure, which can be treated just like a 32-bit integer handle, and then delete the credentials when they are no longer needed. Note that that this only applies to secure connections, and only when credentials are needed; otherwise a NULL pointer (a value of zero) can be passed to the function when connecting to the server.

Thread Affinity

Normally, when a handle is created as the result of establishing a connection with a remote host, the library considers that handle to be owned by the current thread. If another thread attempts to use that handle, an error is returned indicating that it is not the owner. However, in some cases it is desirable to create "worker threads" which are used to perform some specific task in the background. In previous versions of SocketTools, it was required that the worker thread actually establish the connection; there was no means to pass a handle from one thread to another.

The networking libraries now include a new function called AttachThread, which allows a thread to become the owner of a client handle. Each library has its own version of the function, such as FtpAttachThread for the File Transfer Protocol Library. Using this function, the main UI thread can create a connection to an FTP server and then pass that handle to a worker thread to download or upload the file. When the file transfer is complete, the worker thread can then return the handle back to the UI thread, or it can simply close the connection to the server and terminate. In addition, certain functions can now be called from a thread that does not own the handle. These functions are noted in the documentation, but are typically related to obtaining status information about the client session. For example, the FtpGetStatus and FtpGetTransferStatus functions can be called to determine the current status of a file transfer that has been initiated in another thread.

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 © 2008 Catalyst Development Corporation. All rights reserved.