FreePOP ActiveX control documentation

FreePOP ActiveX control

Version 4.1.1

November 4, 2001

Description

FreePOP is an ActiveX control that allows read/write access to a POP3 mailbox and the messages in the mailbox. This ActiveX control was developed with Microsoft Visual Basic 6.0-SP4.

Possible uses

FreePOP allows you to find out the number of unread messages in a POP3 mailbox.
FreePOP allows you access to the various headers of a message (i.e. Subject, Date, From, etc.)
FreePOP allows you to retrieve the contents of a message.
FreePOP allows you to selectively delete a message.
FreePOP allows you to read a message directly into a file.

Why it was created?

I've wanted to write a Winsock application for quite some time now.
I've wanted to learn more about writing an ActiveX control.
I originally built an application that accessed a POP3 mailbox that did some specialized processing based on the contents of the mailbox. I undertook this because I couldn't find a "freeware" product that did exactly what I wanted to do. After building the application, I saw the usefulness of building an ActiveX control of the basics so I could easily re-use it in other programs.

Why Free?

I've always been a big user of "freeware", and have always wanted to make my donation to the world of free software.
I've been unable to find a "freeware" ActiveX POP3 control. (I'm sure there may be some out there, but they certainly aren't as prevalent as new email notification programs).
I would like to learn more about software distribution and support in a "best effort" basis so I can determine if I want to develop other applications for profit in the "shareware" arena.

Limitations

It has only been tested using Visual Basic 6.0-SP4. From what I understand it should work fine with other development environments that support ActiveX controls, but I have no first-hand experience with it. Any comments from folks working in other environments would be appreciated.

Notes

FreePOP makes use of 2 "extended" POP3 commands. The commands are TOP and UIDL. These commands are sent to the server during the SetCurrentMsg method. In versions prior to 2.0.3, if either of these commands were not recognized by the POP3 server, the connection was closed and an error was returned. For version 2.0.3, limited support has been added for POP3 servers which do not recognize the TOP and UIDL commands. If either of these commands are not recognized by the POP3 server the message is automatically read in order to populate the headers (MsgHeaders, MsgFrom, MsgSubject, etc.). Under these conditions, there is no need to execute the RetrieveCurrentMsg method as this has already been done. (Suggestion: If FreePOP1.MsgContents is > " " then there is no need to execute the RetrieveCurrentMsg method). In this situation, the POP3 mail server cannot provide the MsgUniqueID property, so one is generated by the FreePOP control. The format of the pseudo-generated MsgUniqueID property is: POPUsername:PopHostname:MsgNumber
If the FreePOP control is used with Visual FoxPro, you must issue a SYS(2330,0) command before instantiating the object. This deactivates Active-X dual-interface support.

Legal stuff

Every effort has been made to have this control provide the functionality that will be further outlined below.
The author assumes no responsibility or liability for the use of this control in any way, shape, or form.
This control is being released to the public as "freeware". There is no charge for the use of this control in the development environment, and it may be freely distributed as part of another program either for free or for profit.
"Free distribution" is NOT extended to individuals or companies who create or sell any software development programs. Two common examples of "software development programs" would be Visual Basic, or Delphi.

Support

I will provide email support on a "best effort" basis. Please be patient with the "response time" since I have a day job which keeps me very busy.
If you are interested in receiving information about updates and bug fixes, please send me your email address.
I would love to hear any feedback about your experiences with this control, good or bad.

Contact information

Please use the email address FreePOP@harm.net for any communications regarding the FreePOP ActiveX control. The homepage for the FreePOP ActiveX control is: http://www.harm.net/FreePOP

Futures

Due to the availability of reasonably priced full featured POP mail controls, further development on this project will not be likely. Bug fixes will certainly be addressed as they are reported.

Author information

Glenn Harm is employed by a large computer company as a computer consultant. His current expertise is working on large scale Microsoft Exchange Server deployments. He also enjoys all possible ways to keep up with the changing face of computer technology and spends way too much time with his computer and the Internet.

Source Code

