MarshallSoft

SMTP/POP3/IMAP Email Engine

Library for Visual dBase


Programmer's Manual


(SEE4DB)


Version 5.2

March 27, 2010

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



Copyright (C) 2010
All rights reserved



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


Email: info@marshallsoft.com

Web: www.marshallsoft.com


MARSHALLSOFT is a registered trademark of MarshallSoft Computing.




TABLE OF CONTENTS


1 Introduction
1.1 Features
1.2 Documentation Set
1.3 Example Program
1.4 Installation
1.5 Uninstalling
1.6 Pricing
1.7 Updates
2 Library Overview
2.1 Dynamic Link Libraries
2.2 Keycode
2.3 Win32 STDCALL and DECLSPEC
2.4 INCLUDE Files
2.5 Visual dBase 5.6 and 5.7
2.6 Visual dBase 7.0 and above
2.7 Dynamic Strings
2.8 Using Internal Memory
2.9 Error Display
3 Compiler Issues
3.1 Compiling dBase Programs
3.2 Compiling dBase Projects
3.3 Creating Executables
4 Example Programs
4.1 Connectionless Example Programs
4.2 SMTP Example Programs
4.3 POP3/IMAP Example Programs
4.4 IMAP-Only Example Programs
5 Revision History

1 Introduction

The SMTP/POP3/IMAP Email Engine for Visual dBASE (SEE4DB) library is a toolkit that allows software developers to quickly develop SMTP and POP3/IMAP email applications in Visual dBASE or dBASE Plus.

The SMTP/POP3/IMAP Email Engine (SEE) is a component DLL library of functions that uses the Windows API to provide direct and simple control of the SMTP (Simple Mail Transport Protocol), POP3 (Post Office 3), and IMAP 4 (Internet Message Access Protocol) protocols.

A straightforward interface allows sending and receiving email, including multiple MIME base64 and quoted-printable encoded attachments, over any TCP/IP network (such as the Internet). Knowledge of Winsock and TCP/IP is not needed.

The SMTP/POP3/IMAP Programmer's Manual provides information needed to compile and run programs in a Visual dBASE or dBASE Plus programming environment.

The SMTP/POP3/IMAP Email Engine for Visual dBASE component library supports all Win32 (dBASE 7.0, 7.5 and dBASE Plus) versions of dBASE. SEE4DB includes numerous example programs that demonstrate SMTP and POP3/IMAP email functions used to create mail applications using the SEE4DB library.

SEE4DB runs under all versions of Windows (Windows 95, Windows 98, Windows ME, Windows 2000, Windows 2003, Windows NT, Windows XP, Windows Vista and Windows 7). The SMTP/POP3/IMAP Email Engine SDK DLLs (SEE32.DLL or SEE64.DLL) can also be used from any language (C/C++, .NET, Visual Basic, VB. NET, VBA, Delphi, Visual FoxPro, COBOL, PowerBASIC, Xbase++, etc.) capable of calling the Windows API.

When comparing SMTP/POP3/IMAP Email component library against our competition, note that:

MarshallSoft also has versions of the SMTP/POP3/IMAP Email Engine library for C/C++ and .NET (SEE4C), Delphi (SEE4D), PowerBASIC (SEE4PB), Visual FoxPro (SEE4FP), Xbase++ (SEE4XB), COBOL (SEE4CB) and Visual Basic or VB.NET (SEE4VB). All versions of the SEE library use the same DLLs (SEE32.DLL or SEE64.DLL). However, the examples provided for each version are written for the specified programming environment.

The latest versions of SMTP/POP3/IMAP Email Engine (SEE) can be downloaded from our web site at

     http://www.marshallsoft.com/email-component-library.htm

Our goal is to provide a robust SMTP/POP3/IMAP email component library that you and your customers can depend upon. A fully functional evaluation version is available. Contact us if you have any questions.


1.1 Features

Some of the many features of SMTP/POP3/IMAP Email Engine component library are as follows:

Registration includes one year of free updates and technical support.

1.2 Documentation Set

The complete set of documentation consists of three manuals in Adobe PDF format. This is the first manual (SEE_4DB) in the set.

The SEE_4DB Programmer's Manual is the language specific (Visual dBase) manual. All dBASE dependent programming issues such as compiling, compilers and example programs are discussed in this manual.

The SEE User's Manual (SEE_USR) discusses email processing as well as language independent programming issues. Purchasing and license details are also provided.

