IP*Works!

ipworks
Class Pop

java.lang.Object
  |
  +--ipworks.Pop

public class Pop
extends java.lang.Object

The POP control is used retrieve electronic mail from Internet Post Office servers (POP).

The POP control implements a standard internet post office (POP3) client as specified in RFC 1725.

The control is driven by a few key properties and methods as well as the Action property. To connect to a MailServer first set the appropriate User and Password and then connect by calling the Connect method or setting the Action to popConnect . Upon successful connection to the MailServer , the number of waiting messages is shown by the MessageCount property. A message is selected by setting the MessageNumber property to a number between 1 and MessageCount (inclusive). Then, message text and/or headers are received by calling the Retrieve method or by setting Action to the appropriate value.

The message text is received through the Transfer event, whereas the message headers are received through the Header event. Additionally, up to MaxLines from the message body are provided in the MessageText property. The body of the message is also saved in the file specified by the LocalFile property. StartTransfer and EndTransfer events are fired at the beginning and end of message transmission. The PITrail event provides a trace of the interaction between the client and server (excluding message transfers).


Field Summary
static int fwNone
           
static int fwSOCKS4
           
static int fwSOCKS5
           
static int fwTunnel
           
static int popConnect
           
static int popDelete
           
static int popDisconnect
           
static int popIdle
           
static int popReset
           
static int popRetrieve
           
 
Constructor Summary
Pop()
           
 
Method Summary
 void addPopEventListener(PopEventListener l)
           
 void connect()
          Connects to the mail server and attempts to login.
 void delete()
          Delete a message specified by MessageNumber on the server.
 void disconnect()
          Disconnects from the mail server.
 void fireEndTransfer()
          Fired when the message completes transferring.
 void fireError(int errorCode, java.lang.String description)
          Information about errors during data delivery.
 void fireHeader(java.lang.String field, java.lang.String value)
          Fired for every message header being retrieved.
 void firePITrail(int direction, java.lang.String message)
          Traces the commands sent to the mail server, and the respective replies.
 void fireStartTransfer()
          Fired when the message starts transferring.
 void fireTransfer(int bytesTransferred, byte[] text, boolean EOL)
          Fired while the message gets transferred from MailServer .
 int getAction()
          An action code for the component.
 byte[] getFirewallData()
          Used to send other data to firewall.
 java.lang.String getFirewallHost()
          Name or IP address of firewall (optional).
 java.lang.String getFirewallPassword()
          A password if authentication is to be used connecting through the firewall.
 int getFirewallPort()
          Port of the firewall to connect to.
 int getFirewallType()
          Determines the type of firewall to connect through.
 java.lang.String getFirewallUser()
          A user name if authentication is to be used connecting through a firewall.
 java.lang.String getLastReply()
          The last reply from the server.
 java.lang.String getLocalFile()
          The path to a local file for downloading the message body.
 java.lang.String getLocalHost()
          The name of the local host or user-assigned IP interface through which connections are initiated or accepted.
 int getMailPort()
          The server port for POP (default 110).
 java.lang.String getMailServer()
          The name or address of a mail server (internet post office server).
 int getMaxLineLength()
          The maximum expected length for message lines.
 int getMaxLines()
          The maximum number of message lines beside headers to retrieve.
 int getMessageCount()
          The number of messages waiting in the mailbox.
 java.lang.String getMessageHeaders()
          The full headers of the message as retrieved from the server.
 int getMessageNumber()
          Current (selected) message.
 int getMessageSize()
          The size in bytes of the current message.
 java.lang.String getMessageText()
          The full text of the message as retrieved from the server.
 java.lang.String getMessageUID()
          The unique id of the message as specified by the server.
 java.lang.String getPassword()
          The password for the mailbox user.
 int getTimeout()
          A timeout for the component.
 int getTotalSize()
          Cumulative size in bytes of messages in the mailbox (including headers).
 java.lang.String getUser()
          The user id for the mailbox.
 void interrupt()
          Interrupt the Action in progress (if any).
 boolean isConnected()
          Shows whether the component is connected.
 void removePopEventListener(PopEventListener l)
           
 void reset()
          Reset all changes and revert back to the state when the user first connected.
 void retrieve()
          Retrieve a message specified by MessageNumber from the server.
 void setAction(int action)
          An action code for the component.
 void setCommand(java.lang.String command)
          Can be used to send additional commands directly to the POP server.
 void setFirewallData(byte[] firewallData)
          Used to send other data to firewall.
 void setFirewallHost(java.lang.String firewallHost)
          Name or IP address of firewall (optional).
 void setFirewallPassword(java.lang.String firewallPassword)
          A password if authentication is to be used connecting through the firewall.
 void setFirewallPort(int firewallPort)
          Port of the firewall to connect to.
 void setFirewallType(int firewallType)
          Determines the type of firewall to connect through.
 void setFirewallUser(java.lang.String firewallUser)
          A user name if authentication is to be used connecting through a firewall.
 void setLocalFile(java.lang.String localFile)
          The path to a local file for downloading the message body.
 void setLocalHost(java.lang.String localHost)
          The name of the local host or user-assigned IP interface through which connections are initiated or accepted.
 void setMailPort(int mailPort)
          The server port for POP (default 110).
 void setMailServer(java.lang.String mailServer)
          The name or address of a mail server (internet post office server).
 void setMaxLineLength(int maxLineLength)
          The maximum expected length for message lines.
 void setMaxLines(int maxLines)
          The maximum number of message lines beside headers to retrieve.
 void setMessageNumber(int messageNumber)
          Current (selected) message.
 void setPassword(java.lang.String password)
          The password for the mailbox user.
 void setTimeout(int timeout)
          A timeout for the component.
 void setUser(java.lang.String user)
          The user id for the mailbox.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

