1 Introduction

1.1 Documentation Set
1.2 Example Program
1.3 Installation
1.4 Uninstalling
1.5 Ordering
1.6 Updates

2 Compiler Issues

2.1 Delphi Versions
2.2 Compiling Programs
2.3 SEE4D Wrapper
2.4 Key Codes

3 Example Programs

3.1 Version
3.2 Hello
3.3 Mailer
3.4 Status
3.5 Reader
3.6 Register
3.7 Auto Respond
3.8 Get Raw

4 Revision History

1 Introduction

SEE4D is the easiest way to write email applications in Delphi !

The SMTP/POP3 Email Engine (SEE) is a library of functions providing direct and simple control of the SMTP (Simple Mail Transport Protocol) and POP3 (Post Office 3) protocols.

A simple interface allows sending and receiving email, including multiple MIME base64 and quoted- printable encoded attachments. Knowledge of Winsock and TCP/IP is not needed.

With SEE4D, you can write programs that easily:

• Send email with optional MIME attachments.
• Get the number of messages on your email server.
• Get the header lines from any email on your server, without reading the entire email.
• Delete any email on the server without reading it first.
• Receive any email on your server including MIME attachments.

Ten example programs are included, demonstrating SMTP and POP3 functions. All programs will compile using any version of Delphi.

Both Win16 and Win32 DLLs (Dynamic Link Libraries) are provided. SEE4D can be used with Windows 3.X, 95/98, and NT. The SEE4D DLLs (SEE16.DLL and SEE32.DLL) can also be used from any language (C/C++, VB, etc.) capable of calling the Windows API.

When comparing SEE against our competition, note that:

• SEE4D is a standard Windows DLL and is much smaller than a OCX or ActiveX control.
• Both WIN16 and WIN32 DLLs are included.
• SEE4D does NOT depend on ActiveX or similar "support" libraries.
• The WIN32 version of SEE is fully threadable.
• The SEE4D functions can be called from applications not capable of using controls.

1.1 Documentation Set

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

• SEE4D Programmer’s Manual (SEE4D.DOC, SEE4D.TXT, SEE4D.HTM)
• SEE User’s Manual (SEE_USR.DOC, SEE_USR.TXT, SEE_USR.HTM)
• SEE Reference Manual (SEE_REF.DOC, SEE_REF.TXT, SEE_REF.HTM)

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).

1.2 Example Program

The following example segment demonstrates the use of some of the library functions:

var
 Code : Integer;
  SmtpHost : String;
  SmtpFrom : String;
  Text : String;
  Empty : String;
  SmtpTo  : String;
begin
  Empty := Chr(0);
  SmtpHost  := 'mail.your-isp.com';
  SmtpFrom  := '<you@your-isp.com'>';
  SmtpTo    := '<someone@their-isp.com>';
  {create email message}
  Text := 'This is a test message ' + Chr(13) + Chr(10)
        + '-- marshallsoft' + Chr(13) + Chr(10);
  {attach SEE}
  Code := fAttach(1, 0);
  if Code < 0 then
    begin
      Text := Format('Cannot attach SEE (error %d)',[Code]);
      DisplayLine(send.eResult, Text);
      exit
    end;
  {connect to SMTP server}
  Code := fSmtpConnect(0,  SmtpHost, SmtpFrom, Empty);
  if Code < 0 then
    begin
      DisplayError(send.eResult, Code);
      fRelease;
      exit
    end;
  {send email}
  Code := fSendEmail(0, SmtpTo, Empty, Empty, 'Your order', Text, Empty);
  if Code < 0 then
    begin
      DisplayError(send.eResult, Code);
      exit
    end;
  {close}
  fClose(0);
  fRelease
end;

In the example program above, seeAttach is called to initialize SEE and then seeSmtpConnect is called to connect to the SMTP mail host. The SMTP server host name and your email address are required, while the "Reply-To" entry is optional.

seeSendEmail is then called, passing the addressee lists. The primary addressee is provided in the "To List". The CC ("Carbon Copy") lists additional recipients, as does the BCC (Blind Carbon Copy) list. The subject contains the email subject line. The message text is next. If it starts with the '@' symbol, it is considered the name of the file containing the email message. Lastly, the filename of any ASCII or binary attachment is specified. All fields in seeSendEmail are optional except the first.

After returning from seeSendEmail, the seeClose function is called to close the connection to the SMTP server. Lastly, seeRelease is called to perform SEE termination processing and release the Winsock.

1.3 Installation

1. Before installation of SEE4D, your Delphi compiler (any version) should already be installed on your system and tested.
   
   
2. Create your SEE4D project directory, copy the SEE4D archive, and then unzip the archive.
   
   
3. Execute INSTAL16.BAT or INSTAL32.BAT, which will copy the proper files.

   INSTAL16 : for Win16 (Delphi 1)
   

   INSTAL32 : for Win32 (Delphi 2 and above)
   

