Added in API level 37

FileManager

class FileManager
kotlin.Any
   ↳ 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:

  1. 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).
  2. Tracking Progress (Optional): Apps can poll the current status of an operation using fetchResult(String) or simply wait for completion.
  3. 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 android.os.storage.operations.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 android.os.storage.operations.FileOperationResult to the value returned from 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
static String

Broadcast Action: Sent when a file operation has completed.
static String

Extra for ACTION_FILE_OPERATION_COMPLETED: The Request ID (String).
static String

Extra for ACTION_FILE_OPERATION_COMPLETED: The result (android.os.storage.operations.FileOperationResult).
Public methods
FileOperationEnqueueResult

Enqueues a new file operation request.
FileOperationResult?
fetchResult(requestId: String)

Retrieves the current result of a file operation.
static Int

Due to binder transaction limits, the number of reported failures is limited to number returned by this method.
Unit

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

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

Constants

ACTION_FILE_OPERATION_COMPLETED

Added in API level 37
static val ACTION_FILE_OPERATION_COMPLETED: String

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: 

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

EXTRA_REQUEST_ID

Added in API level 37
static val EXTRA_REQUEST_ID: String

Extra for ACTION_FILE_OPERATION_COMPLETED: The Request ID (String).

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

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

EXTRA_RESULT

Added in API level 37
static val EXTRA_RESULT: String

Extra for ACTION_FILE_OPERATION_COMPLETED: The result (android.os.storage.operations.FileOperationResult).

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

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

Public methods

enqueueOperation

Added in API level 37
fun enqueueOperation(request: FileOperationRequest): FileOperationEnqueueResult

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 android.os.storage.operations.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.
Return
FileOperationEnqueueResult A FileOperationEnqueueResult containing the Request ID (on success) or an error code (on failure).
This value cannot be null.
Exceptions
java.lang.RuntimeException if the system service is unreachable.

fetchResult

Added in API level 37
fun fetchResult(requestId: String): FileOperationResult?

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.
This value cannot be null.
Return
FileOperationResult? A FileOperationResult object containing the current status, or null if the request ID is unknown or has been culled from history.
Exceptions
java.lang.RuntimeException if the system service is unreachable.

getMaxReportedFailures

Added in API level 37
static fun getMaxReportedFailures(): Int

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.

Return
Int The maximum number of reported failures reported by File operations.

registerCompletionListener

Added in API level 37
fun registerCompletionListener(requestId: String): Unit

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 if completion notification is desired.

Parameters
requestId String: The unique ID of the request to monitor, as returned by enqueueOperation.
This value cannot be null.
Exceptions
java.lang.RuntimeException if the system service is unreachable.

unregisterCompletionListener

Added in API level 37
fun unregisterCompletionListener(requestId: String): Unit

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.
Exceptions
java.lang.RuntimeException if the system service is unreachable.