1/* 2 * Copyright (c) 2023 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup HdiLpfenceGeofence 18 * @{ 19 * 20 * @brief Provides geofence APIs for the low-power fence service. 21 * 22 * 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. 23 * 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. 24 * 25 * @since 4.0 26 * @version 1.0 27 */ 28 29/** 30 * @file IGeofenceIntf.idl 31 * 32 * @brief Declares the APIs provided by the geofence module. These APIs can be used to add multiple types of geofences, remove geofences, obtain the relationship between a geofence and a device, obtain device geographical location, and send base station offline database data. 33 * 34 * @since 4.0 35 * @version 1.0 36 */ 37 38/** 39 * @brief Declares the path of the geofence module interface package. 40 * 41 * @since 4.0 42 */ 43package ohos.hdi.location.lpfence.geofence.v1_0; 44 45/** 46 * @brief Imports data types of the geofence module. 47 * 48 * @since 4.0 49 */ 50import ohos.hdi.location.lpfence.geofence.v1_0.GeofenceTypes; 51 52/** 53 * @brief Imports callback definitions of the geofence module. 54 * 55 * @since 4.0 56 */ 57import ohos.hdi.location.lpfence.geofence.v1_0.IGeofenceCallback; 58 59/** 60 * @brief Provides APIs for basic geofence operations. 61 * 62 * You can use the APIs to register or unregister a callback, add circle or polygon geofences, remove geofences, obtain the relationship between a geofence and a device, obtain device geographical location, and send offline database data of base stations. 63 */ 64interface IGeofenceIntf { 65 /** 66 * @brief Registers a callback. 67 * 68 * 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. 69 * 70 * @param callbackObj Indicates the callback to register, which needs to be registered only once. For details, see {@link IGeofenceCallback}. 71 * 72 * @return Returns <b>0</b> if the operation is successful. 73 * @return Returns a negative value if the operation fails. 74 * 75 * @since 4.0 76 * @version 1.0 77 */ 78 RegisterGeofenceCallback([in] IGeofenceCallback callbackObj); 79 80 /** 81 * @brief Unregisters a callback. 82 * 83 * When the geofencing feature is no longer required or the registered callback needs to be changed, you need to unregister the callback. 84 * 85 * @param callbackObj Indicates the callback to unregister, which needs to be unregistered only once. For details, see {@link IGeofenceCallback}. 86 * 87 * @return Returns <b>0</b> if the operation is successful. 88 * @return Returns a negative value if the operation fails. 89 * 90 * @since 4.0 91 * @version 1.0 92 */ 93 UnregisterGeofenceCallback([in] IGeofenceCallback callbackObj); 94 95 /** 96 * @brief Adds circle geofences. 97 * 98 * Multiple circle geofences can be added at a time. 99 * 100 * @param circleGeofences Indicates the circle geofences to add. For details, see {@link GeofenceCircleRequest}. 101 * 102 * @return Returns <b>0</b> if the operation is successful. 103 * @return Returns a negative value if the operation fails. 104 * 105 * @since 4.0 106 * @version 1.0 107 */ 108 AddCircleGeofences([in] struct GeofenceCircleRequest[] circleGeofences); 109 110 /** 111 * @brief Adds polygon geofences. 112 * 113 * Multiple polygon geofences can be added at a time. 114 * 115 * @param polygonGeofences Indicates the polygon geofences to add. For details, see {@link GeofencePolygonRequest}. 116 * 117 * @return Returns <b>0</b> if the operation is successful. 118 * @return Returns a negative value if the operation fails. 119 * 120 * @since 4.0 121 * @version 1.0 122 */ 123 AddPolygonGeofences([in] struct GeofencePolygonRequest[] polygonGeofences); 124 125 /** 126 * @brief Removes geofences. 127 * 128 * Multiple geofences can be removed at a time. 129 * 130 * @param geofenceId Indicates the IDs of the geofences to remove. For details, see {@link GeofenceCircleRequest} and {@link GeofencePolygonRequest}. 131 * 132 * @return Returns <b>0</b> if the operation is successful. 133 * @return Returns a negative value if the operation fails. 134 * 135 * @since 4.0 136 * @version 1.0 137 */ 138 RemoveGeofences([in] int[] geofenceId); 139 140 /** 141 * @brief Obtains the relationship between a geofence and this device. 142 * 143 * For details about the relationships between a device and a geofence, see {@link GeofenceTransition}. 144 * 145 * @param geofenceId Indicates the ID of the geofence. 146 * 147 * @return Returns the relationship information obtained if the operation is successful. For details, see {@link GeofenceTransition}. 148 * @return Returns a negative value if the operation fails. 149 * 150 * @since 4.0 151 * @version 1.0 152 */ 153 GetGeofenceStatus([in] int geofenceId); 154 155 /** 156 * @brief Obtains the latest location information. 157 * 158 * The location information is reported by the {@link OnGetCurrentLocationCb} callback. 159 * 160 * @return Returns <b>0</b> if the operation is successful. 161 * @return Returns a negative value if the operation fails. 162 * 163 * @since 4.0 164 * @version 1.0 165 */ 166 GetGeofenceLocation(); 167 168 /** 169 * @brief Obtains geofence information, including the number of geofences supported by and added for this device. 170 * 171 * The geofence information is returned by the {@link OnGetWifenceSizeCb} callback. 172 * 173 * @return Returns <b>0</b> if the operation is successful. 174 * @return Returns a negative value if the operation fails. 175 * 176 * @since 4.0 177 * @version 1.0 178 */ 179 GetGeofenceSize(); 180 181 /** 182 * @brief Sends the base station offline database data. 183 * 184 * If the offline database data is successfully requested, the upper-layer service delivers the data through this API. 185 * 186 * @param dbData Indicates the offline database data to send. For details, see {@link OfflineDb}. 187 * @param cellType Indicates the generation of the mobile communication technologies used by the cell where the device resides. For details, see {@link GeofenceCellType}. 188 * 189 * @return Returns <b>0</b> if the operation is successful. 190 * @return Returns a negative value if the operation fails. 191 * 192 * @since 4.0 193 * @version 1.0 194 */ 195 SendCellOfflineDb([in] struct OfflineDb dbData, 196 [in] int cellType); 197} 198/** @} */ 199