1 /* 2 * Copyright (c) 2024 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 Location 18 * @{ 19 * 20 * @brief Provide functions for querying the status of location switch, starting and stopping locating. 21 * @since 13 22 */ 23 /** 24 * @file oh_location.h 25 * @kit LocationKit 26 * @brief Define interfaces for querying location switch status, starting locating, and stopping locating. 27 * @library libohlocation.so 28 * @syscap SystemCapability.Location.Location.Core 29 * @since 13 30 */ 31 32 #ifndef OH_LOCATION_H 33 #define OH_LOCATION_H 34 35 #include "oh_location_type.h" 36 37 #ifdef __cplusplus 38 extern "C" { 39 #endif 40 41 /** 42 * @brief Check whether the location switch is enabled. 43 * 44 * @param enabled - It is a boolean pointer used to receive location switch status values.\n 45 * Equal to true indicates that the location switch is turned on, false indicates that\n 46 * the location switch is turned off.\n 47 * The caller needs to pass in a non empty boolean pointer, otherwise an error will be returned.\n 48 * @return Location functions result code.\n 49 * For a detailed definition, please refer to {@link Location_ResultCode}.\n 50 * {@link LOCAION_SUCCESS} Successfully obtained the location switch status.\n 51 * {@link LOCATION_INVALID_PARAM} The input parameter enabled is a null pointer.\n 52 * {@link LOCATION_SERVICE_UNAVAILABLE} Abnormal startup of location services.\n 53 * @since 13 54 */ 55 Location_ResultCode OH_Location_IsLocatingEnabled(bool* enabled); 56 57 /** 58 * @brief Start locating and subscribe location changed. 59 * 60 * @param requestConfig - Pointer to the locating request parameters.\n 61 * For details, see {@link Location_RequestConfig}.\n 62 * You can use {@link OH_Location_CreateRequestConfig} to create an instance.\n 63 * @return Location functions result code.\n 64 * For a detailed definition, please refer to {@link Location_ResultCode}.\n 65 * {@link LOCAION_SUCCESS} Successfully start locating.\n 66 * {@link LOCATION_INVALID_PARAM} The input parameter requestConfig is a null pointer.\n 67 * {@link LOCATION_PERMISSION_DENIED} Permission verification failed. The application does not have the\n 68 * permission required to call the API.\n 69 * {@link LOCATION_NOT_SUPPORTED} Capability not supported.\n 70 * Failed to call function due to limited device capabilities.\n 71 * {@link LOCATION_SERVICE_UNAVAILABLE} Abnormal startup of location services.\n 72 * {@link LOCATION_SWITCH_OFF} The location switch is off.\n 73 * @permission ohos.permission.APPROXIMATELY_LOCATION 74 * @since 13 75 */ 76 Location_ResultCode OH_Location_StartLocating(const Location_RequestConfig* requestConfig); 77 78 /** 79 * @brief Stop locating and unsubscribe location changed. 80 * 81 * @param requestConfig - Pointer to the locating request parameters.\n 82 * For details, see {@link Location_RequestConfig}.\n 83 * This parameter needs to be the same as the requestConfig pointer passed in\n 84 * {@link OH_Location_StartLocating}.\n 85 * @return Location functions result code.\n 86 * For a detailed definition, please refer to {@link Location_ResultCode}.\n 87 * {@link LOCAION_SUCCESS} Successfully stop locationg.\n 88 * {@link LOCATION_INVALID_PARAM} 1.The input parameter is a null pointer.\n 89 * 2.Different from the requestConfig pointer passed from {@link OH_Location_StartLocating}.\n 90 * {@link LOCATION_PERMISSION_DENIED} Permission verification failed. The application does not have the\n 91 * permission required to call the API.\n 92 * {@link LOCATION_NOT_SUPPORTED} Capability not supported.\n 93 * Failed to call function due to limited device capabilities.\n 94 * {@link LOCATION_SERVICE_UNAVAILABLE} Possible reasons: 1. Abnormal startup of location services.\n 95 * {@link LOCATION_SWITCH_OFF} The location switch is off.\n 96 * @permission ohos.permission.APPROXIMATELY_LOCATION 97 * @since 13 98 */ 99 Location_ResultCode OH_Location_StopLocating(const Location_RequestConfig* requestConfig); 100 #ifdef __cplusplus 101 } 102 #endif 103 /** @} */ 104 #endif // OH_LOCATION_H