Provides the NativeAbility data information APIs for obtaining the Ability instance ID, Ability name, and napi_env.
File to include: <AbilityKit/ability_runtime/native_ability_wrapper.h>
Library: libability_runtime.so
System capability: SystemCapability.Ability.AbilityRuntime.Core
Since: 26.0.0
Related module: AbilityRuntime
| Name | typedef Keyword | Description |
|---|---|---|
| AbilityRuntime_NativeAbilityWrapper | AbilityRuntime_NativeAbilityWrapper | Defines the NativeAbility data information struct type. |
| Name | Description |
|---|---|
| AbilityRuntime_ErrorCode OH_AbilityRuntime_GetAbilityInstanceId(const AbilityRuntime_NativeAbilityWrapper* nativeAbilityWrapper, char* buffer, const int32_t bufferSize) | Obtains the Ability instance ID from the NativeAbility data information. |
| AbilityRuntime_ErrorCode OH_AbilityRuntime_GetAbilityName(const AbilityRuntime_NativeAbilityWrapper *nativeAbilityWrapper, char *buffer, const int32_t bufferSize, int32_t *writeLength) | Obtains the Ability name from the NativeAbility data information. |
| AbilityRuntime_ErrorCode OH_AbilityRuntime_GetEnv(const AbilityRuntime_NativeAbilityWrapper* nativeAbilityWrapper, napi_env* env) | Obtains the napi_env from the NativeAbility data information. |
AbilityRuntime_ErrorCode OH_AbilityRuntime_GetAbilityInstanceId(
const AbilityRuntime_NativeAbilityWrapper* nativeAbilityWrapper,
char* buffer,
const int32_t bufferSize) Description
Obtains the Ability instance ID from the NativeAbility data information.
Since: 26.0.0
Parameters
| Name | Description |
|---|---|
| AbilityRuntime_NativeAbilityWrapper* nativeAbilityWrapper | Pointer to the NativeAbility data information. |
| char* buffer | Pointer to the buffer that receives the instance ID string. The instance ID is in UUID format and is 37 bytes long. |
| int32_t bufferSize | Length of the buffer, which must be at least 37 bytes. |
Returns
| Type | Description |
|---|---|
| AbilityRuntime_ErrorCode | Returns an error code. Returns ABILITY_RUNTIME_ERROR_CODE_NO_ERROR indicates the operation is successful. Returns ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID indicates nativeAbilityWrapper or buffer is a null pointer, or bufferSize is less than 37. |
Example:
#include <AbilityKit/ability_runtime/native_ability_wrapper.h>
#include <AbilityKit/ability_runtime/ability_runtime_common.h>
void GetAbilityInstanceId(const AbilityRuntime_NativeAbilityWrapper* wrapper)
{
if (wrapper == nullptr) {
// Record the error log and perform other service processing.
return;
}
// The buffer stores the Ability instance ID in UUID format.
char buffer[37] = {0};
AbilityRuntime_ErrorCode err = OH_AbilityRuntime_GetAbilityInstanceId(wrapper, buffer, 37);
if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) {
// Record the error log and perform other service processing.
return;
}
} AbilityRuntime_ErrorCode OH_AbilityRuntime_GetAbilityName(
const AbilityRuntime_NativeAbilityWrapper *nativeAbilityWrapper,
char *buffer,
const int32_t bufferSize,
int32_t *writeLength) Description
Obtains the ability name from the NativeAbility data information.
Since: 26.0.0
Parameters
| Name | Description |
|---|---|
| AbilityRuntime_NativeAbilityWrapper* nativeAbilityWrapper | Pointer to the NativeAbility data information. |
| char* buffer | Pointer to the buffer that receives the ability name string. Pass nullptr to query the length of the ability name. |
| int32_t bufferSize | Length of the buffer, in bytes. Ensure that the buffer has at least one extra byte for '\0'. |
| int32_t* writeLength | Output length of the ability name string. |
Returns
| Type | Description |
|---|---|
| AbilityRuntime_ErrorCode | Result code. Returns ABILITY_RUNTIME_ERROR_CODE_NO_ERROR if the operation is successful. Returns ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID if nativeAbilityWrapper or writeLength is a null pointer, or the buffer is too small to store the ability name. Returns ABILITY_RUNTIME_ERROR_CODE_ABILITY_WRAPPER_INVALID if the NativeAbility data information is invalid or incomplete. Returns ABILITY_RUNTIME_ERROR_CODE_INTERNAL if an internal error occurs. |
Example:
#include <AbilityKit/ability_runtime/native_ability_wrapper.h>
#include <AbilityKit/ability_runtime/ability_runtime_common.h>
void GetAbilityName(const AbilityRuntime_NativeAbilityWrapper* wrapper)
{
if (wrapper == nullptr) {
// Record the error log and perform other service processing.
return;
}
const int32_t bufferSize = 256; // Adjust the buffer size as needed.
char buffer[bufferSize] = {0};
int32_t writeLength = 0;
AbilityRuntime_ErrorCode err = OH_AbilityRuntime_GetAbilityName(wrapper, buffer, bufferSize, &writeLength);
if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) {
// Record the error log and perform other business processing.
return;
}
} AbilityRuntime_ErrorCode OH_AbilityRuntime_GetEnv(
const AbilityRuntime_NativeAbilityWrapper* nativeAbilityWrapper,
napi_env* env) Description
Obtains the napi_env from the NativeAbility data information.
Since: 26.0.0
Parameters
| Name | Description |
|---|---|
| AbilityRuntime_NativeAbilityWrapper* nativeAbilityWrapper | Pointer to the NativeAbility data information. |
| napi_env* env | Pointer to the buffer that receives the napi_env value. The napi_env remains valid until the process terminates. |
Returns
| Type | Description |
|---|---|
| AbilityRuntime_ErrorCode | Returns an error code. Returns ABILITY_RUNTIME_ERROR_CODE_NO_ERROR to indicate the operation is successful. Returns ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID to indicate that nativeAbilityWrapper or env is a null pointer. Returns ABILITY_RUNTIME_ERROR_CODE_ABILITY_WRAPPER_INVALID to indicate that the NativeAbility data information is invalid or incomplete. |
Example:
#include <AbilityKit/ability_runtime/native_ability_wrapper.h>
#include <AbilityKit/ability_runtime/ability_runtime_common.h>
#include <napi/native_api.h>
void GetEnv(const AbilityRuntime_NativeAbilityWrapper* wrapper)
{
if (wrapper == nullptr) {
// Record the error log and perform other business processing.
return;
}
napi_env env = nullptr;
AbilityRuntime_ErrorCode err = OH_AbilityRuntime_GetEnv(wrapper, &env);
if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) {
// Record the error log and perform other business processing.
return;
}
}