POP3Socket

From Xojo Documentation

Revision as of 18:56, 19 November 2009 by WikiSysop (talk) (1 revision)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)


Description

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


Super Class

TCPSocket

Events

Name Parameters Description
ConnectionEstablished Occurs when a connection has been established.
Disconnected Occurs when the connection with the server has been lost.
ListReceived List as String Executes when the ListMessages method is called.

The List parameter contains the message listing.

LoginSuccessful Executes when the login process initiated by calling the Connect method is complete.
MessageCount Count as Integer Executes when the mail server replies to a CountMessages call and contains the number of messages in the mailbox.
MessageDeleted Index as Integer Executes when the mail server replies to a DeleteMessage call and contains the index number of the deleted message.
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.

RollbackSuccessful Executes in response to a call to RollbackServer and indicates that the state of the mailbox has been reset.
ServerAvailable Executes when the mail server has replied to a call to CheckServerConnection and indicates that the mail server has replied to the call.
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.
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: 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

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.


Properties

Name Type Description
EncryptPassword Boolean If True, the password is encrypted when being sent to the mail server.
Password String The password to use for security when connecting to the mail server.
Username String The username to use for authentication when connecting to the mail server.


Methods

Name Parameters Description
CheckServerConnection Sends a "NOOP" command to the mail server.

This is simply 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.

Connect Connects to the mail server and logs in with the values in the Username and Password properties.
CountMessages Asks the server for the number of messages in the mailbox.

It triggers the MessageCount event, from which you can get the total.

DeleteMessage Index as Integer Tells the mail server to delete the specified message.
DisconnectFromServer Disconnects from the mail server.

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

ListMessages [Index as Integer] Requests a message listing. It fires the ListReceived event. It fires the ListReceived event.

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.

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.

RetrieveMessage Index as Integer Reads the entire message specified by Index.
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.

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 REALbasic doesn't yet support.


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.


Examples

The following example is from the "Email Example" project that is in the Internet folder in the Examples folder that is shipped with REALbasic. The project uses two windows. The "demoWindow" window is used to receive emails. The "sendDemoWindow" window uses the SMTPSocket to send emails.

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

If Me.caption = "Connect" then
//get POP3 sever address and port to use


 POP3socket1.Address = NthField(ServerFld.text,":",1)
 POP3socket1.Port = Val(NthField(serverFld.Text,":",2)
If POP3Socket1.Port = 0 then
   POP3Socket.Port =110
End if


//get account info
 POP3Socket1.Username = UsernameFld.text
 POP3Socket1.Password = passwordFld.text


//establish connection
 POP3Socket1.connect
Me.Caption = "Disconnect" //change button text while connected
else
 POP3Socket1.DisconnectFromServer
Me.caption = "Connect"
End if

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

Sub MessageReceived (ID as Integer, Email as EmailMessage)
Dim s as String
  
  // display the message
  s = Email.bodyHTML
  if s = "" then
  s = Email.bodyPlainText
 end if
 BodyFld.text = ReplaceAll(s,Chr(13)+Chr(10),Chr(13))

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

Me.CountMessages

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

Sub TopLinesReceived (ID as Integer, Email as EmailMessage)
// headers received. populate the Listbox
 ListBox1.AddRow Email.Subject()
 ListBox1.Cell(ListBox1.LastIndex,1) = Email.FromAddress()
 ListBox1.Cell(ListBox1.LastIndex,2) = Str(ID)
  
if ID < MessageTotal then // there are still messages left
Me.RetrieveLines id+1,0/ / get the next message headers
 End if

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


See Also

EmailMessage, HTTPSocket, SMTPSocket, SocketCore, TCPSocket classes.