The SEE Reference Manual (SEE_REF) contains details on each individual SEE function as well as error codes.

The online documentation can be accessed on the SMTP/POP3/IMAP Email Engine for Visual dBase product page at:
   
     http://www.marshallsoft.com/dbase-email-component.htm
   


1.3 Example Program

The following example segment demonstrates the use of some of the SMTP/POP3/IMAP Email for Visual dBase component library functions:

     #INCLUDE KEYCODE.CC
     #INCLUDE SEE32.CC
   
     *** 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 8/08/2006"
     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 30 seconds
     Code = seeIntegerParam(0, SEE_CONNECT_WAIT, 30000)
     *** 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,"","","Example Program","Hello from dBase","")
       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, except the first, in seeSendEmail are optional.

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.4 Installation

  1. Before installation of SEE4DB, a dBASE compiler (any 32-bit version) should already be installed on your system and tested.

  2. Unzip SEE4DB52.ZIP (evaluation version) or SEExxxxx.ZIP (registered version where xxxxx is your Customer ID) using any Windows unzip program.

  3. Run the installation program, SETUP.EXE, which will install all SEE4DB files and copy SEE32.DLL to your Windows directory. No Windows system files are modified.

The SETUP installation program creates three sub-directories (default \SEE4DB) as follows:

     DOCS - All documentation files
     APPS - All example code
     DLLS - All DLL's

  1. You're ready to compile and run! For a quick start, load the project file SEEVER.PRG Note that the install process does not modify the registry.

1.5 Uninstalling

Uninstalling SEE4DB is very easy since 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.X/95/98/Me/2003/XP/Vista/Win7 or C:\WINNT for Windows NT/2000. Second, delete the SEE project directory created when installing SEE4DB.

1.6 Pricing

A developer license for SEE4DB can be purchased for $115 USD. Purchasing details can be found in the SEE User's Manual, Section_1.4, "How to Purchase", ( http:/www.marshallsoft.com/see_usr.htm#Section_1.4 )

Also see INVOICE.TXT provided with the evaluation version or order directly on our web site at
   
     http://www.marshallsoft.com/order.htm
   
Registration includes one year of free updates and technical support.  Purchased SEE DLLs never expire.

1.7 Updates

When a developer license is purchased, the developer will be sent a registered DLL plus a license file (SEExxxxx.LIC, where xxxxx is your Customer ID). The license file can be used to update the registered DLL for a period of one year from purchase. Updates can be downloaded from

   
     http://www.marshallsoft.com/update.htm
   

After one year, the developer license must be updated to be able to download updates. The license can be updated for $30 if ordered within one year of the original purchase (or previous update). Between one year and three years, licenses can be updated for $55. After three years, updates are $75.

Note that registered DLL does not expire; however, the ability to download version updates expires after one year. Refer to the file UPDATES.TXT located in the /SEE4DB/DOCS directory for more information.

2 Library Overview

The SMTP/POP3/IMAP Email component library has been tested on multiple computers running Windows 95/98/Me/XP/2003/Vista/Windows 7 and Windows NT/2000.

The SEE4DB library has been tested and works with all versions of 32-bit Visual dBASE and dBASE Plus.

2.1 Dynamic Link Libraries

The SMTP/POP3/IMAP Email component library uses a Win32 dynamic link library (DLL). A DLL is characterized by the fact that it need not be loaded until required by an application program and that only one copy of the DLL is necessary regardless of the number of application programs that use it. Contrast this to the traditional static library that is bound to each and every application that uses it at link time.

An important advantage that DLL's have over other "popular" library formats such as VBX or OCX is that DLL's are callable by all Windows applications. Since DLL's are the building blocks of the Windows Operating System, they will not be replaced by a "newer technology".

2.2 Keycode

SEE32.DLL has a keycode encoded within it. Your keycode is a 9 or 10-digit decimal number (unless it is 0), and will be found in the file KEYCODE.CC. The keycode for the evaluation version is 0. You will receive a new keycode and a new SEE32.DLL after purchasing or updating a developer license. The KEYCODE is passed to SeeAttach.

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 evaluation version of the SEE32.DLL from the Windows search path or delete it.

2.3 Win32 STDCALL and DECLSPEC

