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:

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:

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.

Each manual comes in three formats:

1.2 Example Program

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

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

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 User’s 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 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 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.

Version 2.0: October 2, 1998.

Version 2.1: December 9, 1998.

Version 3.0: April 5, 1999.

Version 3.1: July 21, 1999.

Version 3.2: January 24, 2000.