transport/manager/1.0/IServiceManager.hal

/*
 * Copyright (C) 2016 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package android.hidl.manager@1.0;

import IServiceNotification;

/**
 * Manages all the hidl hals on a device.
 *
 * All examples in this file assume that there is one service registered with
 * the service manager, "android.hidl.manager@1.0::IServiceManager/manager"
 *
 * Terminology:
 *   Package: "android.hidl.manager"
 *   Major version: "1"
 *   Minor version: "0"
 *   Version: "1.0"
 *   Interface name: "IServiceManager"
 *   Fully-qualified interface name: "android.hidl.manager@1.0::IServiceManager"
 *   Instance name: "manager"
 *   Fully-qualified instance name: "android.hidl.manager@1.0::IServiceManager/manager"
 */
interface IServiceManager {

    /**
     * Retrieve an existing service that supports the requested version.
     *
     * WARNING: This function is for libhidl/HwBinder use only. You are likely
     * looking for 'IMyInterface::getService("name")' instead.
     *
     * @param iface    Fully-qualified interface name.
     * @param name     Instance name. Same as in IServiceManager::add.
     *
     * @return service Handle to requested service, same as provided in
     *                 IServiceManager::add. Will be nullptr if not available.
     */
    get(string fqName, string name) generates (interface service);

    /**
     * Register a service. The service manager must be registered as all of the
     * services that it inherits from.
     *
     * WARNING: This function is for libhidl/HwBinder use only. You are likely
     * looking for 'INTERFACE::registerAsService("name")' instead.
     *
     * @param interfaceChain List of fully-qualified interface names. The first
     *                       must be the actual interface name. Subsequent names must
     *                       follow the inheritance hierarchy of the interface.
     * @param name           Instance name. Must also be used to retrieve service.
     * @param service        Handle to registering service.
     *
     * @return success       Whether or not the service was registered.
     *
     */
    add(vec<string> interfaceChain, string name, interface service)
        generates (bool success);

    /**
     * List all registered services. Must be sorted.
     *
     * @return fqInstanceNames List of fully-qualified instance names.
     */
    list() generates (vec<string> fqInstanceNames);

    /**
     * List all instances of a particular service. Must be sorted.
     *
     * @param fqName         Fully-qualified interface name.
     *
     * @return instanceNames List of instance names running the particular service.
     */
    listByInterface(string fqName) generates (vec<string> instanceNames);

    /**
     * Register for service notifications for a particular service. Must support
     * multiple registrations.
     *
     * onRegistration must be sent out for all services which support the
     * version provided in the fqName. For instance, if a client registers for
     * notifications from "android.hardware.foo@1.0", they must also get
     * notifications from "android.hardware.foo@1.1". If a matching service
     * is already registered, onRegistration must be sent out with preexisting
     * = true.
     *
     * @param fqName   Fully-qualified interface name.
     * @param name     Instance name. If name is empty, notifications must be
     *                 sent out for all names.
     * @param callback Client callback to recieve notifications.
     *
     * @return success Whether or not registration was successful.
     */
    registerForNotifications(string fqName,
                             string name,
                             IServiceNotification callback)
        generates (bool success);

    struct InstanceDebugInfo {
        string interfaceName;
        string instanceName;
        // negative values means N/A.
        int32_t pid;
        // 0 means N/A.
        uint64_t ptr;
    };

    /*
     * Similar to list, but contains more information for each instance.
     * @return info a vector where each item contains debug information for each
     *         instance.
     */
    debugDump() generates (vec<InstanceDebugInfo> info);
};