android.provider
Class Gmail

java.lang.Object
  android.provider.Gmail

public final class Gmail
extends Object

A thin wrapper over the content resolver for accessing the gmail provider.

Nested Class Summary

static class	Gmail.Attachment
static class	Gmail.AttachmentColumns The columns that can be requested when querying an attachment's download URI.
static class	Gmail.AttachmentOrigin We track where an attachment came from so that we know how to download it and include it in new messages.
static class	Gmail.AttachmentRendition Indicates a version of an attachment.
static class	Gmail.ConversationColumns
static class	Gmail.ConversationCursor A cursor over conversations.
static class	Gmail.CursorStatus
static class	Gmail.LabelColumns
class	Gmail.LabelCursor A cursor over labels.
static class	Gmail.LabelMap This is a map of labels.
static class	Gmail.MailCursor This is a cursor that only defines methods to move throught the results and register to hear about changes.
static interface	Gmail.MailCursorObserver A MailCursor observer is notified of changes to the result set of a cursor.
static class	Gmail.MessageColumns
static class	Gmail.MessageCursor A cursor over messages.
static class	Gmail.MessageModification A helper class for creating or updating messags.
static class	Gmail.NonexistentLabelException Thrown when an operation is requested with a label that does not exist.
static class	Gmail.PersonalLevel
static class	Gmail.Settings Settings for which conversations should be synced to the phone.
static class	Gmail.SettingsColumns

Field Summary

static String	ATTACHMENT_INFO_SEPARATOR Separates attachment info parts in strings in the database.
static Pattern	ATTACHMENT_INFO_SEPARATOR_PATTERN
static String	AUTHORITY
static Uri	BASE_URI
static Pattern	COMMA_SEPARATOR_PATTERN
static String	COMMAND_ACTIVATE
static String	COMMAND_RESPONSE_OK
static String	COMMAND_RESPONSE_UNKNOWN
static String	COMMAND_RETRY
static String	EMAIL_SEPARATOR Separates email addresses in strings in the database.
static Pattern	EMAIL_SEPARATOR_PATTERN
static String	EXTRA_STATUS Used for finding status in a cursor's extras.
static String	GMAIL_AUTH_SERVICE
static String	INSERT_PARAM_ATTACHMENT_ORIGIN
static String	INSERT_PARAM_ATTACHMENT_ORIGIN_EXTRAS
static String	LABEL_ALL
static String	LABEL_CACHED
static String	LABEL_CHAT
static String	LABEL_DRAFT
static String	LABEL_INBOX
static String	LABEL_OUTBOX
static String	LABEL_SENT
static String	LABEL_SPAM
static String	LABEL_STARRED
static String	LABEL_TRASH
static String	LABEL_UNREAD
static String	LABEL_VOICEMAIL
static String	LABEL_VOICEMAIL_INBOX
static String	PROVIDER_CHANGED_EXTRA_ACCOUNT The account in which the change occurred.
static String	PROVIDER_CHANGED_EXTRA_COUNT The number of unread conversations matching the label.
static String	PROVIDER_CHANGED_EXTRA_GET_ATTENTION Whether to get the user's attention, perhaps by vibrating.
static String	PROVIDER_CHANGED_EXTRA_TAG_LABEL A label that is attached to all of the conversations being notified about.
static String	RESPOND_INPUT_COMMAND
static String	RESPOND_OUTPUT_COMMAND_RESPONSE
static Character	SENDER_LIST_SEPARATOR
static String	SENDER_LIST_TOKEN_ELIDED
static String	SENDER_LIST_TOKEN_LITERAL
static String	SENDER_LIST_TOKEN_NUM_DRAFTS
static String	SENDER_LIST_TOKEN_NUM_MESSAGES
static String	SENDER_LIST_TOKEN_SEND_FAILED
static String	SENDER_LIST_TOKEN_SENDING
static Pattern	SPACE_SEPARATOR_PATTERN
static String[]	sSenderFragments
static TextUtils.SimpleStringSplitter	sSenderListSplitter

Constructor Summary

Gmail(ContentResolver contentResolver)

Method Summary

