SMTP/POP3 Email Engine
Library for C/C++
Programmer's Manual
(SEE4C)
Version 3.2
January 10, 2000
This software is provided as-is.
There are no warranties, expressed or implied.
Copyright (C) 2000
All rights reserved
MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815
Voice : 256-881-4630
FAX : 256-880-0925
email : info@marshallsoft.com
web : www.marshallsoft.com
MarshallSoft is a member of the Association of Shareware Professionals
MARSHALLSOFT is a registered trademark of MarshallSoft Computing.
1 Introduction
1.1 Documentation Set2 Compiler Issues
1.2 Example Program
1.3 Installation
1.4 Uninstalling
1.5 Ordering
1.6 Updates
2.1 Command Line Tool Setup3 Supported Compilers
2.1.1 Microsoft2.2 Command Line Batch Files
2.1.2 Borland
2.1.3 Watcom
2.1.4 Lcc-Win32
2.3 Command Line Makefiles
2.4 Compiling Using an IDE
3.1 Microsoft C/C++4 Compiling Example Programs
3.2 Microsoft Visual C/C++
3.3 Borland C/C++
3.4 Turbo C/C++ for Windows
3.5 Borland C++ Builder
3.6 Watcom C/C++
3.7 Lcc-Win32 C/C++
4.1 Static Libraries5 Example Programs
4.2 Editing EMAIL.H
4.3 Your Key Code
5.1 SMTP Example Programs6 Revision History
5.2 POP3 Example Programs
SEE4C is the easiest way to write email applications in C/C++ !
The SMTP/POP3 Email Engine (SEE) is a library of functions providing direct and simple control of the SMTP (Simple Mail Transport Protocol) and POP3 (Post Office 3) protocols.
A simple interface allows sending and receiving email, including multiple MIME base64 and quoted- printable encoded attachments. Knowledge of Winsock and TCP/IP is not needed. SEE4C includes multiple C/C++ example programs.
With SEE4C, you can write GUI or console mode programs that easily:
Seventeen example programs are included, demonstrating SMTP and POP3 functions. Microsoft Foundation Class (MFC) and Borland C++ Builder (BCB) examples are also included.
SEE4C supports and has been tested with Microsoft C/C++, Microsoft Visual C/C++, Borland C/C++, Turbo C/C++ for Windows, Borland C++ Builder, Watcom C/C++, and Lcc-Win32 compilers. It can also be used with most other C/C++ Windows compilers.
Both Win16 and Win32 DLLs (Dynamic Link Libraries) are provided. SEE4C can be used with Windows 3.X, 95/98, and NT. The SEE4C DLLs (SEE16.DLL and SEE32.DLL) can also be used from any language (Visual Basic, Delphi, etc.) capable of calling the Windows API.
When comparing SEE against our competition, note that:
The complete set of documentation consists of three manuals in three formats. This is the first manual
(SEE4C) in the set.
Each manual comes in three formats:
The following example demonstrates the use of some of the library functions:
#include <windows.h> #include <stdio.h> #include "see.h" void main(int argc, char *argv[]) {int Code; /* attach SEE */ Code = seeAttach(1, 0); /* keycode is 0 */ if(Code<0) {printf(“Cannot attach SEE\n”); exit(1); } /* connect to SMTP server */ Code = seeSmtpConnect( 0, /* channel 0 */ (LPSTR)"mail.yourserver.net", /* your SMTP server */ (LPSTR)"<user@domain.com>", /* your email address */ (LPSTR)NULL); /* Reply-To header */ if(Code<0) {printf(“Connect failed\n”); seeRelease(); exit(1); } /* send email */ Code = seeSendEmail( 0, /* channel 0 */ (LPSTR)"<see@marshallsoft.com>", /* To list */ (LPSTR)NULL, /* CC list */ (LPSTR)NULL, /* BCC list */ (LPSTR)"SEE Test", /* Subject */ (LPSTR)"This is a test.", /* Message text */ (LPSTR)"SEE4C31.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.
The INSTALL batch file must be run to copy the proper DLL's for your compiler. All recent WIN32 C/C++ compilers support the "declspec" keyword. Microsoft VC (version 4.0 and up), Borland (version 5.0 and up), Watcom (version 11.0 and up), and Lcc-Win32 compilers support the "declspec" keyword.
If you have an older Win32 compiler, you can choose to install native mode DLLs. Run the INSTALL installation program, which will copy the proper LIB's and DLL's.
INSTALLU : For Win32 compilers supporting "declspec".
INSTALLM : For native mode Microsoft.
INSTALLB : For native mode Borland.
INSTALLW : For native mode Watcom.
INSTALL1 : For Win16 compilers only.
Choose INSTALLU for Microsoft Visual C/C++, Borland C/C++ 5.0 and later, Borland C++ Builder, Watcom C/C++ version 11.0 and later, and Lcc-Win32.
Uninstalling SEE4C is very easy. SEE does NOT modify the registry. First, delete the SEE project directory created when installing SEE4C. Second, delete SEE16.DLL and SEE32.DLL from your Windows directory, typically C:\WINDOWS for Windows 3.1/95/98 or C:\WINNT for Windows NT. That's it!
See Section 1.5 of the SEE User’s Manual (SEE_USR) for details on ordering.
When you register SEE4C you will receive a set of registered DLLs plus a license file
(SEExxxx.LIC) that
can be used to update your registered DLL’s for a period of one year from purchase.
Updates can be
downloaded from
www.marshallsoft.com/oem.htm
After one year, licenses can be updated for $30 for email delivery.
In order to compile from the command line, command line compiler tools must be set up properly.
For all compilers, your path should point to the compiler BIN directory. For example, to add "C:\BC50\BIN" to your 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 your compiler was installed.
Set the INCLUDE environment variables. For example,
SET INCLUDE=C:\BC50\INCLUDE
BRCC doesn't use any *.CFG files, but will use INCLUDE if set as above.
If "SET LIB=" is used, it must point to Borland’s LIB directory. Assuming that TURBOC.CFG is correct, it is best to clear the LIB environment variable with
SET LIB=
Set the WATCOM environment variables to point to your 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
If your 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 MAILER32.BAT for an example of a console mode command line batch file and FROM32.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.
Makefiles are provided for Microsoft, Borland, and WATCOM command line compilers.
All current windows compilers have an "Integrated Development Environment" (IDE) for building application programs in the Windows environment. Since there is no standard format for IDE project files, file names must be entered into the IDE from the keyboard.
Note that not only do IDE's 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 straight forward. 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 above with SEE16.LIB for 16-bit applications, 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.
SEE4C has been tested with Microsoft C/C++, Microsoft Visual C/C++, Borland C/C++ , Borland C++ Builder, Borland Turbo C/C++, Watcom C/C++, and Lcc-Win32. Other Windows C/C++ compilers may work as well.
Note: See the next section for Microsoft Visual C/C++.
Microsoft 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. Install with “INSTALL 16” in order to compile Win16 applications. For version of Microsoft C/C++ preceding Microsoft Visual C/C++, install with "INSTALL M".
All Microsoft Win16 makefiles end with “16._m_”. Note that many of the example program are console mode programs, and cannot be compiled as Win16 programs since Win16 does not support console mode. To compile, use the Microsoft NMAKE utility:
NMAKE -f FROM16._M_
NMAKE -f QUICK16._M_
NMAKE -f REGME16._M_
SEE can be used with Microsoft Foundation Class (MFC) programs. Use the MFCPGM16.MAK
makefile
to compile the MFC_PGM example program.
NMAKE -f MFCPGM16.MAK
To create a new project, choose "Project", then "New". Select Win16 [or Win32] as the target. A dialog box will then pop up into which the project file names are entered.
Microsoft Visual C/C++ programs can be compiled from either the command line or from within the Microsoft development environment. All MSVC programs are Win32 only.
In order to use SEE with MSVC, install using “INSTALL U”.
Programs can be compiled using command line makefiles. All Microsoft Win16 command line makefiles end with “16._m_” while Win32 command line makefiles end with ’32._m_”. To compile using a makefile, use the Microsoft NMAKE utility. For example,
NMAKE -f QUICK16._M_
NMAKE -f QUICK32._M_
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. Several of the example programs have Microsoft Visual Studio C/C++ makefiles, ending with ".MAK" , such as
stat32.mak
from32.mak
seever32.mak
quick32.mak
To create a new project in MSVC 4.0, choose "File", then "New", then "Project Workspace". Select "Application" or "Console Application" for "Type:" and your 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".
To create a new project in MSVC 5.0, choose "File", then "New", then "Win32 Application" or "Win32 Console Application " and your 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".
Creating a new project in MSVC 6.0 follows the same logic as for MSVC 5.0.
Borland C/C++ 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++ version 5.0 or later, install using “INSTALL U”. To use with Borland version 4.0 or 4.5, install with "INSTALL B".
Programs can be compiled using command line makefiles. All Borland Win16 command line makefiles end with “16._b_” while Borland Win32 command line makefiles end with ’32._b_”. To compile using a makefile, use the Borland MAKE utility. For example,
MAKE -f QUICK16._B_
MAKE -f QUICK32._B_
MAKE -f FROM16._B_
MAKE -f FROM32._B_
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 "Project", then "New Project". Use the INS (Insert) key to pop up a dialog box into which the project file names are entered.
Select "GUI" or "Console" for the "Target Model:" Only "Runtime" and "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.
In order to use SEE with Watcom C/C++ version 11.0 and after, install using “INSTALL U”. To use Watcom version 10.5 or 10.6, install with "INSTALL W".
Watcom cannot create Win16 Winsock programs.
Win32 programs can be compiled using command line makefiles. All Watcom command line makefiles end with "32._w_” for Win32 makefiles. To compile using a makefile, use the Watcom WMAKE utility. For example,
WMAKE -f QUICK32._W_
WMAKE -f FROM32._W_
Win32 programs can also be compiled using command line batch files. See MAILER32.BAT
for an
example of a console mode command line batch file and FROM32.BAT for an example of a GUI
mode
command line batch file. To run these command line batch files from the command line, type
QUICK32 W
Or
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/C++ programs can be compiled from either the command line or from within the development environment.
In order to use SEE with Lcc-Win32 C/C++, install using “INSTALL U”.
Lcc-Win32 is a freeware C compiler developed and distributed by Jacob Navia at
http://www.geocities.com/SiliconValley/Heights/9069/index.html
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 MAILER32.BAT for an example of a console mode command line batch file and FROM32.BAT for an example of a GUI mode command line batch file.
The registered user can also statically link SEE16.OBJ or SEE32.OBJ rather than making calls to the DLL's. For an example, see the Microsoft command line makefile STAT32S._M_. These files are not available in the shareware version.
The file EMAIL.H is included by most of the example programs and contains the following five defines:
#define SMTP_HOST_NAME "smtp_server_name" #define POP3_HOST_NAME "pop3_server_name" #define YOUR_EMAIL_ADDR "your_email_address" #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_HOST_NAME is the name (or IP address) of your SMTP email server. POP3_HOST_NAME is the name of your POP3 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) account. POP3_PASSWORD is the password for you email (POP3) account. For example,
#define SMTP_HOST_NAME "mail.hiwaay.net" #define POP3_HOST_NAME "mail.hiwaay.net" #define YOUR_EMAIL_ADDR "Mike Marshall<mike@marshallsoft.com>" #define POP3_USER_NAME "marshallsoft" #define POP3_PASSWORD "qwerty"
MAILER @test.mai Test "<mike@marshallsoft.com>" test.zip
Note that <> brackets are required around the email address.
QUICK is a Win16/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. QUICK can be compiled from either the command line or from Microsoft Visual Studio (QUICK32.MAK).
"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.
MFC_PGM is a Microsoft Foundation Class (MFC) example program. Win16 (MFCPGM16.MAK) and Win32 (MFCPGM32.MAK) makefiles are provided. File NAFXCW.LIB may have to be copied from MFC\LIB on your Microsoft Visual C/C++ CD disk.
BCAST is a Win32 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. To start BCAST, type
BCAST
Please DO NOT use this for spam! Refer to BCAST.C for more details of use.
VERUSR (Verify User) 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 sales@marshallsoft.com, type
VERUSR msc@traveller.com sales@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.
REGME (Register Me) connects to your SMTP server in order to allow a third party (such as your customers) to send you email, such as registration information. RegMe is a Win16/WIN32 example.
There are nine POP3 example programs. These examples read email.
STAT is a very simple Win32 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.
To run STAT, type
STAT
STAT can be compiled from either the command line or from Microsoft Visual Studio (STAT32.MAK).
FROM is a Win16/Win32 GUI 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 (FROM32.MAK).
STATUS is the Win32 console mode equivalent of FROM. STATUS takes no arguments. All required information is taken from EMAIL.H. To run STATUS, type
STATUS
DELETE is a Win32 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
READER is a Win32 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 READS 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. To run, type
READS
Any attachments are saved to the current directory.
GETDOC is a simple 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. To run, just type
GETDOC
THREAD is a Win32 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.
GETRAW is a Win32 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