For example, in Visual Basic the code could look like this:

  SecureShell.HostName = "remote.server.net"
  SecureShell.UserName = "username"
  SecureShell.Password = "password"

  Dim strResult = SecureShell.Execute("/bin/ps -ef")
  If strResult.Length = 0 And SecureShell.LastError > 0 Then
      MessageBox.Show(SecureShell.LastErrorString)
      Exit Sub
  End If

  TextBox1.Text = strResult

In this example, the typical property values are set for the SSH server domain name or IP address, the user name and password required to authenticate the session. The Execute method is then called, providing the command to execute as a parameter, and the output from the command will be returned to a string value. In this case, we’re connecting to a UNIX based system and listing all of the running processes using the /bin/ps command.

If an error occurs, then the return value will be an empty string and the LastError property will be set to a value which identifies the error condition. In this case, we simply display a message box that shows a human-readable description of the last error code and then exit the subroutine.

As with an interactive terminal session, the entire operation is encrypted over the network, including the command that is sent and the output that it returns. For this reason, using SSH is preferred over the old rexec protocol which would send both the user credentials and the command as plain text. If you’re currently using the Remote Command class in your applications, it’s recommended that you consider rewriting your code to use the SSH component as a secure alternative.

Although the class makes developing server applications significantly easier, there are a few important things to keep in mind when using this class:

Although the code that you’ll write will look like typical single-threaded code that responds to events, it’s actually a multi-threaded application, with each client session isolated in its own thread. When network events are raised, they are being raised within the context of the thread that’s generated them. For example, this means that when the OnRead event fires, it’s not firing within the thread that created that instance of the InternetServer class (e.g.: the main UI thread). Any code that you have inside that event handler is executing in the context of the thread that’s managing that specific client session.

Because network events are being raised in the context of the client session threads, this means you cannot update user interface controls directly from within the event handlers. .NET does not allow one thread to modify a control that was created in another thread (usually the main UI thread). This is an absolute rule, and if you break it, your program is either going to hang or throw an exception. If you want to change any property values or call methods in a control, you need to create a delegate and marshal the call to the UI thread to using the Invoke method. Both the VB.NET and C# examples show how to do this; in the example, it’s used to update a ListBox control. Frequently updating the user interface from within an event handler can have a very negative impact on the overall performance of your program. Marshalling calls across threads to those UI controls is an expensive operation, and while you’re doing it, you’re not servicing network events like OnRead. You should keep it to a minimum, only updating the UI when absolutely necessary.

Another important consideration is that you should never modify shared objects without first synchronizing access to that object. In VB.NET it’s typically done using the SyncLock statement; in C# it’s done using the lock statement. The VB.NET and C# examples show to do this using a shared instance of a Hashtable class which is used to keep track of the number of bytes echoed by the server. While our lower-level API provides thread-safe queuing functions (InetServerEnqueue, InetServerDequeue, etc.) this doesn’t exist in the .NET class, largely because it would be redundant. If you want to use a queue, then you use the .NET Queue class, but the same rule applies; make sure that you synchronize access to the queue. While the InternetServer class does have Lock and Unlock methods, you should never use it for general purpose synchronization in your program. Calling the Lock method will cause every single client thread to block, and so while using Lock and Unlock would seem to be the easiest approach, it’s not a good idea for performance reasons.

The InternetServer class provides two general forms of many methods which are used to exchange data with the clients, ones which requires a handle to the client socket, and ones that do not. It’s not required that you specify a client handle if your code is inside an event handler (or in a function that’s being called by an event handler); the class knows which client raised the event and calls to Read and Write will work with that client (referred to as the “current client” in the documentation). However, if you want to exchange data with a client outside of an event handler, or with a client other than the current client, then you must specify a handle. Also, certain properties only return meaningful results from within an event handler. For example, the ClientAddress property (which returns the IP address of the client) should only be referenced from within an event handler such as OnConnect. The documentation notes when a property or method should only be used inside an event handler.

