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

package org.chromium.content.browser;

import android.os.IBinder;

import org.chromium.base.process_launcher.ChildProcessCreationParams;
import org.chromium.base.process_launcher.FileDescriptorInfo;
import org.chromium.base.process_launcher.IChildProcessService;

import javax.annotation.Nullable;

/**
 * Manages a connection between the browser activity and a child service. ChildProcessConnection is
 * responsible for estabilishing the connection (start()), closing it (stop()) and manipulating the
 * bindings held onto the service (addStrongBinding(), removeStrongBinding(),
 * removeInitialBinding()).
 */
public interface ChildProcessConnection {
    /**
     * Used to notify the consumer about disconnection of the service. This callback is provided
     * earlier than ConnectionCallbacks below, as a child process might die before the connection is
     * fully set up.
     */
    interface DeathCallback {
        void onChildProcessDied(ChildProcessConnection connection);
    }

    /**
     * Used to notify the consumer about the process start. These callbacks will be invoked before
     * the ConnectionCallbacks.
     */
    interface StartCallback {
        /**
         * Called when the child process has successfully started and is ready for connection
         * setup.
         */
        void onChildStarted();

        /**
         * Called when the child process failed to start. This can happen if the process is already
         * in use by another client.
         */
        void onChildStartFailed();
    }

    /**
     * Used to notify the consumer about the connection being established.
     */
    interface ConnectionCallback {
        /**
         * Called when the connection to the service is established.
         * @param pid the pid of the child process
         */
        void onConnected(int pid);
    }

    int getServiceNumber();

    boolean isInSandbox();

    String getPackageName();

    ChildProcessCreationParams getCreationParams();

    IChildProcessService getService();

    /**
     * @return the connection pid, or 0 if not yet connected
     */
    int getPid();

    /**
     * Starts a connection to an IChildProcessService. This must be followed by a call to
     * setupConnection() to setup the connection parameters. start() and setupConnection() are
     * separate to allow to pass whatever parameters are available in start(), and complete the
     * remainder later while reducing the connection setup latency.
     * @param startCallback (optional) callback when the child process starts or fails to start.
     */
    void start(StartCallback startCallback);

    /**
     * Setups the connection after it was started with start().
     * @param commandLine (optional) will be ignored if the command line was already sent in start()
     * @param filesToBeMapped a list of file descriptors that should be registered
     * @param callback optional client specified callbacks that the child can use to communicate
     *                 with the parent process
     * @param connectionCallback will be called exactly once after the connection is set up or the
     *                           setup fails
     */
    void setupConnection(String[] commandLine, FileDescriptorInfo[] filesToBeMapped,
            @Nullable IBinder callback, ConnectionCallback connectionCallback);

    /**
     * Terminates the connection to IChildProcessService, closing all bindings. It is safe to call
     * this multiple times.
     */
    void stop();

    /** @return true iff the initial oom binding is currently bound. */
    boolean isInitialBindingBound();

    /** @return true iff the strong oom binding is currently bound. */
    boolean isStrongBindingBound();

    /**
     * Called to remove the strong binding established when the connection was started. It is safe
     * to call this multiple times.
     */
    void removeInitialBinding();

    /**
     * For live connections, this returns true iff either the initial or the strong binding is
     * bound, i.e. the connection has at least one oom binding. For connections that disconnected
     * (did not exit properly), this returns true iff the connection had at least one oom binding
     * when it disconnected.
     */
    boolean isOomProtectedOrWasWhenDied();

    /**
     * Unbinds the bindings that protect the process from oom killing. It is safe to call this
     * multiple times, before as well as after stop().
     */
    void dropOomBindings();

    /**
     * Attaches a strong binding that will make the service as important as the main process. Each
     * call should be succeeded by removeStrongBinding(), but multiple strong bindings can be
     * requested and released independently.
     */
    void addStrongBinding();

    /**
     * Called when the service is no longer in active use of the consumer.
     */
    void removeStrongBinding();

    /**
     * Attaches a moderate binding that will give the service the priority of a visible process, but
     * keep the priority below a strongly bound process.
     */
    void addModerateBinding();

    /**
     * Called when the service is no longer in moderate use of the consumer.
     */
    void removeModerateBinding();

    /** @return true iff the moderate oom binding is currently bound. */
    boolean isModerateBindingBound();
}