IP*Works!

ipworks
Class Smtp

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

public class Smtp
extends java.lang.Object

The SMTP control is used to send Internet mail using the SMTP protocol (the Internet mail standard).

The SMTP control implements a standard SMTP client as specified in RFC 821. It has a simple plug-and-play interface. It contains a number of properties like SendTo , Subject , From , Cc , BCc , etc. that map directly to the internet mail message headers with the same name (RFC 822). The message text is set in MessageText and/or AttachedFile . Messages are sent by calling the Send method or setting the Action property to 'Send Message'.

The control supports message delivery to multiple recipients through the SendTo , Cc , and BCc properties. Simply specify the destination email addresses separated by commas.

The interface of the control is open-ended. New features, including MIME attachments can be supported by using the OtherHeaders property.

A number of events provide feedback during the operation of the control. The Transfer event is fired during message delivery to show the number of bytes delivered. The PITrail event traces the commands that are sent to the server and the respective replies.


Field Summary
static int fwNone
           
static int fwSOCKS4
           
static int fwSOCKS5
           
static int fwTunnel
           
static int smtpConnect
           
static int smtpDisconnect
           
static int smtpExpand
           
static int smtpIdle
           
static int smtpResetHeaders
           
static int smtpSend
           
static int smtpSendToTerminalAndEmail
           
static int smtpSendToTerminalOnly
           
static int smtpSendToTerminalOrEmail
           
static int smtpVerify
           
 
Constructor Summary
Smtp()
           
 
Method Summary
 void addSmtpEventListener(SmtpEventListener l)
           
 void connect()
          Connects to the mail relay and sends the SMTP HELO command.
 void disconnect()
          Disconnect from the SMTP server.
 void expand(java.lang.String emailAddress)
          Asks the MailServer to expand a name or mailing list.
 void fireEndTransfer()
          Fired when the message text completes transferring.
 void fireError(int errorCode, java.lang.String description)
          Information about errors during data delivery.
 void fireExpand(java.lang.String address)
          Fired for every email address returned by the server when Action is set to Expand .
 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 text starts transferring.
 void fireTransfer(int bytesTransferred)
          Fired while the message text gets transferred to MailServer .
 int getAction()
          An action code for the component.
 java.lang.String getAttachedFile()
          A file to append to MessageText when sending mail.
 java.lang.String getBCc()
          A comma separated list of addresses for blind carbon copies (optional).
 java.lang.String getCc()
          A comma separated list of addresses for carbon copies (optional).
 java.lang.String getDate()
          The Date of the mail message (optional).
 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 getFrom()
          The email address of the sender (required).
 java.lang.String getHello()
          The argument for HELO (herald) command to the server (defaults to local host name).
 java.lang.String getLastReply()
          The last reply from the server.
 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 SMTP (default 25).
 java.lang.String getMailServer()
          The name or address of a mail server (mail relay).
 int getMaxHeaderLength()
          Maximum length for headers to avoid line folding (default 80).
 java.lang.String getMessageDate()
          The Date of the mail message (optional).
 java.lang.String getMessageText()
          The full text of the message to send (without headers).
 java.lang.String getOtherHeaders()
          An RFC 822 compliant string consisting of extra headers.
 java.lang.String getPassword()
          A login password to login with in the MailServer .
 java.lang.String getReplyTo()
          A mail address to reply to (optional).
 java.lang.String getSendTo()
          A comma separated list of addresses for destinations (required).
 java.lang.String getSubject()
          The subject of the mail message (optional).
 int getTimeout()
          A timeout for the component.
 java.lang.String getUser()
          A user id to login as in the MailServer .
 void interrupt()
          Interrupt the Action in progress (if any).
 boolean isAllowExtensions()
          A switch allowing the component to use ESMTP features (SMTP extensions).
 boolean isConnected()
          Shows whether the component is connected.
 void removeSmtpEventListener(SmtpEventListener l)
           
 void resetHeaders()
          Resets all the message headers to empty.
 void send()
          Send the current message.
 void sendToTerminalAndEmail()
          Send to terminal and email.
 void sendToTerminalOnly()
          Send to terminal only.
 void sendToTerminalOrEmail()
          Send to terminal or email.
 void setAction(int action)
          An action code for the component.
 void setAllowExtensions(boolean allowExtensions)
          A switch allowing the component to use ESMTP features (SMTP extensions).
 void setAttachedFile(java.lang.String attachedFile)
          A file to append to MessageText when sending mail.
 void setBCc(java.lang.String BCc)
          A comma separated list of addresses for blind carbon copies (optional).
 void setCc(java.lang.String cc)
          A comma separated list of addresses for carbon copies (optional).
 void setCommand(java.lang.String command)
          Can be used to send additional commands directly to the SMTP server.
 void setDate(java.lang.String date)
          The Date of the mail message (optional).
 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 setFrom(java.lang.String from)
          The email address of the sender (required).
 void setHello(java.lang.String hello)
          The argument for HELO (herald) command to the server (defaults to local host name).
 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 SMTP (default 25).
 void setMailServer(java.lang.String mailServer)
          The name or address of a mail server (mail relay).
 void setMaxHeaderLength(int maxHeaderLength)
          Maximum length for headers to avoid line folding (default 80).
 void setMessageDate(java.lang.String messageDate)
          The Date of the mail message (optional).
 void setMessageText(java.lang.String messageText)
          The full text of the message to send (without headers).
 void setOtherHeaders(java.lang.String otherHeaders)
          An RFC 822 compliant string consisting of extra headers.
 void setPassword(java.lang.String password)
          A login password to login with in the MailServer .
 void setReplyTo(java.lang.String replyTo)
          A mail address to reply to (optional).
 void setSendTo(java.lang.String sendTo)
          A comma separated list of addresses for destinations (required).
 void setSubject(java.lang.String subject)
          The subject of the mail message (optional).
 void setTimeout(int timeout)
          A timeout for the component.
 void setUser(java.lang.String user)
          A user id to login as in the MailServer .
 void verify(java.lang.String emailAddress)
          Send a Verify request to the SMTP server.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