The Visual Basic source code for FreePOP is now available! Information can be obtained by going to: http://www.harm.net/FreePOP/FPsource.asp

How can you help?

Please send any feedback regarding this control to FreePOP@harm.net
Support the "freeware" concept by developing free software for others to use.

FAQ (Frequently Asked Questions)

Q: Are attachments or HTML messages "decoded" or "translated"?

A: FreePOP only returns the "raw" message sent by the POP server. If the message is encoded in any way or if it contains any attachments, it is the responsibility of the programmer to decode them into something that is useful to the calling program.

Q: How do I send email with FreePOP?

A: FreePOP emulates the POP3 protocol which is mailbox (receiving) only. SMTP is the protocol for sending email. Go to ActiveX.com and search on SMTP.

Q: Why not build in support for sending email (SMTP)?

A: Unfortunately, SPAM and Unsolicited Commercial Email (UCE) is a big problem on the Internet. I don't want to be part of the problem by giving Spammers a free tool to use for sending email. Unfortunately, this penalizes people who would use it correctly--fortunately, there are other tools (see the previous question) out there that fill this need.

Q: Where can I get further information on decoding messages or attachments?

A: Purchase the book "Programming Internet Email" by David Wood from O'Reilly. ISBN: 1-56592-479-7. You can order the book from Amazon.com.

Q: I'm getting an error when I try to register or use the control downloaded from the "minimal" kit.

A: Download the "full" kit and run the SETUP.EXE program.

Q: Can I get the source code for FreePOP?

A: Source code for FreePOP is available! Please check http://www.harm.net/FreePOP/FPsource.asp for up to date information.

Q: How do I create an instance of FreePOP from ASP (Active Server Pages) or VBScript?

A: Use the following code:

Dim FreePOP1
Set FreePOP1= CreateObject("FreePOPControl.FreePOP")

Q: Why can't I can't get FreePOP to work in ASP (Active Server Pages) or inside VBscript?

A: For reasons that I'm not entirely sure of, when an object gets created via ASP or VBscript, the routine that initializes the control does not fire. The effect of this is that some default properties are not set correctly. To circumvent that, include the following assignments of properties before calling the .Connect method:

FreePOP1.POPTimeout = 20
FreePOP1.POPPort = 110

Q: Where can I get information on RFCs (Request for Comments)?

A: One of many repositories of RFCs can be found at http://www.faqs.org/rfcs/rfcsearch.html

Q: What is the RFC for POP3?

A: FreePOP follows RFC 1939 and this RFC can be found at: http://www.faqs.org/rfcs/rfc1939.html

FreePOP ActiveX control documentation

Installation

If you have downloaded the full install kit, unzip the files into a directory run the SETUP.EXE, and follow the directions.
If you downloaded the minimal kit, unzip the files into a directory, copy the FPOP411.OCX to your C:\WINDOWS\SYSTEM directory, and then execute the command: REGSVR32 C:\WINDOWS\SYSTEM\FPOP411.OCX. This should work fine if you are working in the Visual Basic version 6.0 environment, and have the latest service pack for Visual Basic installed.

FreePOP Methods

Connect - This method initiates a connection to a POP3 server. It connects, sends the username and password and collects some information about the mailbox. See the Properties section for further information.

Example: FreePOP1.Connect

Disconnect - This method closes the connection previously made to a POP3 server.

Example: FreePOP1.Disconnect

SetCurrentMsg - This method selects a specific message on the POP3 server. The message headers are retrieved and put into various properties. See the Properties section for further information.

Example: FreePOP1.SetCurrentMsg 1

RetrieveCurrentMsg - This method retrieves the currently selected message from the POP3 server. It "reads" it only--it does NOT remove it from the POP3 server. See the Properties section for further information.

Example: FreePOP1.RetrieveCurrentMsg

DeleteCurrentMsg - This method marks the currently selected message for deletion on the POP3 server.

Example: FreePOP1.DeleteCurrentMsg

ResetDeletedMsgs - This method unmarks any messages that have been previously marked for deletion in the current POP3 session.