void	addOrRemoveLabelOnConversation(String account, long conversationId, long maxMessageId, String label, boolean add) Adds or removes the label on the conversation.
static void	addOrRemoveLabelOnMessage(ContentResolver contentResolver, String account, long conversationId, long messageId, String label, boolean add) Adds or removes the label on the message.
void	expungeMessage(String account, long messageId) Expunge the indicated message.
static Uri	getAttachmentDownloadUri(Uri attachmentUri) Return the URI to query in order to find out whether an attachment is downloaded.
static Uri	getAttachmentUri(String account, long messageId, Gmail.Attachment attachment, Gmail.AttachmentRendition rendition, boolean saveToSd) Any given attachment can come in two different renditions (see Gmail.AttachmentRendition) and can be saved to the sd card or to a cache.
static Set<String>	getCanonicalNamesFromLabelIdsString(Gmail.LabelMap labelMap, TextUtils.StringSplitter splitter) Deprecated. remove when the activities stop using canonical names to identify labels
Gmail.ConversationCursor	getConversationCursorForCursor(String account, Cursor cursor) Wraps a Cursor in a ConversationCursor
Gmail.ConversationCursor	getConversationCursorForQuery(String account, String query) Synchronously gets a cursor over all conversations matching a query.
static String	getEmailFromAddressString(String addressString) Returns the email address in an address string
static Set<Long>	getLabelIdsFromLabelIdsString(TextUtils.StringSplitter splitter) Returns the set of labels using the raw labels from a previous getRawLabels() as input.
static String	getLabelIdsStringFromLabelIds(Set<Long> labelIds) Creates a single string of the form that getLabelIdsFromLabelIdsString can split.
Gmail.LabelMap	getLabelMap(String account)
Gmail.MessageCursor	getLocalMessageCursorForQuery(String account, String query) Gets a message cursor over the messages that match the query.
Gmail.MessageCursor	getMessageCursorForConversationId(String account, long conversationId) Gets a cursor over all of the messages in a conversation.
Gmail.MessageCursor	getMessageCursorForMessageId(String account, long messageId) Gets a message cursor over the single message with the given id.
static String	getNameFromAddressString(String addressString) Returns the name in an address string
static void	getSenderSnippet(String instructions, SpannableStringBuilder sb, int maxChars, CharacterStyle unreadStyle, CharacterStyle draftsStyle, CharSequence meString, CharSequence draftString, CharSequence draftPluralString, CharSequence sendingString, CharSequence sendFailedString, boolean forceAllUnread, boolean forceAllRead) Uses sender instructions to build a formatted string.
Gmail.Settings	getSettings(String account) Returns the settings.
static boolean	isLabelUserDefined(String label) Returns whether the label is user-defined (versus system-defined labels such as inbox, whose names start with "^").
static boolean	isLabelUserSettable(String label) Returns whether the label is user-settable.
static TextUtils.StringSplitter	newConversationLabelIdsSplitter()
static TextUtils.StringSplitter	newMessageLabelIdsSplitter()
void	runQueryForConversations(String account, AsyncQueryHandler handler, int token, String query) Asynchronously gets a cursor over all conversations matching a query.
void	setSettings(String account, Gmail.Settings settings) Sets the settings.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

GMAIL_AUTH_SERVICE

public static final String GMAIL_AUTH_SERVICE

See Also:

Constant Field Values

LABEL_SENT

public static final String LABEL_SENT

See Also:

Constant Field Values

LABEL_INBOX

public static final String LABEL_INBOX

See Also:

Constant Field Values

LABEL_DRAFT

public static final String LABEL_DRAFT

See Also:

Constant Field Values

LABEL_UNREAD

public static final String LABEL_UNREAD

See Also:

Constant Field Values

LABEL_TRASH

public static final String LABEL_TRASH

See Also:

Constant Field Values

LABEL_SPAM

public static final String LABEL_SPAM

See Also:

Constant Field Values

LABEL_STARRED

public static final String LABEL_STARRED

See Also:

Constant Field Values

LABEL_CHAT

public static final String LABEL_CHAT

See Also:

Constant Field Values

LABEL_VOICEMAIL

public static final String LABEL_VOICEMAIL

See Also:

Constant Field Values

LABEL_ALL

public static final String LABEL_ALL

See Also:

Constant Field Values

LABEL_VOICEMAIL_INBOX

public static final String LABEL_VOICEMAIL_INBOX

See Also:

Constant Field Values

LABEL_CACHED

public static final String LABEL_CACHED

See Also:

Constant Field Values

LABEL_OUTBOX

public static final String LABEL_OUTBOX

See Also:

Constant Field Values

AUTHORITY

public static final String AUTHORITY

See Also:

Constant Field Values

BASE_URI

public static final Uri BASE_URI

