xref: /drivers/interface/location/lpfence/geofence/v1_0/IGeofenceCallback.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 HdiLpfenceGeofence
 * @{
 *
 * @brief Provides geofence APIs for the low-power fence service.
 *
 * You can use the APIs to add circle or polygon geofences, remove geofences, obtain relationship between a device and a geofence, and obtain the geographical location of a device. The geofence module can work continuously even when the AP is in sleep mode.
 * The geofencing feature is used to determine whether a device reaches a specific geographical location, so that subsequent services, such as switching to the appropriate access card and pushing customized messages, can be implemented.
 *
 * @since 4.0
 * @version 1.0
 */

/**
 * @file IGeofenceCallback.idl
 *
 * @brief Defines the callbacks of the geofence module.
 *
 * @since 4.0
 * @version 1.0
 */

/**
 * @brief Declares the path of the geofence module interface package.
 *
 * @since 4.0
 */
package ohos.hdi.location.lpfence.geofence.v1_0;

/**
 * @brief Imports data types of the geofence module.
 *
 * @since 4.0
 */
import ohos.hdi.location.lpfence.geofence.v1_0.GeofenceTypes;

/**
 * @brief Defines the callback of the geofence module.
 *
 * Before enabling the geofencing feature, you need to register the callback to report the geofence status when the relationship between a geofence and a device changes.
 * For details, see {@link ICellfenceInterface}.
 *
 * @since 4.0
 */
[callback] interface IGeofenceCallback {
    /**
     * @brief Called to report the result when a geofence is added.
     *
     *
     *
     * @param res Indicates the result of the geofence addition. For details, see {@link GeofenceResult}.
     *
     * @return Returns <b>0</b> if the callback is invoked successfully.
     * @return Returns a negative value if the callback fails to be invoked.
     *
     * @since 4.0
     */
    OnGeofenceAddResultCb([in] struct GeofenceResult[] res);

    /**
     * @brief Called to report the result when a geofence is removed.
     *
     *
     *
     * @param res Indicates the result of the geofence removal. For details, see {@link GeofenceResult}.
     *
     * @return Returns <b>0</b> if the callback is invoked successfully.
     * @return Returns a negative value if the callback fails to be invoked.
     *
     * @since 4.0
     */
    OnGeofenceRemoveResultCb([in] struct GeofenceResult[] res);

    /**
     * @brief Called when the geofence status changes.
     *
     * This callback will be invoked to report the geofence status when the relationship between a device and a geofence changes.
     *
     * @param geofenceId Indicates the ID of the geofence.
     * @param location Indicates the latest location information. For details, see {@link GeoLocationInfo}.
     * @param transition Indicates the new geofence status. For details, see {@link GeofenceTransition}.
     * @param timestamp Indicates the timestamp when the geofence status changes.
     *
     * @return Returns <b>0</b> if the callback is invoked successfully.
     * @return Returns a negative value if the callback fails to be invoked.
     *
     * @since 4.0
     */
    OnGeofenceTransitionCb([in] int geofenceId,
                           [in] struct GeoLocationInfo location,
                           [in] unsigned char transition,
                           [in] long timestamp);

    /**
     * @brief Called to report the geofence information of a device.
     *
     *
     *
     * @param size Indicates the geofence usage information. For details, {@link GeofenceSize}.
     *
     * @return Returns <b>0</b> if the callback is invoked successfully.
     * @return Returns a negative value if the callback fails to be invoked.
     *
     * @since 4.0
     */
    OnGetGeofenceSizeCb([in] struct GeofenceSize size);

    /**
     * @brief Called to report the base station offline database data.
     *
     *
     *
     * @param req Indicates the base station offline database data to request. For details, see {@link RequestCellDb}.
     *
     * @return Returns <b>0</b> if the callback is invoked successfully.
     * @return Returns a negative value if the callback fails to be invoked.
     *
     * @since 4.0
     */
    OnGeofenceRequestCellDb([in] struct RequestCellDb req);

    /**
     * @brief Called to report the latest device location information.
     *
     *
     *
     * @param locSource Indicates the source of the location information. For details, see {@link GeofenceLocSource}.
     * @param location Indicates the latest location information. For details, see {@link GeoLocationInfo}.
     *
     * @return Returns <b>0</b> if the callback is invoked successfully.
     * @return Returns a negative value if the callback fails to be invoked.
     *
     * @since 4.0
     */
    OnGetCurrentLocationCb([in] int locSource,
                         [in] struct GeoLocationInfo location);

    /**
     * @brief Called when the low-power fence service is reset.
     *
     *
     *
     * @return Returns <b>0</b> if the callback is invoked successfully.
     * @return Returns a negative value if the callback fails to be invoked.
     *
     * @since 4.0
     */
    OnGeofenceReset();
}
/** @} */