SMTP/POP3 Email Engine

Library for Xbase++


Programmer's Manual


(SEE4XB)


Version 3.2

February 21, 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 INCLUDE Files
2.2 Compiling and Linking Programs
2.3 Key Codes
3 Example Programs
3.1 Version
3.2 Hello
3.3 Mailer
3.4 Status
3.5 Status2
3.6 Reader
3.7 Auto
3.8 GetRaw
3.9 From
4 Revision History

1 Introduction

SEE4XB is the easiest way to write email applications in Alaska Xbase++ !

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

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

A Dynamic Link Library (SEE32.DLL) is provided. SEE4XB can be used with Windows 95, 98, and NT. The SEE4XB DLL (SEE32.DLL) can also be used from any language (C/C++, Delphi, VB, 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 (SEE4XB) in the set.

Each manual comes in three formats:

1.2 Example Program

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

#INCLUDE "DLL.CH"
#INCLUDE "KEYCODE.CH"
#INCLUDE "SEE32.CH"
*** PROGRAMMER: Edit these strings [use host name or IP address for server] ***
SmtpServer = "10.0.0.1"
SmtpFrom = "<mike@10.0.0.1>"
SmtpReply = ""
SmtpTo   = "<mike@10.0.0.1>"
DiagFile = "HELLO.LOG"
*** END PROGRAMMER ***
? "HELLO 02/19/2000"
Code = seeAttach(1, SEE_KEY_CODE)
if Code < 0
  ? "Cannot attach SEE"
  return
endif
Code = seeStringParam(0, SEE_LOG_FILE, @DiagFile)
*** set maximum connect wait to 10 seconds
Code = seeIntegerParam(0, SEE_CONNECT_WAIT, 10000)
*** connect to POP3 server
? "Connecting to " + SmtpServer
Code = seeSmtpConnect(0, @SmtpServer, @SmtpFrom, @SmtpReply)
if Code < 0
  Temp = SPACE(128)
  Code = seeErrorText(0,Code,@Temp,128)
  ? Left(Temp,Code)
else
  *** send email message
  ? "Sending email to " + SmtpTo
  Code = seeSendEmail(0,SmtpTo,"","","Hello from Xbase++","Hello from Xbase++","")
  if Code < 0
    Temp = SPACE(128)
    Code = seeErrorText(0,Code,@Temp,128)
    ? Left(Temp,Code)
  else
    ? "Email has been sent."
  endif
endif
? "Done."
Code = seeClose(0)
Code = seeRelease()
return

In the example program above, seeAttach is called to initialize SEE and then seeSmtpConnect is called to connect to the SMTP mail host. seeSendEmail is then called, passing the addressee lists. The primary addressee is provided in the "To List". 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 SEE4XB, your Xbase++ compiler (any version) should already be installed on your system and tested.

  2. Create your SEE4XB project directory, copy the SEE4XB archive, and then unzip the archive.

  3. Execute INSTALL.BAT, which will copy the proper files.

INSTALL

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

  1. You're ready to compile and run!

  2. For a quick start, load project file SEEVER.PRG

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

1.4 Uninstalling

Uninstalling SEE4XB 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 95/98 or C:\WINNT for Windows NT.

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

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 SEE4XB 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 INCLUDE Files

All example programs include two files; KEYCODE.CH and SEE32.CH. The file SEE32.CH contains all the necessary constants and function declarations for SEE4XB, while the file KEYCODE.CH contains your key code, as discussed in section 2.3 below.

The Xbase++ include file DLL.CH is also required. For example,

#INCLUDE "DLL.CH"
#INCLUDE "KEYCODE.CH"
#INCLUDE "SEE32.CH"

2.2 Compiling and Linking Programs

Before compiling any of the example programs, edit each program with your TCP/IP email parameters, as shown in the example program in section 1.2 above. Server names can be IP addresses (in decimal dot notation) or the host name. Email addresses must be enclosed in angle brackets. For more information on host names and email address formats, refer to the SEE User's Manual (SEE_USR). See section 3.0 "Example Programs" for more details on each of the example programs. To compile and link console mode programs, say EXAMPLE.PRG, use
XPP EXAMPLE.PRG
ALINK EXAMPLE.OBJ SEE32.LIB

To compile and link windows GUI programs, say EXAMPLE.PRG, use

XPP EXAMPLE.PRG
ALINK /SUBSYSTEM:WINDOWS EXAMPLE.OBJ SEE32.LIB

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.CH. The keycode for the shareware version is 0. You will receive a new key code when registering. Your keycode is not your customer ID (which is a 5 digit number).

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 example program, with the exception of SEEVER.PRG, must be editied with your TP/IP email parameters before compiling. Refer to the SEE User's Manual (SEE_USR) for details.

Refer to section 2.1 above for information on compiling and linking the example programs.

3.1 SEEVER

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

This is the first program that you should compile and run.

3.2 HELLO

The HELLO program emails a short message. HELLO.PRG must be edited with your email parameters before compiling.

Compare HELLO with the MAILER example program.

3.3 MAILER

The MAILER example program emails a message, including an optional MIME attachment. MAILER.PRG must be edited with your email parameters before compiling.

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. STATUS.PRG must be edited with your email parameters before compiling.

3.5 STATUS2

The STATUS2 example program operates the same as the STATUS program, except that it uses the "indirect" method (refer to SEE User's Manual SEE_USR). The function seeDriver is called automatically. STATUS2.PRG must be edited with your email parameters before compiling.

Compare STATUS2.PRG with STATUS.PRG.

3.6 READER

READER can read email, including multiple MIME attachments, from your POP3 server, deleting each email after being read. READER.PRG must be edited with your email parameters before compiling.

3.7 AUTO

AUTO ("auto-responder") uses two channels concurrently to automatically respond to all new email. AUTO.PRG must be edited with your email parameters before compiling.

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. GETRAW.PRG must be edited with your email parameters before compiling.

3.9 FROM

The FROM program operates like the STATUS example program, except that it uses an Xbase++ form to enter the POP3 server, user, and password.

The FROM program must be linked as a GUI (rather than console mode) application:

XPP FROM.PRG
ALINK /SUBSYSTEM:WINDOWS FROM.OBJ SEE32.LIB


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

Version 3.1: February 21, 2000.