SMTP/POP3 Email Engine
Library for PowerBASIC


Programmer's Manual


(SEE4PB)


Version 3.2

January 24, 2000


This software is provided as-is.
There are no warranties, expressed or implied.



Copyright (C) 2000
All rights reserved



MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815



Voice : 256-881-4630
FAX :  256-880-0925
email : info@marshallsoft.com
web : www.marshallsoft.com



MarshallSoft is a member of the Association of Shareware Professionals

MARSHALLSOFT is a registered trademark of MarshallSoft Computing.


TABLE OF CONTENTS


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 Compiling Programs          
    2.2 Include Files               
  2.3 Key Code                    
3 Example Programs                
  3.1 SMTP Example Programs       
  3.2 POP3 Example Programs       
4 Revision History                

1  Introduction

SEE4PB is the easiest way to write email applications in PowerBASIC !

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 SEE4PB, you can write programs that easily:

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

Twelve example programs are included, demonstrating SMTP and POP3 functions.  All programs will 
compile using PBCC v1.0 and PBCC v2.0.

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

When comparing SEE against our competition, note that:

o SEE4PB is a standard Windows DLL and is much smaller than a OCX or ActiveX control. 
o SEE4PB does NOT depend on ActiveX or similar "support" libraries. 
o SEE4PB (SEE32.DLL) is fully threadable. 
o The SEE4PB 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 
(SEE4PB) in the set.

o SEE4PB Programmers Manual (SEE4PB.DOC, SEE4PB.TXT, SEE4PB.HTM) 
o SEE Users Manual (SEE_USR.DOC, SEE_USR.TXT, SEE_USR.HTM) 
o SEE Reference Manual (SEE_REF.DOC, SEE_REF.TXT, SEE_REF.HTM) 

Each manual comes in three formats:

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

1.2  Example Program

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

_BEGIN_CODE
   Dim Code As Integer
   Dim Server, IsNull, To, From As Asciiz * 64
   Dim Subject, Message As Asciiz * 64
   IsNull  = Chr$(0)
   Server  = "mail.yourisp.com
   From = "my name<me@myisp.com>"
   To   = "<mike@marshallsoft.com>"
   Subject = "PowerBASIC Test"
   Message = "Emailed from SEE4PB!"
   Code = seeAttach(1, %SEE_KEY_CODE)
   If Code < 0 Then
     ' error calling seeAttach !
     . . .
   End If
   Code = seeSmtpConnect(Server,From,IsNull)
   If Code < 0 Then
     ' error calling seeSmtpConnect !
     . . .     
   End If   
   Code = seeSendEmail(To,IsNull,IsNull,Subject,Message,IsNull)
   If Code < 0 Then
     ' error calling seeSendEmail !
     . . .
   End If
   Code = seeClose()
   Code = seeRelease()
_END_CODE

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 SEE4PB, your PowerBASIC console compiler (or PB/DLL compiler) should 
already be installed on your system and tested.

(2) Create your SEE4PB project directory, copy the SEE4PB archive, and then unzip the archive.

(3) Run INSTALL.BAT which will copy SEE32 to either C:\WINDOWS or C:\WINNT.

(4) Edit the include file EMAIL.INC with your TCP/IP parameters.

(5) You're ready to compile! 

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

1.4  Uninstalling

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

First, run UINSTALL.BAT, which will delete 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 SEE4PB.

1.5  Ordering

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

1.6  Updates

When you register SEE4PB you will receive a set of registered DLLs plus a license file (SEExxxx.LIC) 
that can be used to update your registered DLLs 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 Compiling Programs

The twelve example programs are compiled at the command line with the PowerBASIC Console 
Compiler:

   PBCC AUTO.BAS
   PBCC BCAST.BAS
   PBCC DELETE.BAS
   PBCC GETRAW.BAS
   PBCC MAILER.BAS
   PBCC READER.BAS
   PBCC REGME.BAS
   PBCC SEEVER.BAS
   PBCC STAT.BAS
   PBCC STATUS.BAS
   PBCC TSTAT.BAS
   PBCC VERUSR.BAS

PBCC programs (such as TSTAT.BAS) that reference WINAPI.INC must specify the WINAPI directory 
on the comand line. For example, if your PowerBASIC Console Compiler is installed at C:\PBCC, you 
would compile TSTAT with

   PBCC TSTAT.BAS -IC:\PBCC\WINAPI

Also see section 3 "Example Programs" for more information on each of the example programs.

2.2  Include Files

There are three include files. The first two are included by all example programs.

SEE32.PBI -- Contains the function declarations for SEE32.DLL.
KEYCODE.PBI -- Contains your key code. See the following section.
GETARGS.PBI -- Read and parses command line arguments.

