Locator

java.lang.Object
- ohos.location.Locator

```
public class Locator
extends Object
```
Provides interfaces for initiating location requests, ending the location service, and obtaining the location result cached by the system.

从以下版本开始:

1

SystemCapability

SystemCapability.Location#LOCATION

字段概要

字段
限定符和类型	字段	说明
`static int`	`ERROR_PERMISSION_NOT_GRANTED`	Indicates that the location permission has not been granted when the application calls the `Locator` interface.
`static int`	`ERROR_SWITCH_UNOPEN`	Indicates that the location service has been disabled when the application calls the `Locator` interface.
`static int`	`LOCATION_SERVICE_SWITCH_OFF`	Indicates that the location service is disabled.
`static int`	`LOCATION_SERVICE_SWITCH_ON`	Indicates that the location service is enabled.
`static int`	`SESSION_START`	Indicates that the location request has been accepted by the system.
`static int`	`SESSION_STOP`	Indicates that the location request has finished.

构造器概要

构造器
构造器	说明
`Locator(Context context)`	A constructor used to create a `Locator` instance based on the specified context to implement the location service.
`Locator(AbilityInfo info)`	已过时。 This change is effective since API 3, some app may not create locator object in ablitity, Replaced by`Locator(Context context)`.

方法概要

所有方法实例方法具体方法
限定符和类型	方法	说明
`Location`	`getCachedLocation()`	Obtains the location information cached in the system.
`boolean`	`isLocationSwitchOn()`	Checks whether the location service is enabled.
`boolean`	`registerSwitchCallback(SwitchCallback callback)`	Registers a callback object for obtaining the location service status in real time.
`void`	`requestEnableLocation()`	Requests the user to enable the location service.
`void`	`requestOnce(RequestParam request, LocatorCallback callback)`	Sends a single location request to the system.
`void`	`startLocating(RequestParam request, LocatorCallback callback)`	Sends location requests to the system.
`void`	`stopLocating(LocatorCallback callback)`	Ends the location service.
`boolean`	`unregisterSwitchCallback(SwitchCallback callback)`	Deregisters the callback object used for obtaining the location service status.

从类继承的方法 java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- 字段详细资料
  - ERROR_PERMISSION_NOT_GRANTED
```
public static final int ERROR_PERMISSION_NOT_GRANTED
```
    Indicates that the location permission has not been granted when the application calls the Locator interface.
    The error is returned to the application through LocatorCallback.onErrorReport(int).
    
    从以下版本开始:
    
    1
    
    另请参阅:
    
    常量字段值
  - ERROR_SWITCH_UNOPEN
```
public static final int ERROR_SWITCH_UNOPEN
```
    Indicates that the location service has been disabled when the application calls the Locator interface.
    The error is returned to the application through LocatorCallback.onErrorReport(int).
    
    从以下版本开始:
    
    1
    
    另请参阅:
    
    常量字段值
  - LOCATION_SERVICE_SWITCH_OFF
```
public static final int LOCATION_SERVICE_SWITCH_OFF
```
    Indicates that the location service is disabled.
    The status is returned to the application through SwitchCallback.onSwitchChange(int).
    
    从以下版本开始:
    
    1
    
    另请参阅:
    
    常量字段值
  - LOCATION_SERVICE_SWITCH_ON
```
public static final int LOCATION_SERVICE_SWITCH_ON
```
    Indicates that the location service is enabled.
    The status is returned to the application through SwitchCallback.onSwitchChange(int).
    
    从以下版本开始:
    
    1
    
    另请参阅:
    
    常量字段值
  - SESSION_START
```
public static final int SESSION_START
```
    Indicates that the location request has been accepted by the system.
    The status is returned to the application through LocatorCallback.onStatusChanged(int).
    
    从以下版本开始:
    
    1
    
    另请参阅:
    
    常量字段值
  - SESSION_STOP
```
public static final int SESSION_STOP
```
    Indicates that the location request has finished.
    The status is returned to the application through LocatorCallback.onStatusChanged(int).
    
    从以下版本开始:
    
    1
    
    另请参阅:
    
    常量字段值
- 构造器详细资料
  - Locator
```
@Deprecated
public Locator(AbilityInfo info)
```
    已过时。 This change is effective since API 3, some app may not create locator object in ablitity, Replaced byLocator(Context context).
    
    A constructor used to create a Locator instance based on the specified ability information to implement the location service.
    
    参数:
    
    info - info Indicates the ability information, which is specified by AbilityInfo.
    
    从以下版本开始:
    
    1
  - Locator
```
public Locator(Context context)
```
    A constructor used to create a Locator instance based on the specified context to implement the location service.
    
    参数:
    
    context - Indicates the application context, which is specified by Context.
    
    从以下版本开始:
    
    3
- 方法详细资料
  - isLocationSwitchOn
```
public boolean isLocationSwitchOn()
```
    Checks whether the location service is enabled.
    
    返回:
    
    Returns true if the location service is enabled; returns false otherwise.
    
    从以下版本开始:
    
    1
  - requestEnableLocation
```
public void requestEnableLocation()
                           throws IllegalArgumentException
```
    Requests the user to enable the location service. When this method is called, the system will display a notification to the user.
    If the location service is already enabled, no operation is performed.
    
    抛出:
    
    IllegalArgumentException - Throws this exception if Locator constructed without ability context.
    
    从以下版本开始:
    
    3
  - startLocating
