Class

POP3SecureSocket

Description

Used to retrieve messages on a POP3 mail server using SSL or TLS encryption.

Events

Name

Parameters

Returns

ConnectionEstablished

Disconnected

ListReceived

data As String

LoginSuccessful

MessageDeleted

Index As Integer

MessageReceived

Index As Integer, Message As EmailMessage

MessageCount

Count As Integer

RollbackSuccessful

SendComplete

UserAborted As Boolean

SendProgress

BytesSent As Integer, BytesLeft As Integer

Boolean

ServerAvailable

ServerCommandReply

command As String, data As String

ServerError

ErrorCode As Integer, ErrorMessage As String, MessageID As Integer

TopLinesReceived

Index As Integer, Data As EmailMessage

Property descriptions

POP3SecureSocket.Address

Address As String

The TCP/IP address to try to connect to.

In this example, the address has been entered into a TextField.

TCPSocket1.Address = TextField1.Text

POP3SecureSocket.BytesAvailable

BytesAvailable As Integer

The number of bytes of data are available in the internal receive buffer.

This property is read-only.

TextField1.Text = Me.BytesAvailable.ToString

POP3SecureSocket.BytesLeftToSend

BytesLeftToSend As Integer

The number of bytes left in the queue remaining to be sent.

This property is read-only.

This enables you to create a synchronous socket without needing to subclass it.

TextField1.Text = Me.BytesLeftToSend.ToString

POP3SecureSocket.CertificateFile

CertificateFile As FolderItem

The file that contains the SSL certificate.

This example opens the certificate file and assigns it to the property.

Var f As FolderItem
f = FolderItem.ShowOpenFileDialog("text/plain")
If f <> Nil Then
  Socket1.CertificateFile = f
End If

POP3SecureSocket.CertificatePassword

CertificatePassword As String

The certificate password for the secure connection.

This example sets the certificate password from a TextField.

socket1.CertificatePassword=TextField1.Text

POP3SecureSocket.CertificateRejectionFile

CertificateRejectionFile As FolderItem

The certificate rejection file.

This example gets the certificate rejection file from disk.

Var f As FolderItem
f = FolderItem.ShowOpenFileDialog("text/plain")
If f <> Nil Then
  Socket1.CertificateRejectionFile = f
End If

POP3SecureSocket.Handle

Handle As Integer

This is the socket's internal descriptor and it can be used with Declare statements.

This property is read-only.

  • On Windows, Handle is a Socket, suitable for use in Declares on Windows.

  • On macOS and Linux, Handle is a UNIX socket descriptor.

The descriptor is platform-specific. If Handle is less than zero, the descriptor is not available.

POP3SecureSocket.IsConnected

IsConnected As Boolean

Indicates whether the socket is currently connected.

This property is read-only.

For TCPSockets, a connection means you can send and receive data and are connected to a remote machine. For UDPSockets, this means that you are bound to the port and are able to send, receive, join or leave multicast groups, or set socket options.

If EasyUDPSocket1.IsConnected Then
  ' proceed using the connection
Else
  MessageBox("Connection failed!")
End If

POP3SecureSocket.IsEncryptPassword

IsEncryptPassword As Boolean

If True, the password is encrypted when being sent to the mail server.

' EmailSocket is a POP3SecureSocket on a Window
EmailSocket.Address = "smtp.server.com"
EmailSocket.Port = 519
EmailSocket.IsEncryptPassword = True
EmailSocket.UserName = "<username>"
EmailSocket.Password = "<password>"
EmailSocket.Connect

POP3SecureSocket.LocalAddress

LocalAddress As String

The local IP address of the computer.

This property is read-only.

Var localIP As String = Socket1.LocalAddress

POP3SecureSocket.NetworkInterface

NetworkInterface As NetworkInterface

Specifies which network interface the socket should use when binding.

You can get the network interface(s) of the user's computer by calling the GetNetworkInterface method of the System module.