SEE32 is written in ANSI C and is compiled using the _stdcall and _declspec keywords. This means that SEE4DB uses the same calling conventions and file naming conventions as the Win32 API. In particular, function names are NOT decorated. There are neither leading underscores nor trailing "@size" strings added to function names.

Any Windows application program may call the SEE32 library provided that the proper declaration file is used.

2.4 INCLUDE Files

All example programs include two files; KEYCODE.CC and SEE32.CC. The file SEE32.CC contains all the necessary constants and function declarations for SEE4DB, while the file KEYCODE.CC contains your key code.

There are three recommended ways to handle these INCLUDE files in dBase programs.

  1. Copy the INCLUDE files to the dBASE compiler's INCLUDE directory.
  2. Edit the INCLUDE statements (for each program) with their physical location.
  3. Replace the INCLUDE statements (in each program) by their contents.


2.5 Visual dBase 5.6 and 5.7

SEE4DB does not support Win16 applications.

2.6 Visual dBase 7.0 and above

Visual dBase 7.0 and above, including dBASE Plus, create 32-bit applications, and use the 32-bit DLL, SEE32.DLL. Copy the 32-bit CC file, SEE32.CC to the dBASE compiler's INCLUDE directory.

2.7 Dynamic Strings

The Visual dBase language uses a technique known as "garbage collection" to manage string space at runtime, and may be called internally at any time by the dBase runtime, asynchronous to what you may be doing in your code.

When passing a string buffer to a DLL function into which text will be copied, it is strongly recommended that the local string be allocated immediately before use. For example:

     Code = seeSmtpConnect(0,SmtpServer,SmtpFrom,SmtpFrom)
     if Code < 0
       * allocate buffer just before call
       Temp = SPACE(128)
       * put text in Temp
       Code = seeErrorText(1,Code,Temp,128)
       ? Left(Temp,Code)
     endif

This technique is not necessary for passing a string to a DLL function, only when passing a buffer to a DLL into which data is to be placed by the DLL function.

2.8 Using Internal Memory

This section applies ONLY to using DIRECT mode as discussed in the section "Theory of Operation" in the SMTP/POP3/IMAP User's Manual (SEE_USR).

The dBASE dynamic string management functions (as discussed in Section 2.7 above) have another side effect when running in DIRECT mode (calling seeDriver). If Visual dBase moves memory at runtime, then memory references by dBase will use the new (moved) memory location, although SEE itself will still be using the original memory location previously passed to it. To work around this problem with Visual dBase (and other languages that do dynamic string management), seeGetEmailLines can be instructed to use its own memory:

Code = seeGetEmailLines(Chan, MessageNumber, 0, 0, max_buf_size)

If the fourth argument is 0, SEE will use its own memory. After seeDriver has been called to completion, the internal buffer can be copied by calling

Buffer = SPACE(max_buf_size)

Code = seeDebug(0, SEE_COPY_BUFFER, Buffer, max_buf_size)

seeGetEmailLines is the only function, which requires this technique, since there is no reason to use direct mode in other functions (such as seeErrorText) that use return buffers. See the program STATUS2.PRG for an example of using seeGetEmailLines in direct mode.


2.9 Error Display

Every SEE functions returns an integer value. Negative return values are always errors.

The error message text associated with SEE error codes can be found by calling SeeErrorText. Each sample program contains examples of error processing. For example,

     *(assume ErrCode < 0 is returned by a SEE function)
     Temp = SPACE(128)
     * copy SEE error text to 'Temp'
     Code = seeErrorText(0, ErrCode, Temp, 128)
     * displat the error
     ? Left(Temp, Code)

Also see the file seeErrors.txt for a list of all Winsock and SEE error codes.


3 Compiler Issues

The SMTP/POP3/IMAP Email Engine for Visual dBase component library supports all versions of 32-bit dBASE (Version 7.0, Version 7.5 and dBASE Plus).

3.1 Compiling dBase Programs

dBASE programs end with the extension ".PRG". Before compiling any of the example programs, edit them with your email parameters. Programs can be edited within any text editor, and compiled from the dBASE command window with the COMPILE command (e.g.: COMPILE STATUS.PRG) or executed from the dBASE command window with the DO command (e.g.: DO STATUS.PRG).

To open a program within Visual dBase source editor, choose "File", then "Open". When the "Open File" dialog box appears, choose "Programs" for "Files of Type", then choose the program (*.PRG) to open. Lastly, choose "Open in Source Editor" for "Action" and push the "Open" button.

