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.
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 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.1 Compiling dBase Programs4 Example Programs
3.2 Compiling dBase Projects
3.3 Creating Executables
4.1 Connectionless Example Programs5 Revision History
4.2 SMTP Example Programs
4.3 POP3/IMAP Example Programs
4.4 IMAP-Only Example Programs
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.
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.
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
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.
The SETUP installation program creates three sub-directories (default \SEE4DB) as follows:
DOCS - All documentation files
APPS - All example code
DLLS - All DLL's
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.
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.
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.
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.
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".
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.
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.
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.
SEE4DB does not support Win16 applications.
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.
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.
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.
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.
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).
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.
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.
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
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.
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 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.
There are thirteen (13) SMTP email example programs. SMTP programs send email using an SMTP server.
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.
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.
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.
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 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.
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 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).
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 of calling seeDriver. MAILER2.PRG must be edited with your email parameters before compiling.
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).
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.
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.
AUTO ("auto-responder") uses two channels concurrently to automatically respond to all new email.
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.
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.
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.
READER can read email, including multiple MIME attachments, from your POP3/IMAP server, deleting each email after being read.
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.
The READER2 example program operates the same as the READER program, except that it uses the "direct" method of calling seeDriver.
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
The STATUS2 example program operates the same as the STATUS program, except that it uses the "direct" method of calling seeDriver.
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 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)
Version 5.1: May 28, 2009 (Win32 and Win64 (x64)) versions
Version 5.2: March 27, 2010 (Win32 and Win64) versions