Alternatively, one can run INSTALL.BAT:

INSTALL 16 : for Win16

INSTALL 32 : for Win32

4. You're ready to compile and run!

The INSTALL.BAT program (called by INSTAL16.BAT or INSTAL32.BAT) copies SEE32.DLL (or SEE16.DLL) to either C:\WINDOWS (for Windows 3.1/95/98) or C:\WINNT (for Windows NT 4.0).

5. For a quick start, load project fileVER_PRJ.DPR

Note that the Windows registry is not modified by the install process.

1.4 Uninstalling

Uninstalling SEE4D is very easy. SEE does not modify the registry.

First, run UINSTALL.BAT, which will delete SEE16.DLL and SEE32.DLL from your Windows directory, typically C:\WINDOWS for Windows 3.1/95/98 or C:\WINNT for Windows NT.

Second, delete the SEE project directory created when installing SEE4D.

1.5 Ordering

See the section "Ordering" in the SEE User’s Manual (SEE_USR) for details on ordering.

1.6 Updates

When you register SEE4D you will receive a set of registered DLLs plus a license file (SEExxxx.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, licenses can be updated for $30 for email delivery.

2 Compiler Issues

2.1 Delphi Versions

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.

2.1.1 Delphi 1

The first release of Borland Delphi (version 1) generated Win16 code. Therefore, applications written using Delphi 1 must link with SEE16.DLL.

One very significant limitation of Delphi 1 is that strings are limited to 255 bytes. This limitation makes using the SEE wrapper unit (section 2.3) SEEW.PAS difficult. For this reason, it is suggested that SEE functions be called directly rather than through SEEW.

2.1.2 Delphi 2

Delphi version 2 and above generates Win32 code. Therefore, applications written using Delphi 2 will link with SEE32.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.

2.1.3 Delphi 3, 4, and 5.

There are no know Delphi problems impacting our example programs in Delphi version 3 and above. Applications written using Delphi 3 and above will link with SEE32.DLL

2.2 Compiling Programs

The example programs are compiled from the Delphi development environment using the provided Delphi project files (*.DPR). Be sure to run the install program (INSTAL16.BAT or INSTAL32.BAT) before compiling. See section 3.0 "Example Programs" for more details on each of the example programs.

2.3 SEE4D Wrapper

The SEEW.PAS module is a "wrapper" for SEE.PAS that allows you to pass Delphi strings directly rather than having to first convert them to PCHAR variables. Strings in SEE, like Windows itself, are in reality buffers terminated by a null (0) character. Implementing SEE in this way allows SEE functions to be called by any language capable of calling the Windows API.

Nevertheless, it is certainly more convenient to pass Delphi strings rather than zero terminated buffers. Compare the two following code segments:

{call using SEE -- 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 SEEW -- pass Delphi strings}
  . . .
  Code := fPop3Connect(0, 'mail.marshallsoft.com', 'mike', 'qwerty');
  . . .

2.4 Key Codes

SEE16.DLL and SEE32.DLL have a keycode encoded within them. Your keycode is a 9 or 10 digit decimal number (unless it is 0), and will be found in the file KEYCODE.BAS. The keycode for the shareware version is 0. You will receive a new key code when registering. Your keycode is not your customer ID.

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

3 Example Programs

Each of the following example programs uses the "display" unit and the "SEE" unit:

   DISPLAY.PAS  : Display unit source code.
   SEE.PAS      : SEE Unit source code.

The SEE.PAS code is copied from either SEE16.PAS or SEE32.PAS by the INSTALL.BAT program at installation time.

A few of the example programs also use the "SEE Wrapper" unit SEEW.PAS as described in section 2.3.

   SEEW.PAS      : SEE Wrapper unit source code.

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.

SMTP programs send email, while POP3 programs check and download mail.

3.1 VERSION

This simple program displays the SEE version number, build number, and registration string taken from SEE16.DLL or SEE32.DLL. The VERSION program does not connect to your LAN (or the Internet) .

The VERSION project files are:

VER_PRJ.DPR : Delphi project file.

VER_PGM.DFM : Delphi form file.

VER_PGM.PAS : Program source code.

3.2 HELLO

The HELLO program emails a short message. Before compiling, HELO_PGM.PAS must be edited (line

43. with your email parameters. HELLO uses the SEE wrapper unit (SEEW.PAS).

The HELLO project files are:

HELO_PRJ.DPR : Delphi project file.

HELO_PGM.DFM : Delphi form file.

HELO_PGM.PAS : Program source code.

Compare HELLO with the MAILER example program.

3.3 MAILER

The MAILER example programs emails a message, including optional MIME attachments.

The MAILER project files are:

MAIL_PRJ.DPR : Delphi project file.

MAIL_PGM.DFM : Delphi form file.

MAIL_PGM.PAS : Program source code.

Note that the MAILER program uses the "indirect" method (refer to SEE User's Manual SEE_USR). The function seeDriver is called automatically. A hour glass cursor is displayed while your email is being sent to the server.

3.4 STATUS

STATUS reads the number of email messages waiting on your POP3 server, and displays the "DATE:", "FROM:", and "SUBJECT:" header fields from each email.

The STATUS project files are:

STAT_PRJ.DPR : Delphi project file.

STAT_PGM.DFM : Delphi form file.

STAT_PGM.PAS : Program source code.

3.5 READER

STATUS can read email, including multiple MIME attachments, from your POP3 server, optionally deleting each email after being read.

The READER project files are:

READ_PRJ.DPR : Delphi project file.

READ_PGM.DFM : Delphi form file.

READ_PGM.PAS : Program source code.

Note that the READER program uses the "direct method" (refer to SEE User's Manual SEE_USR). The seeDriver is explicitly called. The progress of the incoming email is displayed.

3.6 REGISTER

REGISTER (Register Me) connects to your SMTP server in order to allow a third party (such as your customers) to send you email, such as registration information.

Before compiling, REG_PGM.PAS must be edited (line 120) with your email parameters.

The REGISTER project files are:

REG_PRJ.DPR : Delphi project file.

REG_PGM.DFM : Delphi form file.

REG_PGM.PAS : Program source code.

3.7 AUTO RESPOND

AUTO ("auto-responder") uses two channels concurrently to automatically respond to all new email. Edit your TCP/IP parameters in AUTO_PGM.PAS (line 82) before compiling. AUTO uses the SEEW.PAS wrapper unit.

The AUTO project files are:

AUTO_PRJ.DPR : Delphi project file.

AUTO_PGM.DFM : Delphi form file.

AUTO_PGM.PAS : Program source code.

3.8 GETRAW

GETRAW is an example program that downloads a specified email message without decoding it (in "raw" format). This is used to see what the email looks like on the server.

All required parameters are taken from the dialog box at runtime.

The GETRAW project files are:

GRAW_PRJ.DPR : Delphi project file.

GRAW_PGM.DFM : Delphi form file.

GRAW_PGM.PAS : Program source code.

4 Revision History

The SMTP/POP3 Email Engine DLLs (SEE16.DLL and SEE32.DLL) are written in ANSI C. All language versions of SEE (C/C++, Delphi, Delphi, PowerBASIC, FoxPro, Delphi, Xbase++, COBOL, and Fortran) use the same identical DLLs.

Version 1.0: June 22, 1998.

• Initial release.

Version 2.0: September 28, 1998.

• A major update adding POP3 capability.
• Another SMTP example program (BCAST).

Version 2.1: November 28, 1998.

• Time zone calculated automatically.
• Fixed bug in seeClose.
• Corrected POP3 problem when boundary definition on 2nd line.
• Added support for alternate MIME boundaries.
• Added seeVerifyUser function.
• Added SEE_GET_REGISTRATION, SEE_GET_CONNECT_STATUS,
• SEE_GET_ATTACH_COUNT, and SEE_GET_LAST_RESPONSE.
• Added GETDOC, SEEVER, and VERUSR example programs.
• SMTP performance improved.
• Added seeEncodeBuffer and seeDecodeBuffer functions.
• Added SEE_FILE_PREFIX and SEE_SET_REPLY parameters.

Version 3.0: April 12, 1999.

• Modified SEE to be fully threadable (adding seeAttach and seeRelease).
• Added seeGetEmailUID function.
• Handles "inline" email text properly.
• Optionally decodes unnamed attachments.
• Added ability to add header lines (SEE_SET_HEADER).
• Can use alternate ports for SMTP or POP3.
• Win16 version can get time zone from TZ environment variable.
• Quoted-printable messages can handle soft line breaks.
• Quoted-printable message can handle embedded HTML text.
• VB Class "seeClass" added.
  
  
  

Version 3.1: July 16, 1999.

• Support ISO-8859-1 (Q or B) encoded attachment filenames.
• Support ISO-8859-1 (Q only) on subject line
• SEE_SAVED_TO_MSG added.
• "+OK" line not written to email message file.
• Added seeExtractLine function.
• Added REGME example program.

Version 3.2: February 7, 2000.

• Can decode printed quotable attachments!
• seeGetEmailLines can use internal memory.
• Added SEE_WRITE_TO_LOG to seeStringParam.
• Added SEE_GET_ATTACH_NAMES to seeDebug to get attachment filename list.
• Ability to reset the SEE_SET_HEADER header string to "nothing".
• Improvements in dynamic memory usage.
• Added GETRAW and AUTO examples.
• Added seeCommand function.