downloadToFile method

Future<int> downloadToFile(
  1. String url,
  2. String path, {
  3. Map<String, Object?>? queryParameters,
  4. bool absoluteUrl = true,
  5. PlexCancelToken? cancelToken,
  6. void onProgress(
    1. int received,
    2. int? total
    )?,
})

Streams url into the file at path and returns the bytes written.

The body is written as it arrives, at the pace the disk takes it — a whole track never sits in memory — to a temporary file next to path, renamed to path only once complete. A failure, a stall past the receive timeout or a cancellation through cancelToken removes the temporary file and throws a PlexException (of type PlexErrorType.cancelled for a cancellation); whatever was at path before is left as it was. Two downloads to the same path never share a temporary file.

onProgress is called after each chunk with the bytes received so far and the total when the server sent a Content-Length (never for a gzip body, whose length on the wire is not the file's).

Implementation

Future<int> downloadToFile(
  String url,
  String path, {
  Map<String, Object?>? queryParameters,
  bool absoluteUrl = true,
  PlexCancelToken? cancelToken,
  void Function(int received, int? total)? onProgress,
}) async {
  final File part;
  final IOSink sink;
  try {
    part = await _createPart(path);
    sink = part.openWrite();
  } on FileSystemException catch (e, st) {
    throw PlexException(
      'Cannot write $path: ${e.message}',
      type: PlexErrorType.state,
      path: url,
      cause: e,
      stackTrace: st,
    );
  }
  var received = 0;
  try {
    final res = await requestStream(
      url,
      queryParameters: queryParameters,
      absoluteUrl: absoluteUrl,
      cancelToken: cancelToken,
    );
    // addStream pauses the body while the disk catches up.
    await sink.addStream(
      res.stream.map((chunk) {
        received += chunk.length;
        onProgress?.call(received, res.contentLength);
        return chunk;
      }),
    );
    await sink.flush();
    await sink.close();
    await part.rename(path);
    return received;
  } catch (e, st) {
    await sink.close().catchError((Object _) {});
    await part.delete().catchError((Object _) => part);
    if (e is PlexException) rethrow;
    throw PlexException(
      'Download to $path failed: $e',
      path: url,
      cause: e,
      stackTrace: st,
    );
  }
}