// Copyright 2017 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

module blink.mojom;

import "services/network/public/mojom/data_pipe_getter.mojom";
import "services/network/public/mojom/http_request_headers.mojom";

// Interface that can be implemented to be informed of certain information while
// reading the data for a blob.
interface BlobReaderClient {
  // Called when the size of the blob being read has been calculated:
  //   |total_size| is the total size of the blob.
  //   |expected_content_size| is how many bytes should be sent over the data
  //      pipe, taking into account a range if the blob was read with ReadRange.
  // If an error occurs while reading the blob, this method might not get called.
  OnCalculatedSize(uint64 total_size,
                   uint64 expected_content_size);

  // Called when reading the blob finished (with success or failure). Status is
  // a net::Error indicating any potential error that might have occurred,
  // |data_length| tells the reader how many bytes were written into the data
  // pipe, and can be used as a sanity check to make sure all bytes were
  // received.
  OnComplete(int32 status, uint64 data_length);
};

// This interface provides access to a blob in the blob system.
interface Blob {
  // Creates a copy of this Blob reference.
  Clone(Blob& blob);

  // Creates a reference to this Blob as a DataPipeGetter.
  AsDataPipeGetter(network.mojom.DataPipeGetter& data_pipe_getter);

  // Causes the entire contents of this blob to be written into the given data
  // pipe. An optional BlobReaderClient will be informed of the result of the
  // read operation.
  ReadAll(handle<data_pipe_producer> pipe, BlobReaderClient? client);

  // Causes a subrange of the contents of this blob to be written into the given
  // data pipe. An optional BlobReaderClient will be informed of the result of
  // the read operation.
  ReadRange(uint64 offset, uint64 length, handle<data_pipe_producer> pipe,
            BlobReaderClient? client);

  // Reads the side-data (if any) associated with this blob. This is the same
  // data that would be passed to OnReceivedCachedMetadata if you were reading
  // this blob through a blob URL.
  ReadSideData() => (array<uint8>? data);

  // This method is an implementation detail of the blob system. You should not
  // ever need to call it directly.
  // This returns the internal UUID of the blob, used by the blob system to
  // identify the blob.
  GetInternalUUID() => (string uuid);
};