|
![]() |
|||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--ipworks.Pop
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 |
public static final int popIdle
public static final int popConnect
public static final int popDisconnect
public static final int popRetrieve
public static final int popDelete
public static final int popReset
public static final int fwNone
public static final int fwTunnel
public static final int fwSOCKS4
public static final int fwSOCKS5
Constructor Detail |
public Pop()
Method Detail |
public int getAction()
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:
User
and Password
. Then it retrieves initial statistics about
the mailbox contents ( MessageCount
and TotalSize
).
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).
MailServer
to retrieve the message specified by MessageNumber
.
Please check also the MaxLines
property.
MailServer
to delete the message specified by MessageNumber
.
MailServer
to reset all changes and revert back to the state
it was when connected.
public void setAction(int action) throws IPWorksException
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:
User
and Password
. Then it retrieves initial statistics about
the mailbox contents ( MessageCount
and TotalSize
).
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).
MailServer
to retrieve the message specified by MessageNumber
.
Please check also the MaxLines
property.
MailServer
to delete the message specified by MessageNumber
.
MailServer
to reset all changes and revert back to the state
it was when connected.
public void setCommand(java.lang.String command) throws IPWorksException
LastReply
property and/or trap the PITrail
events
comming from the server to get the response.
public boolean isConnected()
public byte[] getFirewallData()
public void setFirewallData(byte[] firewallData) throws IPWorksException
public java.lang.String getFirewallHost()
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.
public void setFirewallHost(java.lang.String firewallHost) throws IPWorksException
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.
public java.lang.String getFirewallPassword()
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.
public void setFirewallPassword(java.lang.String firewallPassword) throws IPWorksException
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.
public int getFirewallPort()
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.
public void setFirewallPort(int firewallPort) throws IPWorksException
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.
public int getFirewallType()
FirewallPort
is set to 80.
FirewallPort
is set to 1080.
FirewallPort
is set to 1080.
public void setFirewallType(int firewallType) throws IPWorksException
FirewallPort
is set to 80.
FirewallPort
is set to 1080.
FirewallPort
is set to 1080.
public java.lang.String getFirewallUser()
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.
public void setFirewallUser(java.lang.String firewallUser) throws IPWorksException
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.
public java.lang.String getLastReply()
PITrail
event.
public java.lang.String getLocalFile()
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.
public void setLocalFile(java.lang.String localFile) throws IPWorksException
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.
public java.lang.String getLocalHost()
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.
public void setLocalHost(java.lang.String localHost) throws IPWorksException
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.
public int getMailPort()
MailPort
property while
connected will fail with an error.
public void setMailPort(int mailPort) throws IPWorksException
MailPort
property while
connected will fail with an error.
public java.lang.String getMailServer()
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.
public void setMailServer(java.lang.String mailServer) throws IPWorksException
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.
public int getMaxLineLength()
public void setMaxLineLength(int maxLineLength) throws IPWorksException
public int getMaxLines()
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.
public void setMaxLines(int maxLines) throws IPWorksException
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.
public int getMessageCount()
MessageCount
property is 0. When connected, it contains
the number of messages in the mail box as reported by the POP server.
public java.lang.String getMessageHeaders()
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.
public int getMessageNumber()
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).
public void setMessageNumber(int messageNumber) throws IPWorksException
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).
public int getMessageSize()
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.
public java.lang.String getMessageText()
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.
public java.lang.String getMessageUID()
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.
public java.lang.String getPassword()
MailServer
.
public void setPassword(java.lang.String password) throws IPWorksException
MailServer
.
public int getTimeout()
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.
public void setTimeout(int timeout) throws IPWorksException
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.
public int getTotalSize()
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.
public java.lang.String getUser()
MailServer
.
public void setUser(java.lang.String user) throws IPWorksException
MailServer
.
public void fireEndTransfer()
PopEndTransferEvent
public void fireError(int errorCode, java.lang.String description)
PopErrorEvent
public void fireHeader(java.lang.String field, java.lang.String value)
PopHeaderEvent
public void firePITrail(int direction, java.lang.String message)
PopPITrailEvent
public void fireStartTransfer()
PopStartTransferEvent
public void fireTransfer(int bytesTransferred, byte[] text, boolean EOL)
PopTransferEvent
public void connect() throws IPWorksException
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 .
public void delete() throws IPWorksException
MailServer
to delete the message specified by MessageNumber
.
Calling this method is equivalent to setting the Action
property
to popDelete .
public void disconnect() throws IPWorksException
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 .
public void interrupt() throws IPWorksException
Action
property
to Idle (0) .
public void reset() throws IPWorksException
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 .
public void retrieve() throws IPWorksException
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 .
public void addPopEventListener(PopEventListener l) throws java.util.TooManyListenersException
public void removePopEventListener(PopEventListener l)
|
![]() |
|||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |