• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Working with Latin1/UTF16 Strings Using JSVM-API
2
3## Introduction
4
5This topic walks you through on how to create and use external strings using JSVM-API.
6
7## Basic Concepts
8
9By using JSVM-API, you can create JS strings directly in the memory allocated for Latin1/UTF16 strings. This allows you to manipulate these strings like normal JS strings.
10
11## Available APIs
12
13| API                                  | Description                      |
14|----------------------------------------|--------------------------------|
15| OH_JSVM_CreateExternalStringLatin1     | Creates an external JS string from a C string encoded in ISO-8859-1 format. |
16| OH_JSVM_CreateExternalStringUtf16      | Creates an external JS string from a C string encoded in UTF16-LE format. |
17
18## Example
19
20If you are just starting out with JSVM-API, see [JSVM-API Development Process](use-jsvm-process.md). The following demonstrates only the C++ code involved in manipulating external strings.
21
22### Creating and Using External Strings
23
24CPP code:
25
26```cpp
27
28static char stringLatin1[] = "hello";
29static char16_t stringUTF16[] = "world";
30
31static JSVM_Value testExternalString(JSVM_Env env, JSVM_CallbackInfo info) {
32    JSVM_VM vm;
33    OH_JSVM_GetVM(env, &vm);
34
35    JSVM_HandleScope handleScope;
36    OH_JSVM_OpenHandleScope(env, &handleScope);
37    JSVM_Value jsStrLatin1 = nullptr;
38    bool copied = true;
39    char buf[10];
40    OH_JSVM_CreateExternalStringLatin1(env, stringLatin1, strlen(stringLatin1), nullptr, nullptr,
41                                       &jsStrLatin1, &copied)
42    OH_JSVM_GetValueStringUTF8(env, jsStrLatin1, buf, 10, nullptr);
43    OH_LOG_INFO(LOG_APP, "created latin1 string is : %{public}s\n", buf);
44    // If the value of copied is true, the external string fails to be created. Otherwise, the external string is created successfully.
45    OH_LOG_INFO(LOG_APP, "create external string failed : %{public}d\n", copied);
46    copied = true;
47    JSVM_Value jsStrUTF16 = nullptr;
48    OH_JSVM_CreateExternalStringUtf16(env, stringLatin1, std::char_traits<char16_t>::length(stringUTF16),
49                                      nullptr, nullptr, &jsStrUTF16, &copied)
50    OH_JSVM_GetValueStringUTF8(env, jsStrUTF16, buf, 10, nullptr);
51    OH_LOG_INFO(LOG_APP, "created utf16 string is : %{public}s\n", buf);
52    // If the value of copied is true, the external string fails to be created. Otherwise, the external string is created successfully.
53    OH_LOG_INFO(LOG_APP, "create external string failed : %{public}d\n", copied);
54    OH_JSVM_CloseHandleScope(env, handleScope);
55
56    return nullptr;
57}
58
59static JSVM_CallbackStruct param[] = {
60    {.data = nullptr, .callback = testExternalString},
61};
62
63static JSVM_CallbackStruct *method = param;
64
65// Alias for the wrapperObject method to be called from JS.
66static JSVM_PropertyDescriptor descriptor[] = {
67    {"testExternalString", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
68};
69
70// Call the C++ code from JS.
71const char *srcCallNative = R"JS(testExternalString();)JS";
72
73```
74
75## Expected Result
76```
77created latin1 string is : hello
78create external string failed: 0
79created utf16 string is : world
80create external string failed: 0
81```
82