Leaving this property set to Nil will use the currently selected interface. In the case of UDPSockets, if you assign a non-Nil value, the socket may not be able to receive broadcast messages. The behavior is OS-dependent; it appears to work on Windows but not on other supported operating systems. If you wish to send broadcast packets out, then you should not bind to a specific interface because the behavior is undefined.

This example specifies that the TCPSocket will use the first Network Interface on the user's computer.

TCPSocket1.NetworkInterface = System.NetworkInterface(0)

POP3SecureSocket.Password

Password As String

The password to use for security when connecting to the mail server.

POP3SecureSocket.Port

Port As Integer

The port to bind on or connect to.

On most operating systems, attempting to bind to a port less than 1024 causes a Error event to fire with an error number 107 unless the application is running with administrative permissions. This is due to security features built into the underlying OS.

You need to set the port property explicitly before any call to Listen or Connect as the Port property will be modified to reflect what the actual bound port is during the various stages of operation.

For instance, if you listen on port 8080 and a connection comes in, you can check the Port property to ensure that you're still listening on port 8080 (that the port hasn't been hijacked). Or, if you connect to a socket on port 8080, once the connection occurs, you can check to see what port the OS has bound you to. This will be a random-seeming port number.

This trick can be very useful when you do things like Listen on port 0. In that case, the OS will pick a port for you and listen on it. Then you can check the Port property to see which port the OS picked. This functionality is used for various protocols, such as FTP.

This example sets the Port to 8080.

TCPSocket1.Port = 8080

POP3SecureSocket.RemoteAddress

RemoteAddress As String

The address of the remote machine you are connected to.

This property is read-only.

Use this instead of the Address property to determine the address of the machine you are actually connected to.

This example reports the address of the remote machine that the user is connected to. It is in the Connected event.

TextField1.Text = Me.RemoteAddress

POP3SecureSocket.SSLConnected

SSLConnected As Boolean

True if you have an SSL connection.

This property is read-only.

If Me.SSLConnected Then
  ' connection established with secure communications, proceed ...
Else
  Exit
End If

POP3SecureSocket.SSLConnecting

SSLConnecting As Boolean

True if the socket is in the process of doing a handshake to establish an SSL connection.

This property is read-only.

If Me.SSLConnecting Then
  ' proceed with connection
End If

POP3SecureSocket.SSLConnectionType

SSLConnectionType As SSLConnectionTypes

Specifies the type of SSL connection.

Set this property by assigning a SSLConnectionTypes value to it.

The default is TLSv1. If you need to change the connection type, close the connection first.

This example changes the connection type to TLSv1.

Socket1.SSLConnectionType = SSLSocket.SSLConnectionTypes.TLSv1

POP3SecureSocket.SSLEnabled

SSLEnabled As Boolean

Set to True to specify an SSL connection.

If SSLEnabled is False, the SSLSocket transmits data just like a TCPSocket. This property can be toggled at any time.

Me.SSLEnabled = True

POP3SecureSocket.Username

Username As String

The username to use for authentication when connecting to the mail server.

Method descriptions

POP3SecureSocket.CheckServerConnection

CheckServerConnection

Sends a "NOOP" command to the mail server.

This is a command that asks the server to reply. This can be useful to check that the mail server is still responding and also tells the mail server that you are still connected if there has been no activity for a long period of time.

POP3SecureSocket.Close

Close

Closes the socket's connection, closes any connections the socket may have, and resets the socket.

The only information that is retained after calling Close is the socket's port, address (in the case of TCPSockets), LastErrorCode properties, and data left in the socket's receive buffer. All other information is discarded.

This example closes the EasyTCPSockets that were open. The sockets were added to the main window.

Connector.Close
Listener.Close

POP3SecureSocket.Connect

Connect

Attempts to connect.

For TCPSockets, the address and port properties must be set. For UDPSockets, the port property must be set. The Connect method binds a socket to a port. After calling Connect, the Port property will report the actual port you are bound to.

POP3SecureSocket.CountMessages

