// 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 "mojo/public/mojom/base/big_buffer.mojom";
import "mojo/public/mojom/base/time.mojom";
import "services/network/public/mojom/data_pipe_getter.mojom";
import "services/network/public/mojom/http_request_headers.mojom";
import "services/network/public/mojom/url_loader.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(pending_receiver<Blob> blob);

  // Creates a reference to this Blob as a DataPipeGetter.
  AsDataPipeGetter(pending_receiver<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, pending_remote<BlobReaderClient>? client);

  // Causes a subrange of the contents of this blob to be written into the
  // given data pipe. If |length| is -1 (uint64_t max), the range's end is
  // unbounded so the entire contents are read starting at |offset|. An
  // optional BlobReaderClient will be informed of the result of the read
  // operation.
  ReadRange(uint64 offset, uint64 length, handle<data_pipe_producer> pipe,
            pending_remote<BlobReaderClient>? client);

  // Provides a response to a request for a blob: URL to a URLLoaderClient.
  // This takes into account optional Range request headers, but otherwise
  // ignores the headers. Also verifies the |request_method| is a supported
  // http request method for blob: URLs, and replies with an error if not.
  Load(pending_receiver<network.mojom.URLLoader> loader,
       string request_method,
       network.mojom.HttpRequestHeaders headers,
       pending_remote<network.mojom.URLLoaderClient> 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() => (mojo_base.mojom.BigBuffer? data);

  // If this blob represents a single file on disk, this will capture the
  // current snapshot state of that file.
  [Sync] CaptureSnapshot() => (uint64 length, mojo_base.mojom.Time? modification_time);

  // 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);
};