1/*
2 * Copyright (C) 2016 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.0;
18
19import IServiceNotification;
20import android.hidl.base@1.0::DebugInfo.Architecture;
21
22/**
23 * Manages all the hidl hals on a device.
24 *
25 * All examples in this file assume that there is one service registered with
26 * the service manager, "android.hidl.manager@1.0::IServiceManager/manager"
27 *
28 * Terminology:
29 *   Package: "android.hidl.manager"
30 *   Major version: "1"
31 *   Minor version: "0"
32 *   Version: "1.0"
33 *   Interface name: "IServiceManager"
34 *   Fully-qualified interface name: "android.hidl.manager@1.0::IServiceManager"
35 *   Instance name: "manager"
36 *   Fully-qualified instance name: "android.hidl.manager@1.0::IServiceManager/manager"
37 */
38interface IServiceManager {
39
40    /**
41     * Retrieve an existing service that supports the requested version.
42     *
43     * WARNING: This function is for libhidl/HwBinder use only. You are likely
44     * looking for 'IMyInterface::getService("name")' instead.
45     *
46     * @param iface    Fully-qualified interface name.
47     * @param name     Instance name. Same as in IServiceManager::add.
48     *
49     * @return service Handle to requested service, same as provided in
50     *                 IServiceManager::add. Will be nullptr if not available.
51     */
52    get(string fqName, string name) generates (interface service);
53
54    /**
55     * Register a service. The service manager must retrieve the (inherited)
56     * interfaces that this service implements, and register them along with
57     * the service.
58     *
59     * Each interface must have its own namespace for instance names. If you
60     * have two unrelated interfaces IFoo and IBar, it must be valid to call:
61     *
62     * add("my_instance", foo); // foo implements IFoo
63     * add("my_instance", bar); // bar implements IBar
64     *
65     * WARNING: This function is for libhidl/HwBinder use only. You are likely
66     * looking for 'INTERFACE::registerAsService("name")' instead.
67     *
68     * @param name           Instance name. Must also be used to retrieve service.
69     * @param service        Handle to registering service.
70     *
71     * @return success       Whether or not the service was registered.
72     *
73     */
74    add(string name, interface service) generates (bool success);
75
76    enum Transport : uint8_t {
77        EMPTY,
78        HWBINDER,
79        PASSTHROUGH,
80    };
81
82    /**
83     * Get the transport of a service.
84     *
85     * @param fqName     Fully-qualified interface name.
86     * @param name       Instance name. Same as in IServiceManager::add
87     *
88     * @return transport Transport of service if known.
89     */
90    getTransport(string fqName, string name) generates (Transport transport);
91
92    /**
93     * List all registered services. Must be sorted.
94     *
95     * @return fqInstanceNames List of fully-qualified instance names.
96     */
97    list() generates (vec<string> fqInstanceNames);
98
99    /**
100     * List all instances of a particular service. Must be sorted.
101     *
102     * @param fqName         Fully-qualified interface name.
103     *
104     * @return instanceNames List of instance names running the particular service.
105     */
106    listByInterface(string fqName) generates (vec<string> instanceNames);
107
108    /**
109     * Register for service notifications for a particular service. Must support
110     * multiple registrations.
111     *
112     * onRegistration must be sent out for all services which support the
113     * version provided in the fqName. For instance, if a client registers for
114     * notifications from "android.hardware.foo@1.0", they must also get
115     * notifications from "android.hardware.foo@1.1". If a matching service
116     * is already registered, onRegistration must be sent out with preexisting
117     * = true.
118     *
119     * @param fqName   Fully-qualified interface name.
120     * @param name     Instance name. If name is empty, notifications must be
121     *                 sent out for all names.
122     * @param callback Client callback to recieve notifications.
123     *
124     * @return success Whether or not registration was successful.
125     */
126    registerForNotifications(string fqName,
127                             string name,
128                             IServiceNotification callback)
129        generates (bool success);
130
131    /**
132     * Special values for InstanceDebugInfo pids.
133     */
134    enum PidConstant : int32_t {
135        NO_PID = -1,
136    };
137
138    /**
139     * Returned object for debugDump().
140     */
141    struct InstanceDebugInfo {
142        string interfaceName;
143        string instanceName;
144        int32_t pid; // PidConstants:NO_PID if unavailable
145        vec<int32_t> clientPids;
146        Architecture arch;
147    };
148
149    /**
150     * Similar to list, but contains more information for each instance.
151     * @return info a vector where each item contains debug information for each
152     *         instance.
153     */
154    debugDump() generates (vec<InstanceDebugInfo> info);
155
156    /**
157     * When the passthrough service manager returns a service via
158     * get(string, string), it must dispatch a registerPassthroughClient call
159     * to the binderized service manager to indicate the current process has
160     * called get(). Binderized service manager must record this PID, which can
161     * be retrieved via debugDump.
162     */
163    registerPassthroughClient(string fqName, string name);
164};
165