Finally, while it is possible to exchange data in an event handler with a client other than the one that generated the event, it’s not recommended. This is a case where you should use the Lock method to ensure that you’re the only thread that is attempting to read or write on that socket at the time. Two threads that attempt to read or write data on the same socket has undefined results; there’s no guarantee which thread would “get there first”, and the end result can be really unpredictable behavior by your program. One way to think about this is to think of your server program as a house, with each client connection being a room inside that house. You can do pretty much anything you want inside your own room (from within the event handler code that you write). However, if you want to go into another room and start rearranging the furniture, you need to make sure that every other thread is locked out while you do that. When you’re done and back in your own room, then you unlock the server and continue on.

The file verification is performed using one of several methods, depending on what features the server supports. There are three general options available when performing file verifications using FTP: an MD5 hash, a CRC-32 checksum or a file size comparison. If the server supports the XMD5 command, then this is used to generate an MD5 hash and compare it against the local file; if the hash value matches, then the contents of the file are identical. If the server doesn’t support this feature, a CRC-32 checksum can be generated in a similar fashion using the XCRC command to determine if the file contents are the same. If the FTP server doesn’t support either MD5 or CRC-32, then a simple file size comparison can be performed.

By default, SocketTools will give preference to the MD5 hash, falling back to a CRC-32 checksum. If neither feature is supported by the server, then it will compare file sizes. Naturally, a file size comparison is the least reliable, so developers can specify if they only wish to use the MD5 and/or CRC-32 methods to determine if the file contents match.

Using the storage API is very simple, with methods that create or open an existing storage file, store new messages, retrieve old messages and search for specific messages. For example, you can search the message store for all emails that have a certain subject or were sent by a particular individual. The API itself is independent of the various email protocol components, and can be interfaced with any of them to provide local storage capability for the email messages that you’re processing.

The SocketTools Library Edition includes the message store API as part of the MIME API, with new functions such as MimeOpenMessageStore and MimeFindStoredMessage. The SocketTools Visual Edition includes the new functionality as part of the current MailMessage control, while the SocketTools .NET Edition includes it as part of the SocketTools.MailMessage assembly.

Not all applications have the same needs when it comes to the resource and bandwidth utilization on the local system. In some cases, developers want the data transferred as quickly as possible, regardless of how much network bandwidth they consume. Other programs are designed to run in the background or as a service and need to use very little bandwidth and system resources.

One of the new features in SocketTools 5.0 is the ability to specify transfer priorities. This determines how system resources and network bandwidth should be allocated for the transfer. For the libraries, the transfer priority is set by calling the FtpSetPriority or HttpSetPriority functions. For the .NET classes and ActiveX controls, you can set the Priority property. There are five priority levels which control the transfer rate:

Normal Priority
This is the default priority, and is designed to provide a balance between the file transfer rate and the system resources allocated for the transfer. In most cases, this is the appropriate priority for an interactive user application. At this priority, the transfer won’t interfere with other applications running on the system, either in terms of CPU utilization or network bandwidth.

Background Priority
This priority specifies that the transfer is taking place in the background and should be given a very low priority. At this priority level the CPU utilization is minimal and very little network bandwidth is consumed. The trade-off is that the transfer will take much longer to complete. This priority should be used if low resource utilization is required, and the amount of time to complete the transfer is not important. This priority is not recommended for interactive applications where the user must wait for the transfer to complete.

Low Priority
This priority specifies that the transfer should use less memory and reduce the network bandwidth utilization. It is not as restrictive as a background priority transfer, and is generally recommended for applications that are performing multiple, simultaneous transfers. This will minimize the impact on other applications that are running on the system.

High Priority
This priority specifies that additional system resources should be allocated for the transfer, and there should be no limitations on network bandwidth utilization. High priority transfers typically require more memory, have increased CPU utilization and consume more network bandwidth. Interactive programs that require the transfer to complete quickly can use this priority to increase the overall transfer rate.

