• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1/*
2 * Copyright (c) 2022 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 */
15import { AsyncCallback, Callback } from './basic';
16import { WantAgent } from './@ohos.wantAgent';
17
18 /**
19 * Provides interfaces for initiating location requests, ending the location service,
20 * and obtaining the location result cached by the system.
21 *
22 * @since 7
23 * @syscap SystemCapability.Location.Location.Core
24 * @import import geolocation from '@ohos.geolocation'
25 * @permission ohos.permission.LOCATION
26 */
27declare namespace geolocation {
28    /**
29     * subscribe location changed
30     *
31     * @since 7
32     * @syscap SystemCapability.Location.Location.Core
33     * @permission ohos.permission.LOCATION
34     * @param request Indicates the location request parameters.
35     * @param callback Indicates the callback for reporting the location result.
36     */
37    function on(type: 'locationChange', request: LocationRequest, callback: Callback<Location>) : void;
38
39    /**
40     * unsubscribe location changed
41     *
42     * @since 7
43     * @syscap SystemCapability.Location.Location.Core
44     * @permission ohos.permission.LOCATION
45     * @param callback Indicates the callback for reporting the location result.
46     */
47    function off(type: 'locationChange', callback?: Callback<Location>) : void;
48
49    /**
50     * subscribe location switch changed
51     *
52     * @since 7
53     * @syscap SystemCapability.Location.Location.Core
54     * @permission ohos.permission.LOCATION
55     * @param callback Indicates the callback for reporting the location result.
56     */
57    function on(type: 'locationServiceState', callback: Callback<boolean>) : void;
58
59    /**
60     * unsubscribe location switch changed
61     *
62     * @since 7
63     * @syscap SystemCapability.Location.Location.Core
64     * @permission ohos.permission.LOCATION
65     * @param callback Indicates the callback for reporting the location result.
66     */
67    function off(type: 'locationServiceState', callback?: Callback<boolean>) : void;
68
69    /**
70     * subscribe to cache GNSS locations update messages
71     *
72     * @since 8
73     * @syscap SystemCapability.Location.Location.Gnss
74     * @permission ohos.permission.LOCATION
75     * @param request Indicates the cached GNSS locations request parameters.
76     * @param callback Indicates the callback for reporting the cached GNSS locations.
77     */
78    function on(type: 'cachedGnssLocationsReporting', request: CachedGnssLocationsRequest, callback: Callback<Array<Location>>) : void;
79
80    /**
81     * unsubscribe to cache GNSS locations update messages
82     *
83     * @since 8
84     * @syscap SystemCapability.Location.Location.Gnss
85     * @permission ohos.permission.LOCATION
86     * @param callback Indicates the callback for reporting the cached gnss locations.
87     */
88    function off(type: 'cachedGnssLocationsReporting', callback?: Callback<Array<Location>>) : void;
89
90    /**
91     * subscribe gnss status changed
92     *
93     * @since 8
94     * @syscap SystemCapability.Location.Location.Gnss
95     * @permission ohos.permission.LOCATION
96     * @param callback Indicates the callback for reporting the gnss status change.
97     */
98    function on(type: 'gnssStatusChange', callback: Callback<SatelliteStatusInfo>) : void;
99
100    /**
101     * unsubscribe gnss status changed
102     *
103     * @since 8
104     * @syscap SystemCapability.Location.Location.Gnss
105     * @permission ohos.permission.LOCATION
106     * @param callback Indicates the callback for reporting the gnss status change.
107     */
108    function off(type: 'gnssStatusChange', callback?: Callback<SatelliteStatusInfo>) : void;
109
110    /**
111     * subscribe nmea message changed
112     *
113     * @since 8
114     * @syscap SystemCapability.Location.Location.Gnss
115     * @permission ohos.permission.LOCATION
116     * @param callback Indicates the callback for reporting the nmea message.
117     */
118    function on(type: 'nmeaMessageChange', callback: Callback<string>) : void;
119
120    /**
121     * unsubscribe nmea message changed
122     *
123     * @since 8
124     * @syscap SystemCapability.Location.Location.Gnss
125     * @permission ohos.permission.LOCATION
126     * @param callback Indicates the callback for reporting the nmea message.
127     */
128    function off(type: 'nmeaMessageChange', callback?: Callback<string>) : void;
129
130    /**
131     * add a geofence and subscribe geo fence status changed
132     *
133     * @since 8
134     * @syscap SystemCapability.Location.Location.Geofence
135     * @permission ohos.permission.LOCATION
136     * @param request Indicates the Geo-fence configuration parameters.
137     * @param callback Indicates the callback for reporting the fence status.
138     */
139    function on(type: 'fenceStatusChange', request: GeofenceRequest, want: WantAgent) : void;
140
141    /**
142     * remove a geofence and unsubscribe geo fence status changed
143     *
144     * @since 8
145     * @syscap SystemCapability.Location.Location.Geofence
146     * @permission ohos.permission.LOCATION
147     * @param request Indicates the Geo-fence configuration parameters.
148     * @param callback Indicates the callback for reporting the remove fence result.
149     */
150    function off(type: 'fenceStatusChange', request: GeofenceRequest, want: WantAgent) : void;
151
152    /**
153     * obtain current location
154     *
155     * @since 7
156     * @syscap SystemCapability.Location.Location.Core
157     * @permission ohos.permission.LOCATION
158     * @param callback Indicates the callback for reporting the location result.
159     */
160    function getCurrentLocation(request: CurrentLocationRequest, callback: AsyncCallback<Location>) : void;
161    function getCurrentLocation(callback: AsyncCallback<Location>) : void;
162    function getCurrentLocation(request?: CurrentLocationRequest) : Promise<Location>;
163
164    /**
165     * obtain last known location
166     *
167     * @since 7
168     * @syscap SystemCapability.Location.Location.Core
169     * @permission ohos.permission.LOCATION
170     * @param callback Indicates the callback for reporting the location result.
171     */
172    function getLastLocation(callback: AsyncCallback<Location>) : void;
173    function getLastLocation() : Promise<Location>;
174
175    /**
176     * obtain current location switch status
177     *
178     * @since 7
179     * @syscap SystemCapability.Location.Location.Core
180     * @permission ohos.permission.LOCATION
181     * @param callback Indicates the callback for reporting the location switch result.
182     */
183    function isLocationEnabled(callback: AsyncCallback<boolean>) : void;
184    function isLocationEnabled() : Promise<boolean>;
185
186    /**
187     * request enable location
188     *
189     * @since 7
190     * @syscap SystemCapability.Location.Location.Core
191     * @permission ohos.permission.LOCATION
192     * @param callback Indicates the callback for reporting the location switch status.
193     */
194    function requestEnableLocation(callback: AsyncCallback<boolean>) : void;
195    function requestEnableLocation() : Promise<boolean>;
196
197    /**
198     * enable location switch
199     *
200     * @since 7
201     * @syscap SystemCapability.Location.Location.Core
202     * @systemapi
203     * @permission ohos.permission.MANAGE_SECURE_SETTINGS
204     * @param callback Indicates the callback for reporting the location switch result.
205     */
206    function enableLocation(callback: AsyncCallback<boolean>) : void;
207    function enableLocation() : Promise<boolean>;
208
209    /**
210     * disable location switch
211     *
212     * @since 7
213     * @syscap SystemCapability.Location.Location.Core
214     * @systemapi
215     * @permission ohos.permission.MANAGE_SECURE_SETTINGS
216     * @param callback Indicates the callback for reporting the location switch result.
217     */
218    function disableLocation(callback: AsyncCallback<boolean>) : void;
219    function disableLocation() : Promise<boolean>;
220
221    /**
222     * obtain address info from location
223     *
224     * @since 7
225     * @syscap SystemCapability.Location.Location.Geocoder
226     * @permission ohos.permission.LOCATION
227     * @param callback Indicates the callback for reporting the address info.
228     */
229    function getAddressesFromLocation(request: ReverseGeoCodeRequest, callback: AsyncCallback<Array<GeoAddress>>) : void;
230    function getAddressesFromLocation(request: ReverseGeoCodeRequest) : Promise<Array<GeoAddress>>;
231
232    /**
233     * obtain latitude and longitude info from location address
234     *
235     * @since 7
236     * @syscap SystemCapability.Location.Location.Geocoder
237     * @permission ohos.permission.LOCATION
238     * @param callback Indicates the callback for reporting the latitude and longitude result.
239     */
240    function getAddressesFromLocationName(request: GeoCodeRequest, callback: AsyncCallback<Array<GeoAddress>>) : void;
241    function getAddressesFromLocationName(request: GeoCodeRequest) : Promise<Array<GeoAddress>>;
242
243    /**
244     * obtain geocode service status
245     *
246     * @since 7
247     * @syscap SystemCapability.Location.Location.Geocoder
248     * @permission ohos.permission.LOCATION
249     * @param callback Indicates the callback for reporting the geocode service status.
250     */
251    function isGeoServiceAvailable(callback: AsyncCallback<boolean>) : void;
252    function isGeoServiceAvailable() : Promise<boolean>;
253
254    /**
255     * obtain the number of cached GNSS locations reported at a time
256     *
257     * @since 8
258     * @syscap SystemCapability.Location.Location.Gnss
259     * @permission ohos.permission.LOCATION
260     * @param callback Indicates the callback for reporting the cached GNSS locations size.
261     */
262    function getCachedGnssLocationsSize(callback: AsyncCallback<number>) : void;
263    function getCachedGnssLocationsSize() : Promise<number>;
264
265    /**
266     * all prepared GNSS locations are returned to the application through the callback function,
267     * and the bottom-layer buffer is cleared.
268     *
269     * @since 8
270     * @syscap SystemCapability.Location.Location.Gnss
271     * @permission ohos.permission.LOCATION
272     * @param callback Indicates the callback for reporting the result.
273     */
274    function flushCachedGnssLocations(callback: AsyncCallback<boolean>) : void;
275    function flushCachedGnssLocations() : Promise<boolean>;
276
277    /**
278     * send extended commands to location subsystem.
279     *
280     * @since 8
281     * @syscap SystemCapability.Location.Location.Core
282     * @permission ohos.permission.LOCATION
283     * @param command Indicates the extended Command Message Body.
284     * @param callback Indicates the callback for reporting the send command result.
285     */
286    function sendCommand(command: LocationCommand, callback: AsyncCallback<boolean>) : void;
287    function sendCommand(command: LocationCommand) : Promise<boolean>;
288
289    /**
290     * satellite status information
291     *
292     * @since 8
293     * @syscap SystemCapability.Location.Location.Gnss
294     * @permission ohos.permission.LOCATION
295     */
296    export interface SatelliteStatusInfo {
297        satellitesNumber: number;
298        satelliteIds: Array<number>;
299        carrierToNoiseDensitys: Array<number>;
300        altitudes: Array<number>;
301        azimuths: Array<number>;
302        carrierFrequencies: Array<number>;
303    }
304
305    /**
306     * parameters for requesting to report cache location information
307     *
308     * @since 8
309     * @syscap SystemCapability.Location.Location.Gnss
310     * @permission ohos.permission.LOCATION
311     */
312    export interface CachedGnssLocationsRequest {
313        reportingPeriodSec: number;
314        wakeUpCacheQueueFull: boolean;
315    }
316
317    /**
318     * configuring parameters in geo fence requests
319     *
320     * @since 8
321     * @syscap SystemCapability.Location.Location.Geofence
322     * @permission ohos.permission.LOCATION
323     */
324    export interface GeofenceRequest {
325        priority: LocationRequestPriority;
326        scenario: LocationRequestScenario;
327        geofence: Geofence;
328    }
329
330    /**
331     * configuring parameters in geo fence requests
332     *
333     * @since 8
334     * @syscap SystemCapability.Location.Location.Geofence
335     * @permission ohos.permission.LOCATION
336     */
337    export interface Geofence {
338        latitude: number;
339        longitude: number;
340        radius: number;
341        expiration: number;
342    }
343
344    /**
345     * querying location privacy protocol confirmation status.
346     *
347     * @since 8
348     * @systemapi
349     * @syscap SystemCapability.Location.Location.Core
350     * @permission ohos.permission.LOCATION
351     * @param type indicates location privacy protocol type.
352     * @param callback indicates the callback for reporting the location privacy protocol confirmation status.
353     */
354    function isLocationPrivacyConfirmed(type : LocationPrivacyType, callback: AsyncCallback<boolean>) : void;
355    function isLocationPrivacyConfirmed(type : LocationPrivacyType,) : Promise<boolean>;
356
357    /**
358     * set location privacy protocol confirmation status.
359     *
360     * @since 8
361     * @systemapi
362     * @syscap SystemCapability.Location.Location.Core
363     * @permission ohos.permission.LOCATION
364     * @param type indicates location privacy protocol type.
365     * @param isConfirmed indicates whether the location privacy protocol has been confirmed.
366     * @param callback Indicates the callback for reporting whether the action is set successfully.
367     */
368    function setLocationPrivacyConfirmStatus(type : LocationPrivacyType, isConfirmed : boolean, callback: AsyncCallback<boolean>) : void;
369    function setLocationPrivacyConfirmStatus(type : LocationPrivacyType, isConfirmed : boolean) : Promise<boolean>;
370
371    /**
372     * configuring parameters in reverse geocode requests
373     *
374     * @since 7
375     * @syscap SystemCapability.Location.Location.Geocoder
376     * @permission ohos.permission.LOCATION
377     */
378    export interface ReverseGeoCodeRequest {
379        locale?: string;
380        latitude: number;
381        longitude: number;
382        maxItems?: number;
383    }
384
385    /**
386     * configuring parameters in geocode requests
387     *
388     * @since 7
389     * @syscap SystemCapability.Location.Location.Geocoder
390     * @permission ohos.permission.LOCATION
391     */
392    export interface GeoCodeRequest {
393        locale?: string;
394        description: string;
395        maxItems?: number;
396        minLatitude?: number;
397        minLongitude?: number;
398        maxLatitude?: number;
399        maxLongitude?: number;
400    }
401
402    /**
403     * data struct describes geographic locations.
404     *
405     * @since 7
406     * @syscap SystemCapability.Location.Location.Geocoder
407     * @permission ohos.permission.LOCATION
408     */
409    export interface GeoAddress {
410        latitude?: number;
411        longitude?: number;
412        locale?: string;
413        placeName?: string;
414        countryCode?: string;
415        countryName?: string;
416        administrativeArea?: string;
417        subAdministrativeArea?: string;
418        locality?: string;
419        subLocality?: string;
420        roadName?: string;
421        subRoadName?: string;
422        premises?: string;
423        postalCode?: string;
424        phoneNumber?: string;
425        addressUrl?: string;
426        descriptions?: Array<string>;
427        descriptionsSize?: number;
428    }
429
430    /**
431     * configuring parameters in location requests
432     *
433     * @since 7
434     * @syscap SystemCapability.Location.Location.Core
435     * @permission ohos.permission.LOCATION
436     */
437    export interface LocationRequest {
438        priority?: LocationRequestPriority;
439        scenario?: LocationRequestScenario;
440        timeInterval?: number;
441        distanceInterval?: number;
442        maxAccuracy?: number;
443    }
444
445    /**
446     * configuring parameters in current location requests
447     *
448     * @since 7
449     * @syscap SystemCapability.Location.Location.Core
450     * @permission ohos.permission.LOCATION
451     */
452    export interface CurrentLocationRequest {
453        priority?: LocationRequestPriority;
454        scenario?: LocationRequestScenario;
455        maxAccuracy?: number;
456        timeoutMs?: number;
457    }
458
459    /**
460     * provides information about geographic locations
461     *
462     * @since 7
463     * @syscap SystemCapability.Location.Location.Core
464     * @permission ohos.permission.LOCATION
465     */
466    export interface Location {
467        latitude: number;
468        longitude: number;
469        altitude: number;
470        accuracy: number;
471        speed: number;
472        timeStamp: number;
473        direction: number;
474        timeSinceBoot: number;
475        additions?: Array<string>;
476        additionSize?: number;
477    }
478
479    /**
480     * enum for location priority
481     *
482     * @since 7
483     * @syscap SystemCapability.Location.Location.Core
484     * @permission ohos.permission.LOCATION
485     */
486    export enum LocationRequestPriority {
487        UNSET = 0x200,
488        ACCURACY,
489        LOW_POWER,
490        FIRST_FIX,
491    }
492
493    /**
494     * enum for location scenario
495     *
496     * @since 7
497     * @syscap SystemCapability.Location.Location.Core
498     * @permission ohos.permission.LOCATION
499     */
500    export enum LocationRequestScenario {
501        UNSET = 0x300,
502        NAVIGATION,
503        TRAJECTORY_TRACKING,
504        CAR_HAILING,
505        DAILY_LIFE_SERVICE,
506        NO_POWER,
507    }
508
509    /**
510     * enum for error code
511     *
512     * @since 7
513     * @syscap SystemCapability.Location.Location.Core
514     * @permission ohos.permission.LOCATION
515     */
516    export enum GeoLocationErrorCode {
517        INPUT_PARAMS_ERROR = 101,
518        REVERSE_GEOCODE_ERROR,
519        GEOCODE_ERROR,
520        LOCATOR_ERROR,
521        LOCATION_SWITCH_ERROR,
522        LAST_KNOWN_LOCATION_ERROR,
523        LOCATION_REQUEST_TIMEOUT_ERROR,
524    }
525
526    /**
527     * enum for location privacy type
528     *
529     * @since 8
530     * @syscap SystemCapability.Location.Location.Core
531     * @permission ohos.permission.LOCATION
532     */
533    export enum LocationPrivacyType {
534        OTHERS = 0,
535        STARTUP,
536        CORE_LOCATION,
537    }
538
539    /**
540     * Location subsystem command structure
541     *
542     * @since 8
543     * @syscap SystemCapability.Location.Location.Core
544     * @permission ohos.permission.LOCATION
545     */
546    export interface LocationCommand {
547        scenario: LocationRequestScenario;
548        command: string;
549    }
550}
551
552export default geolocation;