Control Initialization

When you begin developing your application using one of the SocketTools controls, the first thing that must happen is the control must be initialized. In some development environments, such as Visual Basic, this is done automatically when the control is inserted into a form. In other languages, this must be done explicitly by calling the Initialize method for each instance of the control.

The initialization method serves two purposes. It loads the Windows networking libraries required to establish a connection and it validates the runtime license key that you provide. The runtime license key is a string of characters which identifies your license to use and redistribute the SocketTools controls. It is unique to your product serial number and must be used when redistributing your application to an end-user. Many languages will handle the licensing issue transparently, however some languages may require that you explicitly provide your runtime licensing key.

Developers who are evaluating SocketTools will not have a runtime license key and must pass an empty string to the Initialize method. This will enable the control to load on the development system during the evaluation period, but will prevent the control from being redistributed to an end-user until a license has been purchased.

If you install the product with a serial number, the runtime license key will be automatically created for you during the installation process. If you have installed an evaluation copy of SocketTools and then purchased a license, the license key can be created using the License Manager utility that was included with SocketTools. Simply select the License | Header File menu option and select the programming language that you are using. If your language is not listed, select Text File, which will create a simple text file with your license key.

The runtime license key is normally stored in the Include folder where you installed SocketTools and is defined in a file named "csrtkey10" which can be included with your application. For example, C/C++ programmers would use the csrtkey10.h header file while Visual Basic programmers would use the csrtkey10.bas module. The Visual Basic module would define the runtime license key as:

'
' SocketTools 10.0
' Copyright 2023 Catalyst Development Corporation
' All rights reserved
' 
' This file is licensed to you pursuant to the terms of the
' product license agreement included with the original software
' and is protected by copyright law and international treaties.

'
Public Const CSTOOLS10_LICENSE_KEY As String = ""

This could either be included with your Visual Basic application or you could simply copy the string into your application. The control could then be initialized like this:

'
' Initialize the control using the specified runtime
' license key; if the key is not specified, the
' development license will be used
'
nError = ftpClient.Initialize(CSTOOLS10_LICENSE_KEY) 
If nError > 0 Then
    MsgBox "Unable to initialize SocketTools component"
    End
End If

If the Initialize method fails, it will return an error code value that indicates the reason for the failure. A return value of zero indicates that the control was initialized successfully.

An application is only required to call a control's initialization method once, but it must be called for each control that is used. If both the File Transfer Protocol and Hypertext Transfer Protocol controls were being used in the same application, it would be required to call the Initialize methods for each control at the beginning of the program.

It is safe to call the initialization method more than once, but for each time that it is called, you should call the Uninitialize method for that control before your program terminates. In other words, if you called Initialize at the beginning of your program, you should call Uninitialize before your program ends. The Uninitialize method performs any necessary housekeeping operations, such as returning memory allocated for the control back to the operating system. If there are any open connections at the time that the Uninitialize method is called, they will be aborted. After the control has been uninitialized, you must call the Initialize method again in order to use any of the control's other methods.