<?php
/**
 * Provides a mechanism for running Perforce commands.
 *
 * @copyright   2011 Perforce Software. All rights reserved.
 * @license     Please see LICENSE.txt in top-level folder of this distribution.
 * @version     <release>/<patch>
 */
interface P4_Connection_Interface
{
    /**
     * Create a P4_Connection_Interface instance.
     *
     * @param   string  $port        optional - the port to connect to.
     * @param   string  $user        optional - the user to connect as.
     * @param   string  $client      optional - the client spec to use.
     * @param   string  $password    optional - the password to use.
     * @param   string  $ticket      optional - a ticket to use.
     */
    public function __construct(
        $port       = null,
        $user       = null,
        $client     = null,
        $password   = null,
        $ticket     = null);

    /**
     * Connect to a Perforce server.
     *
     * @return  P4_Connection_Interface         provides fluent interface.
     * @throws  P4_Connection_ConnectException  if the connection fails.
     */
    public function connect();

    /**
     * Disconnect from a Perforce server.
     *
     * @return  P4_Connection_Interface     provides fluent interface.
     */
    public function disconnect();

    /**
     * Check connected state.
     *
     * @return  bool    true if connected, false otherwise.
     */
    public function isConnected();

    /**
     * Executes the specified command and returns a perforce result object.
     * No need to call connect() first. Run will connect automatically.
     *
     * @param   string          $command    the command to run.
     * @param   array|string    $params     optional - one or more arguments.
     * @param   array|string    $input      optional - input for the command - should be provided
     *                                      in array form when writing perforce spec records.
     * @param   boolean         $tagged     optional - true/false to enable/disable tagged output.
     *                                      defaults to true.
     * @return  P4_Result the perforce result object.
     * @throws  P4_Connection_CommandException   if the command fails.
     */
    public function run($command, $params = array(), $input = null, $tagged = true);

    /**
     * Return the p4 port.
     *
     * @return  string  the port.
     */
    public function getPort();

    /**
     * Set the p4 port.
     *
     * @param   string  $port               the port to connect to.
     * @return  P4_Connection_Interface     provides fluent interface.
     */
    public function setPort($port);

    /**
     * Return the name of the p4 user.
     *
     * @return  string  the user.
     */
    public function getUser();

    /**
     * Set the name of the p4 user.
     *
     * @param   string  $user               the user to connect as.
     * @return  P4_Connection_Interface     provides fluent interface.
     */
    public function setUser($user);

    /**
     * Return the p4 user's client.
     *
     * @return  string  the client.
     */
    public function getClient();

    /**
     * Set the p4 user's client.
     *
     * @param   string  $client             the name of the client workspace to use.
     * @return  P4_Connection_Interface     provides fluent interface.
     */
    public function setClient($client);

    /**
     * Retrieves the password set for this perforce connection.
     *
     * @return  string  password used to authenticate against perforce server.
     */
    public function getPassword();

    /**
     * Sets the password to use for this perforce connection.
     *
     * @param   string  $password           the password to use as authentication.
     * @return  P4_Connection_Interface     provides fluent interface.
     */
    public function setPassword($password);

    /**
     * Retrieves the ticket set for this perforce connection.
     *
     * @return  string  ticket as generated by perforce server.
     */
    public function getTicket();

    /**
     * Sets the ticket to use for this perforce connection.
     *
     * @param   string  $ticket             the ticket to use as authentication.
     * @return  P4_Connection_Interface     provides fluent interface.
     */
    public function setTicket($ticket);

    /**
     * Retrieves the character set used by this connection.
     *
     * @return  string  charset used for this connection.
     */
    public function getCharset();

    /**
     * Sets the character set to use for this perforce connection.
     *
     * You should only set a character set when connecting to a
     * 'unicode enabled' server.
     *
     * @param   string  $charset            the charset to use (e.g. 'utf8').
     * @return  P4_Connection_Interface     provides fluent interface.
     */
    public function setCharset($charset);