Example: FreePOP1.ResetDeletedMsgs

GetOtherHeader - This method allows you to retrieve other header lines than what are currently provided for you via Properties. For example: the MsgSubject property holds the subject line header, but there is not a property for the "Content-transfer-encoding" header. You can use the GetOtherHeader method to retrieve any header that you wish from the currently selected message. If the header line doesn't exist the returning string will contain "<not found>"

Example: Dim strHeaderLine

strHeaderLine = FreePOP1.GetOtherHeader("Content-transfer-encoding:")

WriteCurrentMsgToFile - This method retrieves the current message (including the headers) and places it in the passed filename.

Example: FreePOP1.WriteCurrentMsgToFile("c:\ msg.txt")

GetStringValueOfProperty - This method returns a true "String" value of any of the properties. All the properties are of type "Variant". This was added in reponse to a person using LabView which is somewhat particular on using typed data.

Example: strSubjectLine = FreePOP1.GetStringValueOfProperty("MsgSubject")

FreePOP Properties

POPHostname - This is a Read/Write property which is used to get/set the name of the POP3 server that you wish to connect to. The value can either be a raw TCPIP address or a DNS name.

Example: FreePOP1.POPHostname = "pop3.yourserver.com"

POPPort - This is a Read/Write property which is used to get/set the port the connect request to the POP3 server is done with. The default for this value is 110.

Example: FreePOP1.POPPort = 111

POPUsername - This is a Read/Write property which is used to get/set the username to use when connecting to the POP3 server.

Example: FreePOP1.POPUsername = "joeschmoe"

POPPassword - This is a Read/Write property which is used to get/set the password to use when connecting to the POP3 server.

Example: FreePOP1.POPPassword = "joespassword"

POPTimeout - This is a Read/Write property which is used to get/set the timeout value (in seconds) for all operations which require interaction with the POP3 server. The default value for this value is 10 seconds.

Example: FreePOP1.POPTimeout = 20

Status - This is a Read-Only property which holds a integer type value representing the status of a connection to a POP3 server.

Value of 0 means disconnected
Value of 1 means connected

StatusText - This is a Read-Only property which holds a text representation of the Status property.

Error - This is a Read-Only property which holds a integer type value representing any error that may have occurred from one of the FreePOP methods.

Value 0 = No error
Value 11 = Connection was accepted but no data received before timeout. Connection closed
Value 12 = Timeout waiting on connect request
Value 13 = Already connected
Value 14 = Error received from USER command:
Value 15 = Error received from PASS command:
Value 16 = Hostname cannot be blank
Value 17 = Username cannot be blank
Value 18 = Error received from STAT command:
Value 19 = Cannot set message number when disconnected
Value 20 = Cannot set message number less than or equal to 0 or greater than the message count
Value 21 = Error using the UIDL command:
Value 22 = Error using the TOP command:
Value 23 = Cannot retrieve message when disconnected
Value 24 = Cannot retrieve message number 0, use the SetCurrentMsg method
Value 25 = Error retrieving the message:
Value 26 = Error using the DELE (delete) command:
Value 27 = Cannot delete message when disconnected
Value 28 = Error using the RSET (reset) command:
Value 29 = Cannot reset deleted messages when disconnected
Value 30 = Error using the LIST command:
Value 31 = File error:

Additionally Winsock may generate an error which can be reflected in the Error property of this control. The ErrorText property will give the text representation of these messages as well. For further information about the various Winsock errors that can occur, see the Visual Basic help file for the Winsock Control.

ErrorText - This is a Read-Only property which holds a text representation of the Error property.

MsgCount - This is a Read-Only property which holds the number of messages in the connected POP3 mailbox. This value is set during the Connect method.

MsgNumber - This is a Read-Only property which holds the number of the currently selected message. This value is set during the SetCurrentMsg method.

MsgUniqueID - This is a Read-Only property which holds a unique identifier provided by the POP3 server for the currently selected message. This value is set during the SetCurrentMsg method.

