1/*
2 * Copyright (C) 2019 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package [email protected];
18
19import @3.5::ICameraDeviceCallback;
20
21/**
22 * Camera device offline session interface.
23 *
24 * Obtained via ICameraDeviceSession::switchToOffline(), this interface contains
25 * the methods and callback interfaces that define how camera service interacts
26 * with an offline session.
27 *
28 * An offline session contains some unfinished capture requests that were submitted
29 * to the parent ICameraDeviceSession before calling switchToOffline, and is
30 * responsible for delivering these capture results back to camera service regardless
31 * of whether the parent camera device is still opened or not. An offline session must
32 * not have access to the camera device's image sensor. During switchToOffline
33 * call, camera HAL must capture all necessary frames from the image sensor that
34 * is needed for completing the requests offline later.
35 */
36interface ICameraOfflineSession {
37    /**
38     * Set the callbacks for offline session to communicate with camera service.
39     *
40     * Offline session is responsible to store all callbacks the camera HAL
41     * generated after the return of ICameraDeviceSession::switchToOffline, and
42     * send them to camera service once this method is called.
43     *
44     * Camera service must not call this method more than once, so these
45     * callbacks can be assumed to be constant after the first setCallback call.
46     */
47    setCallback(ICameraDeviceCallback cb);
48
49    /**
50     * getCaptureResultMetadataQueue:
51     *
52     * Retrieves the queue used along with
53     * ICameraDeviceCallback#processCaptureResult.
54     *
55     * Clients to ICameraOfflineSession must:
56     * - Call getCaptureRequestMetadataQueue to retrieve the fast message queue;
57     * - In implementation of ICameraDeviceCallback, test whether
58     *   .fmqResultSize field is zero.
59     *     - If .fmqResultSize != 0, read result metadata from the fast message
60     *       queue;
61     *     - otherwise, read result metadata in CaptureResult.result.
62     *
63     * @return queue the queue that implementation writes result metadata to.
64     */
65    getCaptureResultMetadataQueue() generates (fmq_sync<uint8_t> queue);
66
67    /**
68     * Close the offline session and release all resources.
69     *
70     * Camera service may call this method before or after the offline session
71     * has finished all requests it needs to handle. If there are still unfinished
72     * requests when close is called, camera HAL must send ERROR_REQUEST for
73     * all unfinished requests and return all buffers via
74     * ICameraDeviceCallback#processCaptureResult or
75     * ICameraDeviceCallback#returnStreamBuffers.
76     * Also, all buffer caches maintained by the offline session must be erased
77     * before the close call returns.
78     */
79    close();
80};
81