1 Introduction

1.1 Features
1.2 Documentation Set
1.3 Example Program
1.4 Installation
1.5 Uninstalling
1.6 Pricing
1.7 Updates
1.8 Keycode (License Key)

2 CSC Library Overview

2.1 Dynamic Link Libraries
2.2 Using the CSC Library
2.3 Win32 STDCALL and DECLSPEC
2.4 Dynamic Strings
2.5 CSC4VB Class
2.6 VB.Net and Visual Studio
2.7 Visual Basic for Applications (VBA)
2.8 PowerBuilder
2.9 Using Threads
2.10 Adding CSC to Your Project
2.11 Example Client/Server Protocol
2.12 Error Display

3 Compiler Issues

3.1 Compiling CSC
3.2 Compiling Example Programs
3.3 Explicitly Loading CSC32.DLL

4 Example Programs

4.1 CSCVER
4.2 CLIENT
4.3 SERVER
4.4 FILEGET
4.5 FILEPUT
4.6 AUTH_C
4.7 AUTH_S
4.8 FileSrv
4.9 FileCli
4.10 Hello
4.11 Download

5 Revision History

1 Introduction

The Client / Server Communications Library for Visual Basic (CSC4VB) is a component library of functions used to create server and client programs that can communicate with each other across any TCP/IP network such as the Internet or a private network (intranet or LAN [local area net]). CSC uses the standard Windows API (Application Programmer's Interface) and Windows Sockets API for all communication calls.

The CSC4VB component library supports and has been tested with all versions of Microsoft Visual Basic including Visual Basic .NET. CSC4VB includes numerous VB and VB. NET example programs that demonstrate client/ server protocols, including examples that connect to HTTP (web) and POP3 servers. All programs will compile using VB-4.0 through VB-6.0.

A Win32 DLL (Dynamic Link Library) is provided. CSC runs under all versions of Windows (95/98/ME/2000/NT/XP/VISTA). The Client / Server Communications Library SDK DLL (CSC32.DLL) can also be used from any language (C++, C++ .NET, Visual C#, Borland Delphi, Visual FoxPro, COBOL, Xbase++, Visual dBase, etc.) capable of calling the Windows API.

CSC4VB functions can also be called from Power Builder as well as VBA (Visual Basic for Applications) languages such as Excel, Microsoft Office and Access.

The Client/Server Communications Programmer's Manual provides information needed to compile programs using CSC in a Visual Basic or VB. NET environment.

When comparing the Client/Server Communications Library against our competition, note that:

1. CSC4VB is a standard Windows DLL (NOT an OCX or ActiveX control) and is much smaller than a comparable OCX or ActiveX control.
2. A WIN32 DLL is included.
3. CSC4VB does NOT depend on ActiveX or Microsoft Foundation Class (MFC) libraries or similar "support" libraries.
4. The WIN32 version of CSC is fully threadable.
5. The CSC functions can be called from applications not capable of using controls.

For the latest version of the CSC software, see

http://www.marshallsoft.com/client-server-communication.htm

Our goal is to provide a robust communication component library that you and your customers can depend upon. A fully functional evaluation version is available. Contact us if you have any questions.

1.1 Features

Some of the many features of the Client/Server Communications Library component are as follows:

• Can be used to create both clients and servers.
• Supports "one time" passwords for improved security.
• Can send a Windows message when a connection is ready to accept.
• Can send a Windows message when incoming data is ready to be read.
• Can send and receive data buffers or entire files.
• Servers can handle multiple connections concurrently.
• Specify the maximum number of connections that the server will accept.
• Allows multiple servers and clients to run simultaneously.
• Free technical support and updates for one year for registered users.
• Royalty free distribution with your compiled application.
• Evaluation versions are fully functional. No unlock code is required.
• Is fully thread safe.
• Supports Windows 95/98/Me/NT/2000/XP/Vista.
• Works with all versions of Microsoft Visual Basic and VB .NET
• Works with VBA (Visual Basic for Applications) such as Excel or Access as well as Power Builder.
• Does not depend on support libraries. Makes calls to core Windows API functions only.
• Can be used with any program (in any language) capable of calling Windows API functions.
• Can be purchased with (or without) ANSI C source code.
• Documentation online as well as in printable format.

CSC can also be used to communicate with other CSC programs, or they can be used to communicate with other TCP programs such as DNS, POP3, SMTP, FTP, HTTP, etc.

A good selection of Visual Basic (and VB.NET) example programs with full source code is included. Refer to Section 6 for more details on each of the example programs.

      cscver     Displays CSC version and build
      auth_c     Authenticating client.
      auth_s     Authenticating server.
      client     Simple client example program.
      FileGet    Receives a file.
      FilePut    Sends a file.
      server     Simple server example program.
      FileSrv    File server example program.
      FileCli    File client example program.
      Hello      Demonstrates use of CSC class.
      Download   Downloads file from web server.

1.2 Documentation Set

The complete set of documentation consists of three manuals in three formats. This is the first manual (CSC_4VB) in the set.

• CSC_4VB Programmer's Manual (CSC_4VB.DOC, CSC_4VB.TXT, CSC_4VB.HTM)
• CSC User's Manual (CSC_USR.DOC, CSC_USR.TXT, CSC_USR.HTM)
• CSC Reference Manual (CSC_REF.DOC, CSC_REF.TXT, CSC_REF.HTM)

The CSC_4VB Programmer's Manual is the language specific (Visual Basic and VB.NET) manual. All language dependent programming issues are discussed in this manual. Information needed to compile your programs in a VB environment is provided in this manual.

The CSC User's Manual (CSC_USR) discusses language independent issues. Information on Client / Server protocols as well as purchasing and license information is provided in the manual.

The CSC Reference Manual (CSC_REF) contains details on each individual CSC function.

Each manual comes in three formats:

• Microsoft Word (files ending in .DOC). The best format for printing manuals.
• Hyper Text (files ending in .HTM). Use any web browser to read.
• ASCII Text (files ending in .TXT).

The documentation is also provided on our web site at

     http://www.marshallsoft.com/csc4vb.htm

1.3 Example Program

The following code segment attempts to connect to the server.

     DataSock = cscClient(HostName, HostPort)
     If DataSock < 0 Then
        Call DisplayError(Client, Code, "cscClient fails")
        Code = cscRelease()
        Exit Sub
     End If
     ' wait for greeting message from server
     Call DisplayText(Client, "Awaiting greeting message...")
     ' send WM_LBUTTONDOWN message when data is ready to be read
     Code = cscDataMessage(Client.bReady.hWnd, DataSock, WM_LBUTTONDOWN)

Also see the example programs in the APPS sub-directory.

1.4 Installation

1. Before installation of CSC4VB, your Visual Basic compiler should already be installed on your system and tested. Note that Visual Basic_4.0 or above is required in order to create Win32 programs.
   
   
2. Unzip CSC4VB40.ZIP(demo version) or CSCxxxx.ZIP (registered version; xxxx is your Customer ID) using any Windows unzip program.
   
   
3. Run the installation program SETUP.EXE which will install all CSC4VB files. SETUP will also copy CSC32.DLL to your Windows directory. No Windows system files are modified. Note that no DLL registration is required.

1.5 Uninstalling

Uninstalling CSC4VB is very easy. CSC does NOT modify the registry. First, delete the CSC4VB project directory created when installing CSC4VB. Second, delete CSC32.DLL from your Windows directory, typically C:\WINDOWS for Windows 95/98/Me/XP/2003/Vista or C:\WINNT for Windows NT/2000.

1.6 Pricing

A developer license for the Client/Server Communications Library can be registered for $115 (or $195 with source code [ANSI C] to the library DLL). Purchasing details can be found in Section 1.3, "How to Purchase", of the CSC User's Manual (CSC_USR). (http://www.marshallsoft.com/csc_usr.htm#Section_1.3)

Also see INVOICE.TXT or http://www.marshallsoft.com/order.htm

1.7 Updates

When you register a developer license for CSC4VB, you will receive a registered DLL plus a license file (CSCxxxx.LIC) that can be used to update your registered DLL's for a period of one year from purchase. Updates can be downloaded from

   
     http://www.marshallsoft.com/oem.htm
   

After one year, your license must be updated if you want to be able to download updates. Your license can be updated for $30 if ordered within one year of the original purchase (or previous update). After one year, licenses can be updated for $55. Updates to the source code can be purchased for $50.

Note that the registered CSC DLL does not expire.

1.8 Keycode (License Key)

CSC32.DLL has a keycode encoded within it. Your keycode is a 9 or 10 digit decimal number (unless it is 0), and will be found in the file KEYCODE.H. The keycode for the evaluation version is 0. You will receive a new key code when registering. The KEYCODE is passed to cscAttach.

If you get an error message (value -74) when calling cscAttach, it means that the keycode in your application does not match the keycode in the DLL. After registering, it is best to remove the evaluation version of the CSC DLL from the Windows search path.

2 Library Overview

2.1 Dynamic Link Libraries

The Client/Server Communication Library component is a Win32 dynamic link library (DLL). A DLL is characterized by the fact that it need not be loaded until required by an application program and that only one copy of the DLL is necessary regardless of the number of application programs that use it. Contrast this to the traditional static library that is bound to each and every application that uses it at link time.

An important advantage that DLLs have over other "popular" library formats such as VBX or OCX is that DLLs are callable by all Windows applications. Since DLLs are the building blocks of the Windows Operating System, they will not be replaced by a "newer technology".

2.2 Using the CSC Library

The Client/Server Communications Library (CSC) has been tested on multiple computers running Windows 95/98, Windows Me, Windows NT4, Windows 2000, Windows XP and Windows Vista.

The CSC4VB library has also been tested with several Visual Basic compilers, from VB_4.0 .0 through VB_6.0 .0 and VB.Net. CSC can also be used with Power Builder as well as 32-bit VBA applications such as Microsoft Office, EXCEL and ACCESS.

The SETUP installation program will copy the Lib's and DLL to your Windows directory. Refer to Section 1.4 "Installation".

2.3 Win32 STDCALL and DECLSPEC

CSC32 is written in ANSI C and is compiled using the _stdcall and _declspec keywords. This means that CSC32 uses the same calling conventions and file naming conventions as the Win32 API. In particular, function names are NOT decorated. There are no leading underscores or trailing "@size" strings added to function names.

The CSC32.DLL functions may be called from any Windows application program capable of calling the Windows API provided that the proper declaration file is used.

2.4 Dynamic Strings

The Visual Basic language uses a technique known as "garbage collection" to manage string space at runtime and may be called internally at any time by the Visual Basic runtime, asynchronous to what you may be doing in your code.

When passing a string buffer to a DLL function into which text will be copied, it is strongly recommended that the local string be allocated immediately before use. For example, a string buffer is passed to the user defined dllGetMessage function , which copies a text message into it. Note that SPACE$(80) is called immediately before dllGetMessage.

      Dim Code As Integer
      Dim Buffer As String * 80
      ' allocate buffer just before call to dllGetMessage
      Buffer = SPACE$(80)
      ' copy message into 'Buffer'
      Code = dllGetMessage(Buffer, 80)
      ' message text is now in 'Buffer'

This technique is not necessary for passing a string to a DLL function, only when passing a buffer to a DLL into which data is to be placed by the DLL function.

2.5 CSCVB Class

The CSC class "cscClass" (cscClass.cls) is a Visual Basic class wrapper for making calls to CSC32.DLL. The class name for each function is the same as the DLL function, except the leading "csc" is replaced by "f".

The functions that return strings do so by use of the "String Result" property. Instantiate cscClass as any other class in VB:

     Dim X As New cscClass

Classes were added to Visual Basic beginning with version 5.0, and are required in order to compile cscClass

2.6 VB.Net and Visual Studio

There are a few differences between VB_4.0 /5/6 and VB.NET/VS Studio that affect writing programs that use CSC.

1. Variables that are declared "As Long" in VB_4.0 /5/6 are declared "As Integer" in VB.Net.
   
   
2. Fixed length strings are not supported in VB.Net. When calling any CSC function that can return a string, memory for the string variable must be allocated first. For example:

   
     Buffer = Space(80)
     Code = cscGetString(0, CSC_GET_REGISTRATION, Buffer, 80)
   

3. Some VB functions must be fully qualified. For example, instead of LEFT, use Microsoft.VisualBasic.Left
   
   
4. The module CSC32.VB (not CSC32.BAS) must be included in all VB.Net programs.

2.7 Visual Basic for Applications (VBA)

The Client/Server Communication component library can be used with Microsoft VBA applications such as EXCEL, ACCESS, and Microsoft Office.

Start EXCEL (or other 32-bit Office VBA program such as WORD or ACCESS), then enter design mode. Enable the "Controls Toolbox", choose "Tools" on the menu bar, then "Customize", and then check "Control Toolbox". From the control toolbox, choose and position a "Command Button". This will create code that looks like

     Private Sub CommandButton1_Click()
   
     End Sub

Replace the generated code with MODULE32.BAS. The easiest way to do this is to paste from the clipboard. Edit the 'HostName' in this code, using the name of the computer (or IP address in dotted decimal notation) where the server application (see SERVER.VBP) is running.

Exit design mode and then press the command button to start the CSC VBA example program.

2.8 PowerBuilder

CSC can also be used with 32 bit Power Builder applications. See PBUILDER.TXT in the \APPs subdirectory for more information.

      CSC32.PBI : Power Builder declaration file.

2.9 Using Threads

CSC4VB is thread safe, and can be used from any Windows application capable of using threads.

The "AddressOf" operator, which was added to Visual Basic beginning in version 5.0, is required in order to create and run a Win32 thread in Visual Basic.

2.10 Adding CSC4VB to Your Project

Copy CSC32.BAS (if running VB_4.0 /5/6), or CSC32.VB (if running VB.Net) into the same directory (folder) as the application program to which you want to add CSC code. You will find these files in the APPS sub-directory (folder) created when you ran SETUP, usually C:\CSC4VB\APPS.

2.10.1 Adding CSC4VB to your VB_4.0 .0, 5.0, or 6.0 Project

Open your existing project with "File", "Open Project". Then choose "Insert", "Module", then add CSC32.BAS and KEYCODE.BAS to your project. If prompted to add "DAO 2.50 Object Library", choose "no".

CSC functions can now be called from your VB program.

2.10.2 Adding CSC4VB to your VB.Net Project

Open your existing project with "File", "Open Project". Then choose "Project", "Add Module", then add CSC32.VB and KEYCODE.VB to your project. CSC functions can now be called from your VB.NET program.

2.11 Example Client/Server Protocol

A description of the protocol used by the example programs can be found in Section_2.7, "Example Protocol", in the CSC User's Manual (http://www.marshallsoft.com/csc_usr.htm#Section_2.7).

Also refer to PROTOCOL.TXT in the \APPS subdirectory.

2.12 Error Display

The error message text associated with CSC error codes can be displayed by calling cscErrorText.

     void DisplayError(int ErrCode, char *MsgPtr)
     {int Len;
      char ErrBuff[129];
      printf("ERROR %d: ", ErrCode);
      if(MsgPtr) printf("%s: ", MsgPtr);
      Len = cscErrorText(ErrCode, (char *)ErrBuff, 128);
      if(Len>0) printf("%s\n", ErrBuff);
      else printf("\n");
     }

3 Compiler Issues

The Client/Server Communication Library for Visual Basic supports and has been tested with all versions of Microsoft Visual Basic (VB 4, VB 5, VB 6 and VB.NET).

3.1 Compiling CSC

The Client/Server Communication component library (CSC32.DLL) is written in standard ANSI C (CSC32.C), and has been compiled using Microsoft Visual C/C++ with the STDCALL and DECLSPEC compiler keywords. Source code for the CSC library is provided in the registered version (if ordered) only.

For more information on the C/C++ version of CSC, download the latest version of CSC4C from our web site at http://www.marshallsoft.com/csc4c.htm

3.2 Compiling Example Programs

Visual Basic project files (.VBP) are provided for all example VB 4/5/6 programs.

Visual Basic NET project files (.VBPROJ) are provided for the VB.Net example programs.

3.3 Explicitly Loading CSC32.DLL

When an application program runs that makes calls to CSC32.DLL, the Windows operating system will locate CSC32.DLL by searching the directories as specified by the Windows search path. If the CSC32.DLL is placed in the \WINDOWS directory (or \WINNT for Windows NT/2000), it will always be found by Windows.

CSC32.DLL can be loaded from an explicit location by replacing "CSC32.DLL" in CSC32.BAS or CSC32.VB by the full path. For example, to load CSC32.DLL from C:\CSC4VB\APPS, the first entry in would be:

     Declare Function cscAcceptConnect Lib "C:\CSC4VB\APPS\CSC32.DLL" (ByVal vSock As Long) As Long

4 Example Programs

The example programs are designed to demonstrate the various capabilities of CSC4VB. The best way to become familiar with CSC4VB is to study and run the example programs.

The example programs can be compiled with the version of Visual Basic indicated below. All example programs are located in the \APPS sub-directory.

4.1 CSCVER

The CSCVER ("CSC Version") example program displays the CSC version number. This is the first program to compile and build since it verifies that CSC32.DLL is installed properly.

The project files are CSCVER.VBP for VB_4.0 and above and CSCVER.VBPROJ for VB.Net.

4.2 CLIENT

CLIENT is a VB example program that operates as a client that connects to the example server programs.

The project files are CLIENT.VBP for VB_4.0 and above and CLIENT.VBPROJ for VB.Net.

4.3 SERVER

SERVER is a VB example program that operates as a server that accepts connections from the example client program (CLIENT).

SERVER accepts a maximum of 3 connections (clients) at any one time.

The project files are SERVER.VBP for VB_4.0 and above and SERVER.VBPROJ for VB.Net.

4.4 FILEGET

FILEGET is a VB example program that operates as a server, and receives files from the FilePut client.

The project file is FILEGET.VBP for VB_4.0 and above.

4.5 FILEPUT

FILEPUT is a VB example program that operates as a client, and transmits files to the FileGet server.

The project file is FILEPUT.VBP for VB_4.0 and above.

4.6 AUTH_C

AUTH_C is a VB example program that operates as a client implementing authenticated (challenge/response) connections.

The project file is AUTH_C.VBP for VB_4.0 and above.

4.7 AUTH_S

AUTH_S is a VB example program that operates as a server implementing authenticated (challenge/response) connections.

The project file is AUTH_S.VBP for VB_4.0 and above.

4.8 FileSrv ("File Server")

The FileSrv example server program can accept multiple connections and allows clients to download files. See the comments in FileSrv.frm or see PROTOCOL.TXT for a description of the protocol used.

The project file is FileSrv.VBP for VB_4.0 and above.

4.9 FileCli ("File Client")

The FileCli example client program connects to the FileSrv example server program in order to download files. See the comments in FileCli.frm or see PROTOCOL.TXT for a description of the protocol used.

The project file is FileCli.VBP for VB_4.0 and above.

4.10 Hello

HELLO is an example program that demonstrates the use of the CSC class cscClass.cls.

The project file is HELLO.VBP for VB_5.0 and above.

4.11 Download

Download is an example client that connects to the MarshallSoft web site (HTTP server) and downloads a file from the ./files directory.

The project file is Download.VBP for VB_4.0 and above.

5 Revision History

Version 2.0

The first Visual Basic version of CSC.

Version 3.0: September 9, 2005.

• Corrected problem not freeing socket when connect fails.
• Increased file length from a 8-digit number to a 9-digit number in cscGetFile and cscPutFile.
• Added CSC_SET_DEBUG_LEVEL to allow for multiple debug levels.
• Increased the default file packet length from 4K to 8K.
• Added cscIsConnected function to allow a server to check if a client is still connected.
• Added cscShortToByte and cscByteToShort.
• Added CSC_GET_BUFFER_SIZE - returns buffer size used in cscGetFile and cscPutFile.
• Added ability to cancel file transfer from remote side.
• Added FileSrv and FileCli example programs.

Version 4.0: April 11, 2007

• Added CSC_GET_DAYS_LEFT to cscGetInteger
• Added CSC_FILE_TOO_LARGE error code.
• Allow multiple listen sockets.
• Changed: cscAttach, cscAwaitConnect, cscAcceptConnect, cscServer
• Removed: cscSendMessage
• Added: cscDataMessage, cscConnectMessage
• Increased NBR_DATA_SOCKS from 128 to 1024.
• Modified CSC_SET_FILE_PATH to also set path for individual data socket.
• Append "-1", "-2", etc to filename if file already exists for cscGetFile
• Added VS_SET_LINGER to cscSetInteger
• Default linger time reduced to 200 ms
• cscAttach now returns DaysLeft (for evaluation version)