---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
` 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.
``` xojo
TCPSocket1.Port = 8080
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
POP3Socket.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.
``` xojo
TextField1.Text = Me.RemoteAddress
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
POP3Socket.Username
**Username** As `String`
The username to use for authentication when connecting to the mail server.
## Method descriptions
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
POP3Socket.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.
If successful, the ServerAvailable event handler is called.
In this example, a POP3Socket has been added to the window and named socket1.
``` xojo
socket1.CheckServerConnection
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
POP3Socket.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.
``` xojo
Connector.Close
Listener.Close
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
POP3Socket.Connect
**Connect**
Connects to the mail server and logs in with the values in the *Username* and *Password*properties.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
POP3Socket.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.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
POP3Socket.DeleteMessage
**DeleteMessage**(Index As `Integer`)
Tells the mail server to delete the specified message.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
POP3Socket.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.
``` xojo
Connector.Disconnect
Listener.Disconnect
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
POP3Socket.DisconnectFromServer
**DisconnectFromServer**
Disconnects from the mail server. This sends a “QUIT” command to the mail server and waits for it to close the connection.
This message logs off from the server. Socket1 is on the layout and has been declared as a POP3Socket.
``` xojo
socket1.DisconnectFromServer
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
POP3Socket.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`:
``` xojo
Var f As FolderItem
Var textInput As TextInputStream
Var rowFromFile, oneCell 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.Split(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
End For
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`.
``` xojo
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
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
POP3Socket.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:
``` xojo
mySocket.Write("you typed: ")
mySocket.Write(key)
mySocket.Write(".")
mySocket.Flush
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
POP3Socket.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.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
POP3Socket.ListMessages
**ListMessages**(\[Index As `Integer`\])
Requests a message listing. It fires the ListReceived event. It calls the ListReceived event handler.
This 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.
This is equivalent to the POP3 **LIST** command.
``` xojo
Me.ListMessages
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
POP3Socket.Lookahead
**Lookahead**(\[Encoding As `TextEncoding`\]) 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.
``` xojo
TextArea1.AddText(listener.Lookahead)
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
POP3Socket.Poll
**Poll**
Polls the socket manually, which allows a socket to be used synchronously.
The `EasyTCPSocket` "Listener" has been added to the window.
``` xojo
Listener.Poll
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
POP3Socket.Purge
**Purge**
Removes all data from the socket's internal receive buffer. It does not affect the socket's internal send buffer.
``` xojo
Listener.Purge
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
POP3Socket.Read
**Read**(Count As `Integer`, \[Enc As `TextEncoding`\]) As `String`
Reads *Count* bytes from the input stream and returns a `String`.
If provided, the optional parameter *Enc* specifies the text encoding to be defined for the `String` to be read.
If *Count* 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` 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`.
``` xojo
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
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
POP3Socket.ReadAll
**ReadAll**(\[Encoding As `TextEncoding`\]) As `String`
Reads all the data from the internal buffer.
This example reads all the data in the buffer into a `TextArea`.
``` xojo
TextField1.AddText(listener.ReadAll)
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
POP3Socket.RetrieveLines
**RetrieveLines**(Index 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.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
POP3Socket.RetrieveMessage
**RetrieveMessage**(Index As `Integer`)
Reads the entire message specified by *Index*.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
POP3Socket.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 by issuing a RSET command to the POP3 server (see RFC 1939 for more details).
On success, the RollbackSuccessful event is fired. Otherwise, the ServerError event is fired.
``` xojo
Me.RollbackServer
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
POP3Socket.SendServerCommand
**SendServerCommand**(Command As `String`)
Sends the command specified by *Command* to the mail server.
This is useful when you need to send a command that in not supported the POP3Socket.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
POP3Socket.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.
``` xojo
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
```
## Event descriptions
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
POP3Socket.ConnectionEstablished
**ConnectionEstablished**
Occurs when a connection has been established.
If you have provided a username and password, the authentication has not taken place yet when this event fires. All commands which require that the user is authenticated will return an error. In such a case, move your code into the `LoginSuccessful` event.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
POP3Socket.Disconnected
**Disconnected**
Occurs when the connection with the server has been lost.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
POP3Socket.ListReceived
**ListReceived**(List As `String`)
Executes when the `ListMessages` method is called.
The *List* parameter contains the message listing in the format described in RFC 1939.
A typical list is:
``` xojo
+OK
1 1253
2 7801
3 534
4 6724
.
```
- "+OK " indicates success
- Each following line consists in the message number, a space and the message size
- The final dot indicates the end of the list
- **NOTE** that the end of line is *normally* CRLF, i.e. `EndOfLine`.
The following code parses the *List* and store data as an array of `Pairs`:
``` xojo
Dim theList() As Pair ' Will hold the result
Dim tmp() As String ' Temporary table
tmp = Split(list, EndOfLine.Windows) ' Store each line in the temporary table
If tmp.Ubound < 2 Then ' There is no more than 2 lines, i.e. there is nothing between the leading "+OK " and the trailing "."
' The list is empty
Return
Else ' The list is not empty
' Walk through the temporary table, avoiding the first and last lines which contain no information
For i As Integer = 1 To tmp.Ubound - 1
Dim s As String
s = tmp(i)
' Append a new Pair made of the message number (before the space character) and the message size (after the space character)
theList.Append(New Pair(Val(NthField(s, " ", 1 )), Val(NthField(s, " ", 2))))
Next
' Now we're ready to process the list
For i As Integer = 0 To theList.Ubound
Dim p As Pair
p = theList(i)
' p.Left contains the message number as an integer
' p.Right contains the message size as an integer
' ... Add your code here
Next
End If
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
POP3Socket.LoginSuccessful
**LoginSuccessful**
Executes when the login process initiated by calling the Connect method is complete.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
POP3Socket.MessageCount
**MessageCount**(Count As `Integer`)
Executes when the mail server replies to a CountMessages call and contains the number of messages in the mailbox.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
POP3Socket.MessageDeleted
**MessageDeleted**(Index As `Integer`)
Executes when the mail server replies to a DeleteMessage call and contains the index number of the deleted message.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
POP3Socket.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 RetrieveMessage. *The Index* parameter contains the index number of the retrieved message and the message contents is in *Message*.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
POP3Socket.RollbackSuccessful
**RollbackSuccessful**
Executes in response to a call to RollbackServer and indicates that the state of the mailbox has been reset.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
POP3Socket.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.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
POP3Socket.SendProgress
**SendProgress**(BytesSent As `Integer`, BytesLeft As `Integer`)
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.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
POP3Socket.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.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
POP3Socket.ServerCommandReply
**ServerCommandReply**(Command As `String`, Data As `String`)
Executes in response to a call to `SendServerCommand` and contains the mail server's response to the command passed.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
POP3Socket.ServerError
**ServerError**(ErrorCode As `Integer`, ErrorMessage As `String`, MessageID As `Integer`)
Executes when a protocol-related error occurs.
The error codes returned in the *ErrorCode* parameter 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 |
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
POP3Socket.TopLinesReceived
**TopLinesReceived**(Index As `Integer`, Data As `EmailMessage`)
Executes in response to a call to RetrieveLines. The *Index* parameter contains the index number of the partial message being retrieved and *Data* contains the requested lines of the message.
## 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.
``` xojo
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.
Steps:
1. 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)
2. Set the username and password. You can also set `EncryptPassword` to `True` if the server supports APOP authentication.
3. Call the `Connect` method.
4. In the `LoginSuccessful` event, add the code that you want to execute, e.g.:
5. Call `ListMessages` to receive the list of messages on the server in the `ListReceived` event
6. Call `RetrieveMessage` to get a message through the `MessageReceived` event
## Sample code
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 `SMTPSecureSocket` 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.
``` xojo
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.
``` xojo
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.
``` xojo
Me.CountMessages
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
The POP3Socket's `TopLinesReceived` event populates the `ListBox` with summary information on each email that was received.
``` xojo
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
```
## Compatibility
All project types on all supported operating systems.
## See also
`TCPSocket` parent class; \* `EmailMessage`, `POP3SecureSocket`, `URLConnection`, `SMTPSecureSocket`, `SocketCore`, `TCPSocket` classes. \* Specifications of POP3 (Post Office Protocol version 3): RFC 1939 and updates.