<?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();
}