MsgHeaders - This is a Read-Only property which holds all the message headers of the currently selected message. This value is set during the SetCurrentMsg method.

MsgSubject - This is a Read-Only property which holds the "subject" line of the currently selected message. This value is set during the SetCurrentMsg method.

MsgFrom - This is a Read-Only property which holds the "from" line of the currently selected message. This value is set during the SetCurrentMsg method.

MsgReturnPath - This is a Read-Only property which holds the "Return-Path" line of the currently selected message. This value is set during the SetCurrentMsg method.

MsgReplyTo - This is a Read-Only property which holds the "Reply-To" line of the currently selected message. This value is set during the SetCurrentMsg method.

MsgDate - This is a Read-Only property which holds the "date" line of the currently selected message. This value is set during the SetCurrentMsg method.

MsgSizeInK - This is a Read-Only property which holds the size (in kilobytes) of the currently selected message. This value is set during the SetCurrentMsg method.

ConnectResponse - This is a Read-Only property which holds the initial response from the POP3 server when a connection is established in the Connect method. The main reason I included this was because some POP3 servers give the current time in GMT as part of their initial connection response.

MsgContents - This is a Read-Only property which holds the body of the currently selected message. This value is set during the RetrieveCurrentMsg method.

DebugMode - This is a run-time only property which can be set to True to initiate retrieving some debug information. This should be used only on request of the author.

DebugFile - This is a run-time only property for debug information, if the DebugMode property has been set to True. This should be used only on request of the author.

FreePOP Events

MsgReadStatus - This is an event that is called during a .RetrieveCurrentMsg or .WriteCurrentMsgToFile methods. Information available in this event are:

Message read so far (in K)
Message size (in K)
Percent completed

Example:

Private Sub FreePOP1_MsgReadStatus(lngMsgReadInK As Variant, lngMsgTotalInK As Variant, intPercentCompleted As Variant)
   Label1.Caption = CStr(intPercentCompleted) & "%"
   ProgressBar1.Min = 0
   ProgressBar1.Max = lngMsgTotalInK
   ProgressBar1.Value = lngMsgReadInK
End Sub

Example

Follow the below directions to set up an environment where you can process all messages in a POP3 mailbox.

1) Start a new project.

2) Go into Project/Components and ensure that the "Glenn Harm's FreePOP Control" control is available and checked.

3) Add a command button to the form.

4) Add a FreePOP control to the form. Ensure that it has the Name of FreePOP1

5) Add a Text box control to the form. Make it as big as possible and name it Text1. Set the MultiLine property to True, and the ScrollBars property to 2-Vertical

6) Copy and paste the below into the Code window of the form. Make appropriate changes for the POP server information

Private Sub Command1_Click()
Dim intCount As Integer

   Command1.Enabled = False
   FreePOP1.POPHostname = "pop3.yourserver.com"
   FreePOP1.POPUsername = "yourusername"
   FreePOP1.POPPassword = "yourpassword"
   FreePOP1.Connect
   If FreePOP1.Error = 0 Then
      MsgBox FreePOP1.MsgCount, vbOKOnly, "Messages in mailbox"
      For intCount = 1 To FreePOP1.MsgCount
         FreePOP1.SetCurrentMsg (intCount)
         If FreePOP1.Error = 0 Then
            FreePOP1.RetrieveCurrentMsg
            Text1.Text = FreePOP1.MsgContents
            DoEvents
            If FreePOP1.Error = 0 Then
               
         ' Do whatever you want for each message here.

         MsgBox FreePOP1.MsgSubject, vbOKOnly, "Subject line"
               MsgBox FreePOP1.GetOtherHeader("Content-transfer-encoding:"), vbOKOnly, _
                                    "An additional header"
            Else
               MsgBox FreePOP1.ErrorText, vbOKOnly, "Error during RetrieveCurrentMsg"
            End If
         Else
            MsgBox FreePOP1.ErrorText, vbOKOnly, "Error during SetCurrentMsg"
         End If
      Next
      FreePOP1.Disconnect
   Else
      MsgBox FreePOP1.ErrorText, vbOKOnly, "Error during Connect"
   End If

   Command1.Enabled = True
End Sub

7) Run the project

Release History

Version 2.0.1 - Initial public release (February 15, 1998)

Version 2.0.2 (February 19, 1998)

Removed DebugInfo property. This was a property to be used only on request of the author.
Added DebugFile property. This property to be used only on request of the author.
Cleaned up some error trapping. If a network error or the remote host closed the connection after a successful connect there were some instances where the control wouldn't realize the connection was dropped and successive calls to the Connect method would return an error code 13--"Already connected".

Version 2.0.3 (March 15, 1998)

When retrieving the headers, the program was previously issuing a TOP command followed by the message number, followed by a 0 (for the number of lines in the message to retrieve). This caused a failure with some POP servers, so the program has been modified to issue a TOP command with the message number only, if the initial TOP command fails.
In some circumstances, a program using FreePOP would crash due to the control determining a timeout, but before entirely closing the connection data would arrive. The connection would close, and would then try to retrieve the data from a closed connection. This problem has been fixed.
Fixed a bug in my interpretation of RFC-1725 (POP3) in determining when all data has been received for certain commands (like TOP and RETR).
Added the DeleteCurrentMsg and ResetDeletedMsgs methods to allow Write access to the POP3 mailbox.
Fixed a *really* stupid error in the RetrieveCurrentMsg method. By the fact that I only received two complaints about it, most POP3 servers must have been tolerant about what the control was sending, but it definitely was not correct per the RFC. Persons exhibiting problems would have received a message something to the effect of "Too many arguments supplied to the RETR command".
Changed the distribution of this documentation file to be a HTML based file.
Enhanced the debug facility.
Allowed continued conversation with the POP3 server even if the UIDL or TOP commands fail (which are used during the SetCurrentMsg method).
Introducted the MsgSizeInK property to hold the size of the currently selected message.
Attempts to read messages > 64K will return the text "This message is too large (>64K) to retrieve" in the MsgContents property. Previously the control would terminate and your program would error out with a "Out of memory" message.

Version 2.0.4 (August 23, 1998)

Fixed a string parsing bug that was causing a run time error upon processing certain subject lines.

Version 2.0.5 (Self release only)

This was not a public release.

Version 2.0.6 (August 6, 1999)

Fixed a string parsing bug that, under some conditions, may not have returned the desired header from the message headers.
Some POP servers would not return the response to some basic POP commands in a single packet, which would cause unexpected results with the FreePOP control and make it unable to deal with those POP servers. The control is now fully compliant with these servers.
Improvements were made to the routines that determine a timeout condition making it more reliable.
Added a method called .GetStringValueOfProperty to return a true "String" value of any of the properties. All the other properties are of type "Variant". This was done in response to a person using LabView which is somewhat particular on using typed data. To get the subject line returned as a real string variable, one would make a call like this str1 = FreePOP1.GetStringValueOfProperty("MsgSubject")
When filling the .MsgContents property after doing a .RetrieveCurrentMsg, the "termination" characters are now removed. The termination characters are <CR><LF>.<CR><LF>
Introduced a method called .WriteCurrentMsgToFile which allows placing all of a message into a specified file. This allows for support of messages > 64K. NOTE: Normally the headers are separate from the message body (the .MsgHeaders and the .MsgContents properties). However, when using the WriteCurrentMsgToFile, both the headers and contents are placed in the file. Example: FreePOP1.WriteCurrentMsgToFile ("c:\msg.txt" )

Version 2.0.7 (August 7, 1999)

Fixed a bug that would cause FreePOP to hang indefinitely while "disconnecting" when a certain error occurred.

Version 2.0.8 (August 9, 1999)

Fixed a bug that would cause an "Error 5 Invalid procedure call or argument" from a program calling FreePOP.

Version 3.0.1 (August 17, 1999)

Fixed numerous problems with the .WriteCurrentMsgToFile method that would cause the control to terminate with various errors including "Out of string space"

Version 4.0.1 (August 7, 2000)

