Xojo Documentation Xojo Documentation

Class (inherits from TCPSocket)

Used to retrieve and manage messages on a POP3 mail server.

Events

ConnectionEstablished MessageDeleted ServerAvailable Disconnected MessageReceived ServerCommandReply ListReceived RollbackSuccessful ServerError LoginSuccessful SendComplete TopLinesReceived MessageCount SendProgress

Properties

Address Handle Password BytesAvailable IsConnected Port BytesLeftToSend LocalAddress RemoteAddress EncryptPassword NetworkInterface Username

Methods

CheckServerConnection Disconnect Purge Close DisconnectFromServer ReadAll Connect ListMessages RetrieveLines Connect Listen RetrieveMessage CountMessages Lookahead RollbackServer DeleteMessage Poll SendServerCommand

Notes

If you use a constructor in a subclass of POP3Socket, you must call the Super class's constructor in your subclass's constructor. The subclass will not work unless this is done.

Specifications of POP3 (Post Office Protocol version 3) are provided in RFC 1939.

Xojo Cloud

To access a POP3 server from web apps running on Xojo Cloud, you will first have to use the FirewallPort class to open the port used to connect to the POP3 server.

Dim fwp As New XojoCloud.FirewallPort(110, _
XojoCloud.FirewallPort.Direction.Outgoing)
fwp.Open // This call is synchronous
If fwp.IsOpen() Then
// Do what you need to do
End If

Basic usage

As any socket, the POP3 sockets work asynchronously, i.e. the methods trigger exchange of data from/to the POP3 server and results are provided through the available events. If an error occurred, it is sent through the ServerError event.

Once the object is created, set the address of the POP3 server and the port (110 is the default port for POP3 servers not using SSL) Set the username and password. You can also set EncryptPassword to True if the server supports APOP authentication. Call the Connect method. In the LoginSuccessful event, add the code that you want to execute, e.g.: Call ListMessages to receive the list of messages on the server in the ListReceived event Call RetrieveMessage to get a message through the MessageReceived event

Examples

The following example is from the "Email Example" project. The project uses two windows. The "demoWindow" window is used to receive emails. The "sendDemoWindow" window uses the SMTPSocket to send emails.

DemoWindow contains fields for entering the server address, username, and password, a PushButton, and a ListBox for displaying the list of messages. A POP3Socket control, POP3Socket1, has been added to the window. The user clicks the “Connect” PushButton to connect to the mail server, receive email, and list the messages in a ListBox. Its Action event establishes a connection to a POP3 server. It gets the name of the server, username, and password from the contents of the TextFields, ServerFld, UserNameFld, and PasswordFld.

If Me.Caption = "Connect" Then
Socket1.address = NthField(ServerFld.Text, ":", 1)
Socket1.Port = Val(NthField(ServerFld.Text, ":", 2))
If Socket1.Port = 0 Then
Socket1.Port = 110
End If

Socket1.Username = UsernameFld.Text
Socket1.Password = PasswordFld.Text

ProgressBar1.Maximum = 0
Socket1.Connect
Me.Caption = "Disconnect"
Else
Socket1.DisconnectFromServer
Me.Caption = "Connect"
End If

The following example in the MessageReceived event of the POP3Socket control, displays the message in the multiline TextArea, BodyFld.

Sub MessageReceived(ID As Integer, Email As EmailMessage)
Dim s As String

// display the message
s = Email.bodyHTML
If s = "" Then
s = Email.BodyPlainText
End If
BodyFld.Text = ReplaceAll(s, Chr(13) + Chr(10), Chr(13))
End Sub

The LoginSuccessful event executes the CountMessages method that's used to determine whether all the messages have been received.

Me.CountMessages

The POP3Socket's TopLinesReceived event populates the ListBox with summary information on each email that was received.

Sub TopLinesReceived(ID As Integer, Email As EmailMessage)
// headers received. populate the Listbox
ListBox1.AddRow(Email.Subject)
ListBox1.Cell(ListBox1.LastIndex, 1) = Email.FromAddress
ListBox1.Cell(ListBox1.LastIndex, 2) = Str(ID)

If ID < MessageTotal Then // there are still messages left
Me.RetrieveLines(id + 1, 0) // get the next message headers
End If
End Sub

After populating the ListBox, it checks against the window property MessageTotal, which contains the result from a call to CountMessages, to see if there are any more message on the server. MessageTotal is assigned the value of the Count parameter in the MessageCount event.

See Also

• EmailMessage, POP3SecureSocket, HTTPSocket, SMTPSocket, SocketCore, TCPSocket classes.
• Specifications of POP3 (Post Office Protocol version 3): RFC 1939 and updates.