POP3 - Post Office Protocol

The POP3 protocol -- defined in the standard RFC 1939 -- is used to retrieve mail messages from a remote mail hub. Usually, this is done over a TCP/IP link, but this is not a requirement.

The Carapace Pop3 module is a class which implements this POP3 protocol. It is a scripted module which can be put on a communications stack.

POP3 is only used for fetching messages -- if you wish to send messages, you may wish to use the SMTP protocol.

Pop3 Stack Requirements

The module directly below the Pop3 module must be a Util module. There are no requirements on the bottom module on the stack, though often it is a Tcp module.

Pop3 Creation

The create function can be used to create a Pop3 module eg.

    (create Pop3)

Once created, this module is tailored using its properties and methods.

However, a Pop3 module is often created in the process of creating a comms stack by using the function buildCommsStack.

Pop3 Properties

A Pop3 module supports the following properties:

property name	property type	description
`user`	String	name of the user when logging on to the POP3 server
`password`	String	password used when logging on to the POP3 server
`secret`	String	a 'secret' known to the POP server -- used for secure authentication using the APOP (strong authenticate logon) command
`timeout`	Integer	timeout (milliseconds) for getting responses back from the server
`stack`	Stack	the layers of the stack below this module in the full stack
`log`	Log	a log for the POP3 connection
`connectionTimestamp`	String	timestamp used for encrypting passwords on the POP3 connection
`errorClass`	Integer	class of POP3-specific errors
`greeting`	String	greeting returned by the POP3 server on connection

Pop3 Methods

The Pop3 module supports the following standard comms module methods:

method name	description
`connect`	connect this module
`disconnect`	disconnect this module

In addition, it supports the following POP-specific methods:

method name	description
`listMailbox`	list the mailbox
`mailboxStatus`	get the status of the mailbox
`messageSize`	get the size of a message
`messageUID`	get the unique mailbox id for a message
`fetch`	fetch a message
`delete`	delete a message
`noop`	check the POP server will send a positive reply
`reset`	reset the POP server
`listMailboxUID`	get a unique id listing for the mailbox
`top`	return the top n lines of the identified message

`listMailbox`

List the mailbox. This returns a list of pairs, where each pair is itself a list:

    ( messageId    msgSize )

POP command: LIST

Arguments: none

Return type: List

`mailboxStatus`

Get the status of the mailbox. This returns a list of two integers:

    ( totalNumberOfMsgs    combinedMsgSize )

POP command: STAT

Arguments: none

Return type: List

`messageSize`

Get the size of a message in bytes.

POP command: LIST

Arguments:

msgNo Integer

Return type: Integer

`messageUID`

Get the unique mailbox id for a message. This message id uniquely identifies a message within the mailbox. Also, this message id remains the same for as long as the message is in the mailbox. This is unlike the message number which is the order of the message in the mailbox and which changes when messages are added/deleted.

POP command: UIDL

Arguments:

msgNo Integer

Return type: String

`fetch`

Fetch the message having the supplied message number.

POP command: RETR

Arguments:

msgNo Integer

Return type: String

`delete`

Delete the message having the supplied message number.

POP command: DELE

Arguments:

msgNo Integer

Return type: String

`noop`

Check the POP server will send a positive reply.

POP command: NOOP

Arguments: none

Return type: String

`reset`

Reset the POP server.

POP command: RSET

Arguments: none

Return type: String

`listMailboxUID`

Get a unique id listing for the mailbox. This returns a list of pairs, where each pair is a list as follows:

    ( msgNo    msgUniqueId )

POP command: UIDL

Arguments: none

Return type: String

`top`

Return the top n lines of the identified message.

Arguments:

msgNo	`Integer`
nLines	`Integer`

Return type: String

Contents

Index

Current topic: communications

Related topics: communications classes, objects