/*
* 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_controller_capi.h
*
* @brief 输入法控制器的头文件，提供绑定（Attach）和解绑（Detach）输入法服务的核心方法，是应用与输入法服务交互的入口和终点。
* Attach必须在创建TextEditorProxy和AttachOptions之后调用，Detach必须在不再使用输入法时调用以释放资源。Attach/Detach必须配对使
* 用。
*
*
功能：通过OH_InputMethodController_Attach将应用绑定到输入法服务，建立双向交互通道；通过
* OH_InputMethodController_Detach将应用从输入法服务解除绑定，关闭交互通道并释放相关资源。
*
*
使用场景：适用于使用NDK开发自绘输入框的应用，需要在应用启动或输入框获得焦点时绑定输入法服务，在应用退出或输入框失去焦点
* 时解绑输入法服务的场景。
*
*
使用后效果：OH_InputMethodController_Attach成功后，应用可通过返回的InputMethodProxy与输入法交互（如显示/隐藏键盘、
* 通知光标更新等），同时输入法可通过TextEditorProxy的回调向应用发送文本插入、删除等通知。OH_InputMethodController_Detach后，交
* 互通道关闭，inputMethodProxy不再有效。
*
* @include
* @library libohinputmethod.so
* @kit IMEKit
* @syscap SystemCapability.MiscServices.InputMethodFramework
* @since 12
* @version 1.0
*/
#ifndef OHOS_INPUTMETHOD_CONTROLLER_CAPI_H
#define OHOS_INPUTMETHOD_CONTROLLER_CAPI_H
#include
#include
#include "inputmethod_text_editor_proxy_capi.h"
#include "inputmethod_inputmethod_proxy_capi.h"
#include "inputmethod_attach_options_capi.h"
#include "../arkui/drag_and_drop.h"
#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */
/**
* @brief 将应用绑定到输入法服务，建立应用与输入法之间的双向交互通道。必须在创建TextEditorProxy和AttachOptions之后调用，绑定成功
* 后，应用可通过返回的InputMethodProxy主动向输入法发送请求和通知，同时输入法可通过TextEditorProxy中注册的回调函数向应用发送文本
* 插入、删除等通知。
*
*
前置条件：
*
1. 必须先通过OH_TextEditorProxy_Create创建InputMethod_TextEditorProxy实例，并通过OH_TextEditorProxy_SetXXXFunc
* 系列函数注册必要的回调（如InsertTextFunc、DeleteForwardFunc、GetTextConfigFunc等）。
*
2. 必须先通过OH_AttachOptions_Create或OH_AttachOptions_CreateWithRequestKeyboardReason创建
* InputMethod_AttachOptions实例。
*
3. TextEditorProxy中注册的回调函数必须已正确实现，否则输入法交互将不完整。
*
*
配对调用：
*
- 调用OH_InputMethodController_Attach后，必须在使用完毕后调用OH_InputMethodController_Detach解除绑定。
*
- 未调用OH_InputMethodController_Detach会导致输入法资源泄漏。
*
- 建议在应用退出或输入框不再需要输入法时及时调用OH_InputMethodController_Detach。
*
*
调用顺序：
*
1. OH_TextEditorProxy_Create → 创建TextEditorProxy
*
2. OH_TextEditorProxy_SetXXXFunc → 注册回调函数
*
3. OH_AttachOptions_Create → 创建AttachOptions
*
4. OH_InputMethodController_Attach → 绑定输入法（返回InputMethodProxy）
*
5. OH_InputMethodProxy_ShowKeyboard / NotifyCursorUpdate 等 → 使用输入法功能
*
6. OH_InputMethodController_Detach → 解绑输入法
*
7. OH_TextEditorProxy_Destroy / OH_AttachOptions_Destroy → 销毁创建的对象
*
*
生命周期管理：
*
- textEditorProxy：调用者自行管理生命周期。若OH_InputMethodController_Attach成功，在下次
* OH_InputMethodController_Attach或OH_InputMethodController_Detach完成之前不可释放textEditorProxy，否则会导致输入法回调时
* 访问无效内存。
*
- options：调用者自行管理生命周期。OH_InputMethodController_Attach调用完成后，options可立即通过
* OH_AttachOptions_Destroy销毁，因为OH_InputMethodController_Attach过程已读取完options中的配置信息。
*
- inputMethodProxy：由OH_InputMethodController_Attach函数通过双指针输出参数分配内存，调用者在
* OH_InputMethodController_Detach之前需保持inputMethodProxy有效，OH_InputMethodController_Detach后该指针不可继续使用。
*
*
线程安全：非线程安全，建议在主线程调用。
* @param textEditorProxy 输入指针，表示指向InputMethod_TextEditorProxy实例的指针。
*
**含义/功能：** 作为应用接收输入法回调通知的通道载体，绑定后输入法将通过此对象中注册的回调函数与应用交互。
*
**使用场景：** 在绑定输入法前，应用需先创建TextEditorProxy并注册必要的回调函数。
*
**使用后效果：** 若OH_InputMethodController_Attach成功，输入法将通过此对象中的回调函数向应用发送通知；若失败，此对象
* 不受影响可继续使用。
*
**前置条件：** 必须通过OH_TextEditorProxy_Create创建，并通过SetXXXFunc系列函数注册回调。
*
**NULL指针处理：** 不可为NULL，传入NULL将返回IME_ERR_NULL_POINTER。
*
**生命周期管理：** 调用者自行管理。若Attach成功，
* 在下次OH_InputMethodController_Attach或OH_InputMethodController_Detach完成之前不可释放textEditorProxy，
* 否则输入法回调时将访问已释放的内存导致未定义行为。
*
**内存分配责任：** 由调用者通过OH_TextEditorProxy_Create分配，通过OH_TextEditorProxy_Destroy释放。
* @param options 输入指针，表示指向InputMethod_AttachOptions实例的指针。
*
**含义/功能：** 指定绑定输入法时的行为配置，包括是否在绑定时显示键盘以及请求键盘的原因。
*
**使用场景：** 在绑定前创建并配置好AttachOptions，用于控制绑定时的键盘显示行为。
*
**使用后效果：** OH_InputMethodController_Attach函数将读取options中的配置参数来决定绑定行为。
*
**前置条件：** 必须通过OH_AttachOptions_Create或OH_AttachOptions_CreateWithRequestKeyboardReason创建。
*
**NULL指针处理：** 不可为NULL，传入NULL将返回IME_ERR_NULL_POINTER。
*
**生命周期管理：** OH_InputMethodController_Attach完成后options可立即销毁，因为绑定过程已读取完配置信息。
* 建议在OH_InputMethodController_Attach成功后调用OH_AttachOptions_Destroy释放内存。
*
**内存分配责任：** 由调用者通过Create函数分配，通过OH_AttachOptions_Destroy释放。
* @param inputMethodProxy 输出双指针，表示指向InputMethod_InputMethodProxy指针的指针。
*
**含义/功能：** 用于接收OH_InputMethodController_Attach成功后返回的InputMethodProxy实例，该实例是应用主动向输入法
* 发送请求和通知的交互通道。
*
**使用场景：** OH_InputMethodController_Attach成功后，调用者通过此指针获取InputMethodProxy，后续调用
* ShowKeyboard、HideKeyboard、 NotifyCursorUpdate等函数时需传入此指针。
*
**使用后效果：** 若OH_InputMethodController_Attach成功，*inputMethodProxy将被赋值为有效的InputMethodProxy指针；
* 若失败，*inputMethodProxy的值不确定，不应使用。
*
**双指针说明：** 此参数为双指针（Pointer to Pointer），
* OH_InputMethodController_Attach函数内部将分配InputMethodProxy的内存并通过此双指针输出给调用者。调用者需提供有效的指针变
* 量地址，不可为NULL。
*
**NULL指针处理：** inputMethodProxy本身不可为NULL，传入NULL将返回IME_ERR_NULL_POINTER。
*
**内存管理：** InputMethodProxy的内存由OH_InputMethodController_Attach函数内部分配，
* 其生命周期由框架管理直到OH_InputMethodController_Detach完成。调用者不可自行释放此内存。
* OH_InputMethodController_Detach后inputMethodProxy指向的内存将被释放，该指针不可继续使用。
*
**相关参数制约：** 此指针仅在OH_InputMethodController_Attach返回IME_ERR_OK时有效；
* OH_InputMethodController_Detach后此指针立即失效，
* 不可继续使用，否则会导致未定义行为或崩溃。
* @return 返回一个特定的错误码。
*
{@link IME_ERR_OK} - 表示成功。此时*inputMethodProxy有效，可用于后续交互。
*
{@link IME_ERR_PARAMCHECK} - 表示参数错误。检查textEditorProxy、options、inputMethodProxy是否为有效指针。
*
{@link IME_ERR_IMCLIENT} - 输入法客户端错误。可能是输入法服务未就绪或连接异常。
*
{@link IME_ERR_IMMS} - 输入法服务错误。可能是系统输入法管理服务异常。
*
{@link IME_ERR_NULL_POINTER} - 非预期的空指针。textEditorProxy、options或inputMethodProxy为NULL时返回。
*
**错误处理建议：** 若返回非IME_ERR_OK，应检查参数有效性后重试；若返回IME_ERR_IMCLIENT或IME_ERR_IMMS，说明服务异常，
* 建议稍后重试。具体错误码可以参考
* {@link InputMethod_ErrorCode}。
* @since 12
*/
InputMethod_ErrorCode OH_InputMethodController_Attach(InputMethod_TextEditorProxy *textEditorProxy,
InputMethod_AttachOptions *options, InputMethod_InputMethodProxy **inputMethodProxy);
/**
* @brief 将应用绑定到输入法服务，同时携带UI上下文信息。适用于需要将输入法与特定UI页面关联的场景（如多窗口场景下指定绑定到哪个页
* 面）。与OH_InputMethodController_Attach的区别在于，此函数额外接受一个ArkUI_ContextHandle参数，用于在多窗口或多页面场景下指
* 定绑定到具体的UI上下文，使输入法服务能精确关联到当前活跃的页面。
*
*
前置条件：
*
1. 必须先获取有效的ArkUI_ContextHandle（通过ArkUI模块创建UI上下文获取）。
*
2. 必须先通过OH_TextEditorProxy_Create创建InputMethod_TextEditorProxy实例，并通过OH_TextEditorProxy_SetXXXFunc
* 系列函数注册必要的回调。
*
3. 必须先通过OH_AttachOptions_Create或OH_AttachOptions_CreateWithRequestKeyboardReason创建
* InputMethod_AttachOptions实例。
*
*
配对调用：
*
- 调用OH_InputMethodController_AttachWithUIContext后，必须在使用完毕后调用OH_InputMethodController_Detach解除绑
* 定。
*
- 未调用OH_InputMethodController_Detach会导致输入法资源泄漏。
*
*
调用顺序：
*
1. 获取ArkUI_ContextHandle
*
2. OH_TextEditorProxy_Create → 创建TextEditorProxy
*
3. OH_TextEditorProxy_SetXXXFunc → 注册回调函数
*
4. OH_AttachOptions_Create → 创建AttachOptions
*
5. OH_InputMethodController_AttachWithUIContext → 绑定输入法（携带UI上下文）
*
6. OH_InputMethodProxy_ShowKeyboard / NotifyCursorUpdate 等 → 使用输入法功能
*
7. OH_InputMethodController_Detach → 解绑输入法
*
8. 销毁创建的对象
*
*
生命周期管理：
*
- context：由ArkUI模块管理，需在绑定期间保持有效。
*
- textEditorProxy：调用者自行管理。若OH_InputMethodController_AttachWithUIContext成功，在下次
* OH_InputMethodController_AttachWithUIContext或OH_InputMethodController_Detach完成之前不可释放。
*
- options：OH_InputMethodController_AttachWithUIContext完成后可立即销毁。
*
- inputMethodProxy：由AttachWithUIContext函数内部分配，OH_InputMethodController_Detach后释放。
*
*
使用场景：适用于多窗口或多页面应用场景，需要将输入法绑定到特定UI页面的场景。当应用有多个UI上下文（如多窗口），使用此函
* 数可确保输入法与正确的页面关联，避免输入法事件发送到错误的窗口。
*
*
线程安全：非线程安全，建议在主线程调用。
*
* @param context 输入指针，表示指向ArkUI_Context实例的指针。
*
**含义/功能：** 指定输入法绑定到哪个UI上下文（页面/窗口），使输入法服务能精确关联到当前活跃的页面。
*
**使用场景：** 在多窗口或多页面应用中，需要将输入法绑定到特定UI上下文时使用。
*
**使用后效果：** 输入法事件将发送到与此上下文关联的页面。
*
**前置条件：** 必须通过ArkUI模块获取有效的ArkUI_ContextHandle。
*
**NULL指针处理：** 不可为NULL，传入NULL将返回IME_ERR_NULL_POINTER。
*
**生命周期管理：** 需在绑定期间保持ArkUI_Context有效，OH_InputMethodController_Detach前不可销毁对应的UI上下文。
* @param textEditorProxy 输入指针，表示指向InputMethod_TextEditorProxy实例的指针。
*
**含义/功能：** 与OH_InputMethodController_Attach中的textEditorProxy参数相同，作为应用接收输入法回调通知的通道载
* 体。使用场景、前置条件、NULL指针处理、
* 生命周期管理均与OH_InputMethodController_Attach中textEditorProxy参数一致。
* @param options 输入指针，表示指向InputMethod_AttachOptions实例的指针。含义/功能：与OH_InputMethodController_Attach中的
* options参数相同，
* 用于指定绑定时的行为配置。使用场景、前置条件、NULL指针处理、生命周期管理均与OH_InputMethodController_Attach中options参数
* 一致。
* @param inputMethodProxy 输出双指针，表示指向InputMethod_InputMethodProxy指针的指针。含义/功能、使用场景、双指针说明、NULL
* 指针处理、内存管理、
* 相关参数制约均与OH_InputMethodController_Attach中的inputMethodProxy参数一致。
* @return 返回一个特定的错误码。
*
{@link IME_ERR_OK} - 表示成功。此时*inputMethodProxy有效，可用于后续交互。
*
{@link IME_ERR_PARAMCHECK} - 表示参数错误。检查context、textEditorProxy、options、inputMethodProxy是否为有效指
* 针。
*
{@link IME_ERR_IMCLIENT} - 输入法客户端错误。
*
{@link IME_ERR_IMMS} - 输入法服务错误。
*
{@link IME_ERR_NULL_POINTER} - 非预期的空指针。context、textEditorProxy、options或inputMethodProxy为NULL时返
* 回。
*
**错误处理建议：** 若返回非IME_ERR_OK，应检查参数有效性后重试；若返回IME_ERR_IMCLIENT或IME_ERR_IMMS，说明服务异常，
* 建议稍后重试。具体错误码可以参考
* {@link InputMethod_ErrorCode}。
* @since 23
*/
InputMethod_ErrorCode OH_InputMethodController_AttachWithUIContext(ArkUI_ContextHandle context,
InputMethod_TextEditorProxy *textEditorProxy, InputMethod_AttachOptions *options,
InputMethod_InputMethodProxy **inputMethodProxy);
/**
* @brief 将应用从输入法服务解除绑定，关闭交互通道。OH_InputMethodController_Detach后，inputMethodProxy不再有效，不可继续使用
* 任何通过inputMethodProxy调用的函数（如ShowKeyboard、HideKeyboard、NotifyCursorUpdate等），否则会导致未定义行为或崩溃。
*
*
前置条件：
*
- 必须先调用OH_InputMethodController_Attach或OH_InputMethodController_AttachWithUIContext成功绑定输入法，并获得
* 有效的inputMethodProxy。
*
*
调用顺序：
*
- 必须先调用OH_InputMethodController_Attach或OH_InputMethodController_AttachWithUIContext绑定输入法。
*
- 调用OH_InputMethodController_Detach完成输入法使用后，不能再使用inputMethodProxy。
*
- OH_InputMethodController_Detach完成后，可安全销毁TextEditorProxy（通过OH_TextEditorProxy_Destroy）。
*
*
错误处理：
*
- 如果inputMethodProxy无效或未绑定，调用OH_InputMethodController_Detach会返回IME_ERR_NULL_POINTER或
* IME_ERR_IMCLIENT。
*
- 重复调用OH_InputMethodController_Detach使用同一个inputMethodProxy可能导致未定义行为，应避免。
*
- OH_InputMethodController_Detach失败后不应继续使用inputMethodProxy。
*
*
生命周期管理：
*
- OH_InputMethodController_Detach后，inputMethodProxy指向的内存由框架释放，调用者不可再使用此指针。
*
- OH_InputMethodController_Detach后，应用可安全销毁TextEditorProxy，因为输入法不再会通过回调访问TextEditorProxy。
*
- 建议OH_InputMethodController_Detach成功后立即调用OH_TextEditorProxy_Destroy和OH_AttachOptions_Destroy释放所有
* 创建的对象。
*
*
线程安全：非线程安全，建议在主线程调用。
*
* @param inputMethodProxy 输入指针，表示指向InputMethod_InputMethodProxy实例的指针。含义/功能：指定要解除绑定的输入法代理实
* 例，
* OH_InputMethodController_Detach将关闭此代理对应的交互通道并释放相关资源。使用场景：在应用不再需要输入法交互时调用，如应用
* 退出、输入框失去焦点等。使用后效果：
* OH_InputMethodController_Detach成功后，inputMethodProxy立即失效，不可继续使用；输入法不再向应用发送回调通知。
*
**前置条件：** 此指针必须由OH_InputMethodController_Attach或OH_InputMethodController_AttachWithUIContext成功返
* 回。
*
**NULL指针处理：** 不可为NULL，传入NULL将返回IME_ERR_NULL_POINTER。
*
**生命周期管理：** 此指针由OH_InputMethodController_Attach/AttachWithUIContext函数分配，
* OH_InputMethodController_Detach成功后由框架释放，调用者不可自行释放，也不可在OH_InputMethodController_Detach后继续使
* 用。
*
**使用注意：** Detach后此指针立即失效，将此指针传入任何InputMethodProxy相关函数会导致未定义行为。
* 同一inputMethodProxy不可重复调用OH_InputMethodController_Detach。
* @return 返回一个特定的错误码。
*
{@link IME_ERR_OK} - 表示成功。解绑完成，inputMethodProxy不再有效。
*
{@link IME_ERR_IMCLIENT} - 表示输入法客户端错误。可能是客户端连接异常或已断开。
*
{@link IME_ERR_IMMS} - 表示输入法服务错误。可能是服务端异常。
*
{@link IME_ERR_NULL_POINTER} - 非预期的空指针。inputMethodProxy为NULL时返回。
*
**错误处理建议：** 若返回IME_ERR_OK，解绑成功，后续可安全销毁所有创建的对象；若返回IME_ERR_IMCLIENT，说明客户端状态
* 异常，建议记录日志并销毁相关对象；
* 若返回IME_ERR_NULL_POINTER，说明传入的指针无效，应检查是否已OH_InputMethodController_Detach或指针已失效。具体错误码可以
* 参考{@link InputMethod_ErrorCode}。
*
* @since 12
*/
InputMethod_ErrorCode OH_InputMethodController_Detach(InputMethod_InputMethodProxy *inputMethodProxy);
#ifdef __cplusplus
}
#endif /* __cplusplus */
/** @} */
#endif // OHOS_INPUTMETHOD_CONTROLLER_CAPI_H