Critical Priority
This priority specifies that the transfer must complete as quickly as possible, without regard for system resource allocation or network bandwidth. With critical priority transfers, no events are generated and Windows messages will not be processed. It is important to note that if you specify this priority level in the main UI thread of an application, it can effectively cause the program to appear to be non-responsive to the user. Use of this priority can also negatively impact the performance of other applications running on the system, both in terms of CPU utilization and the amount of network bandwidth that is consumed during the transfer.

The ability to specify a priority gives your application additional flexibility and control over the transfer process. For more information about setting transfer priorities, you can refer to the technical reference documentation that is included with your copy of SocketTools.

The PowerShell scripting language is similar to C# and provides many of the typical statements in a scripting language (conditional statements, looping control, switch statements and so on) as well as support for regular expressions, array slicing and hash tables. It also supports scoping, allowing you to declare variables to be global or local scope. In addition to many of its features, PowerShell can also make use of .NET assemblies, enabling you to take advantage of the expansive .NET Framework in your own scripts. This opens a lot of possibilities, both for the typical administrative tasks one could perform, but also allows developers to use PowerShell as a test-harness and prototyping tool for their own projects.

With the SocketTools .NET Edition, you can create scripts using the same classes that you use when building your applications. If you are already familiar with SocketTools, then there is virtually no learning curve aside from some minor syntactical differences. Note that even if you’re not familiar with C#, you’ll find the PowerShell scripting language easy to work with. A great book to help you get started is “Windows PowerShell In Action” by Bruce Payette, and something that every aspiring PowerShell user should have on their bookshelf.

Getting Started
To demonstrate how to use SocketTools with PowerShell, the first step is to install PowerShell and the SocketTools .NET Edition on your local system. If you don’t already have a copy of the SocketTools .NET Edition, you can download and install it with a free evaluation license. Once you have everything installed, fire up your copy of PowerShell.

To use one of the SocketTools assemblies, you need to load it. This can be done using the LoadFile method in the System.Reflection.Assembly class. Simply pass the full file name of the assembly as its argument. The SocketTools assemblies are found in the following folder:

C:\Program Files\Common Files\Catalyst Shared\Assemblies\v5.0\v2.0.50727

So let’s say that you want to use the FTP class to download a file to the local system. You would enter the following (note that PS> is the PowerShell prompt and should not be entered):

PS> [System.Reflection.Assembly]::LoadFile("C:\Program Files\Common Files\Catalyst Shared\Assemblies\v5.0\v2.0.50727\SocketTools.FtpClient.dll")

If you’ve entered the path correctly, you’ll get a message that shows the version and location of the assembly that’s been loaded. The next step is to create an instance of the SocketTools.FtpClient class:

PS> $FtpClient = New-Object SocketTools.FtpClient

Using the SocketTools Class
The $FtpClient variable now references an instance of the SocketTools.FtpClient class. With that done, you now have access to all of the various properties and methods. To see a list of the current property values, you can simply enter:

PS> $FtpClient

To download a file, you can use the GetFile method. For example, you could enter:

PS> $FtpClient.GetFile("c:\rfc959.txt", "ftp://ftp.ietf.org/rfc/rfc959.txt;type=a")

The first argument is the name of the file on the local system, and the second argument is the FTP URL that specifies the remote location of the file (the “type a” at the end is part of the FTP URL syntax that specifies the file is an ASCII text file).

An important point to keep in mind is that whenever you specify a path to a method in a .NET class (whether in SocketTools or some other class) you should always specify a full path. This is important because PowerShell keeps track of its current working directory independently of what the assembly considers to be the current working directory. To avoid any possible confusion, it’s always best to be explicit, otherwise you can get some unexpected results.

You’ve downloaded a file and stored it on the local system, but what if you want to manipulate the contents of the file in memory, instead of writing it to disk? Instead of using the GetFile method, use the GetData method instead. It accepts two arguments, the URL of the file that you want to download, and a buffer to store the contents of the file in. To do this, first we need to create a string variable that will contain the file data when the method returns:

PS> $buffer = ""