popIdle

public static final int popIdle

popConnect

public static final int popConnect

popDisconnect

public static final int popDisconnect

popRetrieve

public static final int popRetrieve

popDelete

public static final int popDelete

popReset

public static final int popReset

fwNone

public static final int fwNone

fwTunnel

public static final int fwTunnel

fwSOCKS4

public static final int fwSOCKS4

fwSOCKS5

public static final int fwSOCKS5
Constructor Detail

Pop

public Pop()
Method Detail

getAction

public int getAction()
An action code for the component. Setting the Action property to a valid action code makes the control perform the associated action. If the action completes successfully, execution continues normally, and Action is reset to 0 (Idle). If an error happens, then an IPWorksException exception is raised.

The following are the possible values for the Action property and the corresponding descriptions:

popIdle (0)
Default action. It can also be used to interrupt the current operation.
popConnect (1)
Connects to the mail server and attempts to login using the current User and Password . Then it retrieves initial statistics about the mailbox contents ( MessageCount and TotalSize ).
popDisconnect (2)
Makes the control disconnect from the MailServer by posting a QUIT command. If successful, all changes to the mailbox are committed by the server, otherwise, changes are rolled back to the initial state (before the connection).
popRetrieve (3)
Asks the MailServer to retrieve the message specified by MessageNumber . Please check also the MaxLines property.
popDelete (4)
Asks the MailServer to delete the message specified by MessageNumber .
popReset (5)
Asks the MailServer to reset all changes and revert back to the state it was when connected.


setAction

public void setAction(int action)
               throws IPWorksException
An action code for the component. Setting the Action property to a valid action code makes the control perform the associated action. If the action completes successfully, execution continues normally, and Action is reset to 0 (Idle). If an error happens, then an IPWorksException exception is raised.

The following are the possible values for the Action property and the corresponding descriptions:

popIdle (0)
Default action. It can also be used to interrupt the current operation.
popConnect (1)
Connects to the mail server and attempts to login using the current User and Password . Then it retrieves initial statistics about the mailbox contents ( MessageCount and TotalSize ).
popDisconnect (2)
Makes the control disconnect from the MailServer by posting a QUIT command. If successful, all changes to the mailbox are committed by the server, otherwise, changes are rolled back to the initial state (before the connection).
popRetrieve (3)
Asks the MailServer to retrieve the message specified by MessageNumber . Please check also the MaxLines property.
popDelete (4)
Asks the MailServer to delete the message specified by MessageNumber .
popReset (5)
Asks the MailServer to reset all changes and revert back to the state it was when connected.


