This section will help you upgrade an application written using a previous version of SocketWrench. 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 guide so that you understand what changes were made and how those changes can be implemented in your software.

Supported Platforms

SocketWrench 6.0 is supported on Windows 2000, Windows XP, Windows Server 2003 and Windows Vista. There have been a significant number of internal changes in the core networking code used by the SocketWrench control and library 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. Using SocketWrench on an unsupported platform may require that the user install additional system components such as the Microsoft Layer for Unicode and the latest available version of Internet Explorer.

SocketWrench 6.0 has been specifically designed for full compatibility with the Windows Vista operating system. Developers who are redistributing applications which target Vista should upgrade to the version 6.0 ActiveX control and/or library to ensure compatibility with that platform. It is strongly recommended that you review the 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

The SocketWrench 6.0 ActiveX controls may be used with any programming language that supports the Component Object Model (COM) and ActiveX control interface. This includes languages such as Visual Basic 6.0, Visual FoxPro and PowerBuilder.

The SocketWrench 6.0 dynamic link library 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.

.NET Development

The SocketWrench 6.0 ActiveX controls and dynamic link library may be used with languages such as Visual Basic .NET, Visual C# and Delphi .NET. However, it is strongly recommended that you use the SocketWrench .NET Edition if you are creating applications that target the .NET Framework. This is particularly true in the case of the ActiveX control which imposes a significant amount of overhead due to how COM interop is implemented. A method call to the ActiveX control requires approximately five times the number of instructions than a method call to the SocketWrench .NET managed class requires.

Windows Vista Development

If you are developing on the Windows Vista platform, Microsoft only supports Visual Studio 2005. 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 2005, 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 Vista platform.

Upgrading From Version 4.0

If you are upgrading from SocketWrench 4.0 or 4.5 your applications will be source-compatible with version 6.0 and will not require changes to your existing code. The only requirement is to reference the new ActiveX controls. Note that the control file names have changed, as have their class IDs and interfaces. This means that the new controls are not binary compatible and are not drop-in replacements for the version 4.0 controls.

An application should not attempt to reference both the 4.0 and 6.0 versions of the control within an application. When upgrading to version 6.0, first remove all references to the 4.0 control, save the project and reload it. Then add the reference to the 6.0 control, ensuring that the same object name is used. If you are creating an instance of the control dynamically by specifying its ProgID, such as using the CreateObject function, then it is recommended that you specify the version number as part of the ID. In other words, to create an instance of the FTP control, use "SocketTools.SocketWrench.6" and not simply "SocketTools.SocketWrench". If the version number is omitted, the latest version of the control will always be loaded.

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 control's Initialize method. As with previous versions of SocketWrench, you can use the License Manager utility to generate a file which contains the runtime key you should use. The version 4.0 runtime key is not valid for the version 6.0 control and an error will be returned if an invalid runtime key is specified. Note that it is only necessary to generate a new runtime license key if you are creating an instance of the control dynamically through a reference or using a function like CreateObject.

Upgrading From Version 3.0

If you are upgrading from SocketWrench 3.6 or earlier versions, there are a number of common changes that were made throughout the interface for the ActiveX controls and dynamic link library. These changes do apply to the SocketWrench 3.6 Freeware edition of the control, however they do not apply to version 4.0 or later of the SocketWrench control or library.

Error Codes

SocketWrench 3.6 and earlier versions generated error codes that were the Winsock error codes with a value of 14000 added to them. SocketWrench 6.0 uses the Winsock error codes directly. Existing applications that refer to error codes by constant name will only need to be re-compiled. When possible, references to numeric error codes should be changed to use the constants. It is also recommended that the SocketWrench constants be used instead of the Windows constants. Although the values are the same, use of SocketWrench constants should make the code easier to maintain, and eliminates the need to include definitions of the constants in your projects.

The error constants for SocketWrench have been expanded beyond those strictly related to the Windows Sockets API and a uniform naming convention has been implemented. The SocketWrench errors that correspond to Windows Sockets errors have the same numeric value and can be used interchangeably.

ActiveX Interface Changes

The following table lists the properties, methods and events which have been added, modified and removed. In many cases, changes to an existing method are the addition or one or more optional arguments. In some cases you may find that a reserved parameter has been added. If a method includes a reserved parameter the application should either omit the argument or pass a value of zero.

Conversion Notes

1. Because socket type and address family are now inferred from the Protocol proeprty, this property should be set to swProtocolTcp, swProtocolUdp or swProtocolRaw. These are the only values that are currently supported.
2. Documentation for previous versions of SocketWrench advised that non-zero values of BufferSize should be used if the Binary property was set to False. Setting the Binary property to False guaranteed that a single read would not read past the first encountered end-of-line. Since there was no guarantee that a single read would return up to an end-of-line, it was still incumbent upon an application to explicitly check for end-of-line, if that condition was important to the application logic. Consequently, it was decided to eliminate the Binary property altogether. In addition, the BufferSize property was also eliminated because all read and write buffers are managed internally by the library. To read and write lines of text on the socket, use the ReadLine and WriteLine methods.
3. The Peek and RecvNext properties were eliminated because it was judged that the functionality they provided could be provided at less risk by the applications that might desire it. That is, an application should remove data from the socket in all cases, and manage data that it might want to use later according to its own needs. To determine if data is available to be read, use the IsReadable property instead.
4. All events were renamed to make a clearer distinction between the methods and events, with each event prefixed with the word "On". For example, the Accept event in previous versions of the control has changed to OnAccept in the current version.
5. Event arguments are no longer passed by reference. With the exception of the Index argument, which are used only with control arrays, the event arguments are passed by value and typed as variants. Note that older versions of Delphi, such as Delphi 5.0, may throw an exception when an event is invoked with arguments. This is because Delphi has a defect where it assumes that all event arguments are passed by reference.

SocketWrench API Changes

The following table lists the functions have been added, modified and removed. In many cases, changes to an existing method are the addition or one or more optional arguments. In some cases you may find that a reserved parameter has been added. If a function uses a reserved parameter, the application either pass a value of zero or NULL as specified in the documentation.

ActiveX File Names

The file names of the ActiveX controls and their IDs have changed with the new version. The following table lists the new values which should be used in your application.

Library File Names

The file name for the SocketWrench library has changed with the new version. The following table lists the new name and import library which should be used.

Copyright © 2008 Catalyst Development Corporation. All rights reserved.