// 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 media.mojom;

import "mojo/public/mojom/base/file.mojom";

// Provides a way to organize persistent per-origin/per-cdm-type data
// in the browser's file system.
interface CdmStorage {
  enum Status {
    kSuccess,  // File was successfully opened.
    kInUse,    // File is already open by another client.
    kFailure   // Unable to open file.
  };

  // Opens the file specified by |file_name| for read only. Writing to the file
  // is done using a temporary file created with the CdmFile interface returned.
  // Can be called multiple times for different files, or for the same file if
  // the first one has been closed. If successful, kSuccess will be returned,
  // |file_for_reading| can be used to read the contents, and |cdm_file| should
  // be closed when access to the file is no longer needed (i.e. file closed).
  // On failure, |status| <> kSuccess and |file_for_reading| and |cdm_file|
  // are null.
  // - If the file is already opened, kInUse will be returned in |status|.
  // - |file_name| must not contain forward slash ('/') or backslash ('\'),
  //   and must not start with an underscore ('_'). If this happens,
  //   |status| == kFailure is returned.
  Open(string file_name)
    => (Status status,
        mojo_base.mojom.File? file_for_reading,
        associated CdmFile? cdm_file);
};

// Provides a way to keep track of the file opened. When the connection to this
// object is broken, it is assumed that the file has been closed and that no
// more operations will be performed on it.
//
// This interface is also used to be able to write to the file. Due to sandbox
// restrictions on some platforms (crbug.com/774762), setting the length of the
// file explicitly is not allowed in sandboxed processes. To get around this
// (and avoid file corruption issues), writing is done by opening a new file,
// letting the client write to it, and then replace the original file after
// writing.
interface CdmFile {
  // Open a new file that can be written to. This file will be in the same
  // directory as the original file. If successful, returns |file_for_writing|
  // which can be written to.
  OpenFileForWriting() => (mojo_base.mojom.File? file_for_writing);

  // Closes the file opened for writing and replaces the original file.
  // Returns a new file descriptor that should be used to read the original
  // file from now on.
  CommitWrite() => (mojo_base.mojom.File? updated_file_for_reading);
};