1 Introduction

1.1 Documentation Set
1.2 Example Program
1.3 Installation
1.4 Uninstalling
1.5 Ordering
1.6 Updates

2 Compiler Issues

2.1 Visual Basic Makefiles
2.2 Compiling Programs
2.3 SEE4VB Class
2.4 Dynamic Strings
2.5 Key Code

3 Example Programs

3.1 SMTP Example Programs
3.2 POP3 Example Programs

4 Revision History

1 Introduction

SEE4VB is the easiest way to write email applications in Visual Basic !

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.

With SEE4VB, you can write programs that easily:

• Send email with optional MIME attachments.
• Get the number of messages on your email server.
• Get the header lines from any email on your server, without reading the entire email.
• Delete any email on the server without reading it first.
• Receive any email on your server including MIME attachments.

Ten example programs are included, demonstrating SMTP and POP3 functions. All programs will compile using VB 3.0 through VB 6.0.

Both Win16 and Win32 DLLs (Dynamic Link Libraries) are provided. SEE4VB can be used with Windows 3.X, 95/98, and NT. The SEE4VB DLLs (SEE16.DLL and SEE32.DLL) can also be used from any language (C/C++, Delphi, etc.) capable of calling the Windows API.

When comparing SEE against our competition, note that:

• SEE4VB is a standard Windows DLL and is much smaller than a OCX or ActiveX control.
• Both WIN16 and WIN32 DLLs are included.
• SEE4VB does NOT depend on ActiveX or similar "support" libraries.
• The WIN32 version of SEE is fully threadable.
• The SEE4VB functions can be called from applications not capable of using controls.

1.1 Documentation Set

The complete set of documentation consists of three manuals in three formats. This is the first manual (SEE4VB) in the set.

• SEE4VB Programmer’s Manual (SEE4VB.DOC, SEE4VB.TXT, SEE4VB.HTM)
• SEE User’s Manual (SEE_USR.DOC, SEE_USR.TXT, SEE_USR.HTM)
• SEE Reference Manual (SEE_REF.DOC, SEE_REF.TXT, SEE_REF.HTM)

Each manual comes in three formats:

• Microsoft Word (files ending in .DOC). The best format for printing manuals.
• Hyper Text (files ending in .HTM). Use any web browser to read.
• ASCII Text (files ending in .TXT).

1.2 Example Program

The following example demonstrates the use of some of the library functions:

   Dim Code As Integer
   Dim Server, IsNull, To, From As String
   Dim Subject, Message As String
   IsNull  = Chr$(0)
   Server  = "mail.yourisp.com
   From = "my name<me@myisp.com>"
   To   = "<mike@marshallsoft.com>"
   Subject = "Visual Basic Test"
   Message = "Emailed from SEE4VB!"
   Code = seeAttach(1, SEE_KEY_CODE)
   If Code < 0 Then
     ' error calling seeAttach !
     . . .
   End If
   Code = seeSmtpConnect(Server,From,IsNull)
   If Code < 0 Then
     ' error calling seeSmtpConnect !
     . . .
   End If
   Code = seeSendEmail(To,IsNull,IsNull,Subject,Message,IsNull)
   If Code < 0 Then
     ' error calling seeSendEmail !
     . . .
   End If
   Code = seeClose()
   Code = 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.

1.3 Installation

1. Before installation of SEE4VB, your Visual Basic compiler (any version) should already be installed on your system and tested.
   
   
2. Create your SEE4VB project directory, copy the SEE4VB archive, and then unzip the archive.
   
   
3. Run INSTALL.BAT which will copy SEE32.DLL (for VB 4.0, 5.0, and 6.0) or SEE16.DLL (for VB 3.0) to either C:\WINDOWS.
   
   
4. You're ready to run! Win16 program (VB 3.0) end with "16", while Win32 programs (VB 4.0, 5.0, & up) end with "32". For example,

SEEVER16.MAK --- Makefile for 16-bit Visual Basic.
SEEVER32.MAK --- Makefile for 32-bit Visual Basic.

Note that the Windows registry is not modified.

1.4 Uninstalling

Uninstalling SEE4VB is very easy. SEE does not modify the registry.

First, run UINSTALL.BAT, which will 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.

Second, delete the SEE project directory created when installing SEE4VB.

