目录

RemoteLocationExtensionAbility

RemoteLocationExtensionAbility is currently reserved and is not yet available for public use.

Location sharing messages are designed to provide real-time services and personalized experiences closely linked to geographical locations. This feature requires users to grant the ohos.permission.LOCATION_IN_BACKGROUND permission to apps in advance. When a location sharing message arrives at a device, Push Kit will start the child process of the app, where you can perform operations such as obtaining the location and processing data.

RemoteLocationExtensionAbility provides callbacks for message data retrieval and lifecycle destruction. The restrictions are as follows:

If this extension ability fails to be executed, an error may be returned. Rectify the fault based on the error information. For details, please refer to ArkTS API Error Codes.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Push.PushService

Since: 4.1.0(11)

Constraints

To ensure system security and stability and prevent RemoteLocationExtensionAbility from abusing system resources, the system restricts its capabilities. Referencing certain modules is not supported. For details, please refer to the Appendix.

Modules to Import

import { RemoteLocationExtensionAbility } from '@kit.PushKit';

Attributes

Model restriction: This attribute can be used only in the stage model.

System capability: SystemCapability.Push.PushService

Since: 4.1.0(11)

Name Type Read-Only Optional Description
context RemoteLocationExtensionContext No No Context of RemoteLocationExtensionAbility, which inherits from ExtensionContext.

onReceiveMessage

onReceiveMessage(payload: pushCommon.PushPayload): Promise<void>

API for receiving location sharing message data after an app inherits from RemoteLocationExtensionAbility. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Push.PushService

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
payload pushCommon.PushPayload Yes Location sharing message data.

Returns:

Type Description
Promise<void> Promise that returns no value.

Example:

import { RemoteLocationExtensionAbility, pushCommon } from '@kit.PushKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { geoLocationManager } from '@kit.LocationKit';
import { BusinessError } from '@kit.BasicServicesKit';

const LOG_DOMAIN = 0x0000;
const LOG_TAG = 'RemoteLocationExtAbility';

// In the following example, RemoteLocationExtAbility inherits from RemoteLocationExtensionAbility:
export default class RemoteLocationExtAbility extends RemoteLocationExtensionAbility {
  async onReceiveMessage(payload: pushCommon.PushPayload): Promise<void> {
    hilog.info(LOG_DOMAIN, LOG_TAG, 'onReceiveMessage, payload: %{public}s', JSON.stringify(payload));

    try {
      // Obtain the real-time location.
      await this.handleLocationRequest();
    } catch (err) {
      const e: BusinessError = err as BusinessError;
      hilog.error(LOG_DOMAIN, LOG_TAG, 'handleLocationRequest failed: code=%{public}d, message=%{public}s', e.code, e.message);
    }
  }
  /**
   * Obtain the real-time location.
   */
  private async handleLocationRequest(): Promise<void> {
    const locationEnabled = geoLocationManager.isLocationEnabled();
    if (!locationEnabled) {
      hilog.error(LOG_DOMAIN, LOG_TAG, 'LocationEnabled is close');
      return;
    }

    const request: geoLocationManager.SingleLocationRequest = {
      'locatingPriority': geoLocationManager.LocatingPriority.PRIORITY_LOCATING_SPEED,
      'locatingTimeoutMs': 10000
    };
    const position = await geoLocationManager.getCurrentLocation(request);
    // You can process the position as required.
  }
}

onDestroy

onDestroy(): void

Callback triggered when the RemoteLocationExtensionAbility is destroyed. You are advised to clear resources in this method.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Push.PushService

Since: 4.1.0(11)

Example:

import { RemoteLocationExtensionAbility } from '@kit.PushKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';

const LOG_DOMAIN = 0x0000;
const LOG_TAG = 'RemoteLocationExtAbility';
 
// In the following example, RemoteLocationExtAbility inherits from RemoteLocationExtensionAbility:
export default class RemoteLocationExtAbility extends RemoteLocationExtensionAbility {
  onDestroy(): void {
    hilog.info(LOG_DOMAIN, LOG_TAG, 'RemoteLocationExtAbility onDestroy');

    try {
      this.releaseResources();
    } catch (err) {
      const e: BusinessError = err as BusinessError;
      hilog.error(LOG_DOMAIN, LOG_TAG, 'releaseResources failed, code=%{public}d, message=%{public}s', e.code, e.message);
    }
  }

  /**
   * Releases resources.
   * Implement the service logic based on your needs.
   */
  private releaseResources(): void {
    // Logic of resource release.
  }
}

Appendix

RemoteLocationExtensionAbility does not support referencing the following modules.

Kit Modules
Notification Kit

@ohos.notification (Notification)

@ohos.notificationManager (NotificationManager)
Form Kit

@ohos.app.form.formProvider (formProvider)

@ohos.app.form.formInfo (formInfo)

@ohos.app.form.formBindingData (formBindingData)

@ohos.app.form.FormExtensionAbility (FormExtensionAbility)

@ohos.application.formBindingData (formBindingData)

@ohos.application.formInfo (formInfo)

@ohos.application.formProvider (formProvider)
Call Service Kit telephony.voipCall