Sidebar
k24:k24.5:start
Table of Contents
24.5.0 Component gb.net.pop3
The POP3Client component (gb.net.pop3) provides you with everything you need via its properties and methods in order to be able to use the online mode
- taking into account the required connection security and authentication method to establish and maintain a connection to a POP3 server,
- to request status messages about the connection,
- retrieve the number of emails present in the mailbox,
- get an overview of the e-mails in the mailbox,
- download emails from the mailbox to the POP3 server,
- delete e-mails in the mailbox on the POP3 server or
- to disconnect an existing TCP/IP connection to a POP3 server.
Note:
The component does not provide you with a parser for the content of a downloaded email to display the content of an email - including its attachments!
24.5.0.1 Properties
The POP3Client class has these properties:
| Property | Data type | Description |
|---|---|---|
| Host | String | Sets the POP3 server or returns the server. |
| Port | String | Sets the port used when connecting to the POP3 server or returns the port used. If no port is specified, it is set automatically depending on the set connection security. For an SSL connection the port is 995 and for a plain text connection 110. |
| User | String | Sets the user name used for identification or returns this user name. |
| Password | String | Returns the password used for authentication or sets the password. It cannot be changed once a connection to the POP3 server is established. |
| Status | Integer | Returns the status of the POP3 client connection to the POP3 server. An authentication error is acknowledged with Net.CannotAuthenticate (-16). If a POP3 client connection to the POP3 server could be established without errors, the status Net.Connected (7) is returned and the server waits for commands according to the POP3 protocol or closes the connection after a timeout. |
| Encrypt | Integer | With Net.None (0) no encryption of the connection between POP3 client and POP3 server is used. An encryption of the connection (SSL tunnel) between POP3 client and POP3 server is signalled with the constant Net.SSL (1). |
| Count | Integer | Returns the number of emails in the POP3 server's mailbox. |
| Size | Integer | Returns the size of all e-mails in the POP3 server's mailbox (unit: byte). |
| Debug | Boolean | Sets the debug mode or returns the mode. For the value 'True' all requests to the server and the server responses can be displayed in a separate format. |
| Welcome | String | Returns a special message that the POP3 server sends to the POP3 client after the connection is successfully established. |
Table 24.5.0.1.1 : Properties of the class Pop3Client
Excerpt of the output in the console of the Gambas IDE for the value Pop3Client.Debug = True:
gb.net.pop3: Connecting to 195.004.092.211 gb.net.pop3: Authenticating... gb.net.pop3: Sending: USER meinUsername ' Bei FREENET gilt: Username = komplette EMail-Adresse gb.net.pop3: +OK user ok gb.net.pop3: Sending: PASS ***************** gb.net.pop3: +OK 4 messages (23445 octets). gb.net.pop3: OK
24.5.0.2 Methods
The POP3Client class has these methods:
| Method | ReturnType | Description |
|---|---|---|
| Open( ) | Boolean | Connects the PO3 client to the POP3 server and authenticates the client. The function returns True if the connection could be established successfully and the authentication was successful. |
| Close( ) | Boolean | Logs off the POP3 server and disconnects the client from the server. |
| Abort( ) | - | Terminate the connection and disconnect from the POP3 server. The mailbox is left untouched. E-mails already marked for deletion are restored (rollback). |
| List( ) | String[ ] | The function returns a string array which contains the current number with List()[0]) and the size of each email in the mailbox with List()[1]. |
| ListUniqueID( ) | String[ ] | The function returns a string array containing the unique identifier (UID) of each message on the server. A unique UID uniquely identifies a message and is retained across multiple sessions. The UID is a server-defined string and the RFC (https://tools.ietf.org/html/rfc1939#page-12) does not specify a format for it. Do not rely on a pattern for the UID that you encounter on a particular server. |
| Ping( ) | Boolean | The function sends the NOOP (no operation) command to the POP3 server to check and maintain the status of the connection. You should use a timer to avoid a sudden interruption. |
| Remove ( Index As Integer ) | - | Deletes the email selected via the argument 'Index' in the mailbox, but the email is only marked as the email to be deleted. The argument 'Index' is the (consecutively numbered) index of an email. After logging off from the POP3 server and disconnecting the POP3 client from the POP3 server, the emails marked for deletion are finally deleted from the mailbox. |
| Reset( ) | - | Resets the mailbox to the original state as at the beginning of the session. Emails already marked for deletion are restored (rollback). |
| Stat( ) | Integer[ ] | Returns an integer array containing the number of messages in the mailbox (Stat()[0]) and their total size (Stat()[1]) (unit byte). |
Table 24.5.0.2.1 : Methods of the class POP3Client
You can create the class. Here is an example:
Public hPop3Client As Pop3Client hPop3Client = New Pop3Client()
To manage the individual emails online, you need a so-called message instance:
Public hPop3Client As New Pop3Client Dim hPop3ClientMessage As _Pop3Client_Message hPop3ClientMessage = hPop3Client [ Index As Integer ]
With the following instructions you go through the mailbox online. A message object for each of the individual messages of the type MimeMessage is returned.
Public hPop3Client As New Pop3Client Dim hPop3ClientMessage As _Pop3Client_Message For Each hPop3ClientMessage In hPop3Client ... Next
If you want to find out more about the POP3 protocol, you should at least follow these links:
- https://tools.ietf.org/html/rfc1939#page-15 → APOP (Authenticated Post Office Protocol)
Actuate the author's experience: Only if you know the basics sufficiently well how the POP3 protocol works, you will be able to use the implemented properties and methods of the class POP3Client successfully. Before you work with the class POP3Client → Chapter 24.5.3 in your POP3 projects, you should therefore read the following two chapters on the practical implementation of the POP3 protocol and reproduce the examples on the console with the data of your own e-mail account.
k24/k24.5/start.txt · Last modified: 16.08.2022 (external edit)
Page Tools
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Noncommercial 3.0 Unported
