typedef struct InputMethod_InputMethodProxy InputMethod_InputMethodProxy
Overview
Provides an interaction proxy object between the app and the input method service. The app can call relevant APIs of the input method service and receive event callbacks from the input method service through this object. This struct is an opaque type. Its internal members shall not be accessed directly. Operations can only be performed through the function interfaces provided by this module.
Since: 12
Related module: InputMethod
Header file: inputmethod_inputmethod_proxy_capi.h
Struct Purpose
InputMethod_InputMethodProxy is the core proxy object for interaction between the app and the input method service. It is used to send requests and notifications to the input method service. With this proxy object, the app can show or hide the keyboard, notify the input method of changes to text selection ranges and configurations in the edit field, update the cursor position, and transmit private command data.
Lifecycle Management
- Creation: Created by the OH_InputMethodController_Attach function and returned as an output parameter. This object cannot be manually created.
- Destruction: Manual destruction is prohibited. After OH_InputMethodController_Detach is called to terminate attachment, the InputMethod_InputMethodProxy object will be automatically released by the system and become invalid.
- Validity: InputMethod_InputMethodProxy is only valid between an attach call and the corresponding detach call. After detachment, all functions called via this object return the error code IME_ERR_DETACHED, and the object must no longer be used.
- Repeated creation and destruction: Repeated destruction is not supported. Each attach call generates a new InputMethod_InputMethodProxy instance, and the corresponding detach call invalidates that instance.
Usage Notes
- Before calling any InputMethod_InputMethodProxy-related functions, ensure that the object has been successfully obtained via OH_InputMethodController_Attach and the detach function has not been called.
- The inputMethodProxy pointer must not be NULL. Passing a null pointer results in the error code IME_ERR_NULL_POINTER. Example: This error occurs if a function is called when the null pointer is not checked beforehand. Check whether the pointer is null before invocation. If it is null, obtain a valid object via the attach function first or abort the call.
- After Detach is called, the obtained inputMethodProxy pointer cannot be used again; all operations will return IME_ERR_DETACHED. Example: This code is returned when any API is called after Detach. Check the lifecycle state and use the object only between Attach and Detach; otherwise, call Attach again. This object is an opaque type. It cannot directly access its internal members or perform memory operations (such as malloc/free).
- Not thread-safe. Concurrent operations on the same inputMethodProxy object in a multi-threaded environment are not recommended. Implement locking protection if multi-threaded access is required.
Related functions:
The following functions can be called via an InputMethod_InputMethodProxy object:
Relationships:
- Relationship with TextEditorProxy: InputMethod_TextEditorProxy receives requests and notifications from the input method app, while InputMethod_InputMethodProxy sends requests and notifications to the input method service. The two objects are linked when the attach function is called and form a bidirectional communication channel.
- Relationship with AttachOptions: InputMethod_AttachOptions is passed in when the attach function is called to configure attachment options (such as whether to show the keyboard and the reason for requesting the keyboard). An InputMethod_InputMethodProxy instance is created upon a successful attach call.