setCommand

public void setCommand(java.lang.String command)
                throws IPWorksException
Can be used to send additional commands directly to the POP server. Check the LastReply property and/or trap the PITrail events comming from the server to get the response.


isConnected

public boolean isConnected()
Shows whether the component is connected. Use this property to determine whether the control is connected to the remote host or not.


getFirewallData

public byte[] getFirewallData()
Used to send other data to firewall. When the firewall is a tunneling proxy, use this property to to send custom (additional) headers to the firewall (e.g. headers for custom authentication schemes).


setFirewallData

public void setFirewallData(byte[] firewallData)
                     throws IPWorksException
Used to send other data to firewall. When the firewall is a tunneling proxy, use this property to to send custom (additional) headers to the firewall (e.g. headers for custom authentication schemes).


getFirewallHost

public java.lang.String getFirewallHost()
Name or IP address of firewall (optional). If a FirewallHost is given, requested connections will be authenticated through the specified firewall when connecting.

If the FirewallHost property is set to a Domain Name, a DNS request is initiated and upon successful termination of the request, the FirewallHost property is set to the corresponding address. If the search is not successful, an error is returned.


setFirewallHost

public void setFirewallHost(java.lang.String firewallHost)
                     throws IPWorksException
Name or IP address of firewall (optional). If a FirewallHost is given, requested connections will be authenticated through the specified firewall when connecting.

If the FirewallHost property is set to a Domain Name, a DNS request is initiated and upon successful termination of the request, the FirewallHost property is set to the corresponding address. If the search is not successful, an error is returned.


getFirewallPassword

public java.lang.String getFirewallPassword()
A password if authentication is to be used connecting through the firewall. if FirewallHost is specified, the FirewallUser and FirewallPassword properties are used to connect and authenticate to the given firewall. If the authentication fails, a trappable error is fired.


setFirewallPassword

public void setFirewallPassword(java.lang.String firewallPassword)
                         throws IPWorksException
A password if authentication is to be used connecting through the firewall. if FirewallHost is specified, the FirewallUser and FirewallPassword properties are used to connect and authenticate to the given firewall. If the authentication fails, a trappable error is fired.


getFirewallPort

public int getFirewallPort()
Port of the firewall to connect to. The TCP port for the FirewallHost . See the description of the FirewallHost property for details.

Note that the FirewallPort is set automatically when FirewallType is set to a valid value. See the description of the FirewallType property for details.


setFirewallPort

public void setFirewallPort(int firewallPort)
                     throws IPWorksException
Port of the firewall to connect to. The TCP port for the FirewallHost . See the description of the FirewallHost property for details.

Note that the FirewallPort is set automatically when FirewallType is set to a valid value. See the description of the FirewallType property for details.


getFirewallType

public int getFirewallType()
Determines the type of firewall to connect through. The applicable values are the following:
fwNone (0)
No firewall (default setting).
fwTunnel (1)
Connect through a tunneling proxy. FirewallPort is set to 80.
fwSOCKS4 (2)
Connect through a SOCKS4 Proxy. FirewallPort is set to 1080.
fwSOCKS5 (3)
Connect through a SOCKS5 Proxy. FirewallPort is set to 1080.


setFirewallType

public void setFirewallType(int firewallType)
                     throws IPWorksException
Determines the type of firewall to connect through. The applicable values are the following:
fwNone (0)
No firewall (default setting).
fwTunnel (1)
Connect through a tunneling proxy. FirewallPort is set to 80.
fwSOCKS4 (2)
Connect through a SOCKS4 Proxy. FirewallPort is set to 1080.
fwSOCKS5 (3)
Connect through a SOCKS5 Proxy. FirewallPort is set to 1080.


getFirewallUser

public java.lang.String getFirewallUser()
A user name if authentication is to be used connecting through a firewall. if FirewallHost is specified, the FirewallUser and FirewallPassword properties are used to connect and authenticate to the given firewall. If the authentication fails, a trappable error is fired.


