1	<?php
2
3	/**
4	* SPDX-License-Identifier: EUPL-1.2
5	*
6	* This file is part of icap-flow.
7	*
8	* Licensed under the EUPL, Version 1.2 only (the "Licence");
9	* you may not use this work except in compliance with the Licence.
10	* You may obtain a copy of the Licence at:
11	*
12	*     https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
13	*
14	* Unless required by applicable law or agreed to in writing, software
15	* distributed under the Licence is distributed on an "AS IS" basis,
16	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17	*/
18
19	declare(strict_types=1);
20
21	namespace Ndrstmr\Icap\Transport;
22
23	use Amp\Cancellation;
24	use Ndrstmr\Icap\Config;
25
26	/**
27	* Capability of a transport that hands out a {@see TransportSession}: a connection that carries more than one
28	* write/read round trip. {@see AsyncAmpTransport} and {@see SynchronousStreamTransport} implement it.
29	*
30	* A preview that the server answers with `100 Continue` is continued on the connection it began on (RFC 3507 §4.5),
31	* so {@see \Ndrstmr\Icap\IcapClient} refuses `scanFileWithPreview*()` with a transport that does not implement this
32	* interface (a `\LogicException`, before a file is opened or a connection made). Everything else works with
33	* {@see TransportInterface} alone.
34	*/
35	interface SessionAwareTransport extends TransportInterface
36	{
37	/**
38	* Open a session against the host described by $config. The
39	* caller MUST eventually call {@see TransportSession::release()}
40	* or {@see TransportSession::close()} on the returned session.
41	*/
42	public function openSession(Config $config, ?Cancellation $cancellation = null): TransportSession;
43	}