Added in API level 37

Summary: Constants | Methods | Inherited Methods

FileManager

Kotlin |Java

public final class FileManager
extends Object

java.lang.Object
↳	android.os.storage.FileManager

System service manager for handling privileged, long-running file operations.

The FileManager provides an API for applications to request asynchronous file operations such as moving or copying files. These operations are executed by the system service (`FileService`) on a background thread to ensure application responsiveness and system stability.

Usage Overview

Interacting with the file operation service generally involves three steps:

Enqueueing a Request: Use enqueueOperation(FileOperationRequest) to submit a new operation. This method returns immediately with a FileOperationEnqueueResult, which contains a unique Request ID (if successful) or an error code (if the system is busy).
Tracking Progress (Optional): Apps can poll the current status of an operation using fetchResult(String) or simply wait for completion.
Handling Completion: To receive a notification when the operation finishes (either successfully or with a failure), call registerCompletionListener(String). The system will send a broadcast ACTION_FILE_OPERATION_COMPLETED to your package when the operation reaches a terminal state.

Concurrency and Limits

The system enforces limits on the number of concurrent pending operations to prevent resource exhaustion. If the system is under heavy load, enqueueOperation(FileOperationRequest) may return a result with the error code FileOperationResult.ERROR_BUSY. Applications should handle this case gracefully, potentially by retrying later.

Additionally, the system caps the number of individual file failures reported in a FileOperationResult to the value returned from ERROR(/getMaxReportedFailures). If granular failure reporting is critical for your use case, avoid enqueueing operations that involve more files than the failure reporting limit in a single request.

Summary

Constants
`String`	`ACTION_FILE_OPERATION_COMPLETED` Broadcast Action: Sent when a file operation has completed.
`String`	`EXTRA_REQUEST_ID` Extra for `ACTION_FILE_OPERATION_COMPLETED`: The Request ID (String).
`String`	`EXTRA_RESULT` Extra for `ACTION_FILE_OPERATION_COMPLETED`: The result (`FileOperationResult`).

Public methods
`FileOperationEnqueueResult`	`enqueueOperation(FileOperationRequest request)` Enqueues a new file operation request.
`FileOperationResult`	`fetchResult(String requestId)` Retrieves the current result of a file operation.
`static int`	`getMaxReportedFailures()` Due to binder transaction limits, the number of reported failures is limited to number returned by this method.
`void`	`registerCompletionListener(String requestId)` Registers a listener for the completion of a specific file operation.
`void`	`unregisterCompletionListener(String requestId)` Unregisters a previously registered completion listener for a specific file operation.

Inherited methods

From class


        
          java.lang.Object

`Object`	`clone()` Creates and returns a copy of this object.
`boolean`	`equals(Object obj)` Indicates whether some other object is "equal to" this one.
`void`	`finalize()` Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
`final Class<?>`	`getClass()` Returns the runtime class of this `Object`.
`int`	`hashCode()` Returns a hash code value for the object.
`final void`	`notify()` Wakes up a single thread that is waiting on this object's monitor.
`final void`	`notifyAll()` Wakes up all threads that are waiting on this object's monitor.
`String`	`toString()` Returns a string representation of the object.
`final void`	`wait(long timeoutMillis, int nanos)` Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
`final void`	`wait(long timeoutMillis)` Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
`final void`	`wait()` Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

Constants

ACTION_FILE_OPERATION_COMPLETED

Added in API level 37

public static final String ACTION_FILE_OPERATION_COMPLETED

Broadcast Action: Sent when a file operation has completed.

This broadcast is sent explicitly to the package that initiated the request and registered for notifications via registerCompletionListener(String).

The intent will contain the following extras:

EXTRA_REQUEST_ID - The unique ID of the request that completed.
EXTRA_RESULT - The final FileOperationResult of the operation, including status (FINISHED/FAILED), items processed, and any error messages.

Constant Value: "android.os.storage.action.FILE_OPERATION_COMPLETED"

EXTRA_REQUEST_ID

Added in API level 37

public static final String EXTRA_REQUEST_ID

Extra for ACTION_FILE_OPERATION_COMPLETED: The Request ID (String).

This ID matches the one returned by enqueueOperation(FileOperationRequest).

Constant Value: "android.os.storage.extra.REQUEST_ID"

EXTRA_RESULT

Added in API level 37

public static final String EXTRA_RESULT

Extra for ACTION_FILE_OPERATION_COMPLETED: The result (FileOperationResult).

This parcelable object contains detailed information about the final state of the operation.

Constant Value: "android.os.storage.extra.RESULT"

Public methods

enqueueOperation

Added in API level 37

public FileOperationEnqueueResult enqueueOperation (FileOperationRequest request)

Enqueues a new file operation request.

This method validates the request and submits it to the system service. It returns immediately, without waiting for the operation to execute.

If the system is too busy to accept the request, the returned result will have an error code of FileOperationResult.ERROR_BUSY.

Note: Granular failure reporting is limited to the first 200 failures encountered. For operations where reporting every individual failure is required, it is recommended to break large tasks into multiple requests of 200 files or fewer.

Parameters
`request`	`FileOperationRequest`: The `FileOperationRequest` describing the operation (source, target, mode). This value cannot be `null`.

Returns
`FileOperationEnqueueResult`	A `FileOperationEnqueueResult` containing the Request ID (on success) or an error code (on failure). This value cannot be `null`.

Throws
`RuntimeException`	if the system service is unreachable.

fetchResult

Added in API level 37

public FileOperationResult fetchResult (String requestId)

Retrieves the current result of a file operation.

The system maintains result information for all active operations and a limited history of recently completed ones.

Parameters
`requestId`	`String`: The unique ID of the request to query, as returned by `enqueueOperation(FileOperationRequest)`. This value cannot be `null`.

Returns
`FileOperationResult`	A `FileOperationResult` object containing the current status, or `null` if the request ID is unknown or has been culled from history.

Throws
`RuntimeException`	if the system service is unreachable.

getMaxReportedFailures

Added in API level 37

public static int getMaxReportedFailures ()

Due to binder transaction limits, the number of reported failures is limited to number returned by this method. It is recommended that operations that require complete failure reporting batch their operations to stay below the max reported failures limit.

Returns
`int`	The maximum number of reported failures reported by File operations.

registerCompletionListener

Added in API level 37

public void registerCompletionListener (String requestId)

Registers a listener for the completion of a specific file operation.

When the operation identified by requestId finishes (successfully or with an error), the system will send a ACTION_FILE_OPERATION_COMPLETED broadcast to the calling application.

This method should be called immediately after a successful enqueueOperation(FileOperationRequest) if completion notification is desired.

Parameters
`requestId`	`String`: The unique ID of the request to monitor, as returned by `enqueueOperation(FileOperationRequest)`. This value cannot be `null`.

Throws
`RuntimeException`	if the system service is unreachable.

unregisterCompletionListener

Added in API level 37

public void unregisterCompletionListener (String requestId)

Unregisters a previously registered completion listener for a specific file operation.

Parameters
`requestId`	`String`: The unique ID of the request to stop monitoring. This value cannot be `null`.

Throws
`RuntimeException`	if the system service is unreachable.