1/*
2 * Copyright (C) 2018 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 android.hidl.manager@1.2;
18
19import @1.1::IServiceManager;
20
21import IClientCallback;
22
23interface IServiceManager extends @1.1::IServiceManager {
24    /**
25     * Adds a callback that must be called when the specified server has no clients.
26     *
27     * If the service has clients at the time of registration, the callback is called with
28     * hasClients true. After that, it is called based on the changes in clientele.
29     *
30     * @param fqName Fully-qualified interface name (used to register)
31     * @param name Instance name (of the registered service)
32     * @param server non-null service waiting to have no clients (previously registered)
33     * @param cb non-null callback to call when there are no clients
34     * @return success
35     *     true on success
36     *     false if either
37     *      - the server or cb parameters are null
38     *      - this is called by a process other than the server process
39     */
40    registerClientCallback(string fqName,
41                           string name,
42                           interface server,
43                           IClientCallback cb)
44        generates (bool success);
45
46    /**
47     * Removes a callback previously registered with registerClientCallback.
48     *
49     * If server is null, then this must remove the cb from all matching services.
50     *
51     * @param server service registered with registerClientCallback
52     * @param cb non-null callback to remove
53     * @return success
54     *     true if the server(s) have been removed
55     *     false if cb is null or if the client callback or server could not be found
56     */
57    unregisterClientCallback(interface server, IClientCallback cb) generates (bool success);
58
59    /**
60     * Exactly the same as @1.0::IServiceManager.add, but the interfaceChain of the service is
61     * provided in the same call.
62     *
63     * @param name Instance name. Must also be used to retrieve service.
64     * @param service Handle to registering service.
65     * @param chain service->interfaceChain
66     *
67     * @return success Whether or not the service was registered.
68     */
69    addWithChain(string name, interface service, vec<string> chain) generates (bool success);
70
71    /**
72     * List all instances of a particular service from the manifest. Must be sorted. These HALs
73     * may not be started if they are lazy.
74     *
75     * See also @1.0::IServiceManager's listByInterface function.
76     *
77     * @param fqName Fully-qualified interface name.
78     *
79     * @return instanceNames List of instance names running the particular service.
80     */
81    listManifestByInterface(string fqName) generates (vec<string> instanceNames);
82
83    /**
84     * Unregisters a service if there are no clients for it. This must only unregister the
85     * service if it is called from the same process that registered the service.
86     *
87     * This unregisters all instances of the service, even if they are under a different instance
88     * name.
89     *
90     * Recommended usage is when creating a lazy process, try unregistering when IClientCallback's
91     * onClients(*, false) is called. If this unregister is successful, then it is safe to exit. If
92     * it is unsuccessful, then you can assume a client re-associated with the server. If a process
93     * has multiple servers, and only some succeed in unregistration, then the unregistered services
94     * can be re-registered.
95     *
96     * See also addWithChain and @1.0::IServiceManager's add.
97     *
98     * @param fqName Fully-qualified interface name.
99     * @param name Instance name.
100     * @param service Handle to registering service.
101     *
102     * @return success Whether the service was successfully unregistered.
103     */
104    tryUnregister(string fqName, string name, interface service) generates (bool success);
105};
106