2.3  Key Codes

SEE32.DLL has a keycode encoded within it. Your keycode is a 9 or 10 digit decimal number (unless it is 
zero), and will be found in the file KEYCODE.PBI. The keycode for the shareware version is 0. You will 
receive a new key code when registering.

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. Your customer ID (4 or 5 digit number) is NOT your 
key code! After registering, it is best to remove the shareware version of the SEE DLL's from the 
Windows search path.

3  Example Programs

Before compiling the example programs, edit the include file EMAIL.INC with your SMTP/POP3 host 
and email address. Refer to section "Your SMTP/POP3 Host Name" in the SEE User's Manual 
(SEE_USR) for more information on SMTP/POP3 server names.

SEEVER displays the SEE version number and the SEE registration string. It does not require a 
connection. Compile this program first to verify your installation of SEE4PB. SEEVER takes no command 
line arguments.

3.1  SMTP Example Programs

There are five SMTP example programs. SMTP programs send email.  Don't forget to edit EDMAIL.INC 
before compiling.

3.1.1  AUTO

AUTO ("auto-responder") uses two channels concurrently to automatically respond to all new email.  
AUTO will read (but not delete) all email on your server and reply to each that "your email wsas received".

AUTO (and TSTAT) are the only example programs that use more than one channel concurrently.

3.1.2  MAILER

MAILER emails a message, including optional MIME attachments. All required parameters are input 
using a dialog box at runtime.

For example, to mail TEST.MAI with attachment TEST.ZIP to mike@marshallsoft.com with subject 
"TEST":

   MAILER  "@test.mai"  TEST  "<mike@marshallsoft.com>"  test.zip

Note that <> brackets are required around the email address.

3.1.3  BCAST

BCAST (Broadcast) emails the same message to each recipient from a file of email addresses. Along with 
your SMTP server and your email address, you must create the file containing the email message to send, 
and create another file containing the list of recipients. See EMAIL.LST for an example.

Please DO NOT use this for spam! 

3.1.4  RegMe

RegMe (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. RegMe takes no command line arguments.
Edit REGME.BAS before compiling.

3.1.5  VERUSR

VERUSR (Verify User) connects to a specified SMTP server and requests verification of the user.

Due to security concerns, some SMTP servers will not honor a "verify user" request. A user that does not 
verify does NOT necessarily mean that the email address is not good.

3.2  POP3 Example Programs

There are five POP3 example programs. These examples read email.  Don't forget to edit EDMAIL.INC 
before compiling.

3.2.1  STAT

The STAT program is the simpliest POP3 example. It logs onto the POP3 server and get the number of 
messages waiting. 

STAT takes no command line arguments.

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

STATUS takes no command line arguments.

3.2.2  READER

READER reads an email message from your server, including any MIME attachments. The email message 
is saved as a file.

For example, to read message 1 to file FILE1.TXT,  type

   READER  1  FILE1.TXT

3.2.4 GETRAW

GETRAW is a program that downloads a specified email message without decoding it. This is used to see 
what the email looks like on the server.

For example, to download message 2 from the POP3 account mail.myisp.com as user "mike" and 
password "qwerty", type

   GETRAW  "mail.myisp.com"  "mike"  "qwerty"  2

3.2.5  TSTAT

TSTAT checks several POP3 mailboxes using multiple threads. Edit TSTAT.BAS with the POP3 accounts 
to check before compiling. Note that since TSTAT references the WINAPI directory, it must appear on the 
command line. For example (assuming PBCC is installed at C:\PBCC):

   PBCC TSTAT.BAS -IC:\PBCC\WINAPI

TSTAT takes no command line arguments. Be sure to edit TSTAT.BAS before compiling.


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, Visual Basic, PowerBASIC, FoxPro, Delphi, Xbase++, COBOL, and 
Fortran) use the same identical DLLs.

Version 1.0: June 22, 1998.

o Initial release (for C/C++). 

Version 2.0: October 2, 1998.

o Initial PBCC release. 

Version 2.1: December 9, 1998.

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

Version 3.0: April 5, 1999.

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

Version 3.1: July 21, 1999.

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

Version 3.2: January 24, 2000.

o Added QUOTED_8859 processing (QUOTED_8859). 
o Can decode printed quotable attachments! 
o seeGetEmailLines can use internal memory. 
o Added SEE_WRITE_TO_LOG to seeStringParam. 
o Added SEE_GET_ATTACH_NAMES to seeDebug to get attachment filename list. 
o Ability to reset the SEE_SET_HEADER header string to "nothing". 
o Improvements in dynamic memory usage. 
o Added GETRAW and CODETEST examples. 
o Added support for Lcc-Win32. 
o Added seeCommand function. 

