IServiceManager.hal revision 9a22d1db4dca94f205e25105a3d822dd179d3b53 
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;
20
21/**
22 * Manages all the hidl hals on a device.
23 *
24 * All examples in this file assume that there is one service registered with
25 * the service manager, "android.hidl.manager@1.0::IServiceManager/manager"
26 *
27 * Terminology:
28 *   Package: "android.hidl.manager"
29 *   Major version: "1"
30 *   Minor version: "0"
31 *   Version: "1.0"
32 *   Interface name: "IServiceManager"
33 *   Fully-qualified interface name: "android.hidl.manager@1.0::IServiceManager"
34 *   Instance name: "manager"
35 *   Fully-qualified instance name: "android.hidl.manager@1.0::IServiceManager/manager"
36 */
37interface IServiceManager {
38
39    /**
40     * Retrieve an existing service that supports the requested version.
41     *
42     * WARNING: This function is for libhidl/HwBinder use only. You are likely
43     * looking for 'IMyInterface::getService("name")' instead.
44     *
45     * @param iface    Fully-qualified interface name.
46     * @param name     Instance name. Same as in IServiceManager::add.
47     *
48     * @return service Handle to requested service, same as provided in
49     *                 IServiceManager::add. Will be nullptr if not available.
50     */
51    get(string fqName, string name) generates (interface service);
52
53    /**
54     * Register a service. The service manager must be registered as all of the
55     * services that it inherits from.
56     *
57     * WARNING: This function is for libhidl/HwBinder use only. You are likely
58     * looking for 'INTERFACE::registerAsService("name")' instead.
59     *
60     * @param interfaceChain List of fully-qualified interface names. The first
61     *                       must be the actual interface name. Subsequent names must
62     *                       follow the inheritance hierarchy of the interface.
63     * @param name           Instance name. Must also be used to retrieve service.
64     * @param service        Handle to registering service.
65     *
66     * @return success       Whether or not the service was registered.
67     *
68     */
69    add(vec<string> interfaceChain, string name, interface service)
70        generates (bool success);
71
72    /**
73     * List all registered services. Must be sorted.
74     *
75     * @return fqInstanceNames List of fully-qualified instance names.
76     */
77    list() generates (vec<string> fqInstanceNames);
78
79    /**
80     * List all instances of a particular service. Must be sorted.
81     *
82     * @param fqName         Fully-qualified interface name.
83     *
84     * @return instanceNames List of instance names running the particular service.
85     */
86    listByInterface(string fqName) generates (vec<string> instanceNames);
87
88    /**
89     * Register for service notifications for a particular service. Must support
90     * multiple registrations.
91     *
92     * onRegistration must be sent out for all services which support the
93     * version provided in the fqName. For instance, if a client registers for
94     * notifications from "android.hardware.foo@1.0", they must also get
95     * notifications from "android.hardware.foo@1.1". If a matching service
96     * is already registered, onRegistration must be sent out with preexisting
97     * = true.
98     *
99     * @param fqName   Fully-qualified interface name.
100     * @param name     Instance name. If name is empty, notifications must be
101     *                 sent out for all names.
102     * @param callback Client callback to recieve notifications.
103     *
104     * @return success Whether or not registration was successful.
105     */
106    registerForNotifications(string fqName,
107                             string name,
108                             IServiceNotification callback)
109        generates (bool success);
110
111    struct InstanceDebugInfo {
112        string interfaceName;
113        string instanceName;
114        uint64_t refCount;
115    };
116
117    /*
118     * Similar to list, but contains more information for each instance.
119     * @return info a vector where each item contains debug information for each
120     *         instance.
121     */
122    debugDump() generates (vec<InstanceDebugInfo> info);
123};
124