1/*
2 * Copyright (c) 2024 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 */
15#ifndef OHOS_INPUTMETHOD_PRIVATE_COMMAND_CAPI_H
16#define OHOS_INPUTMETHOD_PRIVATE_COMMAND_CAPI_H
17/**
18 * @addtogroup InputMethod
19 * @{
20 *
21 * @brief InputMethod provides functions to use input methods and develop input methods.
22 *
23 * @since 12
24 */
25
26/**
27 * @file inputmethod_private_command_capi.h
28 *
29 * @brief Provides functions to manage private commands.
30 *
31 * @library libohinputmethod.so
32 * @kit IMEKit
33 * @syscap SystemCapability.MiscServices.InputMethodFramework
34 * @since 12
35 * @version 1.0
36 */
37#include <stddef.h>
38#include <stdint.h>
39
40#include "inputmethod_types_capi.h"
41#ifdef __cplusplus
42extern "C" {
43#endif /* __cplusplus */
44/**
45 * @brief Define the InputMethod_PrivateCommand structure type.
46 *
47 * The private command between text editor and input method.
48 *
49 * @since 12
50 */
51typedef struct InputMethod_PrivateCommand InputMethod_PrivateCommand;
52
53/**
54 * @brief Create a new {@link InputMethod_PrivateCommand} instance.
55 *
56 * @param key The key of the private command.
57 * @param keyLength The length of the key.
58 * @return If the creation succeeds, a pointer to the newly created {@link InputMethod_PrivateCommand}
59 * instance is returned. If the creation fails, NULL is returned, possible cause is insufficient memory.
60 * @since 12
61 */
62InputMethod_PrivateCommand *OH_PrivateCommand_Create(char key[], size_t keyLength);
63/**
64 * @brief Destroy a {@link InputMethod_PrivateCommand} instance.
65 *
66 * @param command Represents a pointer to an {@link InputMethod_PrivateCommand} instance which will be destroyed.
67 * @since 12
68 */
69void OH_PrivateCommand_Destroy(InputMethod_PrivateCommand *command);
70/**
71 * @brief Set key value into {@link InputMethod_PrivateCommand}.
72 *
73 * @param command Represents a pointer to an {@link InputMethod_PrivateCommand} instance which will be set value.
74 * @param key Represents key value.
75 * @param keyLength Represents key length.
76 * @return Returns a specific error code.
77 *     {@link IME_ERR_OK} - success.
78 *     {@link IME_ERR_NULL_POINTER} - unexpected null pointer.
79 * Specific error codes can be referenced {@link InputMethod_ErrorCode}.
80 * @since 12
81 */
82InputMethod_ErrorCode OH_PrivateCommand_SetKey(InputMethod_PrivateCommand *command, char key[], size_t keyLength);
83/**
84 * @brief Set bool data value into {@link InputMethod_PrivateCommand}.
85 *
86 * @param command Represents a pointer to an {@link InputMethod_PrivateCommand} instance which will be set value.
87 * @param value Represents bool data value.
88 * @return Returns a specific error code.
89 *     {@link IME_ERR_OK} - success.
90 *     {@link IME_ERR_NULL_POINTER} - unexpected null pointer.
91 * Specific error codes can be referenced {@link InputMethod_ErrorCode}.
92 * @since 12
93 */
94InputMethod_ErrorCode OH_PrivateCommand_SetBoolValue(InputMethod_PrivateCommand *command, bool value);
95/**
96 * @brief Set integer data value into {@link InputMethod_PrivateCommand}.
97 *
98 * @param command Represents a pointer to an {@link InputMethod_PrivateCommand} instance which will be set value.
99 * @param value Represents integer data value.
100 * @return Returns a specific error code.
101 *     {@link IME_ERR_OK} - success.
102 *     {@link IME_ERR_NULL_POINTER} - unexpected null pointer.
103 * Specific error codes can be referenced {@link InputMethod_ErrorCode}.
104 * @since 12
105 */
106InputMethod_ErrorCode OH_PrivateCommand_SetIntValue(InputMethod_PrivateCommand *command, int32_t value);
107/**
108 * @brief Set string data value into {@link InputMethod_PrivateCommand}.
109 *
110 * @param command Represents a pointer to an {@link InputMethod_PrivateCommand} instance which will be set value.
111 * @param value Represents string data value.
112 * @param valueLength Represents the length of string data value.
113 * @return Returns a specific error code.
114 *     {@link IME_ERR_OK} - success.
115 *     {@link IME_ERR_NULL_POINTER} - unexpected null pointer.
116 * Specific error codes can be referenced {@link InputMethod_ErrorCode}.
117 * @since 12
118 */
119InputMethod_ErrorCode OH_PrivateCommand_SetStrValue(
120    InputMethod_PrivateCommand *command, char value[], size_t valueLength);
121
122/**
123 * @brief Get key value from {@link InputMethod_PrivateCommand}.
124 *
125 * @param command Represents a pointer to an {@link InputMethod_PrivateCommand} instance which will be get value from.
126 * @param key Represents key value.
127 * @param keyLength Represents key length.
128 * @return Returns a specific error code.
129 *     {@link IME_ERR_OK} - success.
130 *     {@link IME_ERR_NULL_POINTER} - unexpected null pointer.
131 * Specific error codes can be referenced {@link InputMethod_ErrorCode}.
132 * @since 12
133 */
134InputMethod_ErrorCode OH_PrivateCommand_GetKey(
135    InputMethod_PrivateCommand *command, const char **key, size_t *keyLength);
136/**
137 * @brief Get value type from {@link InputMethod_PrivateCommand}.
138 *
139 * @param command Represents a pointer to an {@link InputMethod_PrivateCommand} instance which will be get value from.
140 * @param type Represents a pointer to a {@link InputMethod_CommandValueType} instance. Indicates the data type of the
141 * value.
142 * @return Returns a specific error code.
143 *     {@link IME_ERR_OK} - success.
144 *     {@link IME_ERR_NULL_POINTER} - unexpected null pointer.
145 * Specific error codes can be referenced {@link InputMethod_ErrorCode}.
146 * @since 12
147 */
148InputMethod_ErrorCode OH_PrivateCommand_GetValueType(
149    InputMethod_PrivateCommand *command, InputMethod_CommandValueType *type);
150/**
151 * @brief Get bool data value from {@link InputMethod_PrivateCommand}.
152 *
153 * @param command Represents a pointer to an {@link InputMethod_PrivateCommand} instance which will be get value from.
154 * @param value Represents bool data value.
155 * @return Returns a specific error code.
156 *     {@link IME_ERR_OK} - success.
157 *     {@link IME_ERR_NULL_POINTER} - unexpected null pointer.
158 *     {@link IME_ERR_QUERY_FAILED} - query failed, no bool value in command.
159 * Specific error codes can be referenced {@link InputMethod_ErrorCode}.
160 * @since 12
161 */
162InputMethod_ErrorCode OH_PrivateCommand_GetBoolValue(InputMethod_PrivateCommand *command, bool *value);
163/**
164 * @brief Get integer data value from {@link InputMethod_PrivateCommand}.
165 *
166 * @param command Represents a pointer to an {@link InputMethod_PrivateCommand} instance which will be get value from.
167 * @param value Represents integer data value.
168 * @return Returns a specific error code.
169 *     {@link IME_ERR_OK} - success.
170 *     {@link IME_ERR_NULL_POINTER} - unexpected null pointer.
171 *     {@link IME_ERR_QUERY_FAILED} - query failed, no integer value in command.
172 * Specific error codes can be referenced {@link InputMethod_ErrorCode}.
173 * @since 12
174 */
175InputMethod_ErrorCode OH_PrivateCommand_GetIntValue(InputMethod_PrivateCommand *command, int32_t *value);
176/**
177 * @brief Get string data value from {@link InputMethod_PrivateCommand}.
178 *
179 * @param command Represents a pointer to an {@link InputMethod_PrivateCommand} instance which will be get value from.
180 * @param value Represents string data value.
181 * @param valueLength Represents the length of string data value.
182 * @return Returns a specific error code.
183 *     {@link IME_ERR_OK} - success.
184 *     {@link IME_ERR_NULL_POINTER} - unexpected null pointer.
185 *     {@link IME_ERR_QUERY_FAILED} - query failed, no string value in command.
186 * Specific error codes can be referenced {@link InputMethod_ErrorCode}.
187 * @since 12
188 */
189InputMethod_ErrorCode OH_PrivateCommand_GetStrValue(
190    InputMethod_PrivateCommand *command, const char **value, size_t *valueLength);
191#ifdef __cplusplus
192}
193#endif /* __cplusplus */
194/** @} */
195#endif // OHOS_INPUTMETHOD_PRIVATE_COMMAND_CAPI_H