    /**
     * Retrieves the client host set for this connection.
     *
     * @return  string  charset used for this connection.
     */
    public function getHost();

    /**
     * Sets the client host name overriding the environment.
     *
     * @param   string|null $host           the host name to use.
     * @return  P4_Connection_Interface     provides fluent interface.
     */
    public function setHost($host);

    /**
     * Get the current client's root directory.
     *
     * @return  string  the full path to the current client's root.
     */
    public function getClientRoot();

    /**
     * Return an array of connection information.
     *
     * @return  array   the connection information ('p4 info').
     */
    public function getInfo();

    /**
     * Get the identity of this Connection implementation.
     *
     * @return  array   an array of client Connection information containing the name,
     *                  platform, version, build and date of the client library.
     */
    public function getConnectionIdentity();

    /**
     * Authenticate the user with 'p4 login'.
     *
     * @return  string|null     the ticket issued by the server or null if
     *                          no ticket issued (user has no password).
     * @throws  P4_Connection_LoginException    if login fails.
     */
    public function login();

    /**
     * Check if the user we are connected as has super user privileges.
     *
     * @return  bool    true if the user has super, false otherwise.
     */
    public function isSuperUser();

    /**
     * Check if the server we are connected to is case sensitive.
     *
     * @return  bool    true if the server is case sensitive, false otherwise.
     */
    public function isCaseSensitive();

    /**
     * Check if the server we are connected to is using external authentication
     *
     * @return  bool    true if the server is using external authentication, false otherwise.
     */
    public function hasExternalAuth();

    /**
     * Check if the server we are connected to has a auth-set trigger configured.
     *
     * @return  bool    true, if the server has configured an auth-set trigger,
     *                  false, otherwise.
     */
    public function hasAuthSetTrigger();

    /**
     * Add a function to run when connection is closed.
     * Callbacks are removed after they are executed
     * unless persistent is set to true.
     *
     * @param   callable    $callback   the function to execute on disconnect
     *                                  (will be passed connection).
     * @param   bool        $persistent optional - defaults to false - set to true to
     *                                  run callback on repeated disconnects.
     * @return  P4_Connection_Interface provides fluent interface.
     */
    public function addDisconnectCallback($callback, $persistent = false);

    /**
     * Get the server's security level.
     *
     * @return  int     the security level of the server (e.g. 0, 1, 2, 3)
     */
    public function getSecurityLevel();

    /**
     * Get the maximum allowable length of all command arguments.
     *
     * @return  int     the max length of combined arguments - zero for no limit
     */
    public function getArgMax();

    /**
     * Return arguments split into chunks (batches) where each batch contains as many
     * arguments as possible to not exceed ARG_MAX or OPTION_LIMIT.
     *
     * ARG_MAX is a character limit that affects command line programs (p4).
     * OPTION_LIMIT is a server-side limit on the number of flags (e.g. '-n').
     *
     * @param   array       $arguments  list of arguments to split into chunks.
     * @param   array|null  $prefixArgs arguments to begin all batches with.
     * @param   array|null  $suffixArgs arguments to end all batches with.
     * @param   int         $groupSize  keep arguments together in groups of this size
     *                                  for example, when clearing attributes you want to
     *                                  keep pairs of -n and attr-name together.
     * @return  array                   list of batches of arguments where every batch contains as many
     *                                  arguments as possible and arg-max is not exceeded.
     * @throws  P4_Exception            if a argument (or set of arguments) exceed arg-max.
     */
    public function batchArgs(array $arguments, array $prefixArgs = null, array $suffixArgs = null, $groupSize = 1);

    /**
     * Set the name of the application that is using this connection.
     *
     * The application name will be reported to the server and might
     * be necessary to satisfy certain licensing restrictions.
     *
     * @param   string|null     $name       the app name to report to the server.
     * @return  P4_Connection_Interface     provides fluent interface.
     */
    public function setAppName($name);

    /**
     * Get the application name being reported to the server.
     *
     * @return  string|null     the app name reported to the server.
     */
    public function getAppName();
}