org.dvb.internet
Interface EmailClientService

All Superinterfaces:
InternetClientService, Service

public interface EmailClientService
extends InternetClientService

Service representing the resident email client


Method Summary
 void addToAddressBook(java.lang.String address, java.lang.String name)
          Add an entry to the address book.
 java.lang.String getUserEmailAddress()
          Get the email address of the user.
 void setInitialMessage(java.lang.String to, java.lang.String subject, java.lang.String messageBody)
          Set the initial recipient, subject & message body to be used when the email client starts.
 
Methods inherited from interface org.dvb.internet.InternetClientService
canRunApplication, getName, getServiceType, getSupportedClientServices, hasMultipleInstances, retrieveDetails
 
Methods inherited from interface javax.tv.service.Service
equals, getLocator, hashCode
 

Method Detail

getUserEmailAddress

public java.lang.String getUserEmailAddress()
Get the email address of the user. The returned value shall be the same as that obtained by reading the value of the "User @" preference (see org.dvb.user.GeneralPreferences for details).

Returns:
the email address of the user, or null if no email address is set or the email address is not available to the client.
Throws:
java.lang.SecurityException - if the caller does not have a UserPreferencePermission with the name "read".

addToAddressBook

public void addToAddressBook(java.lang.String address,
                             java.lang.String name)
                      throws EntryExistsException,
                             java.io.IOException
Add an entry to the address book. As a side-effect an entry previously added by this method may be lost. Implementations may restrict the number of entries a single MHP application or source of applications may add.

Parameters:
address - the address to be added to the address book
name - the name that should be associated with that address
Throws:
EntryExistsException - if an entry with both the same name and the same address already exists in the address book.
java.lang.IllegalArgumentException - if the string passed as the email address does not conform to the internet email address format
IOException - if no more address book entries can be added due to a lack of storage space or a limitation in the client

setInitialMessage

public void setInitialMessage(java.lang.String to,
                              java.lang.String subject,
                              java.lang.String messageBody)
Set the initial recipient, subject & message body to be used when the email client starts. This URL is specific to this instance of EmailClientService and will not impact any other instance and is only valid for the lifetime of this instance. Calling this method and then selecting the EmailClientService instance is equivalent to selecting the EmailClientService instance, obtaining the EmailClient and then calling the createMessage method there. If the application calling this method is still running when the message is sent (or fails) and has registered an InternetClientListener then the appropriate InternetClientEvent shall be sent corresponding to the success or failure of the operation to send the message.

Parameters:
to - the address to which the email should be sent
subject - the subject for the email
messageBody - the body of the message.
Throws:
java.lang.NullPointerException - if any of the to address, subject or message body are null.
java.lang.IllegalArgumentException - if the destination address is an empty string.