After editing the source program with your internet (or TCP/IP) parameters, you are ready to compile. From the dBase menu bar, choose "Build", then "Compile". To run choose, "Run". The dBASE command window must be displayed in order to view the output.

3.2 Compiling dBase Projects

Visual dBase projects consist of several types of files such as forms, reports, data modules, etc. The project file itself ends with the extension of ".PRJ".

There are two example dBase projects (QUICK and FROM). Open QUICK (or FROM) by choosing "File", then "Open Project" from the dBase menu bar. To compile QUICK , choose "Build" from the menu bar, then "Rebuild All". This will create QUICK.EXE, which can be executed by choosing "Execute quick.exe" from the "Build" menu bar pulldown, or from the Windows command line prompt.

3.3 Creating Executables

dBASE programs end in ".PRG". They can be compiled to an executable using the dBase BUILD command.

For example, to create SEEVER.EXE from SEEVER.PRG in the C:\SEE4DB\APPS directory, type the following in the dBase command window:

     BUILD PROJECT C:\SEE4DB\APPS\WSCVER FROM C:\SEE4DB\APPS\WSCVER
     BUILD EXE C:\SEE4DB\APPS\WSCVER FROM C:\SEE4DB\APPS\WSCVER


4 Example Programs

Each example program, with the exception of SEEVER.PRG, must be edited with your TCP/IP email parameters before compiling. Refer to the SMTP/POP3/IMAP User's Manual (SEE_USR) for details on email parameters.

Before writing your own programs, compile and run several of the example programs.

4.1 Connectionless Example Programs

Several example programs do not require a connection to a server.

4.1.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). Its purpose is display the SEE version, build, and registration string as well as to verify that SEE32.DLL is being found and loaded by Windows.

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

4.1.2 CODETEST

The CODETEST example program demonstrates how to use seeEncodeBuffer and seeDecodeBuffer, which BASE64 encodes and decodes several test strings.


4.2 SMTP Example Programs

There are thirteen (13) SMTP email example programs. SMTP programs send email using an SMTP server.

4.2.1 AUTHEN

AUTHEN is an example program that connects to an SMTP server using SMTP Authentication. You must connect to an SMTP server that allows authentication.

AUTHEN.PRG must be edited with your email parameters before compiling.

4.2.2 AUTO

AUTO ("auto-responder") uses two channels to read email on the POP3 server and at the same time automatically responds to all new email using the SMTP server. AUTO.PRG must be edited with your email parameters before compiling.

4.2.3 BCAST

The BCAST example program emails the same message (BCAST.TXT) to a list of addresses taken from the file, BCAST.EML, containing one email address per line. 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 BCAST.EML for an example.

4.24 FORWARD

The FORWARD example program forwards an email message to a new recipient. Only undecoded email messages can be forwarded.

Undecoded email message can be downloaded using the GETRAW and READER example programs.

4.2.5 GB2312

The GB2312 example program sends a text message that is GB2312 (simplified Chinese) encoded. The recipient's email client will be able to display the email message using the specified GB2312 character set provided that it is capable of identifying GB2312 MIME parts (such as MS OutLook).

4.2.6 GmailMVP (Gmail Via Proxy)

The GmailMVP (Gmail Mailer Via Proxy) example console mode program emails a specified email message connecting to a GMAIL account via the (free) STUNNEL proxy server, which is started and terminated without user intervention. See gmail.txt in the DOCS directory or http://www.marshallsoft.com/gmail.htm for more information on STUNNEL.

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


4.2.8 HTML

The HTML example program connects to an SMTP server and emails an HTML file (TEST.HTM) containing inline graphics (IMAGE1.GIF and IMAGE2.GIF). The graphics files are attached to the HTML email message.

HTML.PRG must be edited with your email parameters before compiling.

4.2.9 ISO8859

The ISO8859 example program sends a text message and subject line that are ISO-8859 encoded. The recipient's email client will be able to display the email message using the specified ISO character set provided that it is capable of identifying ISO-8859 MIME parts (such as MS OutLook).

4.2.10 MAILER

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

4.2.11 MAILER2

The MAILER2 example program operates the same as the MAILER program, except that it uses the "direct" method of calling seeDriver. MAILER2.PRG must be edited with your email parameters before compiling.

4.2.12 MPARTS

The MParts example program sends a multipart MIME email in which the Content-Type headers for each attachment are specified by the programmer.

