1<?php
2
3/**
4 * This file is part of the FreeDSx LDAP package.
5 *
6 * (c) Chad Sikorra <Chad.Sikorra@gmail.com>
7 *
8 * For the full copyright and license information, please view the LICENSE
9 * file that was distributed with this source code.
10 */
11
12namespace FreeDSx\Ldap\Server\RequestHandler;
13
14use FreeDSx\Ldap\Server\Paging\PagingRequest;
15use FreeDSx\Ldap\Server\Paging\PagingResponse;
16use FreeDSx\Ldap\Server\RequestContext;
17
18/**
19 * Server implementations that wish to support paging must use a class implementing this interface.
20 *
21 * @author Chad Sikorra <Chad.Sikorra@gmail.com>
22 */
23interface PagingHandlerInterface
24{
25    /**
26     * Indicates a paging request that has been received and needs a response.
27     *
28     * @param PagingRequest $pagingRequest
29     * @param RequestContext $context
30     * @return PagingResponse
31     */
32    public function page(
33        PagingRequest $pagingRequest,
34        RequestContext $context
35    ): PagingResponse;
36
37    /**
38     * Indicates that a paging request is to be removed / abandoned. No further attempts will be made to complete it.
39     * Any resources involved in its processing, if they still exist, should now be cleaned-up.
40     *
41     * This could be called in a couple of different contexts:
42     *
43     *  1. The client is explicitly asking to abandon the paging request.
44     *  2. The client paging request is being removed due to server resource constraints (request age, max outstanding requests, etc)
45     *  3. The paging request has been successfully completed and all results have been returned.
46     *
47     * @param PagingRequest $pagingRequest
48     * @param RequestContext $context
49     */
50    public function remove(
51        PagingRequest $pagingRequest,
52        RequestContext $context
53    ): void;
54}
55