setFirewallUser

public void setFirewallUser(java.lang.String firewallUser)
                     throws IPWorksException
A user name if authentication is to be used connecting through a firewall. if FirewallHost is specified, the FirewallUser and FirewallPassword properties are used to connect and authenticate to the given firewall. If the authentication fails, a trappable error is fired.


getLastReply

public java.lang.String getLastReply()
The last reply from the server. This is the last reply received from the server. It can be used for information purposes. The same information and more can also be retrieved through the PITrail event.


getLocalFile

public java.lang.String getLocalFile()
The path to a local file for downloading the message body. If the file exists, it is overwritten. (optional) The LocalFile property is used when retrieving a message via the Action property. If LocalFile is empty then the received data is provided through the parameters of the Transfer event.


setLocalFile

public void setLocalFile(java.lang.String localFile)
                  throws IPWorksException
The path to a local file for downloading the message body. If the file exists, it is overwritten. (optional) The LocalFile property is used when retrieving a message via the Action property. If LocalFile is empty then the received data is provided through the parameters of the Transfer event.


getLocalHost

public java.lang.String getLocalHost()
The name of the local host or user-assigned IP interface through which connections are initiated or accepted. The LocalHost property contains the name of the local host as obtained by the gethostname() Winsock call, or if the user has assigned an IP address, the value of that address.

In multihomed hosts (machines with more than one IP interface) setting LocalHost to the value of an interface will make the control initiate connections (or accept in the case of server controls) only through that interface.

If the control is connected, the LocalHost property shows the IP address of the interface through which the connection is made in internet dotted format (aaa.bbb.ccc.ddd). In most cases, this is the address of the local host, except for multihomed hosts (machines with more than one IP interface).

NOTE: LocalHost is not persistent. You must always set it in code, and never in the property window.


setLocalHost

public void setLocalHost(java.lang.String localHost)
                  throws IPWorksException
The name of the local host or user-assigned IP interface through which connections are initiated or accepted. The LocalHost property contains the name of the local host as obtained by the gethostname() Winsock call, or if the user has assigned an IP address, the value of that address.

In multihomed hosts (machines with more than one IP interface) setting LocalHost to the value of an interface will make the control initiate connections (or accept in the case of server controls) only through that interface.

If the control is connected, the LocalHost property shows the IP address of the interface through which the connection is made in internet dotted format (aaa.bbb.ccc.ddd). In most cases, this is the address of the local host, except for multihomed hosts (machines with more than one IP interface).

NOTE: LocalHost is not persistent. You must always set it in code, and never in the property window.


getMailPort

public int getMailPort()
The server port for POP (default 110). A valid port number (a value between 1 and 65535) is required for the connection to take place. The property must be set before a connection is attempted and cannot be changed while a connection is in progress. Any attempt to change the MailPort property while connected will fail with an error.


setMailPort

public void setMailPort(int mailPort)
                 throws IPWorksException
The server port for POP (default 110). A valid port number (a value between 1 and 65535) is required for the connection to take place. The property must be set before a connection is attempted and cannot be changed while a connection is in progress. Any attempt to change the MailPort property while connected will fail with an error.


getMailServer

public java.lang.String getMailServer()
The name or address of a mail server (internet post office server). The MailServer property specifies the IP address (IP number in dotted internet format) or Domain Name of the mail server. It is set before a connection is attempted and cannot be changed once a connection is in progress.

If the MailServer property is set to a Domain Name, a DNS request is initiated and upon successful termination of the request, the MailServer property is set to the corresponding address. If the search is not successful, an error is returned.


setMailServer

public void setMailServer(java.lang.String mailServer)
                   throws IPWorksException
The name or address of a mail server (internet post office server). The MailServer property specifies the IP address (IP number in dotted internet format) or Domain Name of the mail server. It is set before a connection is attempted and cannot be changed once a connection is in progress.

If the MailServer property is set to a Domain Name, a DNS request is initiated and upon successful termination of the request, the MailServer property is set to the corresponding address. If the search is not successful, an error is returned.


