DropBoxManager


public class DropBoxManager
extends Object

java.lang.Object
   ↳ android.os.DropBoxManager


Enqueues chunks of data (from various sources -- application crashes, kernel log records, etc.). The queue is size bounded and will drop old data if the enqueued data exceeds the maximum size. You can think of this as a persistent, system-wide, blob-oriented "logcat".

DropBoxManager entries are not sent anywhere directly, but other system services and debugging tools may scan and upload entries for processing.

Summary

Nested classes

class DropBoxManager.Entry

A single entry retrieved from the drop box. 

Constants

String ACTION_DROPBOX_ENTRY_ADDED

Broadcast Action: This is broadcast when a new entry is added in the dropbox.

String EXTRA_DROPPED_COUNT

Extra for ACTION_DROPBOX_ENTRY_ADDED: integer value containing number of broadcasts dropped due to rate limiting on this EXTRA_TAG

String EXTRA_TAG

Extra for ACTION_DROPBOX_ENTRY_ADDED: string containing the dropbox tag.

String EXTRA_TIME

Extra for ACTION_DROPBOX_ENTRY_ADDED: long integer value containing time (in milliseconds since January 1, 1970 00:00:00 UTC) when the entry was created.

int IS_EMPTY

Flag value: Entry's content was deleted to save space.

int IS_GZIPPED

Flag value: Content can be decompressed with java.util.zip.GZIPOutputStream.

int IS_TEXT

Flag value: Content is human-readable UTF-8 text (can be combined with IS_GZIPPED).

Protected constructors

DropBoxManager()

Create an instance for testing.

Public methods

void addData(String tag, byte[] data, int flags)

Stores binary data, which may be ignored or discarded as with addText(String, String).

void addFile(String tag, File file, int flags)

Stores the contents of a file, which may be ignored or discarded as with addText(String, String).

void addText(String tag, String data)

Stores human-readable text.

DropBoxManager.Entry getNextEntry(String tag, long msec)

Gets the next entry from the drop box after the specified time.

boolean isTagEnabled(String tag)

Checks any denylists (set in system settings) to see whether a certain tag is allowed.

Inherited methods

Constants

ACTION_DROPBOX_ENTRY_ADDED

Added in API level 11
public static final String ACTION_DROPBOX_ENTRY_ADDED

Broadcast Action: This is broadcast when a new entry is added in the dropbox. For apps targeting 35 and later, For apps targeting Android versions lower than 35, you must hold Manifest.permission.READ_LOGS. This broadcast can be rate limited for low priority entries

This is a protected intent that can only be sent by the system.

Constant Value: "android.intent.action.DROPBOX_ENTRY_ADDED"

EXTRA_DROPPED_COUNT

Added in API level 29
public static final String EXTRA_DROPPED_COUNT

Extra for ACTION_DROPBOX_ENTRY_ADDED: integer value containing number of broadcasts dropped due to rate limiting on this EXTRA_TAG

Constant Value: "android.os.extra.DROPPED_COUNT"

EXTRA_TAG

Added in API level 11
public static final String EXTRA_TAG

Extra for ACTION_DROPBOX_ENTRY_ADDED: string containing the dropbox tag.

Constant Value: "tag"

EXTRA_TIME

Added in API level 11
public static final String EXTRA_TIME

Extra for ACTION_DROPBOX_ENTRY_ADDED: long integer value containing time (in milliseconds since January 1, 1970 00:00:00 UTC) when the entry was created.

Constant Value: "time"

IS_EMPTY

Added in API level 8
public static final int IS_EMPTY

Flag value: Entry's content was deleted to save space.

Constant Value: 1 (0x00000001)

IS_GZIPPED

Added in API level 8
public static final int IS_GZIPPED

Flag value: Content can be decompressed with java.util.zip.GZIPOutputStream.

Constant Value: 4 (0x00000004)

IS_TEXT

Added in API level 8
public static final int IS_TEXT

Flag value: Content is human-readable UTF-8 text (can be combined with IS_GZIPPED).

Constant Value: 2 (0x00000002)

Protected constructors

DropBoxManager

Added in API level 8
protected DropBoxManager ()

Create an instance for testing. All methods will fail unless overridden with an appropriate mock implementation. To obtain a functional instance, use Context.getSystemService(Class).

Public methods

addData

Added in API level 8
public void addData (String tag, 
                byte[] data, 
                int flags)

Stores binary data, which may be ignored or discarded as with addText(String, String).

Parameters
tag String: describing the type of entry being stored This value cannot be null.

data byte: value to store This value may be null.

flags int: describing the data Value is either 0 or a combination of IS_EMPTY, IS_TEXT, and IS_GZIPPED

addFile

Added in API level 8
public void addFile (String tag, 
                File file, 
                int flags)

Stores the contents of a file, which may be ignored or discarded as with addText(String, String).

Parameters
tag String: describing the type of entry being stored This value cannot be null.

file File: to read from This value cannot be null.

flags int: describing the data Value is either 0 or a combination of IS_EMPTY, IS_TEXT, and IS_GZIPPED

Throws
IOException if the file can't be opened

addText

Added in API level 8
public void addText (String tag, 
                String data)

Stores human-readable text. The data may be discarded eventually (or even immediately) if space is limited, or ignored entirely if the tag has been blocked (see isTagEnabled(String)).

Parameters
tag String: describing the type of entry being stored This value cannot be null.

data String: value to store This value cannot be null.

getNextEntry

Added in API level 8
public DropBoxManager.Entry getNextEntry (String tag, 
                long msec)

Gets the next entry from the drop box after the specified time. You must always call Entry#close() on the return value! Manifest.permission.READ_LOGS permission is required for apps targeting Android versions lower than 35.
Requires Manifest.permission.READ_DROPBOX_DATA and Manifest.permission.PACKAGE_USAGE_STATS

Parameters
tag String: of entry to look for, null for all tags

msec long: time of the last entry seen

Returns
DropBoxManager.Entry the next entry, or null if there are no more entries

isTagEnabled

Added in API level 8
public boolean isTagEnabled (String tag)

Checks any denylists (set in system settings) to see whether a certain tag is allowed. Entries with disabled tags will be dropped immediately, so you can save the work of actually constructing and sending the data.

Parameters
tag String: that would be used in addText(String, String) or addFile(String, File, int)

Returns
boolean whether events with that tag would be accepted