1.5 Ordering

See the section "Ordering" in the SEE User’s Manual (SEE_USR) for details on ordering.

1.6 Updates

When you register SEE4VB 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

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

After one year, licenses can be updated for $30 for email delivery.

2 Compiler Issues

2.1 Visual Basic Makefiles

The first Visual Basic for Windows (version 3.0) uses a text file known as a "Visual Basic makefile" (.MAK) to list all the file components necessary to compile a program. Beginning in version 4.0, the "Visual Basic Project file" (.VBP) was added. Both formats are "project files".

In order to allow our example programs to be compiled by all versions of Visual Basic, we use the Visual Basic makefile format. However, after loading, the examples can be saved in whatever format desired.

2.2 Compiling Programs

The example programs can be compiled from the Visual Basic development environment using the provided Visual Basic makefiles. Choose "File", then "Open Project" from the main VB menu.

The example program code is stored in VB 3.0 (WIN16) and VB 4.0 (WIN32) formats. All project files (except StatProj) end in "16.MAK" (e.g.: SEEVER16.MAK) or "32.MAK" (e.g.: SEEVER32.MAK) .

After opening a project, VB 5.0 (and VB 6.0) users can save the project files in the VB 5.0 (or VB 6.0) format. When saving the example programs in VB version 5.0 or VB 6.0 format, answer "no" if asked to add the "Microsoft DAO v2.5 library".

Compile and run SEEVER16 (or SEEVER32) as the first example. SEEVER does not require a TCP/IP connection.

2.3 SEE4VB Class

The SEE class "seeClass" (seeClass.cls) is a Visual Basic class wrapper for making calls to SEE32.DLL. The class name for each function is the same as the DLL function, except the leading "see" is replaced by "f".

Those functions that return strings do so by use of the "String Result" property. Instantiate seeClass as any other class in Visual Basic:

Dim X As New seeClass

Also see the SEE4VB Reference Manual (SEE4VB_R.TXT), the example project "StatProj" and the file seeClass.txt.

The use of seeClass is limited to Visual Basic 5.0 and above since previous versions of Visual Basic do not support classes.

2.4 Dynamic Strings

The Visual Basic language use a technique known as "garbage collection" to manage string space at runtime, and may be called internally at any time by the Visual Basic 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, a string buffer is passed to the dllGetMessage function, which copies a text message into it. Note that SPACE$(80) is called immediately before dllGetMessage.

   Dim Code As Integer
   Dim Buffer As String * 80
   ' allocate buffer just before call to dllGetMessage
   Buffer = SPACE$(80)
   ' copy message into 'Buffer'
   Code = dllGetMessage(Buffer, 80)
   ' message text is now in 'Buffer'

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

2.5 Key Codes

SEE16.DLL and SEE32.DLL have a keycode encoded within them. Your keycode is a 9 or 10 digit decimal number (unless it is 0), and will be found in the file KEYCODE.BAS. The keycode for the shareware version is 0. You will receive a new key code when registering.

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 shareware version of the SEE DLL's from the Windows search path.

3 Example Programs

Several example programs are included in SEE4VB. Separate versions for Win16 and Win32 are included. There is also an example program (StatProj) which uses the VB class "seeClass".

Each example program (except StatProj) comes with a VB makefile. WIN16 makefile names end with "16.MAK" (e.g.: SEEVER16.MAK) while WIN32 makefiles end with "32.MAK" (e.g.: SEEVER32.MAK).

The first example program SEEVER displays the SEE library version number and registration string. It does not require a connection. Open project SEEVER16.MAK or SEEVER32.MAK.

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

3.1 SMTP Example Programs

There are five SMTP example programs. SMTP programs send email.

3.1.1 HELLO

HELLO emails a short message. You must edit HELLO16.FRM (or HELLO32.FRM) with your server and email address before compiling.

Open project HELLO16.MAK or HELLO32.MAK.

3.1.2 MAILER

MAILER emails a message, including optional MIME attachments. All required parameters are input using a dialog box at runtime. Open project MAILER16.MAK or MAILER32.MAK.

Note that <> brackets are required around the email address.

3.1.3 BCAST

BCAST (Broadcast) emails the same message to each recipient from a file of email addresses. 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 EMAIL.LST for an example.

Open project BCAST16.MAK or BCAST32.MAK.

