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.
1 Introduction
1.1 Documentation Set2 Compiler Issues
1.2 Example Program
1.3 Installation
1.4 Uninstalling
1.5 Ordering
1.6 Updates
2.1 Compiling Programs 2.2 Include Files3 Example Programs
2.3 Key Code
3.1 SMTP Example Programs4 Revision History
3.2 POP3 Example Programs
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:
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:
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.
Note that the Windows registry is not modified during the install process.
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.
See the section "Ordering" in the SEE User’s Manual (SEE_USR) for details on ordering.
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.
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.
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.
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.
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.
There are five SMTP example programs. SMTP programs send email. Don't forget to edit EDMAIL.INC before compiling.
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.
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.
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!
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.
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.
There are five POP3 example programs. These examples read email. Don't forget to edit EDMAIL.INC before compiling.
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.
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.
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
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
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.
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.