getMaxLineLength

public int getMaxLineLength()
The maximum expected length for message lines. Normally, internet mail message lines are up to 80 characters long, however, different mail systems might use other values. Change the value of this property if you are expecting longer lines.


setMaxLineLength

public void setMaxLineLength(int maxLineLength)
                      throws IPWorksException
The maximum expected length for message lines. Normally, internet mail message lines are up to 80 characters long, however, different mail systems might use other values. Change the value of this property if you are expecting longer lines.


getMaxLines

public int getMaxLines()
The maximum number of message lines beside headers to retrieve. The MaxLines property is to limit the number of text lines besides headers retrieved for messages. It can be used to preview message headers and a portion of their contents, without incurring the overhead of downloading the entire message.

The default value of the property is 0. In this case the entire message will be retrieved, without interruptions.


setMaxLines

public void setMaxLines(int maxLines)
                 throws IPWorksException
The maximum number of message lines beside headers to retrieve. The MaxLines property is to limit the number of text lines besides headers retrieved for messages. It can be used to preview message headers and a portion of their contents, without incurring the overhead of downloading the entire message.

The default value of the property is 0. In this case the entire message will be retrieved, without interruptions.


getMessageCount

public int getMessageCount()
The number of messages waiting in the mailbox. When the control is not connected to the server, the value of the MessageCount property is 0. When connected, it contains the number of messages in the mail box as reported by the POP server.


getMessageHeaders

public java.lang.String getMessageHeaders()
The full headers of the message as retrieved from the server. If the control is not connected, or MessageNumber does not contain a valid message number, the value of this property is an empty string. Otherwise, it contains the full headers of the mail message as reported by the server.

The MailServer is asked about the headers of the message only if the MessageNumber property has changed. If MessageNumber has not changed, the control returns a cached value.


getMessageNumber

public int getMessageNumber()
Current (selected) message. The MessageNumber property specifies a message number in between 1 and MessageCount . The various control actions related to single messages use this property as a message pointer (see the description of the Action property and the MessageSize property).


setMessageNumber

public void setMessageNumber(int messageNumber)
                      throws IPWorksException
Current (selected) message. The MessageNumber property specifies a message number in between 1 and MessageCount . The various control actions related to single messages use this property as a message pointer (see the description of the Action property and the MessageSize property).


getMessageSize

public int getMessageSize()
The size in bytes of the current message. If the control is not connected, or MessageNumber does not contain a valid message number, the value of this property is 0. Otherwise, it contains the size of the mail message (including headers) as reported by the server.

The MailServer is asked about the size of the message only if the MessageNumber property has changed. If MessageNumber has not changed, the control returns a cached value.


getMessageText

public java.lang.String getMessageText()
The full text of the message as retrieved from the server. If the control is not connected, or MessageNumber does not contain a valid message number, the value of this property is an empty string. Otherwise, it contains the text of the mail message as reported by the server (a maximum of MaxLines ).

The MailServer is asked about the text of the message only if the MessageNumber property has changed. If MessageNumber has not changed, the control returns a cached value.


getMessageUID

public java.lang.String getMessageUID()
The unique id of the message as specified by the server. If the control is not connected, or MessageNumber does not contain a valid message number, the value of this property is an empty string. Otherwise, it contains the UID of the mail message as reported by the server.

The MailServer is asked about the UID of the message only if the MessageNumber property has changed. If MessageNumber has not changed, the control returns a cached value.


getPassword

public java.lang.String getPassword()
The password for the mailbox user. This property must be set before the control connects to the MailServer .


setPassword

public void setPassword(java.lang.String password)
                 throws IPWorksException
The password for the mailbox user. This property must be set before the control connects to the MailServer .


getTimeout

public int getTimeout()
A timeout for the component. If the Timeout property is set to 0 (default value) all actions will run uninterrupted until succesful completion, or an error condition is encountered.

If Timeout is set to a positive value, and any action does not complete within Timeout seconds, the action is aborted, and a 'Timeout' error is fired..