EMAIL_SEPARATOR

public static final String EMAIL_SEPARATOR

Separates email addresses in strings in the database.

See Also:

Constant Field Values

EMAIL_SEPARATOR_PATTERN

public static final Pattern EMAIL_SEPARATOR_PATTERN

SPACE_SEPARATOR_PATTERN

public static final Pattern SPACE_SEPARATOR_PATTERN

COMMA_SEPARATOR_PATTERN

public static final Pattern COMMA_SEPARATOR_PATTERN

ATTACHMENT_INFO_SEPARATOR

public static final String ATTACHMENT_INFO_SEPARATOR

Separates attachment info parts in strings in the database.

See Also:

Constant Field Values

ATTACHMENT_INFO_SEPARATOR_PATTERN

public static final Pattern ATTACHMENT_INFO_SEPARATOR_PATTERN

SENDER_LIST_SEPARATOR

public static final Character SENDER_LIST_SEPARATOR

SENDER_LIST_TOKEN_ELIDED

public static final String SENDER_LIST_TOKEN_ELIDED

See Also:

Constant Field Values

SENDER_LIST_TOKEN_NUM_MESSAGES

public static final String SENDER_LIST_TOKEN_NUM_MESSAGES

See Also:

Constant Field Values

SENDER_LIST_TOKEN_NUM_DRAFTS

public static final String SENDER_LIST_TOKEN_NUM_DRAFTS

See Also:

Constant Field Values

SENDER_LIST_TOKEN_LITERAL

public static final String SENDER_LIST_TOKEN_LITERAL

See Also:

Constant Field Values

SENDER_LIST_TOKEN_SENDING

public static final String SENDER_LIST_TOKEN_SENDING

See Also:

Constant Field Values

SENDER_LIST_TOKEN_SEND_FAILED

public static final String SENDER_LIST_TOKEN_SEND_FAILED

See Also:

Constant Field Values

EXTRA_STATUS

public static final String EXTRA_STATUS

Used for finding status in a cursor's extras.

See Also:

Constant Field Values

RESPOND_INPUT_COMMAND

public static final String RESPOND_INPUT_COMMAND

See Also:

Constant Field Values

COMMAND_RETRY

public static final String COMMAND_RETRY

See Also:

Constant Field Values

COMMAND_ACTIVATE

public static final String COMMAND_ACTIVATE

See Also:

Constant Field Values

RESPOND_OUTPUT_COMMAND_RESPONSE

public static final String RESPOND_OUTPUT_COMMAND_RESPONSE

See Also:

Constant Field Values

COMMAND_RESPONSE_OK

public static final String COMMAND_RESPONSE_OK

See Also:

Constant Field Values

COMMAND_RESPONSE_UNKNOWN

public static final String COMMAND_RESPONSE_UNKNOWN

See Also:

Constant Field Values

INSERT_PARAM_ATTACHMENT_ORIGIN

public static final String INSERT_PARAM_ATTACHMENT_ORIGIN

See Also:

Constant Field Values

INSERT_PARAM_ATTACHMENT_ORIGIN_EXTRAS

public static final String INSERT_PARAM_ATTACHMENT_ORIGIN_EXTRAS

See Also:

Constant Field Values

sSenderListSplitter

public static final TextUtils.SimpleStringSplitter sSenderListSplitter

sSenderFragments

public static String[] sSenderFragments

PROVIDER_CHANGED_EXTRA_ACCOUNT

public static final String PROVIDER_CHANGED_EXTRA_ACCOUNT

The account in which the change occurred.

See Also:

Constant Field Values

PROVIDER_CHANGED_EXTRA_COUNT

public static final String PROVIDER_CHANGED_EXTRA_COUNT

The number of unread conversations matching the label.

See Also:

Constant Field Values

PROVIDER_CHANGED_EXTRA_GET_ATTENTION

public static final String PROVIDER_CHANGED_EXTRA_GET_ATTENTION

Whether to get the user's attention, perhaps by vibrating.

See Also:

Constant Field Values

PROVIDER_CHANGED_EXTRA_TAG_LABEL

public static final String PROVIDER_CHANGED_EXTRA_TAG_LABEL

A label that is attached to all of the conversations being notified about. This enables the receiver of a notification to get a list of matching conversations.

See Also:

Constant Field Values

Constructor Detail

Gmail

public Gmail(ContentResolver contentResolver)

Method Detail

getNameFromAddressString

public static String getNameFromAddressString(String addressString)

