1<?php
2namespace Aws;
3
4use Psr\Http\Message\UriInterface;
5use GuzzleHttp\Promise\PromiseInterface;
6
7/**
8 * Represents an AWS client.
9 */
10interface AwsClientInterface
11{
12    /**
13     * Creates and executes a command for an operation by name.
14     *
15     * Suffixing an operation name with "Async" will return a
16     * promise that can be used to execute commands asynchronously.
17     *
18     * @param string $name      Name of the command to execute.
19     * @param array  $arguments Arguments to pass to the getCommand method.
20     *
21     * @return ResultInterface
22     * @throws \Exception
23     */
24    public function __call($name, array $arguments);
25
26    /**
27     * Create a command for an operation name.
28     *
29     * Special keys may be set on the command to control how it behaves,
30     * including:
31     *
32     * - @http: Associative array of transfer specific options to apply to the
33     *   request that is serialized for this command. Available keys include
34     *   "proxy", "verify", "timeout", "connect_timeout", "debug", "delay", and
35     *   "headers".
36     *
37     * @param string $name Name of the operation to use in the command
38     * @param array  $args Arguments to pass to the command
39     *
40     * @return CommandInterface
41     * @throws \InvalidArgumentException if no command can be found by name
42     */
43    public function getCommand($name, array $args = []);
44
45    /**
46     * Execute a single command.
47     *
48     * @param CommandInterface $command Command to execute
49     *
50     * @return ResultInterface
51     * @throws \Exception
52     */
53    public function execute(CommandInterface $command);
54
55    /**
56     * Execute a command asynchronously.
57     *
58     * @param CommandInterface $command Command to execute
59     *
60     * @return \GuzzleHttp\Promise\PromiseInterface
61     */
62    public function executeAsync(CommandInterface $command);
63
64    /**
65     * Returns a promise that is fulfilled with an
66     * {@see \Aws\Credentials\CredentialsInterface} object.
67     *
68     * If you need the credentials synchronously, then call the wait() method
69     * on the returned promise.
70     *
71     * @return PromiseInterface
72     */
73    public function getCredentials();
74
75    /**
76     * Get the region to which the client is configured to send requests.
77     *
78     * @return string
79     */
80    public function getRegion();
81
82    /**
83     * Gets the default endpoint, or base URL, used by the client.
84     *
85     * @return UriInterface
86     */
87    public function getEndpoint();
88
89    /**
90     * Get the service description associated with the client.
91     *
92     * @return \Aws\Api\Service
93     */
94    public function getApi();
95
96    /**
97     * Get a client configuration value.
98     *
99     * @param string|null $option The option to retrieve. Pass null to retrieve
100     *                            all options.
101     * @return mixed|null
102     */
103    public function getConfig($option = null);
104
105    /**
106     * Get the handler list used to transfer commands.
107     *
108     * This list can be modified to add middleware or to change the underlying
109     * handler used to send HTTP requests.
110     *
111     * @return HandlerList
112     */
113    public function getHandlerList();
114
115    /**
116     * Get a resource iterator for the specified operation.
117     *
118     * @param string $name Name of the iterator to retrieve.
119     * @param array  $args Command arguments to use with each command.
120     *
121     * @return \Iterator
122     * @throws \UnexpectedValueException if the iterator config is invalid.
123     */
124    public function getIterator($name, array $args = []);
125
126    /**
127     * Get a result paginator for the specified operation.
128     *
129     * @param string $name   Name of the operation used for iterator
130     * @param array  $args   Command args to be used with each command
131     *
132     * @return \Aws\ResultPaginator
133     * @throws \UnexpectedValueException if the iterator config is invalid.
134     */
135    public function getPaginator($name, array $args = []);
136
137    /**
138     * Wait until a resource is in a particular state.
139     *
140     * @param string|callable $name Name of the waiter that defines the wait
141     *                              configuration and conditions.
142     * @param array  $args          Args to be used with each command executed
143     *                              by the waiter. Waiter configuration options
144     *                              can be provided in an associative array in
145     *                              the @waiter key.
146     * @return void
147     * @throws \UnexpectedValueException if the waiter is invalid.
148     */
149    public function waitUntil($name, array $args = []);
150
151    /**
152     * Get a waiter that waits until a resource is in a particular state.
153     *
154     * Retrieving a waiter can be useful when you wish to wait asynchronously:
155     *
156     *     $waiter = $client->getWaiter('foo', ['bar' => 'baz']);
157     *     $waiter->promise()->then(function () { echo 'Done!'; });
158     *
159     * @param string|callable $name Name of the waiter that defines the wait
160     *                              configuration and conditions.
161     * @param array  $args          Args to be used with each command executed
162     *                              by the waiter. Waiter configuration options
163     *                              can be provided in an associative array in
164     *                              the @waiter key.
165     * @return \Aws\Waiter
166     * @throws \UnexpectedValueException if the waiter is invalid.
167     */
168    public function getWaiter($name, array $args = []);
169}
170