The two attachment types specified in this example are a sound file (.wav) and a PDF file (.pdf).

4.2.13 QUICK

QUICK is similar to MAILER, except that it accepts all necessary Internet TCP/IP settings using a form at runtime. QUICK is organized as a dBASE project.


4.3 POP3/IMAP Example Programs

There are nine (9) POP3/IMAP example programs. These examples read email using a POP3 or IMAP server. Each example program, except FROM.PRG, must be edited with your email parameters before compiling.

4.3.1 AUTO

AUTO ("auto-responder") uses two channels concurrently to automatically respond to all new email.

4.3.2 FROM

FROM is similar to STATUS, except that it accepts all necessary Internet TCP/IP settings using a form at runtime. FROM is organized as a dBASE project.

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

4.3.4 GmailSVP

The GmailSVP (Gmail Status Via Proxy) example console mode program reads the status of each email message on a GMAIL account via the (free) STUNNEL proxy server. See gmail.txt in the DOCS directory or http://www.marshallsoft.com/gmail.htm for more information on STUNNEL.

4.3.5 READER

READER can read email, including multiple MIME attachments, from your POP3/IMAP server, deleting each email after being read.

4.3.6 POP3RD

The Pop3Read example program uses the seePop3Source function to specify an (undecoded) email message file to be read and decoded. There is no connection to any server.

Undecoded email message can be downloaded using the GETRAW and READER example programs.

4.3.7 READER2

The READER2 example program operates the same as the READER program, except that it uses the "direct" method of calling seeDriver.

4.3.8 STATUS

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

4.3.9 STATUS2

The STATUS2 example program operates the same as the STATUS program, except that it uses the "direct" method of calling seeDriver.


4.4 IMAP-Only Example Programs

There are two IMAP-only example programs. These examples access the IMAP server.

4.4.1 ImapFlagsT

The ImapFlagsT example program tests the manipulation of flags on the IMAP server. It reads, sets, and deletes certain flags for the specified email message on the IMAP server.

IMAP flags are:

     \Seen      Message has been read
     \Answered  Message has been answered
     \Flagged   Message is "flagged" for urgent/special attention
     \Deleted   Message is "deleted" for removal by later EXPUNGE
     \Draft     Message has not completed composition (marked as a draft).
     \Recent    Message has arrived since the previous time this mailbox was
                selected. ["\Recent" may be fetched but not stored]

4.4.2 ImapSearch

The ImapSearch example program tests IMAP search capability.

See ImapSearch.txt or http://www.marshallsoft.com/ImapSearch.htm for a complete list of all IMAP search strings.

Example search strings as passed to seeImapSearch():

     SEEN
     SEEN NOT ANSWERED
     FLAGGED SINCE 1-Feb-2008 NOT FROM "Smith"
     LARGER 10000 NOT SEEN

5 Revision History

The SMTP/POP3/IMAP Email Engine DLLs (SEE32.DLL) is written in ANSI C. All programming language versions of SEE (C/C++, Visual Basic, PowerBASIC, Delphi, Visual dBase, Visual dBase, Xbase++, COBOL, and Fortran) use the same identical DLL.

Version 3.0: May 10, 1999.

Version 3.1: August 5, 1999.

Version 3.2: February 17, 2000.

Version 3.3: November 29, 2000

Version 3.4: August 10, 2001

Version 3.5: April 4, 2002

Version 3.6: April 14, 2003

Version 3.7: February 17, 2005.

Version 4.0: August 8, 2006.

Version 5.0: May 22, 2008 (Win32 Version only)

  1. seeImapConnect : Connect to IMAP server.
  2. seeImapFlags : Get, set, or delete message flags.
  3. seeImapSearch : Search for messages with specified flags.
  4. seeImapMsgNumber : Gets message numbers from buffer filled by seeImapSearch.
  5. seeImapSelectMB : Selects IMAP mailbox.
  6. seeImapDeleteMB : Delete a mailbox.
  7. seeImapCreateMB : Create a new mailbox.
  8. seeImapRenameMB : Rename mailboxes.
  9. seeImapCopyMBmail : Copy messages from selected mailbox to specified mailbox.
  10. seeImapListMB : List all available mailboxes.

Version 5.1: May 28, 2009 (Win32 and Win64 (x64)) versions

Version 5.2: March 27, 2010 (Win32 and Win64) versions