withHandleAccess<T> method

  1. @override
Future<T> withHandleAccess<T>(
  1. String handle,
  2. FutureOr<T> operation(
    1. FileSystemEntity entity
    )
)
override

Runs operation with access to the file or directory stored by handle.

Implementations must resolve and activate platform access before invoking operation, then release all access after its returned future completes. They must invoke operation exactly once and complete with its result. The supplied entity must not be retained or used after operation completes. Implementations must still attempt cleanup when operation throws.

Backends must implement this as one balanced operation rather than expose resolution or security-scope lifecycle state to the collection. Calls may overlap, including calls for the same handle, so each invocation must own an independent access lifetime. Do not retain operation or invoke it after this method completes. The collection rejects successful calls that skip or repeat operation, or that do not return its exact result.

Implementation

@override
Future<T> withHandleAccess<T>(
  final String handle,
  final FutureOr<T> Function(FileSystemEntity entity) operation,
) async {
  final parsed = _parseHandle(handle);
  final bookmark = _decodeBookmark(parsed.bookmark);
  var operationStarted = false;
  try {
    return await withBookmarkAccess(bookmark, (final resource) {
      operationStarted = true;
      final entity = resource.entity;
      if (entityKindOf(entity) != parsed.kind) {
        throw FileSystemException(
          'The resolved filesystem entity kind does not match the bookmark.',
          entity.path,
        );
      }
      return operation(entity);
    });
  } on MacOSSecurityScopedBookmarkAccessException {
    if (operationStarted) {
      rethrow;
    }
    throw const PersistentAccessDeniedException();
  }
}