// Copyright 2015 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.

[DartPackage="mojo_services"]
module native_support;

import "files/interfaces/file.mojom";
import "files/interfaces/types.mojom";

// Interface for dealing with (e.g., starting) "native" processes.
[ServiceName="native_support::Process"]
interface Process {
  // Spawns a process, optionally redirecting stdin/stdout/stderr from/to the
  // corresponding |mojo.files.File| (if null, redirects from/to /dev/null).
  // |path| is the path to the binary to execute; |argv| is the argv to give to
  // the process (if null, it just takes |argv[0]| to be |path| with no other
  // arguments); |envp| is the environment to give to the process, consisting of
  // an array of "strings" of the form "NAME=value" (if null, simply inherits
  // the environment from the parent, whatever that is).
  // TODO(vtl): This should really take an array of |mojo.files.File|s (or maybe
  // two, one for input and the other for output), corresponding to FDs, but the
  // C++ bindings generator doesn't support arrays of interfaces yet
  // (https://github.com/domokit/mojo/issues/412).
  // TODO(vtl): The implementation currently ignores |argv[0]| and always fills
  // it in with |path|.
  // TODO(vtl): Inheriting |envp| from the parent is somewhat dubious, and
  // there's also no way to just specify modifications or limit inheritance.
  Spawn(array<uint8> path,
        array<array<uint8>>? argv,
        array<array<uint8>>? envp,
        mojo.files.File? stdin_file,
        mojo.files.File? stdout_file,
        mojo.files.File? stderr_file,
        ProcessController& process_controller)
      => (mojo.files.Error error);
  // Like |Spawn()|, except that the child's stdin/stdout/stderr are redirected
  // from/to |terminal_file|, which should be a |mojo.files.File| for a terminal
  // (i.e., one that behaves like one, including responding to the required
  // ioctls).
  SpawnWithTerminal(array<uint8> path,
                    array<array<uint8>>? argv,
                    array<array<uint8>>? envp,
                    mojo.files.File terminal_file,
                    ProcessController& process_controller)
      => (mojo.files.Error error);
};

// Interface for controlling a process started by one of |Process|'s facilities
// (in particular, |Spawn()| or |SpawnWithTerminal()|).
// TODO(vtl): What does it do if this is closed (without being detached)? Kill
// with SIGHUP?
interface ProcessController {
  // Wait for process completion.
  // TODO(vtl): Add options (e.g., timeout)?
  Wait() => (mojo.files.Error error, int32 exit_status);

  // Kill the process with the given signal (note: does not wait). |signal|
  // should be nonnegative. This is not valid after a successful call to
  // |Wait()|.
  // TODO(vtl): Add constants for signals. (For standard POSIX signals, the
  // values should be the same as the POSIX-specified values, so using POSIX
  // macros for the values should always be OK.)
  Kill(int32 signal) => (mojo.files.Error error);

  // TODO(vtl): Add a "Detach()"?
};