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

Supported Platforms

SocketTools 5.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 SocketTools ActiveX controls 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 SocketTools 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.

Windows Vista

The SocketTools 5.0 Visual Edition 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 5.0 ActiveX controls 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 SocketTools 5.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. Although the ActiveX controls may be used with Visual Basic .NET and Visual C#, it is strongly 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, 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 SocketTools 4.0 or 4.5 your applications will be source-compatible with version 5.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 5.0 versions of a control within an application. When upgrading to version 5.0, first remove all references to the 4.0 control, save the project and reload it. Then add the reference to the 5.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.FtpClient.5" and not simply "SocketTools.FtpClient". 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 5.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 SocketTools, 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 5.0 controls 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 SocketTools 3.6 or earlier versions, there are a number of common changes that were made throughout the interface for the ActiveX controls.

Error Codes

Error codes in SocketTools 5.0 have been changed so that the same values applies to all of the controls. In previous versions, the LastError property would return one value if the FTP control encountered an error, and another value if the HTTP control encountered the same kind of error. Now, they return the same value and can be used interchangeably. If any control times out while trying to establish a connection, it will return the same error code, stErrorOperationTimeout. The number and types of errors have also been significantly expanded to identify specific error conditions. For example, in the previous version if the HTTP control encountered an error while reading data, it would return the generic error ERROR_HTTP_READ. This type of error would tell you what the control was doing when the error occurred, but it wouldn't give you any information as to what actually caused the error. Now, the reason for the failure is much more specific with errors such as stErrorConnectionReset, which tells you that the remote host has reset (aborted) the connection. To make displaying error messages easier, we have also added a LastErrorString property which will return a description of the last error that occurred. It should also be noted that the error codes related to networking correspond to the same Windows Sockets error. For example, the error stErrorOperationWouldBlock is 10035, which is the same was WSAEWOULDBLOCK. This eliminates the need for the SocketError property that was included in previous versions of the controls.

Connection Methods

Those controls which have a Connect method now have additional optional arguments which can be used instead of setting various properties in the control. Properties such as HostName and RemotePort now serve as default values for the Connect method, which means that if the Connect method is called without those arguments, the property value will be used as the default.

Data Exchange

A number of the methods in the previous versions of SocketTools enabled applications to easily store data in local files or the system clipboard. For example, if the MIME control 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 control 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 5.0, methods have been modified which permit the application to pass a string or byte array variable directly between functions. Now, instead of using a temporary file or the clipboard, the application could store the message into a variable, and then pass then pass that variable as an argument to another control's method. 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 these new methods.

Event Handling

In previous versions of SocketTools, the event names used in the control corresponded to the name of the method that was related to them. For example, there was a Read event and a Read method. While this didn't present a problem to Visual Basic, some other languages did have difficulties when the names were the same. To prevent this kind of name collision, we have renamed the events to be prefixed with "On", so that the Read event is now the OnRead event.

Security Functions

There are several new properties related to secure connections. The controls now support the use of client certificates by setting the CertificateStore property to the name of a certificate store on the local system and the CertificateName property to the name of the certificate to use when a secure connection is established. If your current version of SocketTools is 3.5 or earlier which did not support SSL/TLS, the Secure Visual Edition has support for both standard and secure connections, without requiring any third-party libraries or using the WinInet library.

Interface Changes

The following table lists the common 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.

Control 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.

Copyright © 2008 Catalyst Development Corporation. All rights reserved.