When you begin developing your application using one of the SocketTools libraries, the first thing that you must do is initialize the library. This is done by calling the Initialize function for that library in your application's main thread. For example, the File Transfer Protocol library has a function named FtpInitialize, the Hypertext Transfer Protocol library has a function named HttpInitialize and so on. The one exception to this is the File Encoding library, which does not require initialization.

The initialization function 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 libraries. It is unique to your product serial number and must be used when redistributing your application to an end-user.

Developers who are evaluating SocketTools will not have a runtime license key and must pass an empty string or a null pointer. This will enable the library to load on the development system during the evaluation period, but will prevent the library 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 "csrtkey6" which can be included with your application. For example, C/C++ programmers would use the csrtkey6.h header file while Visual Basic programmers would use the csrtkey6.bas module. The C++ header file would look something like this:

//
// SocketTools 6.0
// Copyright © 2008 Catalyst Development Corporation
// All rights reserved
// 
// This module contains the confidential and proprietary information
// of Catalyst Development Corporation and may not be redistributed.
// 
// 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.
// Unauthorized reproduction or distribution may result in severe
// criminal penalties.

#ifndef _INCLUDE_CSRTKEY6_H
#define _INCLUDE_CSRTKEY6_H

#ifndef UNICODE
#define CSTOOLS6_LICENSE_KEY ((LPCSTR)NULL)
#else
#define CSTOOLS6_LICENSE_KEY ((LPCWSTR)NULL)
#endif

#endif /* _INCLUDE_CSRTKEY6_H */

The macro CSTOOLS6_LICENSE_KEY specifies your runtime license key and this is what you would pass as the first argument to the initialization function. For example, here is how a C program would initialize the File Transfer Protocol library:

BOOL bInitialized;
bInitialized = FtpInitialize(CSTOOLS6_LICENSE_KEY, NULL);

if (!bInitialized)
{
    TCHAR szError[256];    
    DWORD dwError;
    dwError = FtpGetLastError();
    FtpGetErrorString(dwError, szError, 256);
    MessageBox(NULL, szError, NULL, MB_OK|MB_TASKMODAL);
    return;
}

Note that in this case, the key is defined as NULL, which means that a runtime license key has not been created yet. The FtpInitialize function would succeed when the program was executed on the development system where the evaluation copy of SocketTools was installed, but would fail on another system. When a license is purchased and the runtime license key is generated, the csrtkey6.h header file would be replaced with the actual key value. After re-compiling your program, you would be able to redistribute the application to other systems.

C++ programmers who are using the class wrappers are not required to explicitly initialize the libraries because this is done automatically in the class constructor. Review the cstools6.h file which defines all of the SocketTools classes to see how the constructor initializes the class.

For another example of how you can initialize the libraries, consider the Visual Basic module csrtkey6.bas which defines the runtime license key:

'
' SocketTools 6.0
' Copyright 2008 Catalyst Development Corporation
' All rights reserved
' 
' This module contains the confidential and proprietary information
' of Catalyst Development Corporation and may not be redistributed.
' 
' This file is licensed to you pursuant to the terms of the
' Catalyst license agreement included with the original software
' and is protected by copyright law and international treaties.
' Unauthorized reproduction or distribution may result in severe
' criminal penalties.
'
Public Const CSTOOLS6_LICENSE_KEY As String = ""

This is similar to the C/C++ header file and could either be included with your Visual Basic application or you could simply copy the string into your application. The equivalent to the C code listed above would look like this:

Dim bInitialized As Long
bInitialized = FtpInitialize(CSTOOLS6_LICENSE_KEY, 0)

If bInitialized = 0 Then
    Dim strError As String * 256
    Dim dwError As Long
    Dim nLength As Long
    dwError = FtpGetLastError()
    nLength = FtpGetErrorString(dwError, strError, 256)
    MsgBox Left(strError, nLength)
    Exit Sub
End If

In both examples, if the FtpInitialize function fails by returning a value of 0 (False), the program displays a message box to the user that explains the error and then exits.

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

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

Copyright © 2008 Catalyst Development Corporation. All rights reserved.