CountMessages

Asks the server for the number of messages in the mailbox. It triggers the MessageCount event, from which you can get the total.

This is equivalent to the POP3 STAT command.

POP3SecureSocket.Disconnect

Disconnect

Disconnects the socket, resets it, and fires a SocketCore Error event with a 102 error to let you know that the socket has been disconnected.

This example disconnects the EasyTCPSockets that were opened.

Connector.Disconnect
Listener.Disconnect

POP3SecureSocket.DisconnectFromServer

DisconnectFromServer

Disconnects from the mail server.

This sends a “QUIT” command to the mail server and waits for it to close the connection.

POP3SecureSocket.EndOfFile

EndOfFile As Boolean

Returns True when there's no more data left to read.

This code reads the rows and columns of data from a tab-delimited text file into a ListBox:

Var f As FolderItem
Var textInput As TextInputStream
Var rowFromFile As String

f = FolderItem.ShowOpenFileDialog("text/plain") ' defined as a FileType
If f <> Nil Then
  textInput = TextInputStream.Open(f)
  textInput.Encoding = Encodings.UTF8

  Do
    rowFromFile = textInput.ReadLine
    Var values() As String = rowFromFile.ToArray(String.Chr(9))
    ListBox1.ColumnCount = values.Count
    ListBox1.AddRow("")
    Var col As Integer
    For Each value As String In values
      ListBox1.CellTextAt(ListBox1.LastAddedRowIndex, col) = value
      col = col + 1
    Next
  Loop Until textInput.EndOfFile

  textInput.Close
End If

This example reads each pair of bytes from a file and writes them in reverse order to a new file. The user chooses the source file using the Open-file dialog box and saves the new file using the Save as dialog box. The EOF property is used to terminate the Do...Loop.

Var readFile As FolderItem = FolderItem.ShowOpenFileDialog("text")
If readFile <> Nil Then
  Var ReadStream As BinaryStream = BinaryStream.Open(readFile, False)
  ReadStream.LittleEndian = True
  Var writeFile As FolderItem = FolderItem.ShowSaveFileDialog("", "")
  If writeFile <> Nil Then
    Var writeStream As BinaryStream = BinaryStream.Create(writeFile, True)
    writeStream.LittleEndian = True
    Do Until ReadStream.EndOfFile
      writeStream.WriteInt8(ReadStream.ReadInt8)
    Loop
    writeStream = Nil
  End If
  readStream = Nil
End If

POP3SecureSocket.Flush

Flush

Immediately sends the contents of internal write buffers to disk or to the output stream.

This function can be useful in point-to-point communication over sockets and similar connections: To optimize for transmission performance, some types of output streams try to collect small pieces of written data into one larger piece for sending instead of sending each piece out individually. By calling Flush, the data collection is stopped and the data is sent without further delay, reducing latency.

When using this on a stream that ends up as a file on disk, it is useful, too: Any short parts of previously written data are written to disk right away, ensuring the data is actually on disk if the application terminates abruptly, e.g. due to a crash.

Avoid calling this method too often. For example, do not call it between successive Write calls because you'll slow down performance without getting much benefit.

A typical use case would look like this:

mySocket.Write("you typed: ")
mySocket.Write(key)
mySocket.Write(".")
mySocket.Flush

POP3SecureSocket.Listen

Listen

Attempts to listen for incoming connections on the currently specified port.

After calling Listen, the Port property will report the actual port you are bound to.

POP3SecureSocket.Lookahead

Lookahead(Encoding As TextEncoding = Nil) As String

Returns a String, containing the data that is available in the internal queue without removing it.

The optional Encoding parameter enables you to specify the text encoding of the data to be returned. The default is Nil. Use the Encodings module to specify an encoding.

This example adds the contents of the internal queue to a TextArea. The Listener EasyTCPSocket has been added to the window.

TextArea1.AddText(listener.Lookahead)

POP3SecureSocket.Poll

Poll

