Build 1.1_r1 (from source)

android.provider
Class Gmail

java.lang.Object
  extended by 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 COMMAND_SET_VISIBLE
           
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_IGNORED
           
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 String SET_VISIBLE_PARAM_VISIBLE
           
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 maxServerMessageId, 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_IGNORED

public static final String LABEL_IGNORED
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

COMMAND_SET_VISIBLE

public static final String COMMAND_SET_VISIBLE
See Also:
Constant Field Values

SET_VISIBLE_PARAM_VISIBLE

public static final String SET_VISIBLE_PARAM_VISIBLE
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:
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 maxServerMessageId,
                                           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
maxServerMessageId - the highest message id to whose labels should be changed. Note that everywhere else in this file messageId means local message id but here you need to use a server message id.
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:


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.

Build 1.1_r1 (from source)

Please submit a feedback, bug or feature