org.dvb.internet

Interface EmailClientService

All Superinterfaces:

InternetClientService, Service

public interface EmailClientService
extends InternetClientService

Service representing the resident email client

Method Summary

Methods

Modifier and Type	Method and Description
void	addToAddressBook(String address, String name) Add an entry to the address book.
String	getUserEmailAddress() Get the email address of the user.
void	setInitialMessage(String to, String subject, 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

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:

SecurityException - if the caller does not have a UserPreferencePermission with the name "read".

addToAddressBook

void addToAddressBook(String address,
                    String name)
                      throws EntryExistsException,
                             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.

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

void setInitialMessage(String to,
                     String subject,
                     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:

NullPointerException - if any of the to address, subject or message body are null.

IllegalArgumentException - if the destination address is an empty string.