xref: /drivers/interface/location/lpfence/cellbatching/v1_0/ICellbatchingInterface.idl

/*
 * Copyright (c) 2023 Huawei Device Co., Ltd.
 * 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.
 */

 /**
 * @addtogroup HdiLpfenceCellbatching
 * @{
 *
 * @brief Provides APIs for recording base station trajectory data for low-power fence services.
 *
 * You can use the APIs to cache and flush the base station data received.
 * The cell batching feature is used to determine the user's activity area based on the base station trajectory data received by the device, so as to further provide service information.
 *
 * @since 4.0
 * @version 1.0
 */

/**
 * @file ICellbatchingInterface.idl
 *
 * @brief Declares the APIs provided by the cell batching module. You can use the APIs to enable or disable the cell batching feature and obtain the base station trajectory data.
 *
 * @since 4.0
 * @version 1.0
 */

/**
 * @brief Declares the path of the cell batching interface package.
 *
 * @since 4.0
 */
package ohos.hdi.location.lpfence.cellbatching.v1_0;

/**
 * @brief Imports data types of the cell batching module.
 *
 * @since 4.0
 */
import ohos.hdi.location.lpfence.cellbatching.v1_0.CellbatchingTypes;

/**
 * @brief Imports callback definitions of the cell batching module.
 *
 * @since 4.0
 */
import ohos.hdi.location.lpfence.cellbatching.v1_0.ICellbatchingCallback;

/**
 * @brief Defines APIs for basic cell batching operations.
 *
 * You can use the APIs to register or unregister a callback, enable or disable the cell batching feature, and obtain the base station trajectory data.
 */
interface ICellbatchingInterface {
    /**
     * @brief Registers a callback.
     *
     * Before enabling the cell batching feature, you need to register a callback to report the base station trajectory data obtained by an app.
     *
     * @param callbackObj Indicates the callback to register, which needs to be registered only once. For details, see {@link ICellbatchingCallback}.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a negative value if the operation fails.
     *
     * @since 4.0
     * @version 1.0
     */
    RegisterCellBatchingCallback([in] ICellbatchingCallback callbackObj);

    /**
     * @brief Unregisters a callback.
     *
     * When the cell batching feature is no longer required or the registered callback needs to be changed, you need to unregister the callback.
     *
     * @param callbackObj Indicates the callback to unregister, which needs to be unregistered only once. For details, see {@link ICellbatchingCallback}.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a negative value if the operation fails.
     *
     * @since 4.0
     * @version 1.0
     */
    UnregisterCellBatchingCallback([in] ICellbatchingCallback callbackObj);

    /**
     * @brief Enables or disables the cell batching feature.
     *
     * After the cell batching feature is enabled, the device caches the base station data received. If the data received is the same as the data previously received, the device does not cache the data.
     *
     * @param req Indicates the parameters used for setting the cell batching feature. For details, see {@link CellbatchingRequest}.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a negative value if the operation fails.
     *
     * @since 4.0
     * @version 1.0
     */
    CellbatchingSwitch([in] struct CellbatchingRequest req);

    /**
     * @brief Flushes the base station trajectory data.
     *
     * The amount of data flushed varies depending on the buffer size of the device and the amount of base station data received by the device. After the data is flushed, the cached base station data will be cleared.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a negative value if the operation fails.
     *
     * @since 4.0
     * @version 1.0
     */
    FlushCellbatching();
}
/** @} */