```
public void startLocating(RequestParam request,
                          LocatorCallback callback)
                   throws IllegalArgumentException
```
    Sends location requests to the system.
    The system starts the location service based on the input location request parameters and reports the location result to the application through the callback passed in this method.
    The system reports the location results to the application in real time until the application proactively stops the location service through stopLocating(ohos.location.LocatorCallback).
    To use this method, your application needs to apply for the ohos.permission.LOCATION permission from the user. If the location access permission has not been granted by the user when this method is called, the system returns ERROR_PERMISSION_NOT_GRANTED to the application through LocatorCallback.
    If the location service is disabled when this method is called, the system returns error code ERROR_SWITCH_UNOPEN through LocatorCallback.
    
    参数:
    
    request - Indicates the location request parameters.
    
    callback - Indicates the callback for reporting the location result.
    
    抛出:
    
    IllegalArgumentException - Throws this exception if the specified RequestParam object or the specified LocatorCallback object is null.
    
    从以下版本开始:
    
    1
    
    另请参阅:
    
    RequestParam, LocatorCallback
  - stopLocating
```
public void stopLocating(LocatorCallback callback)
                  throws IllegalArgumentException
```
    Ends the location service.
    The specified callback object must be the same as that provided to the system when the location request is initiated.Otherwise, ending the location service will fail.
    
    参数:
    
    callback - Specifies the callback object for returning the location result.
    
    抛出:
    
    IllegalArgumentException - Throws this exception if the specified LocatorCallback object is null.
    
    从以下版本开始:
    
    1
    
    另请参阅:
    
    LocatorCallback
  - requestOnce
```
public void requestOnce(RequestParam request,
                        LocatorCallback callback)
                 throws IllegalArgumentException
```
    Sends a single location request to the system.
    The system starts the location service based on the input location request parameters and reports the location result to the application through the callback passed in this method.
    This location request is automatically stopped after the system reports the location result. If the location cannot be completed within a reasonable amount of time due to environment issues, you can call stopLocating(ohos.location.LocatorCallback) to enable the application to proactively stop the location request.
    To use this method, your application needs to apply for the ohos.permission.LOCATION permission from the user. If the location access permission has not been granted by the user when this method is called, the system returns ERROR_PERMISSION_NOT_GRANTED to the application through LocatorCallback.
    If the location service is disabled when this method is called, the system returns error code ERROR_SWITCH_UNOPEN through LocatorCallback.
    
    参数:
    
    request - Indicates the location request parameters.
    
    callback - Indicates the callback for reporting the location result.
    
    抛出:
    
    IllegalArgumentException - Throws this exception if the specified RequestParam object or the specified LocatorCallback object is null.
    
    从以下版本开始:
    
    1
    
    另请参阅:
    
    RequestParam, LocatorCallback
  - getCachedLocation
```
public Location getCachedLocation()
                           throws SecurityException
```
    Obtains the location information cached in the system.
    You can call this method to obtain the cached location information if you do not need the real-time location data.
    To use this method, you need to apply for the ohos.permission.LOCATION permission from the user.
    
    返回:
    
    Returns the location information cached in the system; returns null if no location information has been cached.
    
    抛出:
    
    SecurityException - Throws this exception if your application is not granted the ohos.permission.LOCATION permission.
    
    从以下版本开始:
    
    1
    
    另请参阅:
    
    Location
  - registerSwitchCallback
```
public boolean registerSwitchCallback(SwitchCallback callback)
                               throws IllegalArgumentException
```
    Registers a callback object for obtaining the location service status in real time.
    
    参数:
    
    callback - Specifies the callback object for obtaining the location service status. The value must not be null.
    
    返回:
    
    Returns true if the registration is successful; returns false otherwise.
    
    抛出:
    
    IllegalArgumentException - Throws this exception if the specified SwitchCallback object is null.
    
    从以下版本开始:
    
    1
    
    另请参阅:
    
    SwitchCallback
  - unregisterSwitchCallback
```
public boolean unregisterSwitchCallback(SwitchCallback callback)
                                 throws IllegalArgumentException
```
    Deregisters the callback object used for obtaining the location service status.
    
    参数:
    
    callback - Specifies the callback object used for obtaining the location service status. The value must not be null.
    
    返回:
    
    Returns true if the deregistration is successful; returns false otherwise.
    
    抛出:
    
    IllegalArgumentException - Throws this exception if the value of callback is null.
    
    从以下版本开始:
    
    3
    
    另请参阅:
    
    SwitchCallback

类 Locator

字段概要

构造器概要

方法概要

从类继承的方法 java.lang.Object

字段详细资料

ERROR_PERMISSION_NOT_GRANTED

ERROR_SWITCH_UNOPEN

LOCATION_SERVICE_SWITCH_OFF

LOCATION_SERVICE_SWITCH_ON

SESSION_START

SESSION_STOP

构造器详细资料

Locator

Locator

方法详细资料

isLocationSwitchOn

requestEnableLocation

startLocating

stopLocating

requestOnce

getCachedLocation

registerSwitchCallback

unregisterSwitchCallback