The control will use DoEvents to enter an efficient wait loop during any potential waiting period, making sure that all system events are processed immediately as they arrive. This ensures that the host application does not "freeze" and always remains responsive.


setTimeout

public void setTimeout(int timeout)
                throws IPWorksException
A timeout for the component. If the Timeout property is set to 0 (default value) all actions will run uninterrupted until succesful completion, or an error condition is encountered.

If Timeout is set to a positive value, and any action does not complete within Timeout seconds, the action is aborted, and a 'Timeout' error is fired..

The control will use DoEvents to enter an efficient wait loop during any potential waiting period, making sure that all system events are processed immediately as they arrive. This ensures that the host application does not "freeze" and always remains responsive.


getTotalSize

public int getTotalSize()
Cumulative size in bytes of messages in the mailbox (including headers). When the control is not connected to the server, the value of the TotalSize property is 0. When connected, it contains the cumulative size of all the messages in the mail box as reported by the POP server.


getUser

public java.lang.String getUser()
The user id for the mailbox. This property must be set before the control connects to the MailServer .


setUser

public void setUser(java.lang.String user)
             throws IPWorksException
The user id for the mailbox. This property must be set before the control connects to the MailServer .


fireEndTransfer

public void fireEndTransfer()
Fired when the message completes transferring. (Called internally to dispatch the event.)
See Also:
PopEndTransferEvent

fireError

public void fireError(int errorCode,
                      java.lang.String description)
Information about errors during data delivery. (Called internally to dispatch the event.)
See Also:
PopErrorEvent

fireHeader

public void fireHeader(java.lang.String field,
                       java.lang.String value)
Fired for every message header being retrieved. (Called internally to dispatch the event.)
See Also:
PopHeaderEvent

firePITrail

public void firePITrail(int direction,
                        java.lang.String message)
Traces the commands sent to the mail server, and the respective replies. (Called internally to dispatch the event.)
See Also:
PopPITrailEvent

fireStartTransfer

public void fireStartTransfer()
Fired when the message starts transferring. (Called internally to dispatch the event.)
See Also:
PopStartTransferEvent

fireTransfer

public void fireTransfer(int bytesTransferred,
                         byte[] text,
                         boolean EOL)
Fired while the message gets transferred from MailServer . (Called internally to dispatch the event.)
See Also:
PopTransferEvent

connect

public void connect()
             throws IPWorksException
Connects to the mail server and attempts to login. Connects to the mail server and attempts to login using the current User and Password . Then it retrieves initial statistics about the mailbox contents ( MessageCount and TotalSize ).

Calling this method is equivalent to setting the Action property to popConnect .


delete

public void delete()
            throws IPWorksException
Delete a message specified by MessageNumber on the server. Asks the MailServer to delete the message specified by MessageNumber .

Calling this method is equivalent to setting the Action property to popDelete .


disconnect

public void disconnect()
                throws IPWorksException
Disconnects from the mail server. Makes the control disconnect from the MailServer by posting a QUIT command. If successful, all changes to the mailbox are committed by the server, otherwise, changes are rolled back to the initial state (before the connection).

Calling this method is equivalent to setting the Action property to popDisconnect .


interrupt

public void interrupt()
               throws IPWorksException
Interrupt the Action in progress (if any). Calling this method is equivalent to setting the Action property to Idle (0) .


reset

public void reset()
           throws IPWorksException
Reset all changes and revert back to the state when the user first connected. Asks the MailServer to reset all changes and revert back to the state it was when connected.

Calling this method is equivalent to setting the Action property to popReset .


retrieve

public void retrieve()
              throws IPWorksException
Retrieve a message specified by MessageNumber from the server. Asks the MailServer to retrieve the message specified by MessageNumber . Please check also the MaxLines property.

Calling this method is equivalent to setting the Action property to popRetrieve .


addPopEventListener

public void addPopEventListener(PopEventListener l)
                         throws java.util.TooManyListenersException

removePopEventListener

public void removePopEventListener(PopEventListener l)

IP*Works!

Copyright (c) 2001 /n software inc. - All rights reserved.