Please DO NOT use this for spam!

3.1.4 RegMe

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.

Edit your TCP/IP parameters in RegMe16.FRM (line 125) and RegMe32.FRM (line 149) before compiling.

Open project REGME16.MAK or REGME32.MAK.

3.1.5 AUTO

AUTO ("auto-responder") uses two channels concurrently to automatically respond to all new email. Edit your TCP/IP parameters in AUTO16.FRM (line 57) and AUTO32.FRM (line 73) before compiling.

Open project AUTO16.MAK or AUTO32.MAK.

3.2 POP3 Example Programs

There are five POP3 example programs. These examples read email.

3.2.1 STATUS

STATUS reads the number of email messages waiting on your POP3 server, and displays the "DATE:", "FROM:", and "SUBJECT:" header fields from each email. All required parameters are input at runtime.

Open project STATUS16.MAK or STATUS32.MAK.

3.2.2 READER

READER can read email, including multiple MIME attachments, from your POP3 server, optionally deleting each email after being read. All required parameters are input at runtime.

Open READER16.MAK or READER32.MAK.

3.2.3 VERUSR

VERUSR (Verify User) connects to a specified SMTP server and requests verification of the user.

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.

Open VERUSR16.MAK or VERUSR32.MAK.

3.2.4 GETRAW

GETRAW is a Win32 program that downloads a specified email message without decoding it. This is used to see what the email looks like on the server.

All required parameters are coded inside GETRAW16.FRM (line 66) and GETRAW32.FRM (line 67) and must be edited before compiling.

Open GETRAW16.MAK or GETRAW32.MAK.

3.2.5 StatProj

STATPROJ gets the number of email messages waiting on your POP3 server.

The "StatProj" example uses the Visual Basic class seeClass.cls. For more details on the seeClass, refer to section 2.3 "SEE4VB Class".

All required parameters are input at runtime. Open STATPROJ.VBP from Visual Basic 5.0 (or above).

4 Revision History

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

Version 1.0: June 22, 1998.

• Initial release.

Version 2.0: September 28, 1998.

• A major update adding POP3 capability.
• Another SMTP example program (BCAST).

Version 2.1: November 28, 1998.

• Time zone calculated automatically.
• Fixed bug in seeClose.
• Corrected POP3 problem when boundary definition on 2nd line.
• Added support for alternate MIME boundaries.
• Added seeVerifyUser function.
• Added SEE_GET_REGISTRATION, SEE_GET_CONNECT_STATUS,
• SEE_GET_ATTACH_COUNT, and SEE_GET_LAST_RESPONSE.
• Added GETDOC, SEEVER, and VERUSR example programs.
• SMTP performance improved.
• Added seeEncodeBuffer and seeDecodeBuffer functions.
• Added SEE_FILE_PREFIX and SEE_SET_REPLY parameters.

Version 3.0: April 12, 1999.

• Modified SEE to be fully threadable (adding seeAttach and seeRelease).
• Added seeGetEmailUID function.
• Handles "inline" email text properly.
• Optionally decodes unnamed attachments.
• Added ability to add header lines (SEE_SET_HEADER).
• Can use alternate ports for SMTP or POP3.
• Win16 version can get time zone from TZ environment variable.
• Quoted-printable messages can handle soft line breaks.
• Quoted-printable message can handle embedded HTML text.
• VB Class "seeClass" added.
  
  
  

Version 3.1: July 16, 1999.

• Support ISO-8859-1 (Q or B) encoded attachment filenames.
• Support ISO-8859-1 (Q only) on subject line
• SEE_SAVED_TO_MSG added.
• "+OK" line not written to email message file.
• Added seeExtractLine function.
• Added REGME example program.

Version 3.2: January 17, 2000.

• Added QUOTED_8859 processing (QUOTED_8859).
• Can decode printed quotable attachments!
• seeGetEmailLines can use internal memory.
• Added SEE_WRITE_TO_LOG to seeStringParam.
• Added SEE_GET_ATTACH_NAMES to seeDebug to get attachment filename list.
• Ability to reset the SEE_SET_HEADER header string to "nothing".
• Improvements in dynamic memory usage.
• Added GETRAW and CODETEST examples.
• Added support for Lcc-Win32.
• Added seeCommand function.