File Download Cache Manager

A Flutter plugin for managing file downloads with queue management, priority handling, and caching capabilities.

Features

• Priority-based Download Queue: Download files with configurable priorities
• Automatic Cache Management: Checks if files are already downloaded to avoid redundant downloads
• Progress Tracking: Monitor download progress with callbacks
• Folder Structure: Automatically creates folder structure based on URL paths
• Concurrent Download Prevention: Prevents duplicate downloads of the same file
• Resume Support: Uses temporary .downloading files during download process
• File Type Filtering: Supports filtering for specific file types (MP4, SVGA)

Installation

Add this to your package's pubspec.yaml file:

dependencies:
  file_download_cache_manager: ^${latest version}

Setup

Provider Configuration

Configure the provider in your app:

import 'package:provider/provider.dart';
import 'package:file_download_cache_manager/file_download_cache_manager.dart';

// Add to your providers
ChangeNotifierProvider<BigFilesProvider>(
  create: (_) => BigFilesProvider(),
  lazy: false,
),

Usage

Basic Download

Add a file to the download queue with lowest priority (999):

final provider = Provider.of<BigFilesProvider>(context, listen: false);

final result = await provider.addDownload(
  'https://example.com/video.mp4',
  progressCallback: (received, total) {
    print('Progress: ${(received / total * 100).toStringAsFixed(2)}%');
  },
);

if (result.isSuccess) {
  print('Downloaded to: ${result.filePath}');
} else {
  print('Download failed: ${result.error}');
}

Priority Download

Insert a download with specific priority (lower number = higher priority):

final result = await provider.insertDownload(
  'https://example.com/important-video.mp4',
  priority: 1, // Higher priority
  progressCallback: (received, total) {
    print('Progress: $received/$total');
  },
);

Check if File is Downloaded

final isDownloaded = await provider.isFileDownloaded(
  'https://example.com/video.mp4',
);

if (isDownloaded) {
  final filePath = await provider.getLocalFilePath(
    'https://example.com/video.mp4',
  );
  print('File available at: $filePath');
}

Monitor Queue Status

Consumer<BigFilesProvider>(
  builder: (context, provider, child) {
    return Column(
      children: [
        Text('Queue length: ${provider.downloadQueue.length}'),
        Text('Processing: ${provider.isProcessingQueue}'),
      ],
    );
  },
)

API Reference

BigFilesProvider

Main provider class for handling downloads.

Methods

• addDownload(String url, {DownloadProgressCallback? progressCallback}) - Add download with lowest priority
• insertDownload(String url, {required int priority, DownloadProgressCallback? progressCallback}) - Add download with specific priority
• isFileDownloaded(String url) - Check if file exists in cache
• getLocalFilePath(String url) - Get local file path if downloaded

Properties

• downloadQueue - List of queued downloads
• isProcessingQueue - Whether queue is currently being processed

DownloadResult

Result object returned after download completion.

Properties

• status - Download status (pending, downloading, completed, failed, cancelled)
• filePath - Local file path (empty if failed)
• error - Error message (if failed)
• totalBytes - Total file size in bytes
• receivedBytes - Downloaded bytes

Helper Methods

• isSuccess - Returns true if download completed successfully
• isFailed - Returns true if download failed
• isDownloading - Returns true if currently downloading

DownloadStatus

Enum representing download states:

• pending - Queued but not started
• downloading - Currently downloading
• completed - Successfully downloaded
• failed - Download failed
• cancelled - Download was cancelled

File Storage

Files are stored in the application documents directory with folder structure mirroring the URL path:

<documents_directory>/<host>/<path>/<filename>

Example:

URL: https://resource-miku.voloshow.top/image/admin/20250904/video.mp4
Path: <documents>/resource-miku.voloshow.top/image/admin/20250904/video.mp4

Supported File Types

By default, the manager only allows:

• MP4 files (.mp4)
• SVGA files (.svga)

To modify supported file types, update the _isAllowedFile method in the source code.

Error Handling

The plugin handles various error scenarios:

• Invalid URLs
• Unsupported file types
• Network errors
• Storage permission issues
• Disk space issues

All errors are captured and returned in the DownloadResult object.

Dependencies

• dio - HTTP client for downloads
• path_provider - Access to device directories
• flutter/foundation.dart - ChangeNotifier support