Client / Server Communications
Library for Delphi
Programmer's Manual
(CSC4D)
Version 4.0
April 25, 2007.
This software is provided as-is.
There are no warranties, expressed or implied.
Copyright (C) 2007
All rights reserved
MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815
Voice : 1.256.881.4630
FAX : 1.256.880.0925
web : www.marshallsoft.com
MARSHALLSOFT is a registered trademark of MarshallSoft Computing.
1 Introduction
1.1 Features2 CSC Library Overview
1.2 Documentation Set
1.3 Example Program
1.4 Installation
1.5 Uninstalling
1.6 Pricing
1.7 Updates
2.1 Dynamic Link Libraries3 Compiler Issues
2.2 Keycode
2.3 Using the CSC Library
2.4 Win32 STDCALL and DECLSPEC
2.5 Adding CSC4D to Your Project
2.6 CSC4D Wrapper
2.7 Example Protocol
2.8 Error Display
3.1 Delphi Versions4 Delphi Example Programs
3.2 Compiling Programs
3.3 Compiling CSC Source
5 Revision History
The Client / Server Communications Library for Delphi (CSC4D) 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 CSC4D component library supports and has been tested with all 32-bit versions of Borland Delphi, including Delphi 2006 and .NET 2.0. CSC4D includes numerous Delphi example programs that demonstrate client/ server protocols to help software developers easily build software applications using the CSC SDK.
A Win32 DLL (Dynamic Link Library) is provided. CSC runs under all versions of 32-bit Windows (95/98/ME/2000/NT/XP/2003/Vista). The Client / Server Communications Library SDK DLL (CSC32.DLL) can also be used from any language (C++, .NET, C#, Visual Basic, VB.NET, ACCESS, EXCEL, VBA, Visual FoxPro, COBOL, Xbase++, Visual dBase, etc.) capable of calling the Windows API.
The Client/Server Communications Programmer's Manual provides information needed to compile programs and example programs in a Delphi environment.
When comparing the Client/Server Communications Library against our competition, note that:
MarshallSoft also has versions of the Client/Server Communications Library for C/C++ (CSC4C), and Visual Basic (CSC4VB). Each version of CSC uses the same DLL (CSC32.DLL). However, the examples provided for each version are written for the specified computer language.
All versions of the Client/Server Communications Library (CSC) can be downloaded from our web site at
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.
Some of the many features of the Client/Server Communications Library component are as follows:
CSC can also be used to communicate with other CSC programs, or used to communicate with other TCP programs such as DNS, POP3, SMTP, FTP, HTTP, etc.
A good selection of Borland (CodeGear) Delphi example programs with full source code is included. Refer to Section 6 for more details on each of the example projects.
ver_prj.dpr Displays CSC version and build.
helo_prj.dpr Displays CSC version and build using wrapper.
client_prj.dpr Example client program.
server_prj.dpr Example server program.
download_prj.dpr Example download (from web) program.
auth_client_prj.dpr Authenticating client.
auth_server_prj.dpr Authenticating server.
File_Server_prj.dpr Example file server.
File_Client_prj.dpr Example file client.
Client.bdsproj Example Delphi NET client program.
Server.bdsproj Example Delphi NET server program.
The complete set of documentation consists of three manuals in three formats. This is the first manual (CSC_4D) in the set.
Each manual comes in three formats:
The CSC_4D Programmer's Manual is the language specific (Delphi) manual. . All language dependent programming issues are discussed in this manual. Information needed to compile your programs in a Delphi 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.
The documentation is also provided on our web site at
http://www.marshallsoft.com/csc4d.htm
The following code segment attempts to connect to the server.
{connect to server}
DataSock := cscClient(HostName, HostPort);
if DataSock < 0 then
begin
DisplayLine(client.mHistory, 'cscClient fails');
DisplayError(client.mHistory, DataSock);
exit;
end;
{connected: now wait 7 seconds for greeting message from server}
Call DisplayText(client.mHistory, "Awaiting greeting message...")
Code := cscAwaitData(DataSock, 7000);
if Code = 0 then
begin
DisplayLine(client.mHistory, 'Greeting message not seen');
exit;
end;
Also see the example programs in the APPS sub-directory.
Uninstalling CSC4D is very easy. CSC does NOT modify the registry. First, delete the CSC4D project directory created when installing CSC4D. Second, delete CSC32.DLL from your Windows directory, typically C:\WINDOWS for Windows 95/98/Me/XP/VISTA or C:\WINNT for Windows NT/2000.
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
When you purchase a developer license for CSC4D, you will receive a registered DLL plus a license file (CSCxxxx.LIC) that can be used to update your registered DLL 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, if previously purchased, can be purchased for $50.
Note that the registered CSC DLL does not expire.
The CSC32.DLL functions may be called by any Windows application program capable of calling the Windows API provided that the proper declaration file is used.
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".
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.PAS. 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.
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 CSC4D library will work with all versions of Borland (CodeGear) Delphi including Delphi 2006.
The SETUP installation program will copy the Lib's and DLL to your Windows directory. Refer to Section 1.4 "Installation".
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.
Copy CSC32.PAS to the same directory (folder) as the application program to which you want to add CSC code. You will find these files in the APPS directory (folder) created when you ran SETUP, usually C:\ CSC4D\APPS.
For Win32 Delphi, add CSC32 and keycode to your "uses" clause in your source program (*.PAS). For example,
uses
csc32, keycode, ...
You can leave 'keycode' out above if you paste your numerical keycode value (found in keycode.pas) directly into the call to cscAttach. Also add csc32 to your project file (*.DPR). For example,
uses
csc32 in 'csc32.pas', ...
{pass the key code}
Code := cscAttach(1, CSC_KEY_CODE);
The CSC32W.PAS module is a "wrapper" for CSC32.PAS that allows you to pass Delphi strings directly rather than having to first convert them to PCHAR variables. Strings in CSC, like Windows itself, are in reality buffers terminated by a null (0) character. Implementing CSC in this way allows CSC functions to be called by any language capable of calling the Windows API. Note that wrapper functions (defined in CSC32W.PAS) are named beginning with the letter 'f'. For instance, "fAttach" is the wrapper function that calls "cscAttach".
Nevertheless, it is certainly more convenient to pass Delphi strings rather than zero terminated buffers. Compare the two following code segments:
{call using CSC -- pass pointers to null terminated buffers}
var
Code : Integer;
HostPtr : PChar;
UserPtr : PChar;
PassPtr : PChar;
begin
GetMem(HostPtr, 64); StrPCopy(HostPtr, 'mail.marshallsoft.com');
GetMem(UserPtr, 64); StrPCopy(UserPtr, 'mike');
GetMem(PassPtr, 64); StrPCopy(PassPtr, 'qwerty');
Code := seePop3Connect(0, HostPtr, UserPtr, PassPtr);
FreeMem(HostPtr,64); FreeMem(UserPtr,64); FreeMem(PassPtr,64);
. . .
{call using CSC32W -- pass Delphi strings}
. . .
Code := fClient(0, 'mail.marshallsoft.com', 'mike', 'qwerty');
. . .
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 directory.
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");
}
Applications written with Delphi link with the same identical DLL's as for applications written in all other supported languages, such as C/C++ and Visual Basic.
Delphi version 1 generates Win16 code. CSC32.DLL is a 32-bit DLL and cannot be called from 16-bit application programs such as those compiled by Delphi 1.
Delphi version 2 and above generates Win32 code. Therefore, applications written using Delphi 2 will link with CSC32.DLL. Strings can be much larger than 255 bytes.
Delphi 2 seems to have a problem with some of the string functions. Although the default is "large strings", some of the string functions (such as StrPas) copy only 255 bytes.
There are no known Delphi problems impacting our example programs in Delphi version 3 and above. Applications written using Delphi 3 and above will link with CSC32.DLL
Beginning in Delphi 7, the filename of a unit must match the unit name.
Delphi 2005 and 2006 are Borland's latest Delphi product with support for both Win32 and Microsoft .NET Framework. Application programs written using Delphi 2005 and 2006 will use CSC32.DLL.
When loading Win32 Delphi projects with Delphi 2005and 2006, a window entitled "Project Upgrade" will be displayed:
This project must be upgraded before it can be opened. Please select which project type you wish to target:
( ) Delphi for .NET
( ) Delphi for Win32
Choose "Delphi for Win32" for all projects except "client.bdsproj" and "server.bdsproj", which are Delphi for .NET projects.
The example programs are compiled from the Delphi development environment using the provided Delphi project files (*.DPR).
The example programs will compile and run with any version of Delphi. They have each been tested using Delphi 1 through Delphi 5 and Delphi 2005.
Respond with "OK" to the message "Cannot find resource file..." and it will be properly rebuilt.
See Section 4 "Example Programs" for more details on each of the example programs.
CSC4D may also be used with "Borland Pascal for Windows".
The source code for the CSC DLL's is written in standard ANSI C (CSC32.C), and has been compiled using Microsoft Visual C++. The Win32 version is compiled with the STDCALL and DECLSPEC compiler keywords. Source code for the CSC library can be purchased at the same time as a CSC developer license is purchased.
CSC may also be compiled using Borland C/C++ or Watcom C/C++ compilers. If you recompile CSC32.C using Borland or Watcom compilers, the resulting DLL can only be used by applications compiled with the same compiler, unless the STDCALL and DECLSPEC keywords are specified. 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/client-server-communication.htm
The DISPLAY.PAS unit is used to display text in Delphi memos. DISPLAY.PAS contains 4 procedures:
DisplayChar : Displays character.
DisplayString : Displays string.
DisplayLine : Displays line.
DisplayError : Displays error message.
The example programs are designed to demonstrate the various capabilities of CSC4D. The best way to become familiar with CSC4D is to study and run the example programs.
The example programs can be compiled with any version of 32-bit Delphi although there are separate examples for Delphi NET. All example programs are located in the APPS sub-directory.
The CSC units used by the example programs are:
CSC32.PAS : Win32 CSC unit.
CSC32W.PAS : Win32 CSC unit used by HELO project.
CSC32UC.PAS : NET unit used by Client NET project.
The VERSION example program displays the CSC version number, build, and registration string. This is the first program to compile and build since it verifies that CSC32.DLL is installed properly.
The VERSION project files are:
VER_PRJ.DPR : Delphi project file.
VER_PGM.DFM : Delphi form file.
VER_PGM.PAS : Program source code.
HELO is an example program that displays the CSC version number, build, and registration string using the CSC32W.PAS wrapper unit.
The HELO project files are:
HELO_PRJ.DPR : Delphi project file.
HELO_PGM.DFM : Delphi form file.
HELO_PGM.PAS : Program source code.
CLIENT is an example client program that operates as a client that connects to the example server program (SERVER).
The CLIENT project files are:
CLIENT_PRJ.DPR : Delphi project file.
CLIENT_PGM.DFM : Delphi form file.
CLIENT_PGM.PAS : Program source code.
SERVER is an example server program that accepts connections from the example client program (CLIENT).
SERVER accepts a maximum of 3 connections (clients) at any one time.
The SERVER project files are:
SERVER_PRJ.DPR : Delphi project file.
SERVER_PGM.DFM : Delphi form file.
SERVER_PGM.PAS : Program source code.
The File_Server example server program can accept multiple connections and allows clients to download files. See the comments in File_Server_Pgm.pas or see PROTOCOL.TXT for a description of the protocol used.
The File_Server project files are:
File_Server_PRJ.DPR : Delphi project file.
File_Server_PGM.DFM : Delphi form file.
File_Server_PGM.PAS : Program source code.
The File_Client example client program connects to the File_Server example server program in order to download files. See the comments in File_Client_Pgm.pas or see PROTOCOL.TXT for a description of the protocol used.
The File_Client project files are:
File_Client_PRJ.DPR : Delphi project file.
File_Client_PGM.DFM : Delphi form file.
File_Client_PGM.PAS : Program source code.
The Auth_Server example program demonstrates how server-side authentication is done in CSC4D. Auth_Server accepts connections from Auth_Client.
The File_Server project files are:
Auth_Server_PRJ.DPR : Delphi project file.
Auth_Server_PGM.DFM : Delphi form file.
Auth_Server_PGM.PAS : Program source code.
The Auth_Client example program demonstrates how client-side authentication is done in CSC4D. Auth_Server accepts connections from Auth_Client.
The File_Client project files are:
Auth_Client_PRJ.DPR : Delphi project file.
Auth_Client_PGM.DFM : Delphi form file.
Auth_Client_PGM.PAS : Program source code.
The (NET) CLIENT example program is the Delphi 2005/2006 NET equivalent of the Delphi Win32 CLIENT example program.
The Delphi 2005/2006 NET project files are:
client.bdsproj : Delphi NET project file
client.dpr : Delphi NET project file
WinForm_Client.pas : Delphi NET form source
WinForm_Client.resx : Delphi NET resource file
WinForm_Client.TWinForm.resources : Delphi NET resource file
The (NET) SERVER example program is the Delphi 2005/2006 NET equivalent of the Delphi Win32 SERVER example program.
The Delphi 2005/2006 NET project files are:
server.bdsproj : Delphi NET project file
server.dpr : Delphi NET project file
WinForm_Server.pas : Delphi NET form source
WinForm_Server.resx : Delphi NET resource file
WinForm_Server.TWinForm.resources : Delphi NET resource file
CSC32.DLL is written in ANSI C. All language versions of CSC (C/C++, Visual Basic, and Delphi) use the same identical DLL.
Version 3.0: November 1, 2005
Version 4.0: April 25, 2007