IServiceManager.hal revision 705e5da46d6f6fa5a2177afe460304668bd9102c 
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 be registered as all of the
56     * services that it inherits from.
57     *
58     * WARNING: This function is for libhidl/HwBinder use only. You are likely
59     * looking for 'INTERFACE::registerAsService("name")' instead.
60     *
61     * @param interfaceChain List of fully-qualified interface names. The first
62     *                       must be the actual interface name. Subsequent names must
63     *                       follow the inheritance hierarchy of the interface.
64     * @param name           Instance name. Must also be used to retrieve service.
65     * @param service        Handle to registering service.
66     *
67     * @return success       Whether or not the service was registered.
68     *
69     */
70    add(vec<string> interfaceChain, string name, interface service)
71        generates (bool success);
72
73    /**
74     * List all registered services. Must be sorted.
75     *
76     * @return fqInstanceNames List of fully-qualified instance names.
77     */
78    list() generates (vec<string> fqInstanceNames);
79
80    /**
81     * List all instances of a particular service. Must be sorted.
82     *
83     * @param fqName         Fully-qualified interface name.
84     *
85     * @return instanceNames List of instance names running the particular service.
86     */
87    listByInterface(string fqName) generates (vec<string> instanceNames);
88
89    /**
90     * Register for service notifications for a particular service. Must support
91     * multiple registrations.
92     *
93     * onRegistration must be sent out for all services which support the
94     * version provided in the fqName. For instance, if a client registers for
95     * notifications from "android.hardware.foo@1.0", they must also get
96     * notifications from "android.hardware.foo@1.1". If a matching service
97     * is already registered, onRegistration must be sent out with preexisting
98     * = true.
99     *
100     * @param fqName   Fully-qualified interface name.
101     * @param name     Instance name. If name is empty, notifications must be
102     *                 sent out for all names.
103     * @param callback Client callback to recieve notifications.
104     *
105     * @return success Whether or not registration was successful.
106     */
107    registerForNotifications(string fqName,
108                             string name,
109                             IServiceNotification callback)
110        generates (bool success);
111
112    /**
113     * Returned object for debugDump().
114     */
115    struct InstanceDebugInfo {
116        string interfaceName;
117        string instanceName;
118        vec<int32_t> clientPids;
119        Architecture arch;
120    };
121
122    /**
123     * Similar to list, but contains more information for each instance.
124     * @return info a vector where each item contains debug information for each
125     *         instance.
126     */
127    debugDump() generates (vec<InstanceDebugInfo> info);
128
129    /**
130     * When the passthrough service manager returns a service via
131     * get(string, string), it must dispatch a registerPassthroughClient call
132     * to the binderized service manager to indicate which process has called
133     * get. Binderized service manager must record this PID, which can
134     * be retrieved via debugDump.
135     */
136    oneway registerPassthroughClient(string fqName, string name, int32_t pid);
137};
138