Returns the name in an address string

Parameters:

addressString - such as "bobby" <bob@example.com>

Returns:

returns the quoted name in the addressString, otherwise the username from the email address

getEmailFromAddressString

public static String getEmailFromAddressString(String addressString)

Returns the email address in an address string

Parameters:

addressString - such as "bobby" <bob@example.com>

Returns:

returns the email address, such as bob@example.com from the example above

isLabelUserDefined

public static boolean isLabelUserDefined(String label)

Returns whether the label is user-defined (versus system-defined labels such as inbox, whose names start with "^").

isLabelUserSettable

public static boolean isLabelUserSettable(String label)

Returns whether the label is user-settable. For example, labels such as LABEL_DRAFT should only be set internally.

getLabelIdsFromLabelIdsString

public static Set<Long> getLabelIdsFromLabelIdsString(TextUtils.StringSplitter splitter)

Returns the set of labels using the raw labels from a previous getRawLabels() as input.

Returns:

a copy of the set of labels. To add or remove labels call MessageCursor.addOrRemoveLabel on each message in the conversation.

getCanonicalNamesFromLabelIdsString

public static Set<String> getCanonicalNamesFromLabelIdsString(Gmail.LabelMap labelMap,
                                                              TextUtils.StringSplitter splitter)

Deprecated. remove when the activities stop using canonical names to identify labels

newMessageLabelIdsSplitter

public static TextUtils.StringSplitter newMessageLabelIdsSplitter()

Returns:

a StringSplitter that is configured to split message label id strings

newConversationLabelIdsSplitter

public static TextUtils.StringSplitter newConversationLabelIdsSplitter()

Returns:

a StringSplitter that is configured to split conversation label id strings

getLabelIdsStringFromLabelIds

public static String getLabelIdsStringFromLabelIds(Set<Long> labelIds)

Creates a single string of the form that getLabelIdsFromLabelIdsString can split.

getConversationCursorForCursor

public Gmail.ConversationCursor getConversationCursorForCursor(String account,
                                                               Cursor cursor)

Wraps a Cursor in a ConversationCursor

Parameters:

account - the account the cursor is associated with

cursor - The Cursor to wrap

Returns:

a new ConversationCursor

runQueryForConversations

public void runQueryForConversations(String account,
                                     AsyncQueryHandler handler,
                                     int token,
                                     String query)

Asynchronously gets a cursor over all conversations matching a query. The query is in Gmail's query syntax. When the operation is complete the handler's onQueryComplete() method is called with the resulting Cursor.

Parameters:

account - run the query on this account

handler - An AsyncQueryHanlder that will be used to run the query

token - The token to pass to startQuery, which will be passed back to onQueryComplete

query - a query in Gmail's query syntax

getConversationCursorForQuery

public Gmail.ConversationCursor getConversationCursorForQuery(String account,
                                                              String query)

Synchronously gets a cursor over all conversations matching a query. The query is in Gmail's query syntax.

Parameters:

account - run the query on this account

query - a query in Gmail's query syntax

getMessageCursorForMessageId

public Gmail.MessageCursor getMessageCursorForMessageId(String account,
                                                        long messageId)

Gets a message cursor over the single message with the given id.

Parameters:

account - get the cursor for messages in this account

messageId - the id of the message

Returns:

a cursor over the message

getLocalMessageCursorForQuery

public Gmail.MessageCursor getLocalMessageCursorForQuery(String account,
                                                         String query)

Gets a message cursor over the messages that match the query. Note that this simply finds all of the messages that match and returns them. It does not return all messages in conversations where any message matches.

Parameters:

account - get the cursor for messages in this account

query - a query in GMail's query syntax. Currently only queries of the form [label:] are supported

Returns:

a cursor over the messages

getMessageCursorForConversationId

public Gmail.MessageCursor getMessageCursorForConversationId(String account,
                                                             long conversationId)

Gets a cursor over all of the messages in a conversation.

Parameters:

account - get the cursor for messages in this account

conversationId - the id of the converstion to fetch messages for

Returns:

a cursor over messages in the conversation

expungeMessage

public void expungeMessage(String account,
                           long messageId)

Expunge the indicated message. One use of this is to discard drafts.

Parameters:

account - the account of the message id

messageId - the id of the message to expunge

addOrRemoveLabelOnConversation

public void addOrRemoveLabelOnConversation(String account,
                                           long conversationId,
                                           long maxMessageId,
                                           String label,
                                           boolean add)
                                    throws Gmail.NonexistentLabelException

