SMTP/POP3/IMAP Email Engine
Library for Visual FoxPro
Programmer's Manual
(SEE4FP)
Version 5.0
May 19, 2008
This software is provided as-is.
There are no warranties, expressed or implied.
Copyright (C) 2008
All rights reserved
MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815
Voice : 1.256.881.4630
email : info@marshallsoft.com
web : www.marshallsoft.com
MARSHALLSOFT is a registered trademark of MarshallSoft Computing.
1 Introduction
1.1 Features2 Library Overview
1.2 Documentation Set
1.3 Example Program
1.4 Installation
1.5 Uninstalling
1.6 Pricing
1.7 Updates
2.1 Dynamic Link Libraries3 Compiler Issues
2.2 Keycode
2.3 Win32 STDCALL and DECLSPEC
2.4 INCLUDE Files
2.5 Dynamic Strings
2.6 Null Terminated Strings
2.7 FoxPro Forms
2.8 Using Internal Memory
2.9 Error Display
3.1 Compiling Programs4 Example Programs
3.2 16-bit FoxPro
3.3 Compiling to an Executable
4.1 Connectionless Example Programs5 Revision History
4.2 SMTP Email Example Programs
4.3 POP3/IMAP Email Example Programs
4.4 IMAP-Only Email Example Programs
The SMTP/POP3/IMAP Email Engine for Visual FoxPro (SEE4FP) library is a powerful toolkit that allows software developers to quickly develop SMTP and POP3/IMAP email applications in Visual FoxPro. The SMTP/POP3/IMAP Email Engine (SEE) is a component library of functions providing 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. 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 FoxPro programming environment.
The SMTP/POP3/IMAP Email Engine for Visual FoxPro component library supports and has been tested with all versions of Visual FoxPro. SEE4FP includes numerous example programs that demonstrate SMTP and POP3/IMAP functions to help software developers easily build mail applications using the SEE4FP library.
SEE4FP runs under all versions of Windows (Windows 95, Windows 98, Windows ME, Windows 2000, Windows 2003, Windows NT, Windows XP, and Vista). The SMTP/POP3/IMAP Email Engine SDK DLL (SEE32.DLL) can also be used from any language (C/C++, .NET, Visual Basic, VB. NET, VBA, Delphi, dBASE, COBOL, PowerBASIC, Xbase++, etc.) capable of calling the Windows API.
When comparing the 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++ (SEE4C), Delphi (SEE4D), PowerBASIC (SEE4PB), dBASE (SEE4DB), Xbase++ (SEE4XB), Visual Basic (SEE4VB) and COBLOL (SEE4CB). All versions of the SEE library use the same DLL (SEE32.DLL). However, the examples provided for each version are written for the specified computer language.
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.
Some of the many features of the SMTP/POP3/IMAP Email Engine component library are as follows:
Registration includes one year of free technical support and updates.
The complete set of documentation consists of three manuals in two formats. This is the first manual (SEE4FP) in the set.
Each manual comes in three formats:
The SEE_4FP Programmer's Manual is the language specific (Visual FoxPro) manual. All language 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. The manual also contains a list of SEE error codes.
Use Microsoft Word or Microsoft WordPad to print the document files. The online documentation can be accessed on the SMTP/POP3/IMAP Email Engine for Visual FoxPro product page at:
http://www.marshallsoft.com/vfp-email-component.htm
The following example segment demonstrates the use of some of the SMTP/POP3/IMAP Email for Visual FoxPro component library functions: It is recommended that the INCLUDE statements, KEYCODE.FOX and SEE32CON.FOX, be replaced with their contents.
#INCLUDE KEYCODE.FOX
#INCLUDE SEE32CON.FOX
DECLARE INTEGER seeAttach in SEE32.DLL INTEGER NbrChans, INTEGER KeyCode
DECLARE INTEGER seeClose in SEE32.DLL INTEGER Chan
DECLARE INTEGER seeErrorText in SEE32.DLL INTEGER Chan, INTEGER Code, STRING
@Buffer,INTEGER BufLen
DECLARE INTEGER seeIntegerParam in SEE32.DLL INTEGER Chan, INTEGER Param,
INTEGER Value
DECLARE INTEGER seeRelease in SEE32.DLL
DECLARE INTEGER seeStringParam in SEE32.DLL INTEGER Chan, INTEGER Param,
STRING @Value
*** PROGRAMMER: Edit these strings [use host name or IP address for server] ***
SmtpServer = "10.0.0.1"
SmtpFrom = "<mike@10.0.0.1>"
SmtpReply = Chr(0)
SmtpTo = "<mike@10.0.0.1>"
DiagFile = "HELLO.LOG"
*** END PROGRAMMER ***
? "HELLO 5/21/2008"
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,"","","This is the subject","Message","")
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.
Note that the install process does not modify the registry.
Uninstalling SEE4FP is very easy. SEE does not modify the registry.
First, run UINSTALL.BAT, which will.SEE32.DLL from your Windows directory, typically C:\WINDOWS for Windows 95/98/Me or C:\WINNT for Windows NT/2000/XP/Vista.
Second, delete the SEE project directory created when installing SEE4FP.
A developer license for SEE4FP can be purchased for $115. Purchasing details can be found in Section _1.4 "How to Purchase" in the SEE User's Manual (SEE_USR.HTM). 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 technical support and updates.
When a developer license is purchased, the developer will be sent a set of registered DLLs plus a license file (SEExxxxx.LIC, where xxxxx is your Customer ID). The license file can be used to update the 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, your license must be updated if you want to be able to download updates. Your 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 one year, licenses can be updated for $75.
Note that registered DLL's do not expire; however, the ability to download version updates expires after one year.
Refer to the file UPDATES.TXT located in the /SEE4FP/APPS directory for more information.
The SMTP/POP3/IMAP Email component library includes 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".
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.FOX. The keycode for the evaluation (shareware) 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.
SEE32 is written in ANSI C and is compiled using the _stdcall and _declspec keywords. This means that SEE4FP 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.
All example programs contain two INCLUDE files; KEYCODE.FOX and SEE32CON.FOX. The file SEE32CON.FOX contains all the necessary constants for SEE4FP, while the file KEYCODE.FOX contains your keycode, as discussed in Section 2.2.
Since function declarations cannot be in an INCLUDE file (at least through VFP version 5.0), they are listed in each program following the two INCLUDE files (KEYCODE.FOX and SEE32CON.FOX). The complete list of function declarations is also in the file SEE32FUN.FOX
Due to the behavior of Visual FoxPro regarding INCLUDE files, it is strongly recommended that the INCLUDE files KEYCODE.FOX and SEE32CON.FOX be replaced with their contents in application programs (i.e., copy and paste contents) of the INCLUDE file.
The Visual FoxPro language uses a technique known as "garbage collection" to manage string space at runtime, and may be called internally at any time by the FoxPro 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.
All strings returned from SEE functions are null terminated. That is, the end of the string is delimited by a Chr(0) character. These strings may be converted for FoxPro in one of two ways: (1) if the length of the string is known, use the FoxPro LEFT function: For example,
* BASE64 encode
CodedBuff = SPACE(CODED_SIZE)
CodedLen = seeEncodeBuffer(@ClearBuffOne, @CodedBuff, ClearLenOne)
? "CodedBuff: ", Left(CodedBuff, CodedLen)
If the length of the null terminated string is not known, use the FoxPro AT function to find the position of Chr(0). For example,
N = seeExtractText(@Buffer, @FromText, @Temp, 255)
* extract return address
Pos = AT(":", Temp)
if Pos = 0
? "Missing ':' in 'From' or 'ReplyTo' header"
Kode = Closeup()
return
endif
SEE functions can be called from any Visual FoxPro code module, such as programs, classes, and forms. See the FROM.SCT example form.
This section applies ONLY to using DIRECT mode as discussed in Section 6 "Theory Of Operation" in the SMTP/POP3/IMAP Email User's Manual (SEE_USR).
The Visual FoxPro dynamic string management functions (as discussed in Section 2.4 above) have another side effect when running in DIRECT mode (calling seeDriver). If Visual FoxPro moves memory at runtime, then memory references by FoxPro 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 FoxPro (and other languages that do dynamic string management), you can instruct seeGetEmailLines to use its own memory:
Code = seeGetEmailLines(Chan, MessageNumber, 0, 0, max_buf_size)
If the 4th 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. Refer to the program STATUS2.PRG for an example of using seeGetEmailLines in direct mode.
The error message text associated with SEE error codes can be displayed by calling SeeErrorText. Each sample program contains examples of error processing.
Also see the file seeErrors.txt for a list of all Winsock and SEE error codes.
The SMTP/POP3/IMAP Email Engine for Visual FoxPro component library works with all versions of Visual FoxPro.
The example programs are compiled from the Visual FoxPro development environment. Before running the example programs, edit each example program with your TCP/IP email parameters, as shown in the example program in Section 1.3 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). Refer to Section 3.0 below, "Example Programs", for more details on each of the example programs.
SEE4FP no longer supports 16-bit FoxPro.
FoxPro programs end in ".PRG". They can be compiled to an executable using the FoxPro BUILD command.
For example, to create SEEVER.EXE from SEEVER.PRG in the C:\TEMP directory, type the following in the FoxPro command window:
BUILD PROJECT C:\TEMP\SEEVER FROM C:\TEMP\SEEVER
BUILD EXE C:\TEMP\SEEVER FROM C:\TEMP\SEEVER
FoxPro executables require VFP500.DLL and VFP5ENU.DLL (ENglish User), and may have to be copied from the VFP CDROM. If you are using an earlier or later version of VFP than version 5.0, substitute the appropriate DLL's for the above.
The FoxPro output display window will disappear as soon as your executable completes. In order to allow the user to control when the display window disappears, add the following code to your application, just before the final return.
? " Type any key to exit..."
X = InKey(0)
Each of the following example programs is written for 32-bit FoxPro.
Most of the example programs, with the exception of SEEVER, CODETEST, and FROM, must be edited with your TCP/IP email parameters before compiling. Refer to the SMTP/POP3/IMAP Email User's Manual (SEE_USR) for details regarding TCP/IP email parameters.
It is highly recommended that INCLUDE statements in the example programs be replaced by their contents before compiling.
Before writing your own programs, compile and run the example programs.
Several example programs do not require a connection to a server.
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 to 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.
The CODETEST example program demonstrates how to use seeEncodeBuffer and seeDecodeBuffer, which BASE64 encodes and decodes several test strings. The CODETEST example program also demonstrates the use of seeEncodeUTF8 and seeDecodeUTF8.
There are 10 SMTP example programs. SMTP programs send email using an SMTP server. Don't forget to edit the TCP/IP parameters in each program before compiling.
AUTHEN is an example program that connects to an SMTP server using SMTP Authentication. You must connect to a SMTP server that allows authentication.
AUTHEN.PRG must be edited with your email parameters 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 was received".
AUTO.PRG must be edited with your email parameters before compiling.
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.
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).
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.
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.
The ISO8859 example program sends a text message and subject line that is 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).
The MAILER example program emails a message, including an optional MIME attachment. MAILER.PRG must be edited with your email parameters before compiling.
The MAILER2 example program operates the same as the MAILER program, except that it uses the "direct" method (refer to the SMTP/POP3/IMAP Email User's Manual, (SEE_USR). The function seeDriver is called under program control.
Compare to MAILER.PRG.
The MParts example program sends a multipart MIME email in which the programmer specifies the Content-Type headers for each attachment.
The two attachment types specified in this example are a sound file (.wav) and of PDF file (.pdf).
The FORWARD example program forwards an email message to a new recipient. Only undecoded email messages can be forwarded.
There are eight POP3/IMAP email example programs. These examples read email from a POP3 (or IMAP) server.. Don't forget to edit your email parameters in each program 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 was received".
AUTO.PRG must be edited with your email parameters before compiling.
The FROM example program is similar to STATUS, except it uses a VFP form to input TCP/IP information at runtime.
From the VFP menu (File/Open), open FROM.PJX. Then, from the project manager dialog box, choose the "Build" button, then "Build Executable" for "Action". After compiling, you will be able to run FROM.EXE.
GETRAW is an example program that downloads a specified email message without decoding it (in "raw" format). This is used to examine what the email looks like on the server. GETRAW.PRG must be edited with your email parameters before compiling.
READER can read email, including multiple MIME attachments, from your POP3 server, optionally deleting each email after being read. READER can also download email without decoding. READER.PRG must be edited with your email parameters before compiling.
The STAT example program reads the number of email messages waiting on your POP3 server. STAT.PRG must be edited with your email parameters before compiling.
The STATUS example program reads the number of email messages waiting on your POP3 server, and displays the "DATE:", "FROM:", and "SUBJECT:" header fields from each email, as well as the UID for each email message. STATUS.PRG must be edited with your email parameters before compiling.
The STATUS2 example program operates the same as the STATUS program, except that it uses the "direct" method (refer to SMTP/POP3/IMAP Email User's Manual, SEE_USR). The function seeDriver is called under program control. STATUS2.PRG must be edited with your email parameters before compiling.
Compare STAT.PRG, STATUS.PRG, and STATUS2.PRG.
The POP3RD example program uses the seePop3Source function to specify an (undecoded) email message file to be read and decoded.
There are two IMAP-only example programs. These examples access the IMAP server.
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]
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
The SMTP/POP3/IMAP Email Engine DLL (SEE32.DLL) is written in ANSI C. All programming language versions of SEE (C/C++, .NET, Visual Basic, VB .NET, PowerBASIC, Visual FoxPro, Delphi, dBase, Xbase++, COBOL, and Fortran) use the same SEE32.DLL.
Version 3.0: June 10, 1999.
Version 3.1: August 3, 1999.
Version 3.2: February 14, 2000.
Version 3.3: November 13, 2000
Version 3.4: August 7, 2001
Version 3.5: March 29, 2002
Version 3.6: April 14, 2003
Version 3.7: February 10, 2005.
Version 4.0: July 3, 2006.
Version 4.0: August 10, 2006.
Version 5.0: May 19, 2008 (Win32 Version only)