/*
* Copyright (c) 2024 Huawei Device Co., Ltd.
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
* @addtogroup InputMethod
* @{
*
* @brief InputMethod模块提供C语言接口来使用输入法。"使用输入法"面向应用侧调用。
*
*
功能定位：该模块为应用侧开发者提供自绘输入框与输入法服务交互的完整C API，支持应用绑定/解绑输入法服务、向输入法发送请求
* 和通知、接收输入法的回调通知、配置输入框属性、管理光标和避让信息等核心功能。
*
*
使用场景：适用于使用NDK开发自绘输入框的应用，需要与系统输入法服务进行交互的场景。典型流程为：应用创建TextEditorProxy
* （文本编辑器代理）和AttachOptions（绑定配置选项），通过Controller绑定输入法服务，绑定成功后通过InputMethodProxy（输入法代
* 理）与输入法交互，使用完毕后通过Controller解绑。
*
*
使用后效果：绑定输入法后，应用可接收输入法的文本插入、删除、光标移动等回调通知，也可主动向输入法发送光标更新、选区变
* 更、私有命令等请求。解绑后，所有交互通道关闭，相关资源释放。
*
*
生命周期管理：本模块遵循严格的创建/销毁配对原则和绑定/解绑配对原则：
*
*
- 绑定/解绑配对：OH_InputMethodController_Attach必须与OH_InputMethodController_Detach配对调用，未解绑会导致输入法
* 资源泄漏。
*
- 创建/销毁配对：所有Create函数创建的对象必须通过对应的Destroy函数销毁，否则会导致内存泄漏。
*
- 调用顺序：先创建依赖对象（TextEditorProxy、AttachOptions），再执行Attach绑定，绑定成功后使用InputMethodProxy交
* 互，最后Detach解绑并销毁所有创建的对象。
*
*
线程安全：本模块的API非线程安全，建议在主线程调用。TextEditorProxy的回调执行线程可通过
* OH_TextEditorProxy_SetCallbackInMainThread配置。
*
*
模块架构: 本模块由9个头文件组成，按职责分为四层：
*
*
- 控制层：inputmethod_controller_capi.h —— 模块核心入口，提供绑定/解绑输入法服务的能力，是所有交互的起点和终点。
*
- 交互层：inputmethod_text_editor_proxy_capi.h和inputmethod_inputmethod_proxy_capi.h —— 双向交互通道。
* TextEditorProxy是输入法→应用方向的回调注册通道，应用通过它接收输入法的文本插入、删除等通知；InputMethodProxy是应用→输入法方向
* 的请求发送通道，应用通过它向输入法发送光标更新、选区变更等通知。
*
- 配置层：inputmethod_attach_options_capi.h、inputmethod_text_config_capi.h、inputmethod_cursor_info_capi.h、
* inputmethod_text_avoid_info_capi.h —— 各类配置和信息的承载对象，分别管理绑定选项、输入框配置、光标位置信息、避让区域信息。
*
- 数据层：inputmethod_private_command_capi.h和inputmethod_types_capi.h —— 私有命令数据和公共类型定义（枚举、错误
* 码等）。
*
*
典型调用流程：
*
1. 通过inputmethod_text_editor_proxy_capi.h创建TextEditorProxy并注册回调。
*
2. 通过inputmethod_attach_options_capi.h创建AttachOptions配置绑定选项。
*
3. 通过inputmethod_controller_capi.h调用Attach绑定输入法，获取InputMethodProxy。
*
4. 通过inputmethod_inputmethod_proxy_capi.h使用InputMethodProxy与输入法交互。
*
5. 通过inputmethod_text_config_capi.h、inputmethod_cursor_info_capi.h等管理配置信息。
*
6. 通过inputmethod_controller_capi.h调用Detach解绑。
*
7. 销毁所有创建的对象。
*
* @library libohinputmethod.so
* @kit IMEKit
* @syscap SystemCapability.MiscServices.InputMethodFramework
* @since 12
*/
/**
* @file inputmethod_inputmethod_proxy_capi.h
*
* @brief 输入法代理的头文件，提供应用主动向输入法服务发送请求和通知的方法，包括显示/隐藏键盘、通知选区变更、通知光标更新、通知配
* 置变更、发送私有命令等。InputMethodProxy实例由OH_InputMethodController_Attach返回，不可自行创建，在Detach之前保持有效。
*
* @include
* @library libohinputmethod.so
* @kit IMEKit
* @syscap SystemCapability.MiscServices.InputMethodFramework
* @since 12
* @version 1.0
*/
#ifndef OHOS_INPUTMETHOD_INPUTMETHOD_PROXY_CAPI_H
#define OHOS_INPUTMETHOD_INPUTMETHOD_PROXY_CAPI_H
#include
#include "inputmethod_types_capi.h"
#include "inputmethod_attach_options_capi.h"
#include "inputmethod_cursor_info_capi.h"
#include "inputmethod_private_command_capi.h"
#ifdef __cplusplus
extern "C"{
#endif /* __cplusplus */
/**
* @brief 应用与输入法服务之间的交互代理对象，应用可通过此对象调用输入法服务的相关接口，并接收输入法服务的事件回调。该结构体为不透
* 明类型（opaque type），调用者不可直接访问其内部成员，仅可通过本模块提供的函数接口进行操作。
*
*
用途
*
*
InputMethod_InputMethodProxy是应用端与输入法服务交互的核心代理对象，用于向输入法服务发送请求和通知。通过此代理对象，
* 应用可以控制键盘的显示与隐藏、通知编辑框的文本选区变化和配置变化、更新光标位置、以及发送私有命令数据。
*
*
生命周期管理
*
*
- 创建方式：由[OH_InputMethodController_Attach](capi-inputmethod-controller-capi-h.
* md#oh_inputmethodcontroller_attach)函数创建并作为输出参数返回，调用者不可手动创建此对象。
*
- 销毁方式：不可手动销毁。当调用[OH_InputMethodController_Detach](capi-inputmethod-controller-capi-h.
* md#oh_inputmethodcontroller_detach)解除绑定后，InputMethod_InputMethodProxy对象将由系统自动释放并失效。
*
- 有效性：InputMethod_InputMethodProxy仅在Attach与Detach之间有效。Detach后，所有通过此对象调用的函数将返回
* IME_ERR_DETACHED错误码，不可再使用。
*
- 重复创建/销毁：不支持重复销毁。每次Attach会产生一个新的InputMethod_InputMethodProxy实例，对应的Detach会使其失效。
*
*
使用注意事项
*
*
- 调用任何InputMethod_InputMethodProxy相关函数前，必须确保已通过[OH_InputMethodController_Attach]
* (capi-inputmethod-controller-capi-h.md#oh_inputmethodcontroller_attach)成功获取该对象，且尚未调用Detach。
*
- inputMethodProxy指针不可为NULL，传入NULL指针将导致IME_ERR_NULL_POINTER错误码。示例：调用前未判空即调用函数时触
* 发，应在调用前判断指针是否为NULL，若为NULL则先通过Attach获取有效对象或终止调用。
*
- Detach后不可再使用已获取的inputMethodProxy指针，所有操作将返回IME_ERR_DETACHED。示例：在Detach后调用任何接口时返
* 回该码，应检查生命周期状态，仅在Attach与Detach之间使用该对象，否则重新Attach。此对象为不透明类型，不可直接访问内部成员或进行内
* 存操作（如malloc/free）。
*
- 非线程安全，不建议在多线程环境下同时操作同一个inputMethodProxy对象，如需多线程访问请自行加锁保护。
*
*
相关函数：
*
*
以下为可通过InputMethod_InputMethodProxy对象调用的操作函数：
* | 函数 | 描述 |
* | -- | -- |
* | [OH_InputMethodProxy_ShowKeyboard](capi-inputmethod-inputmethod-proxy-capi-h.
* md#oh_inputmethodproxy_showkeyboard) | 显示键盘。 |
* | [OH_InputMethodProxy_ShowTextInput](capi-inputmethod-inputmethod-proxy-capi-h.
* md#oh_inputmethodproxy_showtextinput) | 显示文本输入框。 |
* | [OH_InputMethodProxy_HideKeyboard](capi-inputmethod-inputmethod-proxy-capi-h.
* md#oh_inputmethodproxy_hidekeyboard) | 隐藏键盘。 |
* | [OH_InputMethodProxy_NotifySelectionChange](capi-inputmethod-inputmethod-proxy-capi-h.
* md#oh_inputmethodproxy_notifyselectionchange) | 通知文本框选区变化。 |
* | [OH_InputMethodProxy_NotifyConfigurationChange](capi-inputmethod-inputmethod-proxy-capi-h.
* md#oh_inputmethodproxy_notifyconfigurationchange) | 通知输入框配置变化。 |
* | [OH_InputMethodProxy_NotifyCursorUpdate](capi-inputmethod-inputmethod-proxy-capi-h.
* md#oh_inputmethodproxy_notifycursorupdate) | 通知光标位置变化。 |
* | [OH_InputMethodProxy_SendPrivateCommand](capi-inputmethod-inputmethod-proxy-capi-h.
* md#oh_inputmethodproxy_sendprivatecommand) | 发送私有数据命令。 |
*
*
关联关系:
*
- 与TextEditorProxy的关系：[InputMethod_TextEditorProxy](capi-inputmethod-inputmethod-texteditorproxy.md)负责
* 接收输入法应用的请求和通知，InputMethod_InputMethodProxy负责向输入法服务发送请求和通知。两者在Attach时同时建立关联，构成双向
* 通信通道。
*
- 与AttachOptions的关系：[InputMethod_AttachOptions](capi-inputmethod-inputmethod-attachoptions.md)在Attach时
* 传入，用于配置绑定选项（如是否显示键盘、请求键盘原因等），Attach成功后生成InputMethod_InputMethodProxy实例。
*
* @since 12
*/
typedef struct InputMethod_InputMethodProxy InputMethod_InputMethodProxy;
/**
* @brief 显示键盘。调用此函数后，系统将请求输入法应用弹出软键盘界面，用于文本输入。
*
*
使用场景：当应用需要主动拉起键盘以便用户进行文本输入时调用此函数，例如编辑框获得焦点后需要显示键盘的场景。
*
*
使用后效果：调用成功后，输入法应用将弹出软键盘界面；调用失败后，返回对应的错误码，需根据错误码进行处理。
*
*
前置条件：必须先调用[OH_InputMethodController_Attach](capi-inputmethod-controller-capi-h.
* md#oh_inputmethodcontroller_attach)获取inputMethodProxy实例，且当前处于已绑定（Attached）状态。
*
*
生命周期管理：inputMethodProxy由[OH_InputMethodController_Attach](capi-inputmethod-controller-capi-h.
* md#oh_inputmethodcontroller_attach)创建输出，不可手动销毁。当调用[OH_InputMethodController_Detach]
* (capi-inputmethod-controller-capi-h.md#oh_inputmethodcontroller_detach)解除绑定后，inputMethodProxy将失效，此后再调用此
* 函数将返回IME_ERR_DETACHED错误码。
*
*
调用顺序：OH_InputMethodController_Attach → OH_InputMethodProxy_ShowKeyboard →
* OH_InputMethodProxy_HideKeyboard → OH_InputMethodController_Detach
*
*
线程安全：此函数非线程安全，不建议在多线程环境下同时操作同一个inputMethodProxy对象，如需多线程访问请自行加锁保护。
*
* @param inputMethodProxy 输入指针，表示指向{@link InputMethod_InputMethodProxy}实例的指针。inputMethodProxy由调用
* [OH_InputMethodController_Attach](capi-inputmethod-controller-capi-h.md#oh_inputmethodcontroller_attach)获取。该指针不
* 可为NULL，若传入NULL指针将返回IME_ERR_NULL_POINTER错误码。Detach后该指针失效，不可再用于调用任何InputMethodProxy相关函数。
* @return 返回一个特定的错误码。
*
{@link IME_ERR_OK} - 表示成功，键盘已请求显示。
*
{@link IME_ERR_IMCLIENT} - 输入法客户端错误，可能是客户端内部异常。
*
{@link IME_ERR_IMMS} - 输入法服务错误，可能是输入法管理服务不可用。
*
{@link IME_ERR_DETACHED} - 未绑定输入法，表示已调用Detach，需重新Attach后再使用。
*
{@link IME_ERR_NULL_POINTER} - 非预期的空指针，传入的inputMethodProxy为NULL。
*
具体错误码可以参考{@link InputMethod_ErrorCode}。
* @since 12
*/
InputMethod_ErrorCode OH_InputMethodProxy_ShowKeyboard(InputMethod_InputMethodProxy *inputMethodProxy);
/**
* @brief 显示文本输入框。与ShowKeyboard不同，此接口可通过AttachOptions指定请求键盘输入的原因，系统根据原因决定是否弹出键盘。
*
*
使用场景：当应用需要在特定场景下（如主动切换输入框、恢复输入等）请求显示文本输入界面时调用此函数，特别适用于需要携带
* RequestKeyboardReason的场景。
*
*
使用后效果：调用成功后，系统将根据options中的RequestKeyboardReason决定是否弹出键盘并激活文本输入；调用失败后，返回对
* 应的错误码。
*
*
前置条件：必须先调用[OH_InputMethodController_Attach](capi-inputmethod-controller-capi-h.
* md#oh_inputmethodcontroller_attach)获取inputMethodProxy实例，且当前处于已绑定（Attached）状态。options参数需先通过
* [OH_AttachOptions_Create](capi-inputmethod-attach-options-capi-h.md#oh_attachoptions_create)创建。
*
*
生命周期管理：inputMethodProxy由[OH_InputMethodController_Attach](capi-inputmethod-controller-capi-h.
* md#oh_inputmethodcontroller_attach)创建输出，不可手动销毁。Detach后失效。options的生命周期由调用者管理，使用完毕后需调用
* [OH_AttachOptions_Destroy](capi-inputmethod-attach-options-capi-h.md#oh_attachoptions_destroy)销毁。
*
*
线程安全：此函数非线程安全，不建议在多线程环境下同时操作同一个inputMethodProxy对象。
*
* @param inputMethodProxy 输入指针，表示指向{@link InputMethod_InputMethodProxy}实例的指针。inputMethodProxy由调用
* [OH_InputMethodController_Attach](capi-inputmethod-controller-capi-h.md#oh_inputmethodcontroller_attach)获取。该
* 指针不可为NULL，若传入NULL指针将返回IME_ERR_NULL_POINTER错误码。Detach后该指针失效。
* @param options 输入指针，表示指向{@link InputMethod_AttachOptions}实例的指针，用于获取配置选项。该指针不可为NULL，
* 若传入NULL指针将返回IME_ERR_NULL_POINTER错误码。此接口中只需关注{@link InputMethod_RequestKeyboardReason}属性，表示请
* 求键盘输入的原因。AttachOptions中的ShowKeyboard属性在此接口中始终为true，无需额外关注。
* @return 返回一个特定的错误码。
*
{@link IME_ERR_OK} - 表示成功。
*
{@link IME_ERR_IMCLIENT} - 输入法客户端错误。
*
{@link IME_ERR_IMMS} - 输入法服务错误。
*
{@link IME_ERR_DETACHED} - 未绑定输入法，已Detach需重新Attach。
*
{@link IME_ERR_NULL_POINTER} - 非预期的空指针，inputMethodProxy或options为NULL。
*
具体错误码可以参考{@link InputMethod_ErrorCode}。
* @since 15
*/
InputMethod_ErrorCode OH_InputMethodProxy_ShowTextInput(
InputMethod_InputMethodProxy *inputMethodProxy, InputMethod_AttachOptions *options);
/**
* @brief 隐藏键盘。调用此函数后，系统将请求输入法应用关闭软键盘界面。
*
*
使用场景：当应用需要主动收起键盘时调用此函数，例如编辑框失去焦点、用户完成输入后需要隐藏键盘的场景。
*
*
使用后效果：调用成功后，输入法应用将收起软键盘界面；调用失败后，返回对应的错误码。
*
*
前置条件：必须先调用[OH_InputMethodController_Attach](capi-inputmethod-controller-capi-h.
* md#oh_inputmethodcontroller_attach)获取inputMethodProxy实例，且当前处于已绑定（Attached）状态。
*
*
生命周期管理：inputMethodProxy由[OH_InputMethodController_Attach](capi-inputmethod-controller-capi-h.
* md#oh_inputmethodcontroller_attach)创建输出，不可手动销毁。Detach后失效，再调用此函数将返回IME_ERR_DETACHED。
*
*
线程安全：此函数非线程安全，不建议在多线程环境下同时操作同一个inputMethodProxy对象。
*
* @param inputMethodProxy 输入指针，表示指向{@link InputMethod_InputMethodProxy}实例的指针。inputMethodProxy由调用
* [OH_InputMethodController_Attach](capi-inputmethod-controller-capi-h.md#oh_inputmethodcontroller_attach)获取。该
* 指针不可为NULL，若传入NULL指针将返回IME_ERR_NULL_POINTER错误码。Detach后该指针失效。
* @return 返回一个特定的错误码。
*
{@link IME_ERR_OK} - 表示成功，键盘已请求隐藏。
*
{@link IME_ERR_IMCLIENT} - 输入法客户端错误。
*
{@link IME_ERR_IMMS} - 输入法服务错误。
*
{@link IME_ERR_DETACHED} - 未绑定输入法，已Detach需重新Attach。
*
{@link IME_ERR_NULL_POINTER} - 非预期的空指针。
*
具体错误码可以参考{@link InputMethod_ErrorCode}。
* @since 12
*/
InputMethod_ErrorCode OH_InputMethodProxy_HideKeyboard(InputMethod_InputMethodProxy *inputMethodProxy);
/**
* @brief 通知文本框选区变化。当输入框内文本内容、光标位置或选中文本发生变化时，通过此接口将变更信息通知给输入法应用，使输入法能够
* 感知编辑框的文本状态。
*
*
使用场景：当编辑框中的文本内容被修改、光标位置发生移动、或用户选中文本发生变化时调用此函数，确保输入法应用与编辑框的文
* 本状态保持同步。
*
*
使用后效果：调用成功后，输入法应用将接收到选区变更信息，并据此更新输入法内部状态（如候选词、联想等）；调用失败后，返回
* 对应的错误码。
*
*
前置条件：必须先调用[OH_InputMethodController_Attach](capi-inputmethod-controller-capi-h.
* md#oh_inputmethodcontroller_attach)获取inputMethodProxy实例，且当前处于已绑定（Attached）状态。
*
*
生命周期管理：inputMethodProxy由[OH_InputMethodController_Attach](capi-inputmethod-controller-capi-h.
* md#oh_inputmethodcontroller_attach)创建输出，不可手动销毁。Detach后失效。
*
*
内存管理：text参数为输入指针，由调用者分配内存，函数内部仅读取该数据，不会修改或释放。调用者负责text数组内存的生命周期
* 管理。
*
*
线程安全：此函数非线程安全，不建议在多线程环境下同时操作同一个inputMethodProxy对象。
*
* @param inputMethodProxy 输入指针，表示指向{@link InputMethod_InputMethodProxy}实例的指针。inputMethodProxy由调用
* [OH_InputMethodController_Attach](capi-inputmethod-controller-capi-h.md#oh_inputmethodcontroller_attach)获取。该
* 指针不可为NULL，若传入NULL指针将返回IME_ERR_NULL_POINTER错误码。Detach后该指针失效。
* @param text 输入指针，整个输入文本，采用UTF-16编码。由调用者分配内存，函数仅读取该数据。该指针不可为NULL。长度最大限制为
* 8K（8192个char16_t字符，对应16384字节），超出此限制将返回IME_ERR_PARAMCHECK。
* @param length 输入参数，text参数的字符数量（单位：char16_t字符个数）。取值范围：大于0且不超过8192。超过8192将返回
* IME_ERR_PARAMCHECK错误码。
* @param start 输入参数，所选文本的起始位置（单位：字符偏移量，从0开始计数）。取值范围：大于等于0且小于等于end。取值原则：start
* 应小于等于end，且不超过text的实际长度。
* @param end 输入参数，所选文本的结束位置（单位：字符偏移量，从0开始计数）。取值范围：大于等于start且小于等于text的实际长度。取
* 值原则：当无选中文本时，start与end相等，表示光标位置。
* @return 返回一个特定的错误码。
*
{@link IME_ERR_OK} - 表示成功。
*
{@link IME_ERR_PARAMCHECK} - 参数错误，可能是length超过8K限制、start/end范围不合法等，请检查参数值是否在有效范围
* 内。
*
{@link IME_ERR_IMCLIENT} - 输入法客户端错误。
*
{@link IME_ERR_IMMS} - 输入法服务错误。
*
{@link IME_ERR_DETACHED} - 未绑定输入法，已Detach需重新Attach。
*
{@link IME_ERR_NULL_POINTER} - 非预期的空指针，inputMethodProxy为NULL。
*
具体错误码可以参考{@link InputMethod_ErrorCode}。
* @since 12
*/
InputMethod_ErrorCode OH_InputMethodProxy_NotifySelectionChange(
InputMethod_InputMethodProxy *inputMethodProxy, char16_t text[], size_t length, int start, int end);
/**
* @brief 通知输入框配置变化。当编辑框的回车键类型或输入类型发生变化时，通过此接口将新的配置信息通知给输入法应用，使输入法能够调整
* 键盘布局和输入行为。
*
*
使用场景：当编辑框的输入类型（如从文本模式切换为数字模式）或回车键类型（如从"完成"切换为"搜索"）发生变化时调用此函数。
*
*
使用后效果：调用成功后，输入法应用将根据新的配置调整键盘布局和回车键显示；调用失败后，返回对应的错误码。
*
*
前置条件：必须先调用[OH_InputMethodController_Attach](capi-inputmethod-controller-capi-h.
* md#oh_inputmethodcontroller_attach)获取inputMethodProxy实例，且当前处于已绑定（Attached）状态。
*
*
生命周期管理：inputMethodProxy由[OH_InputMethodController_Attach](capi-inputmethod-controller-capi-h.
* md#oh_inputmethodcontroller_attach)创建输出，不可手动销毁。Detach后失效。
*
*
线程安全：此函数非线程安全，不建议在多线程环境下同时操作同一个inputMethodProxy对象。
*
* @param inputMethodProxy 输入指针，表示指向{@link InputMethod_InputMethodProxy}实例的指针。inputMethodProxy由调用
* [OH_InputMethodController_Attach](capi-inputmethod-controller-capi-h.md#oh_inputmethodcontroller_attach)获取。该
* 指针不可为NULL，若传入NULL指针将返回IME_ERR_NULL_POINTER错误码。Detach后该指针失效。
* @param enterKey 输入参数，回车键类型。取值范围：{@link InputMethod_EnterKeyType}枚举值，如IME_ENTER_KEY_UNSPECIFIED、
* IME_ENTER_KEY_GO、IME_ENTER_KEY_SEARCH等。使用后效果：输入法将据此调整回车键的显示标签和功能。
* @param textType 输入参数，输入框类型。取值范围：{@link InputMethod_TextInputType}枚举值，如
* IME_TEXT_INPUT_TYPE_UNSPECIFIED、
* IME_TEXT_INPUT_TYPE_TEXT、IME_TEXT_INPUT_TYPE_NUMBER等。使用后效果：输入法将据此切换键盘布局（如数字键盘、文本键盘
* 等）。
* @return 返回一个特定的错误码。
*
{@link IME_ERR_OK} - 表示成功。
*
{@link IME_ERR_PARAMCHECK} - 参数错误，可能是enterKey或textType值不合法，请检查枚举值是否在有效范围内。
*
{@link IME_ERR_IMCLIENT} - 输入法客户端错误。
*
{@link IME_ERR_IMMS} - 输入法服务错误。
*
{@link IME_ERR_DETACHED} - 未绑定输入法，已Detach需重新Attach。
*
{@link IME_ERR_NULL_POINTER} - 非预期的空指针。
*
具体错误码可以参考{@link InputMethod_ErrorCode}。
* @since 12
*/
InputMethod_ErrorCode OH_InputMethodProxy_NotifyConfigurationChange(InputMethod_InputMethodProxy *inputMethodProxy,
InputMethod_EnterKeyType enterKey, InputMethod_TextInputType textType);
/**
* @brief 通知光标位置变化。当编辑框中光标位置发生变化时，通过此接口将新的光标信息通知给输入法应用，使输入法能够根据光标位置调整候
* 选词窗口的显示位置。
*
*
使用场景：当编辑框中光标位置发生移动时调用此函数，例如用户点击编辑框中不同位置、代码主动移动光标等场景。
*
*
使用后效果：调用成功后，输入法应用将接收到新的光标信息，并据此调整候选词窗口的定位；调用失败后，返回对应的错误码。
*
*
前置条件：必须先调用[OH_InputMethodController_Attach](capi-inputmethod-controller-capi-h.
* md#oh_inputmethodcontroller_attach)获取inputMethodProxy实例。cursorInfo需先通过[OH_CursorInfo_Create]
* (capi-inputmethod-cursor-info-capi-h.md#oh_cursorinfo_create)创建并设置相关属性。
*
*
生命周期管理：inputMethodProxy由Attach创建输出，不可手动销毁，Detach后失效。cursorInfo的生命周期由调用者管理，使用完
* 毕后需调用[OH_CursorInfo_Destroy](capi-inputmethod-cursor-info-capi-h.md#oh_cursorinfo_destroy)销毁。
*
*
线程安全：此函数非线程安全，不建议在多线程环境下同时操作同一个inputMethodProxy对象。
*
* @param inputMethodProxy 输入指针，表示指向{@link InputMethod_InputMethodProxy}实例的指针。inputMethodProxy由调用
* {@link OH_InputMethodController_Attach}获取。该指针不可为NULL，若传入NULL指针将返回IME_ERR_NULL_POINTER错误码。
* Detach后该指针失效。
* @param cursorInfo 输入指针，指向{@link InputMethod_CursorInfo}实例的指针，表示光标信息。该指针不可为NULL，若传入NULL指针将
* 返回IME_ERR_NULL_POINTER错误码。
* cursorInfo由调用者通过[OH_InputMethodController_Attach](capi-inputmethod-controller-capi-h.
* md#oh_inputmethodcontroller_attach)创建，函数仅读取其内部数据，不会修改或释放。使用完毕后调用者需调用
* {@link OH_CursorInfo_Destroy}释放cursorInfo。
* @return 返回一个特定的错误码。
*
{@link IME_ERR_OK} - 表示成功。
*
{@link IME_ERR_PARAMCHECK} - 参数错误，可能是cursorInfo内部数据不合法，请检查光标信息参数。
*
{@link IME_ERR_IMCLIENT} - 输入法客户端错误。
*
{@link IME_ERR_IMMS} - 输入法服务错误。
*
{@link IME_ERR_DETACHED} - 未绑定输入法，已Detach需重新Attach。
*
{@link IME_ERR_NULL_POINTER} - 非预期的空指针，inputMethodProxy或cursorInfo为NULL。
*
具体错误码可以参考{@link InputMethod_ErrorCode}。
* @since 12
*/
InputMethod_ErrorCode OH_InputMethodProxy_NotifyCursorUpdate(
InputMethod_InputMethodProxy *inputMethodProxy, InputMethod_CursorInfo *cursorInfo);
/**
* @brief 发送私有数据命令。应用通过此接口向输入法应用发送自定义的私有命令数据，用于实现应用与输入法之间的私有通信协议。
*
*
使用场景：当应用需要向输入法应用传递自定义的私有数据（如业务特定的指令、配置参数等）时调用此函数，适用于应用与输入法之
* 间有私有通信协议的场景。
*
*
使用后效果：调用成功后，输入法应用将通过[OH_TextEditorProxy_ReceivePrivateCommandFunc]
* (capi-inputmethod-text-editor-proxy-capi-h.md#oh_texteditorproxy_receiveprivatecommandfunc)回调接收到私有命令数据；调用
* 失败后，返回对应的错误码。
*
*
前置条件：必须先调用[OH_InputMethodController_Attach](capi-inputmethod-controller-capi-h.
* md#oh_inputmethodcontroller_attach)获取inputMethodProxy实例，且当前处于已绑定（Attached）状态。
*
*
生命周期管理：inputMethodProxy由Attach创建输出，不可手动销毁，Detach后失效。privateCommand数组中每个元素的生命周期
* 由调用者管理，使用完毕后需调用[OH_PrivateCommand_Destroy](capi-inputmethod-private-command-capi-h.
* md#oh_privatecommand_destroy)逐个销毁。
*
*
性能建议：privateCommand数组最多包含5个命令对象（size最大为5），超出此限制将返回IME_ERR_PARAMCHECK。单个命令对象最大
* 大小为32KB，超出限制可能导致数据传输失败。
*
*
线程安全：此函数非线程安全，不建议在多线程环境下同时操作同一个inputMethodProxy对象。
*
* @param inputMethodProxy 输入指针，表示指向{@link InputMethod_InputMethodProxy}实例的指针。inputMethodProxy由调用
* [OH_InputMethodController_Attach](capi-inputmethod-controller-capi-h.md#oh_inputmethodcontroller_attach)获取。该
* 指针不可为NULL，若传入NULL指针将返回IME_ERR_NULL_POINTER错误码。Detach后该指针失效。
* @param privateCommand 输入指针，私有命令数组，每个元素为指向InputMethod_PrivateCommand实例的指针。由调用者创建并分配内存，
* 函数仅读取数据。该指针不可为NULL。单个命令对象最大大小为32KB（包含key和value的总大小），超出可能导致传输失败。数组最大长度为5
* （即size参数最大为5）。
* @param size 输入参数，私有命令数组的元素个数。取值范围：大于0且不超过5。超过5将返回IME_ERR_PARAMCHECK错误码。
* @return 返回一个特定的错误码。
*
{@link IME_ERR_OK} - 表示成功，私有命令已发送。
*
{@link IME_ERR_PARAMCHECK} - 参数错误，可能是size超过5、privateCommand为NULL、或单个命令超过32KB，请检查参数值。
*
{@link IME_ERR_IMCLIENT} - 输入法客户端错误。
*
{@link IME_ERR_IMMS} - 输入法服务错误。
*
{@link IME_ERR_DETACHED} - 未绑定输入法，已Detach需重新Attach。
*
{@link IME_ERR_NULL_POINTER} - 非预期的空指针，inputMethodProxy或privateCommand为NULL。
*
具体错误码可以参考{@link InputMethod_ErrorCode}。
* @since 12
*/
InputMethod_ErrorCode OH_InputMethodProxy_SendPrivateCommand(
InputMethod_InputMethodProxy *inputMethodProxy, InputMethod_PrivateCommand *privateCommand[], size_t size);
#ifdef __cplusplus
}
#endif /* __cplusplus */
/** @} */
#endif // INPUTMETHOD_INPUTMETHOD_PROXY_CAP_H