Adds or removes the label on the conversation.

Parameters:

account - the account of the conversation

conversationId - the conversation

maxMessageId - the highest message id to whose labels should be changed

label - the label to add or remove

add - true to add the label, false to remove it

Throws:

Gmail.NonexistentLabelException - thrown if the label does not exist

addOrRemoveLabelOnMessage

public static void addOrRemoveLabelOnMessage(ContentResolver contentResolver,
                                             String account,
                                             long conversationId,
                                             long messageId,
                                             String label,
                                             boolean add)

Adds or removes the label on the message.

Parameters:

contentResolver - the content resolver.

account - the account of the message

conversationId - the conversation containing the message

messageId - the id of the message to whose labels should be changed

label - the label to add or remove

add - true to add the label, false to remove it

Throws:

Gmail.NonexistentLabelException - thrown if the label does not exist

getSettings

public Gmail.Settings getSettings(String account)

Returns the settings.

Parameters:

account - the account whose setting should be retrieved

setSettings

public void setSettings(String account,
                        Gmail.Settings settings)

Sets the settings. A sync will be scheduled automatically.

getSenderSnippet

public static void getSenderSnippet(String instructions,
                                    SpannableStringBuilder sb,
                                    int maxChars,
                                    CharacterStyle unreadStyle,
                                    CharacterStyle draftsStyle,
                                    CharSequence meString,
                                    CharSequence draftString,
                                    CharSequence draftPluralString,
                                    CharSequence sendingString,
                                    CharSequence sendFailedString,
                                    boolean forceAllUnread,
                                    boolean forceAllRead)

Uses sender instructions to build a formatted string.

Sender list instructions contain compact information about the sender list. Most work that can be done without knowing how much room will be availble for the sender list is done when creating the instructions.

The instructions string consists of tokens separated by SENDER_LIST_SEPARATOR. Here are the tokens, one per line:

• n
• int, the number of non-draft messages in the conversation
• d
• int, the number of drafts in the conversation
• l
• literal html to be included in the output
• s indicates that the message is sending (in the outbox without errors)
• f indicates that the message failed to send (in the outbox with errors)
• for each message
  • int, 0 for read, 1 for unread
  • int, the priority of the message. Zero is the most important
  • text, the sender text or blank for messages from 'me'
• e to indicate that one or more messages have been elided

The instructions indicate how many messages and drafts are in the conversation and then describe the most important messages in order, indicating the priority of each message and whether the message is unread.

Parameters:

instructions - instructions as described above

sb - the SpannableStringBuilder to append to

maxChars - the number of characters available to display the text

unreadStyle - the CharacterStyle for unread messages, or null

draftsStyle - the CharacterStyle for draft messages, or null

sendingString - the string to use when there are messages scheduled to be sent

sendFailedString - the string to use when there are messages that mailed to send

meString - the string to use for messages sent by this user

draftString - the string to use for "Draft"

draftPluralString - the string to use for "Drafts"

getLabelMap

public Gmail.LabelMap getLabelMap(String account)

getAttachmentUri

public static Uri getAttachmentUri(String account,
                                   long messageId,
                                   Gmail.Attachment attachment,
                                   Gmail.AttachmentRendition rendition,
                                   boolean saveToSd)

Any given attachment can come in two different renditions (see Gmail.AttachmentRendition) and can be saved to the sd card or to a cache. The gmail provider automatically syncs some attachments to the cache. Other attachments can be downloaded on demand. Attachments in the cache will be purged as needed to save space. Attachments on the SD card must be managed by the user or other software.

Parameters:

account - which account to use

messageId - the id of the mesage with the attachment

attachment - the attachment

rendition - the desired rendition

saveToSd - whether the attachment should be saved to (or loaded from) the sd card or

Returns:

the URI to ask the content provider to open in order to open an attachment.

getAttachmentDownloadUri

public static Uri getAttachmentDownloadUri(Uri attachmentUri)

Return the URI to query in order to find out whether an attachment is downloaded.

Querying this will also start a download if necessary. The cursor returned by querying this URI can contain the columns in Gmail.AttachmentColumns.

Deleting this URI will cancel the download if it was not started automatically by the provider. It will also remove bookkeeping for saveToSd downloads.

Parameters:

attachmentUri - the attachment URI as returned by getAttachmentUri. The URI's authority Gmail.AUTHORITY. If it is not then you should open the file directly.