SMTP/POP3/IMAP Email Engine
Library for C/C++
Programmer's Manual
(SEE4C)
Version 5.0
April 8, 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 (License Key)
2.3 Console Mode
2.4 Using the Library
2.5 Win32 STDCALL and DECLSPEC
2.6 Using Threads
2.7 Calling SEE from Visual C++
2.8 Adding SEE Functions to an Existing Program
2.9 Error Display
2.10 Explicitly Loading SEE32.DLL
3.1 Compiling Using an IDE4 Supported Compilers
3.2 Command Line Tool Setup
3.3 Command Line Batch Files
3.4 Command Line Makefiles
4.1 Microsoft Visual C++5 Compiling Example Programs
4.2 Microsoft Visual Studio C++
4.3 Microsoft Visual Studio C#
4.4 Borland C/C++
4.5 Turbo C/C++ for Windows
4.6 Borland C++ Builder
4.7 Watcom C/C++
4.8 LCC-Win32 C
5.1 Static Libraries6 Example Programs
5.2 Editing EMAIL.H
6.1 Connectionless Example Programs7 Revision History
6.2 SMTP Example Programs
6.3 POP3/IMAP Example Programs
6.4 IMAP-Only Example Programs
The SMTP/POP3/IMAP Email Engine for C/C++ (SEE4C) library is a toolkit that allows software developers to quickly develop SMTP and POP3/IMAP email applications in C/C++.
The SMTP/POP3/IMAP Email Engine (SEE) is a component 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 straight forward interface allows sending and receiving email, including multiple MIME base64 and quoted-printable encoded attachments. Knowledge of Winsock and TCP/IP is not needed.
SEE4C includes twenty-eight C/C++ example programs, including Visual Studio C++ and Visual Studio C#, which demonstrate SMTP and POP3/IMAP email functions. Microsoft Foundation Class (MFC) and Borland C++ Builder (BCB) examples are also provided.
The SMTP/POP3/IMAP Email Engine for C/C++ component library supports and has been tested with C/C++, Microsoft Visual C++, Visual Studio .NET Framework (Visual C++ .NET, C# .NET), Borland C/C++, Borland Turbo C++ for Windows, Borland C++ Builder, Watcom C/C++, and LCC-Win32 C compilers. SEE4C can also be used with most other C/C++ Windows compilers.
This SMTP/POP3/IMAP Users Manual provides information need to compile and run programs in a C/C++ programming environment.
SEE4C 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.DL) can also be used from any language (Visual Basic, Delphi, Visual FoxPro, COBOL, Xbase++, dBase, Microsoft Office, 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 Visual Basic (SEE4VB), Delphi (SEE4D), PowerBASIC (SEE4PB), Visual FoxPro (SEE4FP), Visual dBASE (SEE4DB), and Xbase++ (SEE4XB). 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 Email Engine component library are as follows:
The complete set of documentation consists of three manuals in two formats. This is the first manual (SEE_4C) in the set.
Each manual comes in two formats:
The SEE_4C Programmer's Manual is the language specific (C/C++) 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 SMTP and POP3/IMAP email processing as well as language independent programming issues such as application notes. Purchasing and licensing information is also provided.
The SEE Reference Manual (SEE_REF) contains details on each individual SEE function and provides 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 C/C++ product page at:
http://www.marshallsoft.com/see4c.htm
The following example demonstrates the use of some of the SMTP/POP3/IMAP Email library functions:
#include <windows.h>
#include <stdio.h>
#include "see.h"
void main(int argc, char *argv )
{int Code;
// attach SEE library
Code = seeAttach(1, 0); // evaluation keycode is 0
if(Code<0)
{printf("Cannot attach SEE\n");
exit(1);
}
// connect to SMTP mail server
Code = seeSmtpConnect(
0, // channel 0
(char *)"mail.yourserver.net", // your SMTP server
(char *)"<user@domain.com>", // your email address
(char *)NULL); // Reply-To header
if(Code<0)
{printf("Connect failed\n");
seeRelease();
exit(1);
}
// send email
Code = seeSendEmail(
0, // channel 0
(char *)"<support@marshallsoft.com>", // To list
(char *)NULL, // CC list
(char *)NULL, // BCC list
(char *)"SEE Test", // Subject
(char *)"This is a test.", // Message text
(char *)"SEE4C50.ZIP"); // MIME attachment
if(Code<0) printf("email NOT sent\n");
// close connection to server
seeClose(0)
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.
All recent WIN32 C/C++ compilers support the "declspec" keyword. Microsoft Visual C++ (version 4.0 and up), Borland C++ (version 5.0 and up), Watcom C/C++ (version 11.0 and up), and LCC-Win32 C compilers support the "declspec" keyword. If you have an older Win32 compiler, you can get the legacy DLLs from our web site at
http://www.marshallsoft.com/see4c.htm
Uninstalling SEE4C is very easy. SEE does NOT modify the registry or any Windows system files.
First, run UNINSTAL.BAT (or UINSTALL.BAT), which will delete SEE32.DLL from the Windows directory, typically C:\WINDOWS for Windows 95/98/ME/XP/Vista or C:\WINNT for Windows NT/2000. Next delete the SEE4C project directory created when installing SEE4C.
A developer license for SEE4C can be registered for $115. Purchasing details can be found in Section 1.4 "How to Purchase" in the SEE User's Manual (SEE_USR). Also see INVOICE.TXT or
http://www.marshallsoft.com/order.htm
When a developer license is purchased, the developer will be sent a set of registered DLLs plus a license file (SEExxxx.LIC). 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 three years, updates are $75.
Note that the registered DLL's never expire.
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".
The following files can be found in the DLL sub-directory when SETUP is run:
see32.dll - Win32 version of SEE
see32mt.dll - Win32 (multitasking) version of SEE
Note: The LIB files for the above DLLs can be found the in the APPS directory
msoft_static.zip contains (for Microsoft C/C++):
see32.obj - SEE 32-bit static object file
msc-str.obj - SEE string function object file
msc-vs.obj - SEE virtual socket function object file
msoft_static_MT.zip contains (for Microsoft C/C++):
see32mt.obj - SEE 32-bit static object file (multitasking version)
msc-str.obj - SEE string function object file
msc-vs.obj - SEE virtual socket function object file
bc50_static.zip contains (for Borland C/C++ 5.0):
see32.obj - SEE 32-bit static object file
msc-str.obj - SEE string function object file
msc-vs.obj - SEE virtual socket function object file
bc55_static.zip contains (for Borland C/C++ 5.5):
see32.obj - SEE 32-bit static object file
msc-str.obj - SEE string function object file
msc-vs.obj - SEE virtual socket function object file
SEE32.DLL has a keycode encoded within it. The keycode is a 9 or 10 digit decimal number (unless it is 0), and will be found in the file KEYCODE.H. The keycode for the evaluation (shareware) version is 0. You will receive a new keycode and a set of new DLL's when registering. 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 them.
SEE4C functions can be called from console mode programs. A "console mode" program is a Windows 95/98/NT/2000/Me/XP/Vista WIN32 command line program running in a command window. Although console mode programs look like DOS programs, they are WIN32 programs that have access to the Win32 API and the entire Windows address space. Programming using console mode programs reduces the complexity of using GUI code. All console mode programs can be converted to GUI mode by adding the necessary Windows interface code
The SMTP/POP3/IMAP Email component library has been tested on multiple computers running Windows 95/98/Me/XP/Vista, and Windows NT/2000.
The SEE4C library has also been tested with several C/C++ compilers, including Microsoft Visual C/C++ (all versions including Visual Studio C++ and Visual Studio C#), Borland C/C++, Borland C++ Builder, Turbo C/C++ for Windows, and Watcom C/C++.
The SETUP installation program will copy the Lib's and DLL's to the Windows directory. Refer to Section 1.4 "Installation".
After SETUP is run, the SEE4C files are copied to the directory specified (default \SEE4C). Three sub-directories are created, as follows:
DOCS - All documentation files
APPS - All example code
DLLS - All DLL's
Our 32-bit libraries are compiled using the _stdcall and _declspec keywords. This means that they use the same calling conventions and file naming conventions as the Win32 API. In particular, function names are NOT decorated. There are no leading underscores or trailing "@size" strings added to function names.
Microsoft Visual C/C++ users can look at the DLL function names using the dumpbin.exe executable:
dumpbin /exports SEE32.dll
Some older compilers such as Borland C/C++ 4.0/4.5 and Watcom 10.5/10.6 do not support the "declspec" keyword. DLL's for these compilers can be downloaded from
http://www.marshallsoft.com/see4c.htm
SEE4C is thread safe. Refer to the THREAD.C example program, which demonstrates the use of multiple threads. THREAD checks several POP3 mailboxes simultaneously.
Like Windows itself, SEE functions are coded in ANSI C, but they can be called directly from both ANSI C programs and from C++ programs.
SEE functions can also be called using the C++ class wrapper fsee. See fsee.cpp and fsee.h. Refer to HELLO.CPP for an example.
In order to call SEE functions from an existing program, (1) add
#include "see.h"
to your application source code, (2) link with SEE32.LIB (for MSVC), SEE32BCB.LIB (Borland C/C++ and C++ Builder), SEE32.LIB (Watcom), or SEE32LCC (Win32/LCC), and recompile from source.
The error message text associated with SEE error codes can be displayed by calling seeErrorText. Each sample program contains examples of error processing.
When an application program runs that makes calls to SEE32.DLL, the Windows operating system will locate SEE.DLL by searching the directories as specified by the Windows search path. If the SEE32.DLL is placed in the \WINDOWS directory (or \WINNT for Windows NT/2000), it will always be found by Windows.
However, SEE32.DLL can also be loaded from a specified directory by using the GetProcAddress Win32 API function. For an example, refer to the LoadLib.c program.
Application programs can be compiled using an IDE or command line compiler tools. The following sections provide general compiler information.
All current windows compilers have an "Integrated Development Environment" (IDE) for building application programs in the Windows environment. Since there is not a standard format for IDE project files, file names must be entered into the IDE from the keyboard.
Note that not only do IDEs vary between the different compiler manufacturers, but they also vary from version to version for the same compiler.
Creating a project makefile for the examples that have only command line makefiles is fairly straightforward. To begin, create a new project. For console mode applications, be sure to choose a console mode project type. For GUI applications, choose a GUI mode project type.
All of the IDE's use the concept of a file hierarchy. For example, the STAT example program file hierarchy in the IDE (for 32-bit) should look like:
STAT.EXE
+++ STAT.C
+++ SEE32.LIB
Replace SEE32.LIB with SEE32BCB.LIB if using Borland C++ Builder, and with SEE32LCC.LIB if using LCC-Win32.
The order of the files is not significant. Also refer to the sections on individual IDE's that follow this section.
Most of the example programs can be compiled from your compiler's IDE. For Visual C++, "project makefiles" are used since they can be used by all versions of Visual C++ (v4.0, v5.0, and v6.0, etc.). When opening the workspace, select "makefiles(.mak)" for the file type.
Alternatively, for VC++ v6.0, select "projects (.dsp)" for the file type.
Many software developers overlook the power of using command line compilers. There are a number of very significant advantages to using the command line version of your C/C++ compiler. Among these are:
If you want to compile from the command line, your command line compiler tools must be set up properly. Note that you have an option of installing the command line tools (or not) when your compiler is first installed. Refer to your compiler manufacturer's manual for details.
If necessary, increase the size of the environment table space (to 1024 for example) by adding
SHELL=C:\COMMAND.COM /e:1024 /p
to CONFIG.SYS in C:\ and then restart the computer. Yes, this works for all versions of Windows, including Windows NT, Windows 2000, and Windows XP
For all compilers, the path should point to the compiler's BIN directory. For example, to add "C:\BC50\BIN" to the existing path, use
PATH C:\BC50\BIN;%PATH%
Set LIB and INCLUDE environment variables. For example,
SET INCLUDE=C:\MSVC\INCLUDE
SET LIB=C:\MSVC\LIB
Check that TURBOC.CFG, BCC32.CFG, TLINK.CFG, and TLINK32.CFG all have the correct information in them, as they should have when the compiler was installed. For example, assuming the BC compiler is installed at C:\BC5, the INCLUDE (-I) and LIB (-L) paths are specified by:
-IC:\BC5\INCLUDE
-LC:\BC5\LIB
BRCC (the Borland Resource Compiler) doesn't use the *.CFG files. Set the INCLUDE environment variable or BRCC will not be able to find the INCLUDE files (such as WINDOWS.H). For example,
SET INCLUDE=C:\BC5\INCLUDE
Clear the LIB environment variable (so it is not present when SET is typed at the command line) with
SET LIB=
Set the WATCOM environment variables to point to the compilers include (H) and BIN directories. For example,
SET INCLUDE=C:\WC11\H;C:\WC11\H\NT
SET WATCOM=C:\WC11
SET EDPATH=C:\WC11\EDDAT
SET WWINHELP=E:\BINW
The LCC environment variables are set like the others. For example,
SET INCLUDE=C:\LCC\INCLUDE
SET LIB=C:\LCC\LIB
After making the above changes for the compiler, type PATH at the command line prompt to verify the search path, and type SET at the command line prompt to verify the INCLUDE and LIB environment variables.
If the compiler installation includes command line tools, then all of the example programs can be compiled directly from the command line. These same compiler commands can also be placed in a batch file.
See MAILER$.bat for an example of a console mode command line batch file and FROM$.bat for an example of a GUI mode command line batch file. Similarly, command line batch files can be created for all of the example programs.
Command line makefiles originated on UNIX systems. They are the standard way that C/C++ programs are constructed in command line environments. The advantage of makefiles (as compared to an integrated development environment) is that all compiler switches are coded within the makefile and the makefile can be run with a single keystroke.
Command line makefiles are provided for Microsoft, Borland, Watcom, and LCC-Win32 command line compilers. They can be found in the APPS sub-directory:
The SMTP/POP3 Email Library for C/C++ has been tested with Microsoft Visual C++ (all versions including Visual Studio C++ and Visual Studio C# through Visual Studio 2008), Borland C/C++, Borland C++ Builder, Borland Turbo C++, Watcom C/C++, and Lcc-Win32 C. Other Windows C/C++ compilers may work as well. Refer also to Section 5, "Compiling Example Programs".
Microsoft Visual C/C++ programs can be compiled from either the command line or from within the Microsoft development environment.
The last Win16 Microsoft compiler is version 1.52. All Microsoft Visual C++ compilers (beginning with version 4.0) compile Win32 programs ONLY.
Programs can be compiled using command line makefiles. All Microsoft command line makefiles end with '"_m_". To compile using a makefile, use the Microsoft NMAKE utility. For example,
NMAKE -f STATUS._M_
The file MICROSOFT60.ZIP contains the Microsoft Visual C++ (v4.0, v5.0, v6.0) command line
makefiles.
SEE can be used with Microsoft Foundation Class (MFC) programs. Use the MFCPGM32.MAK makefile to compile the MFC_PGM example program.
NMAKE -f MFCPGM32.MAK
To open an existing project, choose "File", then "Open Workspace", and then select "makefiles" from the list of file types. Most of the example programs have Microsoft Developer C/C++ project makefiles, ending with ".MAK" , such as SEEVER.MAK
To create a new project in MSVC v4.0, choose "File", then "New", then "Project Workspace". Select "Application" or "Console Application" for "Type:" and the project name for "Name". Choose Win32 for platform. Then select "Create". Select "Insert", then "Files into Project". Add all filenames including any resource file (.RC) and SEE32.LIB. Lastly, select "Build", then "Rebuild All". Be sure to specify /YX rather than /Yu in the project settings [Build, Settings..., C/C++].
To open an existing project, choose "File", then "Open Workspace", and then select "makefiles" from the list of file types. Most of the example programs have Microsoft Developer C/C++ project makefiles, ending with ".MAK" , such as SEEVER.MAK.
To create a new project in MSVC v5.0, choose "File", then "New", then "Win32 Application" or "Win32 Console Application " and the project name. Check "Create new workspace". Select "Project", then "Add to Project". Add all filenames including any resource file (.RC) and SEE32.LIB. Lastly, select "Rebuild All".
If the compiler complains that it cannot find "_main", "Console Application" was chosen but the program being compiled is a GUI application. If the compiler complains that it cannot find "WinMain", "Application" was chosen but the program being compiled is a console mode application. Be sure to specify /YX rather than /Yu in your project settings [Build, Settings..., C/C++].
To open an existing project, follow the same directions as for MSVC (Microsoft Visual C++) v5.0, except that a DSP project file may be used instead of the MAK project makefile.
To create a new project in MSVC v6.0, follow the same directions as for MSVC v5.0 above.
Open the VC project file (files ending in ".vcproj"), build and run, as in previous version of Visual Studio. Also see section 4.2 below.
The "Express Edition" of Microsoft C++ is available as a free download at http://www.microsoft.com/express/download/
Open the VC project file (files ending in ".vcproj"), build and run, as in previous version of Visual Studio. Also see section 4.2 below.
All Microsoft Visual C++ .NET and Visual Studio C++ projects end with the extension ".vcproj". For example,
vc_vers.vcproj
In order to open an existing Visual C++ project, choose "File", "Open", and then "Project" from the Visual Studio menu. Specify the directory containing the Visual C++ project files (for example, C:\SEE4C\APPS).
In order to call SEE functions from Visual Studio C++ programs, do the following to the existing Visual Studio C++ project:
#include "see.h"
#include "keycode.h"
after the existing #include statements.
NOTE: If using pre-compiled headers, the include statement
#include "stdafx.h"
must be the first include statement in the program.
SMTP/POP3 Email functions can be called from Microsoft Visual C# (C-sharp) in the same manner as Win32 API functions.
All Visual Studio C# projects end with extension ".csproj". For example,
cs_vers.csproj
In order to open an existing C# project, choose "File", "Open", and then "Project" from the Microsoft C# Development Environment. Specify the directory containing the C# project files (for example, C:\SEE4C\APPS).
In order to call SEE functions from an existing Visual C# programs, do the following to the C# source code:
public class see : System.Windows.Forms.Form
Look at the cs_vers program in the \APPS sub-directory for an example.
See the CS_MAIL example project.
Borland C/C++ Version 5.0 programs can be compiled from either the command line or from within the Borland development environment.
In order to use SEE with Borland C/C++ Versions 4.5 or earlier, download the legacy DLLs from
http://www.marshallsoft.com/see4c.htm
Borland C/C++ version 5.5 (which can be downloaded from www.borland.com) is a free console mode compiler (no IDE). Makefiles for BC 5.5 end with "._i_", and (like Borland C++ Builder) use ILINK32 rather than TLINK32. Be careful with linker response files (*.RSP) -- they must NOT end with a carriage return / line feed!
Borland programs always link with SEE32BCB.LIB.
Programs can be compiled using command line makefiles. All Borland Win32 command line makefiles end with "32._b_" or "32._i_" (for BC 5.5). To compile using a makefile, use the Borland MAKE utility. For example,
MAKE -f QUICK32._B_
MAKE -f QUICK32._I_
MAKE -f FROM32._B_
MAKE -f FROM32._I_
To create a new project, first turn off LINKER case sensitivities: Choose "Options", "Projects", "Linker", "General". Turn off the "case sensitive link" and "case sensitive exports and imports" boxes.
Next, choose "Files", then "New Project". Use the INS (Insert) key to pop up a dialog box into which the project file names are entered. Lastly, add SEE32BCB.LIB to the project. SEE32BCB.LIB can also be created from SEE32.DLL using the Borland IMPLIB utility:
IMPLIB SEE32BCB.LIB SEE32.DLL
Select "GUI" or "Console" for the "Target Model". Only "Static" or "Dynamic" should be checked for "Standard Libraries:"
Borland Turbo C/C++ for Windows does not have command line tools, so all programs must be compiled from the Turbo C/C++ integrated environment.
Follow the same directions as above (Borland IDE), except that the "Target Model:" can be any listed.
Borland C++ Builder does not have command line tools, so all programs must be compiled from the Borland C++ Builder integrated environment. Compile the BCB example program QM_PRJ with QM_PRJ.MAK if running BCB version 1 through 3, and compile with QM_PRJ.BPR if running BCB version 4 or above.
To load the QM_PRJ example project, Choose "File" / "Open Project" on the menu bar. Load QM_PRJ.MAK (or QM_PRJ.BPR). Then choose "Build All" from "Project" to create the executable. Note that SEE32BCB.LIB is the LIB file used with Borland C++ Builder.
Watcom C/C++ programs can be compiled from either the command line or from within the Watcom development environment.
Note that SYBASE no longer sells or supports WATCOM C/C++. See their "End of Life Notice" at http://www.sybase.com/detail?id=20510
Win32 programs can be compiled using command line makefiles. All Watcom command line makefiles end with "32._w_" for Win32 makefiles. Use WCC386.EXE to compile C programs and WPP386.EXE to compile C++ programs.
To compile using a makefile, use the Watcom WMAKE utility. For example,
WMAKE -f MAILER32._W_
WMAKE -f FROM32._W_
Win32 programs can also be compiled using command line batch files. To run these command line batch files from the command line, type
MAILER32 W
To create a new project, choose "File", then "New Project". Enter the project name and then choose Win32 as the target. Use the INS (Insert) key to pop up a dialog box into which the project file names are entered.
Select "Options" from the main window, then "C Compiler Switches", then "10". Memory Models and Processor Switches". Check "80386 Stack based calling [-3s]", then check "32-bit Flat model [-mf]".
LCC-Win32 C programs can be compiled from either the command line or from within the development environment. LCC-Win32 is a freeware (non-commercial use) C compiler developed and distributed by Jacob Navia at
http://www.cs.virginia.edu/~lcc-win32/
To use our DLLs with LCC-Win32, you must link with SEE32LCC.LIB. This file can also be re-created using the LCC-Win32 utility BUILDLIB.
buildlib see32.lcc see32lcc.lib
Then, compile and link as normal. For example, to compile the MAILER console mode example program,
lcc -DWIN32 mailer.c
lcclnk mailer.obj see32.lib -subsystem:console
To compile the GUI mode example FROM,
lcc -DWIN32 about.c
lcc -DWIN32 from.c
lcc -DWIN32 paint.c
lrc from.rc
lcclnk from.obj about.obj paint.obj see32lcc.lib from.res
-subsystem:windows
See MAILER$.BAT for an example of a console mode command line batch file and FROM$.BAT for an example of a GUI mode command line batch file.
Before compiling any of the example programs (except for the connectionless example programs), edit the file EMAIL.H with the email configuration as explained in Section 5.2 "Editing EMAIL.H".
Most of the example programs are written in console mode. This was done in order to provide the clearest possible code, without the complication and complexity of GUI code. All console mode programs can be converted to GUI mode by coding the necessary windows code
The registered developer can also statically link SEE32.OBJ rather than making calls to SEE32.DLL. For an example, refer to the Microsoft command line makefile STAT32S._M_. These files are not available in the evaluation version.
To create an application that links SEE32.OBJ statically:
If using Microsoft Developer Studio, make these changes:
The file EMAIL.H is included by most of the example programs and contains the following defines:
#define YOUR_EMAIL_ADDR "<you@your-isp.com>"
#define SMTP_HOST_NAME "smtp.your-isp.com"
#define SMTP_USER_NAME "smtp_account_name"
#define SMTP_PASSWORD "smtp_account_password"
#define POP3_HOST_NAME "pop3.your-isp.com"
#define POP3_USER_NAME "pop3_account_name"
#define POP3_PASSWORD "pop3_account_password"
and must be edited with your email configuration before compiling any of the example programs. This information is required for all email clients. If you are unsure of any of these settings, look in your email client program (Eudora, Pegasus, etc.).
SMTP_USER_NAME and SMTP_PASSWORD are required ONLY if you will be doing SMTP authentication. They are usually the same as POP3_USER_NAME and POP3_PASSWORD. Refer to the SMTP/POP3 Email User's Manual (SEE_USR) for more information on authentication.
SMTP_HOST_NAME is the name (or IP address) of your SMTP email server. POP3_HOST_NAME is the name of your POP3 (or IMAP) server, which is typically the same as the SMTP server. YOUR_EMAIL_ADDR is your email address. Brackets "<>" are required. POP3_USER_NAME is the account name for your email (POP3 or IMAP) account. POP3_PASSWORD is the password for your email (POP3 or IMAP) account.
For example,
#define YOUR_EMAIL_ADDR "Mike Marshall<info@marshallsoft.com>"
#define SMTP_HOST_NAME "mail.hiwaay.net"
#define SMTP_USER_NAME "marshallsoft"
#define SMTP_PASSWORD "qwerty"
#define POP3_HOST_NAME "mail.hiwaay.net"
#define POP3_USER_NAME "marshallsoft"
#define POP3_PASSWORD "qwerty"
Note that EMAIL.H is used only in the example programs. Strings passed to SEE functions can be taken from any source (hard-coded, read from keyboard, read from file, etc.).
Not all of the #defines are used by the example programs. For example, SMTP_USER_NAME and SMTP_PASSWORD are used only by the AUTHEN example program.
The example programs can be compiled by using either the command line compiler or the compiler integrated development environment (IDE). Most compiler vendors provide both IDE and command line tools, although some compilers are command line only (Borland C/C++ 5.5 and LCC-Win32) or IDE only (Borland C/C++ Builder).
Some of the example programs are written in GUI mode, although most are written in console mode. Note that console mode programs must be run from the Windows command prompt. Also note that console mode programs can be converted to GUI mode by adding the necessary Windows interface code.
Refer also to Section 4, "Supported Compilers".
Several example programs do not require a connection to a server.
QUICK is a Win32 GUI example program that displays the SEE32.DLL Version and Build #. Run this program to verify that SEE has been installed properly.
nmake -f quick._m_ (Microsoft VC)
make -f quick._b_ (Borland 5.
make -f quick._i_ (Borland 5.5)
wmake -f quick._w_ (Watcom 11)
quick$.bat (LCC-WIN32)
Open workspace quick.mak in VC IDE.
Open workspace quick.dsp in VC (ver 6.0 only).
The VC_QUICK example GUI mode program is the Visual Studio C++ version of the QUICK example.
Open project VC_QUICK.VCPROJ in Visual Studio C++.
The CS_QUICK example GUI mode program is the C# (C-sharp) version of the VC_QUICK example.
Open project CS_QUICK.CSPROJ in Visual Studio C#.
The SEEVER example console mode program displays the SEE library version number and registration string. 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. It is the console mode version of the QUICK example program.
SEEVER can be compiled from either the command line or from Microsoft Visual Studio (SEEVER32.MAK).
The HELLO example console mode program is a C++ version of SEEVER that demonstrates the use of the fsee class.
The CODETEST example console mode program demonstrates how to use seeEncodeBuffer and seeDecodeBuffer, which BASE64 encodes and decodes several test strings. It also has an example of encoding and decoding UTF-8 strings.
The Pop3Rd example console mode program uses the seePop3Source function to specify an (undecoded) email message file to be decoded.
There are twenty SMTP example programs. SMTP programs send email.
AUTHEN is a console mode example program that connects to an SMTP server using SMTP Authentication. Note that the SMTP server name, user name, and password are specified in the EMAIL.H file for this example program. AUTHEN takes no arguments.
AUTO ("auto-responder") is a console mode program that uses two channels concurrently to automatically respond to all new email. AUTO takes no arguments.
BCAST is a console mode program which emails the same message, (BCAST.MAI), to a list of addresses taken from the file, BCAST.EML, containing one email address per line. BCAST takes no arguments. Compare to the MAILS example in 6.2.6.
Refer to BCAST.C for more details of use.
GETDOC is a simple (console mode) automatic email document retrieval system. It looks for commands on the subject line of incoming mail.
If "LIST" is found as the subject of an email (without any email body), the GETDOC program emails LIST.TXT to the sender. The LIST.TXT file should contain a list of all available documents.
If "GET docname" is found as the subject of an email message (without any email body), the GETDOC program emails the requested file (docname) to the sender, provided that the requested file is available.
GETDOC takes no arguments. All required information is taken from EMAIL.H.
MAILER is a console mode program that emails a message, taking its input from the command line. For example, to email the file TEST.TXT with subject "test" to support@marshallsoft.com with (optional) attachment TEST.ZIP, type
MAILER @test.txt Test "<info@marshallsoft.com>" test.zip
Note that <> brackets are required around the email address.
The MAILS console mode example program reads a list of email addresses from a file, then breaks the list into sets of addresses in which each set is sent (using the BCC field) as one email. MAILS takes no arguments. Compare to the BCAST example in 6.2.3 above.
Refer to MAILS.C for more details of use.
MFC_PGM is a Microsoft Foundation Class (MFC) example program. Compile using the MFCPGM.MAK makefile. File NAFXCW.LIB may have to be copied from MFC\LIB on the Microsoft Visual C/C++ CD disk.
The MULTI console mode example program emails two messages, including a MIME attachment. MULTI takes no arguments.
"Quick Message" (QM_PRJ & QM_PGM) is a Borland C++ Builder (Win32 GUI) program that emails a message from the GUI. Borland C++ Builder is required to compile this program. All necessary information is entered at runtime into dialog boxes. Compile using QM_PRJ.MAK for BCB version 1 through 3, and QM_PRJ.BPR for BCB version 4 and above.
MailTo is a Win32 GUI (Graphical User Interface) application that emails a message entered into a dialog box. All necessary information is entered at runtime into dialog boxes. MailTo can be compiled from either the command line or from Microsoft Visual Studio (MailTo.MAK).
The SendHTML console mode example program sends an HTML email (with embedded graphics attachments), which can be displayed by any email client that is capable of rendering HTML, such as Outlook and Eudora. SendHTML takes no arguments. Compare to the MailHTML example program.
VERUSR (Verify User) is a console mode program that accepts multiple email addresses on the command line. It connects to the SMTP server for each email address and requests verification of the user. For example, to verify msc@traveller.com and info@marshallsoft.com, type
VERUSR msc@traveller.com info@marshallsoft.com
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.
The ISO8859 console mode program sends a text message and a 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 SendUTF8 console mode example program sends a text message and subject line that is UTF-8 encoded. The recipient's email client will be able to display the email message using the Unicode character set provided that it is capable of identifying UTF-8 MIME parts and is Unicode capable.
The MailHTML example GUI mode program emails an HTML encoded message, with optional embedded images, alternate text, and additional attachments. All parameters are taken from a dialog box. Compare to the SendHTML example program.
The MParts console mode example program sends a multipart MIME email in which the Content-Type headers for each attachment are specified.
The two attachment types specified in this example are a sound file (.wav) and of a PDF file (.pdf).
The VC_MAIL example console mode program is the Visual Studio C++ version of the MAILER example program in section 6.2.5 above.
Load the VC_MAIL.VCPROJ project in Visual Studio C++.
The CS_MAIL example GUI mode program is the Visual Studio C# (C-sharp) version of the MAILER example program in section 6.2.5 above.
Load the project CS_MAIL.CSPROJ in C#.
The GB2312 example console mode 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 FORWARD example console mode program forwards an (undecoded) email to a new recipient.
There are eleven POP3/IMAP example programs that read email.
AUTO ("auto-responder") is a console mode program that uses two channels concurrently to automatically respond to all new email. AUTO both reads and sends email. AUTO takes no arguments.
DELETE is a console mode program that deletes an email message from the server. Be careful! Once deleted, an email message cannot be recovered. All required information except the email range to delete is taken from EMAIL.H. For example, to delete email messages 2 through 5, type
DELETE 2 5
Note that email is not physically deleted until the connection to the POP3 server is closed.
FROM is a Win32 GUI mode application that reads and displays selected header information, without reading the entire email message. FROM also makes a very handy utility program.
FROM can be compiled from either the command line or from Microsoft Visual Studio (FROM.MAK).
The GETDOC example is a simple (console mode) automatic email document retrieval system. It looks for commands on the subject line of incoming mail. GETDOC both reads and sends email.
If "LIST" is found as the subject of an email (without any email body), the GETDOC program emails LIST.TXT to the sender. The LIST.TXT file should contain a list of all available documents.
If "GET docname" is found as the subject of an email message (without any email body), the GETDOC program emails the requested file (docname) to the sender, provided that the requested file is available.
GETDOC takes no arguments. All required information is taken from EMAIL.H.
GETRAW is a console mode that downloads a specified email message without decoding it. This is used to see what the email looks like on the server. GETRAW takes all its arguments from the command line. For example, to read email message 2 into file EMAIL.TXT, type
GETRAW 2 EMAIL.TXT
Also see the READER example program below in Section 6.3.6, which can also download email without decoding it.
READER is a console mode program that reads an email message, including any MIME attachments, saving it to disk. For example, to read email message #1 and save it as file MYMAIL.TXT,
READER 1 MYMAIL.TXT
Any attachments are saved to the current directory.
The READHTML console mode example program reads an incoming HTML email message and then launches the internet browser in order to display the email as rendered HTML.
The READS console mode program is similar to READER except that it reads all email from the POP3 server. READS takes no arguments. All required information is taken from EMAIL.H. Attachments (if any) are saved to the current directory.
STAT is a very simple console modem program that returns the number of email messages waiting on the POP3 server. This is the first POP3 example to edit, compile, and run. STAT takes no arguments.
STAT can be compiled from either the command line or from Microsoft Visual Studio (STAT32.MAK).
STATUS is the console mode equivalent of FROM. STATUS takes no arguments. All required information is taken from EMAIL.H.
THREAD is a console mode program that uses threads to check several POP3 mailboxes simultaneously. You must edit THREAD.C with the POP3 mailbox settings to check before compiling.
There are three IMAP-only example programs. All of the POP3 programs in the above section will also work with IMAP servers after defining the symbol
CONNECT_TO_IMAP_SERVER
in the program source code before compiling.
The ImapFlagsT console-mode 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.
The ImapSearch console-mode example program tests IMAP search capability.
See ImapSearch.txt for a list of all IMAP search strings.
The ImapMBtest console-mode example program tests IMAP functions seeImapConnect, seeImapListMB, seeImapDeleteMB, seeImapCreateMB, and seeImapSelectMB.
Version 1.0: June 1, 1998.
Version 2.0: September 14, 1998.
Version 2.1: November 16, 1998.
Version 3.0: April 1, 1999.
Version 3.1: July 12, 1999.
Version 3.2: January 10, 2000.
Version 3.3: October 3, 2000
Version 3.4: July 12, 2001
Version 3.5: March 5, 2002
Version 3.6: March 14, 2003
Version 3.7: January 17, 2005.
Version 4.0: June 12, 2006.
Version 5.0: April 8, 2008 (Win32 Version only)