Bugs fixed

In some situations (notably when the CPU was near 100%) that FreePOP would cause a runtime error of 40006 when the .Connect method was executing.
Some headers were not being processed correctly if there were other similar headers.
If values for POPPort, MsgCount, or MsgSizeInK were greater than 32,767 a runtime error would occur. These variables have been converted to be of type Long rather than Integer.

Changes

Previously, the message headers and size of the message were read during the .SetCurrentMsg method. This caused unnecessary overhead for anyone just wanting to see if there were new email messages since last check (by keeping track of each message's .MsgUniqueID property and checking on successive calls). The headers and size of the message are now read on demand by retrieving one of the following properties: MsgHeaders, MsgSubject, MsgFrom, MsgReturnPath, MsgReplyTo, MsgDate, MsgSizeInK, or the GetOtherHeader method). Existing programs should function the same, but it would be wise to now check the .Error property after utilizing one of the above listed properties for the first time following a .SetCurrentMsg method call.
The display name of the control (Seen from the Components selection dialog) has been changed from "Glenn Harm's FreePOP ...." to "FreePOP ..."
An event named MsgReadStatus has been added. This event is raised as messages are being read and can be used to display status of the current message being downloaded. Status information available is:
- Message read so far (in K)
- Message size (in K)
- Percent completed

Version 4.0.1 (August 7, 2000)

Bugs fixed

In some situations (notably when the CPU was near 100%) that FreePOP would cause a runtime error of 40006 when the .Connect method was executing.
Some headers were not being processed correctly if there were other similar headers.
If values for POPPort, MsgCount, or MsgSizeInK were greater than 32,767 a runtime error would occur. These variables have been converted to be of type Long rather than Integer.

Changes

Previously, the message headers and size of the message were read during the .SetCurrentMsg method. This caused unnecessary overhead for anyone just wanting to see if there were new email messages since last check (by keeping track of each messages .MsgUniqueID property and checking on successive calls). The headers and size of the message are now read on demand by retrieving one of the following properties: MsgHeaders, MsgSubject, MsgFrom, MsgReturnPath, MsgReplyTo, MsgDate, MsgSizeInK, or the GetOtherHeader method). Existing programs should function the same, but it would be wise to now check the .Error property after utilizing one of the above listed properties for the first time following a .SetCurrentMsg method call.
The display name of the control (Seen from the Components selection dialog) has been changed from "Glenn Harm's FreePOP ...." to "FreePOP ..."
An event named MsgReadStatus has been added. This event is raised as messages are being read and can be used to display status of the current message being downloaded. Status information available is:

Message read so far (in K)
Message size (in K)
Percent completed

Version 4.1.1 (November 4, 2001)

Bugs fixed

In version 2.0.3 I implemented a workaround for servers who didn't comply to the RFC and implement the TOP and UIDL commands. Somewhere along the line, I broke this workaround, but this workaround functionality has now been restored.
A user reported a problem using the .RetriveCurrentMsg where the program was determining a timeout. This particular user's email server was sending part of the message termination string across two packets and FreePOP didn't anticipate this particular situation. This particular behavior is now accounted for correctly.

Changes

Previously, the control forced one to use the .WriteCurrentMsgToFile if the message was determined to be larger than 64K. I initially thought this was the size limit of a string, but this is indeed not the case with current versions of Visual Basic. What initially led me to believe this was receiving run time errors when testing the control when the .MsgContents got over 64K in size. Indeed I was receiving a run time error, but it was not due to the size of the string, but because I was trying to assign the contents of the string to a VB TextBox control. It simply assumed the string was at fault, when in fact it was a limitation of the TextBox control.

Special thanks to

Paul Kearney - Beta tester
Jason Everly - Beta tester
Jan-Martin Krikken - Beta tester
Dean Anglin - Beta tester
Shadi Shalabi - Beta tester (http://www.shadisoft.com)
Steven Miller - Beta tester
Larry Perry - Enhancement suggestions
Michael Proctor - Enhancement suggestions

Return to FreePOP home page