IMailbox interface
The IMailbox interface represents an electronic mailbox used for communicating with incoming and outgoing electronic mail. IMailbox provides methods for opening and closing a mailbox, as well as for receiving and sending mail messages. You must have access to either an SMTP or POP mail server.
To create an instance of the IMailbox interface, use createMailbox( ) in the AppLogic class (deprecated), as shown in the following example:
IMailbox mb = createMailbox("SMTPHostName", "myUserName",
"pass7878", "myEmailAddr@myOrg.com");
Package
com.kivasoft
Methods
Related Topics
createMailbox( ) in the AppLogic class (deprecated)
Taking Advantage of NAS Features
close( )
Closes an open electronic mailbox session.
Syntax
public int close()
Usage
Use close( ) to close a mailbox session and commit changes on the mail server, if applicable. If sessions are open on both the POP and SMTP server, close( ) terminates both sessions.
Closing a session does not terminate the IMailbox object. The AppLogic can later reopen a session using open( ).
Rule
The AppLogic can only close a mailbox session that is open.
Return Value
GXE.SUCCESS if the method succeeds.
Example
// Define the string parameters that will be passed
// to IMailbox methods
String sendhost = "smtp.kivasoft.com";
String recvhost = "pop.kivasoft.com";
String user = "eugene";
String pswd = "eugenesSecretPassword";
String useraddr = "eugene@kivasoft.com";
String sendTo[] = {"friend@otherhost.net", null};
String mesg = "Hi Friend, How are you?";
public void sendMail()
{
// Create an IMailbox instance
IMailbox sendMB;
sendMB = createMailbox(sendhost, user, pswd, useraddr);
if (sendMB != null) // sendMB successfully created
{
// Open a session with the mail server
if (sendMB.open(GX_MBOX_OPEN_FLAG.OPEN_SEND)== GXE.SUCCESS)
{
// Send a mail message
sendMB.send(sendTo,mesg);
// Close the mailbox session
sendMB.close();
}
}
}
Related Topics
open( )
createMailbox( ) in the AppLogic class (deprecated)
open( )
Opens a session with the mail server.
Syntax
public int open(
int dwFlag)
dwFlag.
Access level used to open the mailbox. Specify one of the following options:
Usage
Use open( ) to explicitly open a session with the mail server after instantiating the IMailbox object. Alternatively, the AppLogic can open a session after having closed a previous session using close( ).
Depending on the setting of the dwFlag parameter, open( ) starts a session on the SMTP server only, on the POP server only, or on both servers at once (two separate sessions).
Rule
The AppLogic must call open( ) before calling other methods.
Tip
To conserve system resources, use only the access level you need. For example, if the AppLogic will only be sending electronic mail messages, specify GX_MBOX_OPEN_FLAG.OPEN_SEND, not GX_MBOX_OPEN_FLAG.OPEN_SEND |GX_MBOX_OPEN_FLAG.OPEN_RECV.
Return Value
GXE.SUCCESS if the method succeeds.
Example
// Define the string parameters that will be passed
// to IMailbox methods
String sendhost = "smtp.kivasoft.com";
String recvhost = "pop.kivasoft.com";
String user = "eugene";
String pswd = "eugenesSecretPassword";
String useraddr = "eugene@kivasoft.com";
String sendTo[] = {"friend@otherhost.net", null};
String mesg = "Hi Friend, How are you?";
public void sendMail()
{
// Create an IMailbox instance
IMailbox sendMB;
sendMB = createMailbox(sendhost, user, pswd, useraddr);
if (sendMB != null) // sendMB successfully created
{
// Open a session with the mail server
if (sendMB.open(GX_MBOX_OPEN_FLAG.OPEN_SEND))
{
// Send a mail message
sendMB.send(sendTo,mesg);
// Close the mailbox session
sendMB.close();
}
}
}
Related Topics
send( )
createMailbox( ) in the AppLogic class (deprecated)
retrieve( )
Retrieves electronic mail messages from the inbox.
Syntax
public IValList retrieve(
boolean bLatest,
boolean bDelete)
bLatest.
Specify true to retrieve the latest unread messages. Specify false to retrieve all messages in the inbox.
bDelete.
Specify true to delete retrieved messages when the mailbox session is closed. Specify false to leave the retrieved messages on the mail server.
Usage
Use retrieve( ) to get unread messages from the inbox. Once retrieved, messages are marked as READ.
Rule
To use retrieve( ), the AppLogic must have first opened the mailbox session using open( ) and have specified either GX_MBOX_OPEN_FLAG.OPEN_RECV or GX_MBOX_OPEN_FLAG.OPEN_SEND |GX_MBOX_OPEN_FLAG.OPEN_RECV as the dwFlag parameter.
Tip
AppLogic can use retrieveReset( ) to undo changes (deletes, read flags) to messages in the inbox.
Return Value
IValList that contains the retrieved messages, or null for failure.
Example
// Create mailbox object to connect to a POP mail server
IMailbox recvMB;
public void recvMail()
{
// Only check messages received after the last open
BOOL Latest = true;
// Remove retrieved messages from the mail server
BOOL Delete = true;
// Create an IMailbox instance
IMailbox recvMB;
recvMB = createMailbox(recvhost, user, pswd, useraddr);
if (recvMB != null)
{
if (recvMB.open(GX_MBOX_OPEN_FLAG.OPEN_RECV))
{
// Count the number of new messages
int numMsgs = recvMB.retrieveCount();
if(numMsgs > 0)
{
IValList mesgList;
// Retrieve the new messages
mesgList = recvMB.retrieve(Latest,Delete);
// Use IValList methods to iterate through
// the returned IValList. The keys in the
// IValList are the message numbers. The
// values are the email messages as strings
}
recvMB.close();
}
}
}
Related Topics
open( )
createMailbox( ) in the AppLogic class (deprecated)
retrieveCount( )
Counts the number of unread electronic mail messages in the inbox.
Syntax
public int retrieveCount()
Usage
Before calling retrieve( ), use retrieveCount( ) to count the number of retrievable messages in the inbox. The AppLogic might do this to avoid retrieving an empty inbox. If the AppLogic iterates through the messages after they have been retrieved, the AppLogic can call retrieveCount( ) to determine the maximum number of iterations required to process all available inbox messages.
Rule
To use retrieveCount( ), the AppLogic must have first opened the mailbox session using open( ) and have specified either GX_MBOX_OPEN_FLAG.OPEN_RECV or GX_MBOX_OPEN_FLAG.OPEN_SEND|GX_MBOX_OPEN_FLAG.OPEN_RECV as the dwFlag parameter.
Return Value
The number of available unread electronic mail messages in the inbox. The retrieveCount( ) method returns 0 for no messages and a negative number if an error ocurred.
Example
// Create mailbox object to connect to a POP mail server
IMailbox recvMB;
public void recvMail()
{
// Only check messages received after the last open
BOOL Latest = true;
// Remove retrieved messages from the mail server
BOOL Delete = true;
// Create an IMailbox instance
IMailbox recvMB;
recvMB = createMailbox(recvhost, user, pswd, useraddr);
if (recvMB != null)
{
if (recvMB.open(GX_MBOX_OPEN_FLAG.OPEN_RECV))
{
// Count the number of new messages
int numMsgs = recvMB.retrieveCount();
if(numMsgs > 0)
{
IValList mesgList;
// Retrieve the new messages
mesgList = recvMB.retrieve(Latest,Delete);
// Use IValList methods to iterate through
// the returned IValList. The keys in the
// IValList are the message numbers. The
// values are the email messages as strings
}
recvMB.close();
}
}
}
Related Topics
open( )
retrieve( )
createMailbox( ) in the AppLogic class (deprecated)
retrieveReset( )
Resets the status of retrieved messages in the mailbox from read to unread and abandons (rolls back) any message deletions.
Syntax
public int retrieveReset()
Usage
Use retrieveReset( ) to undo any changes made as a result of retrieving inbox messages with retrieve( ).
Rules
Return Value
GXE.SUCCESS if the method succeeds.
Related Topics
open( )
retrieve( )
createMailbox( ) in the AppLogic class (deprecated)
send( )
Sends an electronic mail message to one or more mail addresses.
Syntax
public int send(
String[] ppTo,
String pMesg)
ppTo.
A list of email addresses, to which you want to send e-mail. The address or addresses must be supplied in a null-terminated array.
pMesg.
Text of the electronic mail message. Use Internet mail formatting conventions for specifying advanced features in the message text, such as CC: or BCC: addresses, the Subject header, uuencode, MIME attachments, receipt notification, and so on. For syntax specifications, see your POP and SMTP protocol documentation.
Rules
Tip
The send( ) method automatically includes the FROM: address that the AppLogic specified in the pUserAddr parameter of createMailbox( ) in the AppLogic class (deprecated).
Return Value
GXE.SUCCESS if the method succeeds.
Example
// Define the string parameters that will be passed
// to IMailbox methods
String sendhost = "smtp.kivasoft.com";
String recvhost = "pop.kivasoft.com";
String user = "eugene";
String pswd = "eugenesSecretPassword";
String useraddr = "eugene@kivasoft.com";
String sendTo[] = {"friend@otherhost.net", null};
String mesg = "Hi Friend, How are you?";
public void sendMail()
{
// Create an IMailbox instance
IMailbox sendMB;
sendMB = createMailbox(sendhost, user, pswd, useraddr);
if (sendMB != null) // sendMB successfully created
{
// Open a session with the mail server
if (sendMB.open(GX_MBOX_OPEN_FLAG.OPEN_SEND))
{
// Send a mail message
sendMB.send(sendTo,mesg);
// Close the mailbox session
sendMB.close();
}
}
}
Related Topics
open( ),
retrieve( )
createMailbox( ) in the AppLogic class (deprecated)
|
Previous
