c2/1.0/IComponentStore.hal

/*
 * Copyright (C) 2018 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 hardware.google.media.c2@1.0;

import android.hardware.media.bufferpool@1.0::IClientManager;
import IComponentInterface;
import IComponentListener;
import IComponent;
import IConfigurable;
import IInputSurface;

interface IComponentStore extends IConfigurable {

    /**
     * Creates a component by name.
     *
     * This method must return within 100ms.
     *
     * @param name Name of the component to create. This should match one of the
     *     names returned by listComponents().
     * @param listener The component listener to use for the component.
     * @param pool The buffer pool client manager of the component listener.
     *     This must be null if the listener process does not own a buffer pool.
     * @return status Status of the call, which may be
     *   - OK        - The component was created successfully.
     *   - NOT_FOUND - There is no component with the given name.
     *   - NO_MEMORY - Not enough memory to create the component.
     *   - TIMED_OUT - The component could not be created within the time limit.
     *                 (unexpected)
     *   - CORRUPTED - Some unknown error prevented the creation of the
     *                 component. (unexpected)
     * @return comp The created component if `Status = OK`.
     */
    createComponent(
            string name,
            IComponentListener listener,
            IClientManager pool
        ) generates (
            Status status,
            IComponent comp
        );

    /**
     * Creates a component interface by name.
     *
     * This method must return within 100ms.
     *
     * @param name Name of the component interface to create. This should match
     *     one of the names returned by listComponents().
     * @return status Status of the call, which may be
     *   - OK        - The component interface was created successfully.
     *   - NOT_FOUND - There is no component interface with the given name.
     *   - NO_MEMORY - Not enough memory to create the component interface.
     *   - TIMED_OUT - The component interface could not be created within the
     *                 time limit. (unexpected)
     *   - CORRUPTED - Some unknown error prevented the creation of the
     *                 component interface. (unexpected)
     * @return compIntf The created component interface if `Status = OK`.
     */
    createInterface(
            string name
        ) generates (
            Status status,
            IComponentInterface compIntf
        );

    /**
     * Component traits.
     */
    struct ComponentTraits {
        /**
         * Name of the component.
         */
        string name;

        enum Domain : uint32_t {
            AUDIO,
            VIDEO,
            OTHER = 0xffffffff,
        };
        /**
         * Component domain. The framework may not recognize `OTHER`.
         */
        Domain domain;
        /**
         * If #domain is `OTHER`, #domainOther can be used to provide additional
         * information. Otherwise, #domainOther is ignored. The framework may
         * not inspect this value.
         */
        uint32_t domainOther;

        enum Kind : uint32_t {
            DECODER,
            ENCODER,
            OTHER = 0xffffffff,
        };
        /**
         * Component kind. The framework may not recognize `OTHER`.
         */
        Kind kind;
        /**
         * If #kind is `OTHER`, #kindOther can be used to provide additional
         * information. Otherwise, #kindOther is ignored. The framework may not
         * inspect this value.
         */
        uint32_t kindOther;

        /**
         * Rank used by MediaCodecList to determine component ordering. Lower
         * value means higher priority.
         */
        uint32_t rank;

        /**
         * Media type.
         */
        string mediaType;

        /**
         * Aliases for component name for backward compatibility.
         *
         * \note Multiple components can have the same alias (but not the same
         * component name) as long as their media types differ.
         */
        vec<string> aliases;
    };

    /**
     * Returns the list of components supported by this component store.
     *
     * This method must return within 500ms.
     *
     * @return traits List of component traits for all components supported by this store in no
     * particular order.
     */
    listComponents() generates (vec<ComponentTraits> traits);

    /**
     * Creates a persistent input surface that can be used as an input surface
     * for any IComponent instance
     *
     * This method must return within 100ms.
     *
     * @return surface A persistent input surface
     */
    createInputSurface() generates (IInputSurface surface);

    /**
     * Returns a list of StructDescriptor object for a set of requested
     * structures that this store is aware of.
     *
     * This operation must be performed at best effort, e.g. the component
     * store must simply ignore all struct indices that it is not aware of.
     *
     * @param indices struct indices to return des
     * @return status Status of the call, which may be
     *   - OK        - The operation completed successfully.
     *   - NOT_FOUND - Some indices were not known.
     *   - NO_MEMORY - Not enough memory to complete this method.
     * @return structs List of StructDescriptor objects.
     */
    getStructDescriptors(
            vec<ParamIndex> indices
        ) generates (
            Status status,
            vec<StructDescriptor> structs
        );

    /**
     * Returns information required for using BufferPool API in buffer passing.
     * If the returned pool is not null, the client can call registerSender() to
     * register its IAccessor instance, hence allowing the client to send
     * buffers to components hosted by this process.
     *
     * @return pool If the component store supports receiving buffers via
     *     BufferPool API, \p pool must be a valid `IClientManager` instance.
     *     Otherwise, \p pool must be null.
     */
    getPoolClientManager(
        ) generates (
            IClientManager pool
        );

    /**
     * The store must copy the contents of \p src into \p dst without changing
     * the format of \p dst.
     *
     * @param src Source buffer.
     * @param dst Destination buffer.
     * @return status Status of the call, which may be
     *   - OK        - The copy is successful.
     *   - CANNOT_DO - \p src and \p dst are not compatible.
     *   - REFUSED   - No permission to copy.
     *   - CORRUPTED - The copy cannot be done. (unexpected)
     */
    copyBuffer(Buffer src, Buffer dst) generates (Status status);

};