This is important because the second argument to the GetData method must be passed by reference. To do this, the variable must already exist and the [ref] attribute must be specified for the parameter. Here’s an example:

PS> $FtpClient.GetData("ftp://ftp.ietf.org/rfc/rfc959.txt;type=a", [ref] $buffer)

When the GetData method returns, the $buffer variable will contain the contents of the file and you can manipulate it as you would any string type.

More Information
Hopefully will give you an idea of how you can use SocketTools with PowerShell as a means to accomplish administrative tasks, as well as help you with your development projects. Here’s some more links to help you get started:

• Windows PowerShell Download
• Windows PowerShell Quick Reference
• Windows PowerShell Programmer’s Guide
• PowerShell Quick Start

Coding Shortcuts Using URLs
For those of you using the SocketTools .NET Edition or Visual Edition, the typical sequence of method calls requires that you establish a connection using the Connect method, then perform the action that you want to take (for example, calling the GetFile method to download a file) and then terminating the connection by calling the Disconnect method.

For the File Transfer and Hypertext Transfer components, we’ve added the ability to use URLs without requiring that you explicitly establish a connection to the server first. New code can be written to take advantage of this feature, but existing code will continue to work as it always has.

Visual Basic Example
For example, here’s some Visual Basic code (using a Visual Edition component) that connects to our web server and downloads the index file, storing it on the local system:

Dim strHostName As String = "www.catalyst.com"
Dim strRemoteFile As String = "/index.html"
Dim strLocalFile As String = "c:\index.html"
Dim nError As Integer

nError = HttpClient1.Connect(strHostName, 80)
If nError = 0 Then
    nError = HttpClient1.GetFile(strLocalFile, strRemoteFile)
End If

If nError > 0 Then
    MsgBox(HttpClient1.LastErrorString, MsgBoxStyle.Exclamation)
    Exit Sub
End If

HttpClient1.Disconnect()

With SocketTools 5.0, that code can be reduced to the following:

Dim strLocalFile As String = "c:\index.html"
Dim strRemoteFile As String = "http://www.catalyst.com/index.html"
Dim nError As Integer

nError = HttpClient1.GetFile(strLocalFile, strRemoteFile)
If nError > 0 Then
    MsgBox(HttpClient1.LastErrorString, MsgBoxStyle.Exclamation)
    Exit Sub
End If

By providing a complete URL as the remote file that you want to download, you can omit the explicit calls to the Connect and Disconnect methods, and have the component automatically manage the connection for you. This applies to the GetFile and PutFile methods, as well as methods such as GetData, PutData, PostData and so on. This also applies to the same methods that are available in the SocketTools .NET Edition.

C/C++ Example
For developers who are using the SocketTools Library Edition, there’s some shortcuts available to you as well. The FtpDownloadFile, FtpUploadFile, HttpDownloadFile and HttpUploadFile functions are high-level “wrapper functions” around the API that enable you to upload and download files in a single function call. For example:

LPCTSTR lpszLocalFile = _T("c:\\index.html");
LPCTSTR lpszRemoteFile = _T("http://www.catalyst.com/index.html");
BOOL bResult;

bResult = HttpDownloadFile(lpszLocalFile,
                           lpszRemoteFile,
                           HTTP_TIMEOUT,
                           HTTP_OPTION_DEFAULT,
                           NULL, NULL, 0);

if (bResult == FALSE)
{
    DWORD dwError = HttpGetLastError();
    _tcprintf(_T("Unable to download file, error %08lX\n"), dwError);
}

There still are some cases where you want to explicitly connect to the server. If you’re going to perform multiple file transfers, it’s more efficient to call the Connect method, call GetFile or PutFIle for each file, and then Disconnect. When you use URLs, then a connection will be established for each file that’s being transferred. By explicitly connecting to the server, you have more direct control over the “lifetime” of the client session. However, for single operations (downloading one file at a time, or posting data to a script on a web server) the ability to use URLs can simplify and reduce the amount of code that you need to write.