Client / Server Communications
Library for Delphi
Programmer's Manual
(CSC4D)
Version 6.0
August 5, 2009
This software is provided as-is.
There are no warranties, expressed or implied.
Copyright (C) 2009
All rights reserved
MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815
Voice : 1.256.881.4630
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 Win32 STDCALL and DECLSPEC
2.4 Adding CSC4D to Your Project
2.5 CSC4D Wrapper
2.6 Example Protocol
2.7 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 toolkit that allows software developers to quickly develop server client TCP/IP and UDP applications in Delphi and Delphi for .NET.
The Client / Server Communications Library (CSC) is a component library that uses the Windows API to create client and server programs (Win32 and Win64) that can communicate with each other across any TCP or UDP network such as the Internet or a private network (intranet or LAN [local area net]).
The CSC library can 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.
The Client / Server Communications Library for Delphi (CSC4D) component library supports and has been tested with all 32-bit versions of Delphi [2005/2006/2007/2009] including Delphi for .NET. CSC4D includes multiple Delphi example programs demonstrating client/server protocols, including examples that connect to HTTP (web) and POP3 servers as well as encrypt files.
A Win32 DLL is provided (a 64-bit DLL is available). CSC4D runs under all versions of Windows (95/98/ME/2000/2003/NT/XP/Vista). The Client / Server Communications Library SDK DLL (CSC32.DLL) can also be used from any language (Visual C++, .NET, 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 using CSC in a Delphi programming 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), Visual Basic (CSC4VB) and Visual FoxPro (CSC4FP). Each version of CSC uses the same DLL (CSC32.DLL). However, the examples provided for each version are written for the specified programming 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 SDK are as follows:
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.
POP3Stat.dpr Returns the number of emails waiting on POP3 server.
GetPrice.dpr Downloads stock price from finance.yahoo.com
uNetTime.dpr UDP client gets Network Time.
Client.bdsproj Example Delphi NET client program.
Server.bdsproj Example Delphi NET server program.
The complete set of documentation consists of three manuals in two formats. This is the first manual (CSC_4D) in the set.
Each manual comes in two 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 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 \CSC4D\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 the Windows directory, typically C:\WINDOWS for Windows 95/98/Me/2003/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.4, "How to Purchase", of the CSC User's Manual (CSC_USR). See http://www.marshallsoft.com/csc_usr.htm#Section_1.4
Also see INVOICE.TXT or http://www.marshallsoft.com/order.htm
When a developer license is purchased for CSC, the developer will be sent a registered DLL plus a license file (CSCxxxxx.LIC). The license file can be used to update the registered DLL for a period of one year from purchase. Updates can be downloaded from
http://www.marshallsoft.com/oem.htm
After one year, the developer license must be updated to be able to download updates. The license can be updated for $30 if ordered within one year of the original purchase (or previous update). Between one year and three years, licenses can be updated for $55. After three years, updates are $75. Updates to the source code can be purchased for $40.
Note that the registered CSC DLL does not expire (only the ability to download updates expires).
The Client/Server Communications Library (CSC) has been tested on multiple computers running Windows 95/98, Windows Me, Windows NT4, Windows 2000, Windows 2003, Windows XP and Windows Vista.
The CSC4D library will work with all 32-bit versions of Borland (Codegear) Delphi including Delphi 2009 and Delphi for .NET. 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 SETUP installation program will copy the Lib's and DLL to the Windows directory. Refer to Section 1.4 "Installation". After SETUP is run, the CSC4D files are copied to the directory specified (default \CSC4D). Three sub-directories are created, as follows:
DOCS - All documentation files
APPS - All example code
DLLS - All DLL's
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. The 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 an error message (value -74) is returned when calling cscAttach , it means that the keycode in the CSC application does not match the keycode in the DLL. After registering, it is best to remove the evaluation version of the CSC32.DLL from the Windows search.
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. The files will be in the \APPS directory (folder) created when SETUP was run, usually C:\ CSC4D\APPS.
For Win32 Delphi, add CSC32 and keycode to the "uses" clause in the application source program (*.PAS). For example,
uses
csc32, keycode, ...
Alternatively, the above "keycode" can be left out and instead the numerical keycode value (found in keycode.pas) can be pasted directly into the call to cscAttach. Also add csc32 to the project file (*.DPR). For example,
uses
csc32 in 'csc32.pas', ...
{pass the key code [0 for evaluation version]}
Code := cscAttach(1, 0, 123456789);
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;
ServerPtr : PChar;
ServerPort : Integer;
begin
GetMem(ServerPtr, 128);
StrPCopy(ServerPtr, 'mail.marshallsoft.com');
ServerPort := 5001;
Code := cscClient(ServerPtr, ServerPort);
FreeMem(ServerPtr, 128);
. . .
{call using CSC32W -- pass Delphi strings}
. . .
Code := fClient('mail.marshallsoft.com', 5001);
. . .
Several of the Client/Server Communications Library demonstration programs use the following example protocol:
"CSC Example Server"
The server responds with the following response strings when presented with the corresponding requests (REQ) from the client:
REQ Response String Request Example Response Example
WHO Sends name of the server. WHO W_SERVER
VER Sends server version #. VER 2.0
BYE OK (then disconnects) BYE OK
ECHO Sends string after "ECHO " ECHO Hello Hello
The above protocol is just an example. The programmer can create whatever protocol is required. Request strings can be any length, although it is best to keep them as short as possible..
Also refer to PROTOCOL.TXT in the \CSC4D\APPS directory.
procedure DisplayError(Memo: TMemo; ErrCode : Integer);
var
Code : Integer;
Text : String;
Ptr : PChar;
begin
if ErrCode < 0 then
begin
GetMem(Ptr, 128);
Code := cscErrorText(ErrCode, Ptr, 120);
if Code > 0 Then DisplayLine(Memo, StrPas(Ptr));
Text := Format('CSC error %d.',[ErrCode]);
FreeMem(Ptr,128);
DisplayLine(Memo,Text);
end
end;
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.
Beginning with Delphi 2003, Delphi has two "personalities": (1) Win32 Delphi and (2) Delphi for .NET. Win32 Delphi programs are a continuation of the Delphi language as seen in earlier versions of Delphi. Delphi .NET is a version of Delphi designed to use the Microsoft .NET Framework.
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 though Delphi 2009 are Borland's (Codegear) latest Delphi product with support for both Win32 and Microsoft .NET Framework. Application programs written using Delphi 2005, 2006, 2007 and 2009 will use CSC32.DLL.
When loading Win32 Delphi projects with Delphi 2005/2006/2007/2009, 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 through Delphi 2009.
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.
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 is compiled 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 \CSC4D\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. Files are encrypted when transmitted. 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. Files are decrypted when received. 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 (challenge/response) 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 (challenge/response) 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/2007/2009 for .NET equivalent of the Delphi Win32 CLIENT example program.
The Delphi 2005/2006/2007/2009 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 /2007/2006/2007/2009 NET equivalent of the Delphi Win32 SERVER example program.
The 2005/2006/2007/2009 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
Download is an example client that connects to the MarshallSoft web site (HTTP server) and downloads a file from the ./files directory.
The Download project files are:
Download_PRJ.DPR : Delphi project file.
Download_PGM.DFM : Delphi form file.
Download_PGM.PAS : Program source code.
GetPrice is an example client that demonstrates how to download stock price quotes from Yahoo.
The GetPrice project files are:
GetPrice_PRJ.DPR : Delphi project file.
GetPrice_PGM.DFM : Delphi form file.
GetPrice_PGM.PAS : Program source code.
POP3Stat is an example client that logs onto a POP3 account and returns the number of emails waiting.
The POP3Stat project files are:
POP3Stat_PRJ.DPR : Delphi project file.
POP3Stat_PGM.DFM : Delphi form file.
POP3Stat_PGM.PAS : Program source code.
uNetTime is an example UDP client that connects to a Network Time Server (on well known port 37) and gets the network time (seconds since 1 January 1900 GMT) from the server. The default server is
time-A.timefreq.bldrdoc.gov
The POP3Stat project files are:
uNetTime_PRJ.DPR : Delphi project file.
uNetTime_PGM.DFM : Delphi form file.
uNetTime.PGM.PAS : Program source code.
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
Version 5.0: October 9, 2008
Version 6.0: August 5, 2009