smtpIdle

public static final int smtpIdle

smtpConnect

public static final int smtpConnect

smtpDisconnect

public static final int smtpDisconnect

smtpSend

public static final int smtpSend

smtpResetHeaders

public static final int smtpResetHeaders

smtpExpand

public static final int smtpExpand

smtpVerify

public static final int smtpVerify

smtpSendToTerminalAndEmail

public static final int smtpSendToTerminalAndEmail

smtpSendToTerminalOrEmail

public static final int smtpSendToTerminalOrEmail

smtpSendToTerminalOnly

public static final int smtpSendToTerminalOnly

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

Smtp

public Smtp()
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:

smtpIdle (0)
Default action. It can also be used to interrupt the current operation.
smtpConnect (1)
Connects to the mail relay and sends the SMTP HELO command, thus preparing for sending messages. Any number of messages can later be sent using the smtpSendMessage action below.
smtpDisconnect (2)
Disconnects from the mail relay.
smtpSend (3)
If the control is not connected to the mail relay, a connection is created. Then the control attempts to deliver the current message and attached file.
smtpResetHeaders (4)
Resets all the message headers to "" (empty string). Use this property before creating a new message, so that headers from the previous message are not carried over to the next one.
smtpExpand (5)
Asks the MailServer to expand the name or mailing list given in the [ SendTo property. The resulting response is provided in one or more Expand events (one for each address). The control will try to connect to the mail relay if it is not already connected.
smtpVerify (6)
Asks the MailServer to verify the address in the SendTo property. In case of success SendTo will then hold the verified email address. The control will try to connect to the mail relay if it is not already connected.
smtpSendToTerminalAndEmail (7)
Similar to Send but requests also that the message is sent to the terminal of the user as well, if he is logged on and accepts terminal messages. This action requires that AllowExtensions is set to True and is not supported by all mail relays.
smtpSendToTerminalOrEmail (8)
Similar to Send but requests instead that the message is first sent to the user's terminal. If the user is not logged in or does not accept terminal messages, the message is sent to his mailbox. This action requires that AllowExtensions is set to True and is not supported by all mail relays.
smtpSendToTerminalOnly (9)
Similar to Send but requests instead that the message is first to the user's terminal. An exception with the server's response is raised if the user is not logged in or does not accept terminal messages. This action requires that AllowExtensions is set to True and is not supported by all mail relays.


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:

smtpIdle (0)
Default action. It can also be used to interrupt the current operation.
smtpConnect (1)
Connects to the mail relay and sends the SMTP HELO command, thus preparing for sending messages. Any number of messages can later be sent using the smtpSendMessage action below.
smtpDisconnect (2)
Disconnects from the mail relay.
smtpSend (3)
If the control is not connected to the mail relay, a connection is created. Then the control attempts to deliver the current message and attached file.
smtpResetHeaders (4)
Resets all the message headers to "" (empty string). Use this property before creating a new message, so that headers from the previous message are not carried over to the next one.
smtpExpand (5)
Asks the MailServer to expand the name or mailing list given in the [ SendTo property. The resulting response is provided in one or more Expand events (one for each address). The control will try to connect to the mail relay if it is not already connected.
smtpVerify (6)
Asks the MailServer to verify the address in the SendTo property. In case of success SendTo will then hold the verified email address. The control will try to connect to the mail relay if it is not already connected.
smtpSendToTerminalAndEmail (7)
Similar to Send but requests also that the message is sent to the terminal of the user as well, if he is logged on and accepts terminal messages. This action requires that AllowExtensions is set to True and is not supported by all mail relays.
smtpSendToTerminalOrEmail (8)
Similar to Send but requests instead that the message is first sent to the user's terminal. If the user is not logged in or does not accept terminal messages, the message is sent to his mailbox. This action requires that AllowExtensions is set to True and is not supported by all mail relays.
smtpSendToTerminalOnly (9)
Similar to Send but requests instead that the message is first to the user's terminal. An exception with the server's response is raised if the user is not logged in or does not accept terminal messages. This action requires that AllowExtensions is set to True and is not supported by all mail relays.


isAllowExtensions

public boolean isAllowExtensions()
A switch allowing the component to use ESMTP features (SMTP extensions). If AllowExtensions is true, the control will first send the EHLO greeting to the server and, if that fails, the standard HELO command will be sent.

The property is true by default but may be disabled if it's known in advance that the MailServer doesn't support SMTP extensions.


setAllowExtensions

public void setAllowExtensions(boolean allowExtensions)
                        throws IPWorksException
A switch allowing the component to use ESMTP features (SMTP extensions). If AllowExtensions is true, the control will first send the EHLO greeting to the server and, if that fails, the standard HELO command will be sent.

The property is true by default but may be disabled if it's known in advance that the MailServer doesn't support SMTP extensions.


getAttachedFile

public java.lang.String getAttachedFile()
A file to append to MessageText when sending mail. The content of AttachedFile is appended to the text in MessageText (if any) and sent to the mail relay. This property is useful for sending arbitrarily large messages and/or sending MIME attachments.

It is advisable that the text contained in the file be a collection of lines with lengths less than or equal to 80 bytes separated by CRLF ("\\r\\n") . The text in the message lines must contain 7-bit characters so that the message can be successfully pass through the multitude of mail systems on the Internet.

The control automatically escapes lines that start with a "." by adding another as specified in RFC 822. The message text is unescaped by the receiving agent, so the process is fully transparent.


setAttachedFile

public void setAttachedFile(java.lang.String attachedFile)
                     throws IPWorksException
A file to append to MessageText when sending mail. The content of AttachedFile is appended to the text in MessageText (if any) and sent to the mail relay. This property is useful for sending arbitrarily large messages and/or sending MIME attachments.

It is advisable that the text contained in the file be a collection of lines with lengths less than or equal to 80 bytes separated by CRLF ("\\r\\n") . The text in the message lines must contain 7-bit characters so that the message can be successfully pass through the multitude of mail systems on the Internet.

The control automatically escapes lines that start with a "." by adding another as specified in RFC 822. The message text is unescaped by the receiving agent, so the process is fully transparent.


getBCc

public java.lang.String getBCc()
A comma separated list of addresses for blind carbon copies (optional). The BCc property specifies a comma separated list of destinations where to send blind carbon copies of the mail message. A copy of the message is sent to each destination, but no BCc SMTP header is created containing the destination addresses, so individual recipients never see the list of the other recipients.

The control will return an error if the MailServer returns an error code about any email address specified in SendTo or Cc but it will only fire an Error event if the same happens with an email address specified in BCc .

If the resulting BCc header is longer than MaxHeaderLength , then it is folded according to RFC 822 specifications.


setBCc

public void setBCc(java.lang.String BCc)
            throws IPWorksException
A comma separated list of addresses for blind carbon copies (optional). The BCc property specifies a comma separated list of destinations where to send blind carbon copies of the mail message. A copy of the message is sent to each destination, but no BCc SMTP header is created containing the destination addresses, so individual recipients never see the list of the other recipients.

The control will return an error if the MailServer returns an error code about any email address specified in SendTo or Cc but it will only fire an Error event if the same happens with an email address specified in BCc .

If the resulting BCc header is longer than MaxHeaderLength , then it is folded according to RFC 822 specifications.


getCc

public java.lang.String getCc()
A comma separated list of addresses for carbon copies (optional). The Cc property specifies a comma separated list of destinations where to send carbon copies of the mail message. A copy of the message is sent to each destination, and a Cc SMTP header is created containing the destination addresses. This header is sent to every recipient of the message. If you don't want to copy this information to every recipient, then use blind carbon copies instead (see the description of the BCc ).

The control will return an error if the MailServer returns an error code about any email address specified in SendTo or Cc but it will only fire an Error event if the same happens with an email address specified in BCc .

If the resulting Cc header is longer than MaxHeaderLength , then it is folded according to RFC 822 specifications.


setCc

public void setCc(java.lang.String cc)
           throws IPWorksException
A comma separated list of addresses for carbon copies (optional). The Cc property specifies a comma separated list of destinations where to send carbon copies of the mail message. A copy of the message is sent to each destination, and a Cc SMTP header is created containing the destination addresses. This header is sent to every recipient of the message. If you don't want to copy this information to every recipient, then use blind carbon copies instead (see the description of the BCc ).

The control will return an error if the MailServer returns an error code about any email address specified in SendTo or Cc but it will only fire an Error event if the same happens with an email address specified in BCc .

If the resulting Cc header is longer than MaxHeaderLength , then it is folded according to RFC 822 specifications.


setCommand

public void setCommand(java.lang.String command)
                throws IPWorksException
Can be used to send additional commands directly to the SMTP 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.


getDate

public java.lang.String getDate()
The Date of the mail message (optional). If the Date property contains a non-empty string, then a Date SMTP header is created and attached to the message. If not, then the date information is added by the mail relay(s) the message goes through.

If the resulting Date header is longer than MaxHeaderLength , then it is folded according to RFC 822 specifications.

RFC 822 contains detailed date format specifications. An example of a valid date is "Fri, 1 Mar 96 21:24:52 EST".


setDate

public void setDate(java.lang.String date)
             throws IPWorksException
The Date of the mail message (optional). If the Date property contains a non-empty string, then a Date SMTP header is created and attached to the message. If not, then the date information is added by the mail relay(s) the message goes through.

If the resulting Date header is longer than MaxHeaderLength , then it is folded according to RFC 822 specifications.

RFC 822 contains detailed date format specifications. An example of a valid date is "Fri, 1 Mar 96 21:24:52 EST".


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.


getFrom

public java.lang.String getFrom()
The email address of the sender (required). The From property is used to create a From SMTP header. This header identifies the sender of the message. A valid email address is required. Examples of valid addresses are: "Your Name" or address@company.com

If the resulting From header is longer than MaxHeaderLength , then it is folded according to RFC 822 specifications.


setFrom

public void setFrom(java.lang.String from)
             throws IPWorksException
The email address of the sender (required). The From property is used to create a From SMTP header. This header identifies the sender of the message. A valid email address is required. Examples of valid addresses are: "Your Name" or address@company.com

If the resulting From header is longer than MaxHeaderLength , then it is folded according to RFC 822 specifications.


getHello

public java.lang.String getHello()
The argument for HELO (herald) command to the server (defaults to local host name). The Hello property specifies a string to send to the MailServer at connection time as an argument to the SMTP HELO command. This generally identifies the host sending mail, and that's why the Hello property defaults to the name of the local host. The property is provided in case the control does not accept the default value and a custom value (such as, for example, a fully qualified domain name) must be sent.

If AllowExtensions is true the EHLO command will be sent instead of the HELO command.


setHello

public void setHello(java.lang.String hello)
              throws IPWorksException
The argument for HELO (herald) command to the server (defaults to local host name). The Hello property specifies a string to send to the MailServer at connection time as an argument to the SMTP HELO command. This generally identifies the host sending mail, and that's why the Hello property defaults to the name of the local host. The property is provided in case the control does not accept the default value and a custom value (such as, for example, a fully qualified domain name) must be sent.

If AllowExtensions is true the EHLO command will be sent instead of the HELO command.


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.


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 SMTP (default 25). 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 while connected will fail with an error.


setMailPort

public void setMailPort(int mailPort)
                 throws IPWorksException
The server port for SMTP (default 25). 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 while connected will fail with an error.


getMailServer

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

The current version of the control does not provide a default value for the mail relay. You must provide a host name yourself. Generally, any internet host with an SMTP server will suffice (a UNIX host for example), but it is preferable to select a MailServer that is close to the machine sending mail.

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 (mail relay). The MailServer property specifies the IP address (IP number in dotted internet format) or Domain Name for a mail relay through which messages will be routed. It is set before a connection is attempted and cannot be changed once a connection is in progress.

The current version of the control does not provide a default value for the mail relay. You must provide a host name yourself. Generally, any internet host with an SMTP server will suffice (a UNIX host for example), but it is preferable to select a MailServer that is close to the machine sending mail.

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.


getMaxHeaderLength

public int getMaxHeaderLength()
Maximum length for headers to avoid line folding (default 80). The MaxHeaderLength specifies the maximum line length supported by the mail delivery system. Any headers longer than MaxHeaderLength are folded as specified in RFC 822.

It is generally a good idea to use a MaxHeaderLength of less than 100 bytes, although different mail relays and mail servers have different requirements for header lengths.


setMaxHeaderLength

public void setMaxHeaderLength(int maxHeaderLength)
                        throws IPWorksException
Maximum length for headers to avoid line folding (default 80). The MaxHeaderLength specifies the maximum line length supported by the mail delivery system. Any headers longer than MaxHeaderLength are folded as specified in RFC 822.

It is generally a good idea to use a MaxHeaderLength of less than 100 bytes, although different mail relays and mail servers have different requirements for header lengths.


getMessageDate

public java.lang.String getMessageDate()
The Date of the mail message (optional). If the MessageDate property contains a non-empty string, then a Date SMTP header is created and attached to the message. If not, then the date information is added by the mail relay(s) the message goes through.

If the resulting Date header is longer than MaxHeaderLength , then it is folded according to RFC 822 specifications.

RFC 822 contains detailed date format specifications. An example of a valid date is "Fri, 1 Mar 96 21:24:52 EST".


setMessageDate

public void setMessageDate(java.lang.String messageDate)
                    throws IPWorksException
The Date of the mail message (optional). If the MessageDate property contains a non-empty string, then a Date SMTP header is created and attached to the message. If not, then the date information is added by the mail relay(s) the message goes through.

If the resulting Date header is longer than MaxHeaderLength , then it is folded according to RFC 822 specifications.

RFC 822 contains detailed date format specifications. An example of a valid date is "Fri, 1 Mar 96 21:24:52 EST".


getMessageText

public java.lang.String getMessageText()
The full text of the message to send (without headers). The MessageText property contains the full text of the message.

It is advisable that the text contained in this property be a collection of lines with lengths less than or equal to 80 bytes separated by CRLF ("\\r\\n") . The text in the message lines must contain 7-bit characters so that the message can be successfully pass through the multitude of mail systems on the Internet.

The control automatically escapes lines that start with a "." by adding another as specified in RFC 822. The message text is unescaped by the receiving agent, so the process is fully transparent.


setMessageText

public void setMessageText(java.lang.String messageText)
                    throws IPWorksException
The full text of the message to send (without headers). The MessageText property contains the full text of the message.

It is advisable that the text contained in this property be a collection of lines with lengths less than or equal to 80 bytes separated by CRLF ("\\r\\n") . The text in the message lines must contain 7-bit characters so that the message can be successfully pass through the multitude of mail systems on the Internet.

The control automatically escapes lines that start with a "." by adding another as specified in RFC 822. The message text is unescaped by the receiving agent, so the process is fully transparent.


getOtherHeaders

public java.lang.String getOtherHeaders()
An RFC 822 compliant string consisting of extra headers. The OtherHeaders property contains a string of headers to be appended to the message headers created from other properties like SendTo , Subject , etc.

The headers must of the format "header: value" as specified in RFC 822. Header lines should be separated by CRLF ("\\r\\n").

Use this property with caution. If OtherHeaders contains invalid headers, message delivery might not be successful.

The OtherHeaders property is useful for extending the functionality of the control. A good example is delivery of MIME encoded messages.

SPECIAL CASE: if OtherHeaders starts with an empty line (CRLF), then the value of OtherHeaders is used instead of the normally computed message headers.


setOtherHeaders

public void setOtherHeaders(java.lang.String otherHeaders)
                     throws IPWorksException
An RFC 822 compliant string consisting of extra headers. The OtherHeaders property contains a string of headers to be appended to the message headers created from other properties like SendTo , Subject , etc.

The headers must of the format "header: value" as specified in RFC 822. Header lines should be separated by CRLF ("\\r\\n").

Use this property with caution. If OtherHeaders contains invalid headers, message delivery might not be successful.

The OtherHeaders property is useful for extending the functionality of the control. A good example is delivery of MIME encoded messages.

SPECIAL CASE: if OtherHeaders starts with an empty line (CRLF), then the value of OtherHeaders is used instead of the normally computed message headers.


getPassword

public java.lang.String getPassword()
A login password to login with in the MailServer . If the Password property is set to a non-empty string, then when connecting to the MailServer an AUTH command is sent in order to provide authentication information for the user.


setPassword

public void setPassword(java.lang.String password)
                 throws IPWorksException
A login password to login with in the MailServer . If the Password property is set to a non-empty string, then when connecting to the MailServer an AUTH command is sent in order to provide authentication information for the user.


getReplyTo

public java.lang.String getReplyTo()
A mail address to reply to (optional). If the ReplyTo property contains a non-empty string, a Reply-To SMTP header is created for the message. This header shows the address to use for replies (useful if this address is different from the one in From ).

If the resulting Reply-To header is longer than MaxHeaderLength , then it is folded according to RFC 822 specifications.


setReplyTo

public void setReplyTo(java.lang.String replyTo)
                throws IPWorksException
A mail address to reply to (optional). If the ReplyTo property contains a non-empty string, a Reply-To SMTP header is created for the message. This header shows the address to use for replies (useful if this address is different from the one in From ).

If the resulting Reply-To header is longer than MaxHeaderLength , then it is folded according to RFC 822 specifications.


getSendTo

public java.lang.String getSendTo()
A comma separated list of addresses for destinations (required). The SendTo property specifies a comma separated list of destinations for the mail message. A copy of the message is sent to each of them, and a To SMTP header is created containing the destination addresses.

The control will fail if the MailServer returns an error code about any email address specified in SendTo or Cc but it will silently ignore the error if the same happens with an email address specified in BCc .

If the resulting To header is longer than MaxHeaderLength , then it is folded according to RFC 822 specifications.


setSendTo

public void setSendTo(java.lang.String sendTo)
               throws IPWorksException
A comma separated list of addresses for destinations (required). The SendTo property specifies a comma separated list of destinations for the mail message. A copy of the message is sent to each of them, and a To SMTP header is created containing the destination addresses.

The control will fail if the MailServer returns an error code about any email address specified in SendTo or Cc but it will silently ignore the error if the same happens with an email address specified in BCc .

If the resulting To header is longer than MaxHeaderLength , then it is folded according to RFC 822 specifications.


getSubject

public java.lang.String getSubject()
The subject of the mail message (optional). The string in Subject is sent with a Subject SMTP header to the mail recipient.

If the resulting Subject header is longer than MaxHeaderLength , then it is folded according to RFC 822 specifications.


setSubject

public void setSubject(java.lang.String subject)
                throws IPWorksException
The subject of the mail message (optional). The string in Subject is sent with a Subject SMTP header to the mail recipient.

If the resulting Subject header is longer than MaxHeaderLength , then it is folded according to RFC 822 specifications.


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.


getUser

public java.lang.String getUser()
A user id to login as in the MailServer . If the User property is set to a non-empty string, then when connecting to the MailServer an AUTH command is sent in order to provide authentication information for the user.


setUser

public void setUser(java.lang.String user)
             throws IPWorksException
A user id to login as in the MailServer . If the User property is set to a non-empty string, then when connecting to the MailServer an AUTH command is sent in order to provide authentication information for the user.


fireEndTransfer

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

fireError

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

fireExpand

public void fireExpand(java.lang.String address)
Fired for every email address returned by the server when Action is set to Expand . (Called internally to dispatch the event.)
See Also:
SmtpExpandEvent

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:
SmtpPITrailEvent

fireStartTransfer

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

fireTransfer

public void fireTransfer(int bytesTransferred)
Fired while the message text gets transferred to MailServer . (Called internally to dispatch the event.)
See Also:
SmtpTransferEvent

connect

public void connect()
             throws IPWorksException
Connects to the mail relay and sends the SMTP HELO command. Connects to the mail relay and sends the SMTP HELO command, thus preparing for sending messages. Any number of messages can later be sent using the smtpSendMessage action below.

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


disconnect

public void disconnect()
                throws IPWorksException
Disconnect from the SMTP server. Disconnects from the mail relay.

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


expand

public void expand(java.lang.String emailAddress)
            throws IPWorksException
Asks the MailServer to expand a name or mailing list. The resulting response is provided in one or more Expand events (one for each address). The control will try to connect to the mail relay if it is not already connected.

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


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) .


resetHeaders

public void resetHeaders()
                  throws IPWorksException
Resets all the message headers to empty. Resets all the message headers to "" (empty string). Use this property before creating a new message, so that headers from the previous message are not carried over to the next one.

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


send

public void send()
          throws IPWorksException
Send the current message. If the control is not connected to the mail relay, a connection is created. Then the control attempts to deliver the current message and attached file.

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


sendToTerminalAndEmail

public void sendToTerminalAndEmail()
                            throws IPWorksException
Send to terminal and email. Similar to Send but requests also that the message is sent to the terminal of the user as well, if he is logged on and accepts terminal messages. This action requires that AllowExtensions is set to True and is not supported by all mail relays.

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


sendToTerminalOnly

public void sendToTerminalOnly()
                        throws IPWorksException
Send to terminal only. Similar to Send but requests instead that the message is sent to the user's terminal. An exception with the server's response is raised if the user is not logged in or does not accept terminal messages. This method requires that AllowExtensions is set to True and is not supported by all mail relays.

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


sendToTerminalOrEmail

public void sendToTerminalOrEmail()
                           throws IPWorksException
Send to terminal or email. Similar to Send but requests instead that the message is first sent to the user's terminal. If the user is not logged in or does not accept terminal messages, the message is sent to his mailbox. This action requires that AllowExtensions is set to True and is not supported by all mail relays.

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


verify

public void verify(java.lang.String emailAddress)
            throws IPWorksException
Send a Verify request to the SMTP server. Asks the MailServer to verify the email address provided in the 'EmailAddress' parameter.

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


addSmtpEventListener

public void addSmtpEventListener(SmtpEventListener l)
                          throws java.util.TooManyListenersException

removeSmtpEventListener

public void removeSmtpEventListener(SmtpEventListener l)

IP*Works!

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