Polls the socket manually, which allows a socket to be used synchronously.

The EasyTCPSocket "Listener" has been added to the window.

Listener.Poll

POP3SecureSocket.Purge

Purge

Removes all data from the socket's internal receive buffer. It does not affect the socket's internal send buffer.

Listener.Purge

POP3SecureSocket.Read

Read(Bytes As Integer, Encoding As TextEncoding = Nil) As String

Reads Bytes bytes from the input stream and returns a String.

If provided, the optional parameter Encoding specifies the text encoding to be defined for the String to be read.

If Bytes is higher than the amount of bytes currently available in the stream, all available bytes will be returned. Therefore, make sure to always consider the case that you get less than you requested. To see if you received all requested bytes, check the returned string's String.Bytes property (avoid using Length as it may give a different number if the encoding is not nil).

If not enough memory is available, you get back an empty string.

This example reads the first 1000 bytes from a BinaryStream.

Var readFile As FolderItem = FolderItem.ShowOpenFileDialog("text/plain")
If readFile <> Nil Then
  Var ReadStream As BinaryStream = BinaryStream.Open(readFile, False)
  ReadStream.LittleEndian = True
  TextArea1.Text = ReadStream.Read(1000, Encodings.UTF8)
End If

POP3SecureSocket.ReadAll

ReadAll(Encoding As TextEncoding = Nil) As String

Reads all the data from the internal buffer.

This example reads all the data in the buffer into a TextArea.

TextField1.AddText(listener.ReadAll)

POP3SecureSocket.ReadError

ReadError As Boolean

If True then an error occurred during reading.

POP3SecureSocket.RemoveMessageAt

RemoveMessageAt(id As Integer)

Tells the mail server to remove the specified message.

POP3SecureSocket.RequestMessages

RequestMessages([id As Integer])

Requests a message listing.

RequestMessages triggers the ListReceived event. The list consists of the message index and the size of the message. If no index is passed, it gets the entire list from the server. If a specific index is passed, it will return just the index message and size of the message.

POP3SecureSocket.RetrieveLinesAt

RetrieveLinesAt(id As Integer, lineCount As Integer)

Returns the specified number of lines of a message.

The mail server will return the first LineCount of lines that exist in the message you are requesting via the Index parameter. If LineCount is zero, then the mail server returns only the headers for the message.

This is equivalent to the POP3 TOP command.

POP3SecureSocket.RetrieveMessageAt

RetrieveMessageAt(index As Integer)

Reads the entire message specified by Index.

POP3SecureSocket.RollbackServer

RollbackServer

Resets the mail server to the state that it was when you logged in.

RollbackServer can be used to Undo deletions that occur by accident. The changes aren't committed until the connection is closed. RollbackServer will roll back changes that have not yet been committed.

POP3SecureSocket.SendCommand

SendCommand(Command As String)

Sends the command specified by Command to the mail server.

SendCommand is useful when you need to send a command that in not supported by the socket.

POP3SecureSocket.Write

Write(Data As String)

Writes the passed data to the output stream.

Note that in order to make sure that the data actually ends up on disk or gets sent to the socket it is connected to, the stream must either get closed or the Flush method be called. Otherwise, the data, if small, may end up temporarily in a write buffer before either a certain time has passed or more data is written. This buffering increases performance when writing lots of small pieces of data, but may be causing unwanted delays when another process, e.g. the other end of a socket connection, is waiting for the data. Consider calling the Flush method to reduce latencies that this buffering may cause in such cases.

If Write fails, an IOException will be raised.

This example displays the Save As dialog box and writes the contents of the TextArea1 to a text file.

Var f As FolderItem
Var stream As BinaryStream
f = FolderItem.ShowSaveFileDialog(FileTypes1.Text, "Untitled.txt")
If f<> Nil Then
  stream = BinaryStream.Create(f, True)
  stream.Write(TextArea1.Text)
  stream.Close
End If

POP3SecureSocket.WriteError

WriteError As Boolean

If True then an error occurred during writing.

Event descriptions

POP3SecureSocket.ConnectionEstablished

ConnectionEstablished

Occurs when a connection has been established.

POP3SecureSocket.Disconnected

Disconnected

Occurs when the connection has been terminated.

POP3SecureSocket.ListReceived

ListReceived(data As String)

Executes when the RequestMessages method is called. The data parameter contains the message listing.

POP3SecureSocket.LoginSuccessful

LoginSuccessful

Executes when the login process initiated by calling the Connect method is complete.

POP3SecureSocket.MessageDeleted

MessageDeleted(Index As Integer)

Executes when the mail server replies to a RemoveMessageAt call and contains the index number of the deleted message.

POP3SecureSocket.MessageReceived

MessageReceived(Index As Integer, Message As EmailMessage)

Executes when a message has been received from the mail server, in response to a call to RetrieveMessageAt. Index contains the index number of the retrieved message and the message contents is in Message.

POP3SecureSocket.MessageCount

MessageCount(Count As Integer)

Executes when the mail server replies to a CountMessages call and contains the number of messages in the mailbox.

POP3SecureSocket.RollbackSuccessful

RollbackSuccessful

Executes in response to a call to RollbackServer and indicates that the state of the mailbox has been reset.

POP3SecureSocket.SendComplete

SendComplete(UserAborted As Boolean)

Occurs when a send has completed.

Use this to determine when all your data has been sent. UserAborted will be True if the user aborted the send by returning True from the SendProgress event. You can use this information to update different status variables or to inform user about the success or failure of the transfer. If the send was completed, this value is False. UserAborted will always be False for UDP sockets.

POP3SecureSocket.SendProgress

SendProgress(BytesSent As Integer, BytesLeft As Integer) As Boolean

Occurs when your network provider queues your data in chunks and is about to send the next chunk.

The parameters indicate the amount of progress that has been made during the send. Returns a Boolean.

Returning True from this event causes the send to be cancelled. This does not close the socket's connection; it only clears the buffer. After all of the data has been transferred you will get a final SendProgress event followed by a SendComplete event.

bytesSent is the number of bytes that were sent in the chunk, not the total number of bytes sent.

POP3SecureSocket.ServerAvailable

ServerAvailable

Executes when the mail server has replied to a call to CheckServerConnection and indicates that the mail server has replied to the call.

POP3SecureSocket.ServerCommandReply

ServerCommandReply(command As String, data As String)

Executes in response to a call to SendCommand and contains the mail server's response to the command passed.

POP3SecureSocket.ServerError

ServerError(ErrorCode As Integer, ErrorMessage As String, MessageID As Integer)

Executes when a protocol-related error occurs.

The error codes are as follows:

Value

Description

0

Unknown Error Message

1

Incorrect Password

2

IncorrectUsername

3

Delete Message Failed

4

List Messages Failed

5

Retrieve Lines Failed

6

Retrieve Message Failed

POP3SecureSocket.TopLinesReceived

TopLinesReceived(Index As Integer, Data As EmailMessage)

Executes in response to a call to RetrieveLines. Index contains the index number of the partial message being retrieved and Data contains the requested lines of the message.

Notes

The POP3SecureSocket is nearly identical to the deprecated POP3Socket class, except that it is derived from the SSLSocket class instead of the TCPSocket class. This enables you to send secure email by setting the Secure property of the SSLSocket class.

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

Sample code

The following code in the MessageReceived event handler places the body of an email message in a TextArea.

Sub MessageReceived(ID As Integer, email As EmailMessage)
  Var s As String
  s = email.BodyHTML
  If s = "" Then
    s = email.BodyPlainText
  End If
  TextArea1.Text = s
End Sub

Compatibility

All project types on all supported operating systems.

See also

SSLSocket parent class; EmailMessage, URLConnection, POP3SecureSocket, SMTPSecureSocket, SMTPSecureSocket, SSLSocket, SocketCore, TCPSocket classes.