1 /* 2 * Copyright (C) 2022 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 16 #ifndef ACCESSIBLE_ABILITY_CLIENT_H 17 #define ACCESSIBLE_ABILITY_CLIENT_H 18 19 #include <map> 20 #include <memory> 21 #include "accessibility_element_info.h" 22 #include "accessibility_event_info.h" 23 #include "accessibility_gesture_inject_path.h" 24 #include "accessibility_window_info.h" 25 #include "accessible_ability_listener.h" 26 #include "iremote_object.h" 27 28 namespace OHOS { 29 namespace Accessibility { 30 class AccessibleAbilityClient : public virtual RefBase { 31 public: 32 /** 33 * @brief Destruct 34 */ 35 virtual ~AccessibleAbilityClient() = default; 36 37 /** 38 * @brief Gets an instance of AccessibleAbilityClient. 39 * @return Return an instance of AccessibleAbilityClient. 40 */ 41 static sptr<AccessibleAbilityClient> GetInstance(); 42 43 /** 44 * @brief Gets remote object. 45 * @return Remote object. 46 */ 47 virtual sptr<IRemoteObject> GetRemoteObject() = 0; 48 49 /** 50 * @brief Obtains elementInfo of focus. 51 * @param focusType The type of focus. It contains FOCUS_TYPE_INPUT and FOCUS_TYPE_ACCESSIBILITY. 52 * @param elementInfo The accessibilityElementInfo of focus. 53 * @return Return RET_OK if obtains elementInfo successfully, otherwise refer to the RetError for the failure. 54 */ 55 virtual RetError GetFocus(const int32_t focusType, AccessibilityElementInfo &elementInfo) = 0; 56 57 /** 58 * @brief Obtains elementInfo of focus. 59 * @param sourceInfo The source info to get focus. 60 * @param focusType The type of focus. It contains FOCUS_TYPE_INPUT and FOCUS_TYPE_ACCESSIBILITY. 61 * @param elementInfo The accessibilityElementInfo of focus. 62 * @return Return RET_OK if obtains elementInfo successfully, otherwise refer to the RetError for the failure. 63 */ 64 virtual RetError GetFocusByElementInfo(const AccessibilityElementInfo &sourceInfo, const int32_t focusType, 65 AccessibilityElementInfo &elementInfo) = 0; 66 67 /** 68 * @brief Sends simulate gestures to the screen. 69 * @param gesturePath The gesture which need to send. 70 * @return Return RET_OK if the gesture sends successfully, otherwise refer to the RetError for the failure. 71 */ 72 virtual RetError InjectGesture(const std::shared_ptr<AccessibilityGestureInjectPath> &gesturePath) = 0; 73 74 /** 75 * @brief Obtains elementInfo of the accessible root node. 76 * @param elementInfo The elementInfo of the accessible root node. 77 * @return Return RET_OK if obtains elementInfo successfully, otherwise refer to the RetError for the failure. 78 */ 79 virtual RetError GetRoot(AccessibilityElementInfo &elementInfo) = 0; 80 81 /** 82 * @brief Obtains elementInfo of the accessible root node. 83 * @param windowInfo The source window info to get root. 84 * @param elementInfo The elementInfo of the accessible root node. 85 * @return Return RET_OK if obtains elementInfo successfully, otherwise refer to the RetError for the failure. 86 */ 87 virtual RetError GetRootByWindow(const AccessibilityWindowInfo &windowInfo, 88 AccessibilityElementInfo &elementInfo) = 0; 89 90 /** 91 * @brief Obtains elementInfos of the accessible root node in batchs. 92 * @param elementInfos ElementInfos of the accessible root node and its recursive subnodes. 93 * @return Return RET_OK if obtains elementInfos successfully, otherwise refer to the RetError for the failure. 94 */ 95 virtual RetError GetRootBatch(std::vector<AccessibilityElementInfo>& elementInfos) = 0; 96 97 /** 98 * @brief Obtains elementInfos of the accessible root node in batchs. 99 * @param windowInfo The source window info to get root. 100 * @param elementInfos ElementInfos of the accessible root node and its recursive subnodes. 101 * @param isFilter Indicates whether to filter nodes. 102 * @param needCut Indicates whether to remove invisible nodes. 103 * @return Return RET_OK if obtains elementInfos successfully, otherwise refer to the RetError for the failure. 104 */ 105 virtual RetError GetRootByWindowBatch(const AccessibilityWindowInfo &windowInfo, 106 std::vector<AccessibilityElementInfo>& elementInfos, bool isFilter = false, bool needCut = false) = 0; 107 108 /** 109 * @brief Get the window information related with the event 110 * @param windowId The window id. 111 * @param windowInfo The window information. 112 * @return Return RET_OK if obtains windowInfo successfully, otherwise refer to the RetError for the failure. 113 */ 114 virtual RetError GetWindow(const int32_t windowId, AccessibilityWindowInfo &windowInfo) = 0; 115 116 /** 117 * @brief Obtains the list of interactive windows on the device, in the layers they are visible to users. 118 * @param windows The information of windows. 119 * @return Return RET_OK if obtains windowInfo successfully, otherwise refer to the RetError for the failure. 120 */ 121 virtual RetError GetWindows(std::vector<AccessibilityWindowInfo> &windows) = 0; 122 123 /** 124 * @brief Obtains the list of interactive windows on the device, in the layers they are visible to users. 125 * @param displayId the id of display 126 * @param windows The information of windows. 127 * @return Return RET_OK if obtains windowInfo successfully, otherwise refer to the RetError for the failure. 128 */ 129 virtual RetError GetWindows(const uint64_t displayId, std::vector<AccessibilityWindowInfo> &windows) = 0; 130 131 /** 132 * @brief Gets the next focused node in the specified direction of the currently focused node. 133 * @param elementInfo The source info to get next info. 134 * @param direction Indicates the direction to obtain the next focused node. Refer to FocusMoveDirection 135 * @param nextElementInfo The info of next element. 136 * @return Return RET_OK if gets next elementInfo successfully, otherwise refer to the RetError for the failure. 137 */ 138 virtual RetError GetNext(const AccessibilityElementInfo &elementInfo, const FocusMoveDirection direction, 139 AccessibilityElementInfo &nextElementInfo) = 0; 140 141 /** 142 * @brief Get the child node information by child index. 143 * @param index The index of the child. 144 * @param parent The parent info to get child. 145 * @param child The element info of child. 146 * @return Return RET_OK if gets child elementInfo successfully, otherwise refer to the RetError for the failure. 147 */ 148 virtual RetError GetChildElementInfo(const int32_t index, const AccessibilityElementInfo &parent, 149 AccessibilityElementInfo &child) = 0; 150 151 /** 152 * @brief Get the children node information 153 * @param parent The parent info to get children. 154 * @param children The element info of children. 155 * @return Return RET_OK if gets children elementInfo successfully, otherwise refer to the RetError for the failure. 156 */ 157 virtual RetError GetChildren(const AccessibilityElementInfo &parent, 158 std::vector<AccessibilityElementInfo> &children) = 0; 159 160 /** 161 * @brief Searches for node information based on the specified content. 162 * @param elementInfo The source info. 163 * @param text specified content 164 * @param elementInfos The element infos of specified content. 165 * @return Return RET_OK if gets elementInfos successfully, otherwise refer to the RetError for the failure. 166 */ 167 virtual RetError GetByContent(const AccessibilityElementInfo &elementInfo, const std::string &text, 168 std::vector<AccessibilityElementInfo> &elementInfos) = 0; 169 170 /** 171 * @brief Get the node information related with the event 172 * @param eventInfo The source info to get source. 173 * @param elementInfo The element info of source. 174 * @return Return RET_OK if gets elementInfos successfully, otherwise refer to the RetError for the failure. 175 */ 176 virtual RetError GetSource(const AccessibilityEventInfo &eventInfo, AccessibilityElementInfo &elementInfo) = 0; 177 178 /** 179 * @brief Get Parent node information 180 * @param child The child element info to get parent. 181 * @param parent The parent element info. 182 * @return Return RET_OK if gets info successfully, otherwise refer to the RetError for the failure. 183 */ 184 virtual RetError GetParentElementInfo(const AccessibilityElementInfo &child, AccessibilityElementInfo &parent) = 0; 185 186 /** 187 * @brief Get node information based on element id in active window. 188 * @param elementId The target element id. 189 * @param windowId The target window id. 190 * @param targetElementInfo The element info of specified content. 191 * @return Return RET_OK if gets info successfully, otherwise refer to the RetError for the failure. 192 */ 193 virtual RetError GetByElementId(const int64_t elementId, const int32_t windowId, 194 AccessibilityElementInfo &targetElementInfo) = 0; 195 196 /** 197 * @brief Get node information based on inspectorKey in active window. 198 * @param inspectorKey The target inspectorKey. 199 * @param elementInfo The element info of specified content. 200 * @return Return RET_OK if gets info successfully, otherwise refer to the RetError for the failure. 201 */ 202 virtual RetError SearchElementInfoByInspectorKey(const std::string &inspectorKey, 203 AccessibilityElementInfo &elementInfo) = 0; 204 205 /** 206 * @brief Executes a specified action. 207 * @param elementInfo The source info to execute action. 208 * @param action: the action type 209 * @param actionArguments: The parameter for action type. such as: 210 * action: ACCESSIBILITY_ACTION_NEXT_HTML_ITEM, 211 * actionArguments(ACTION_ARGU_HTML_ELEMENT,HtmlItemType) 212 * action: ACCESSIBILITY_ACTION_PREVIOUS_HTML_ITEM, 213 * actionArguments(ACTION_ARGU_HTML_ELEMENT,HtmlItemType) 214 * action: ACCESSIBILITY_ACTION_NEXT_TEXT, 215 * actionArguments(ACTION_ARGU_MOVE_UNIT,MOVE_UNIT_XXX) 216 * action: ACCESSIBILITY_ACTION_PREVIOUS_TEXT, 217 * actionArguments(ACTION_ARGU_MOVE_UNIT,MOVE_UNIT_XXX) 218 * action: ACCESSIBILITY_ACTION_SET_SELECTION, 219 * actionArguments({ACTION_ARGU_SELECT_TEXT_START,"1"(start location)}, 220 * {ACTION_ARGU_SELECT_TEXT_END,"10"(end location)}) 221 * action: ACCESSIBILITY_ACTION_SET_TEXT, 222 * actionArguments(ACTION_ARGU_SET_TEXT,"the text of setted") 223 * @return Return RET_OK if performs action succeed, otherwise refer to the RetError for the failure. 224 */ 225 virtual RetError ExecuteAction(const AccessibilityElementInfo &elementInfo, const ActionType action, 226 const std::map<std::string, std::string> &actionArguments) = 0; 227 228 /** 229 * @brief Enable status value. 230 * @param isEnable flag Screen Curtain. 231 * @return Return RET_OK if registers listener successfully, otherwise refer to the RetError for the failure. 232 */ 233 virtual RetError EnableScreenCurtain(bool isEnable) = 0; 234 235 /** 236 * @brief To return the result of cursor position. 237 * @param elementInfo The source info to cursor position. 238 * @param position: The position of the cursor to get. 239 */ 240 virtual RetError GetCursorPosition(const AccessibilityElementInfo &elementInfo, int32_t &position) = 0; 241 /** 242 * @brief Register ability listener. 243 * @param listener The listener to add. 244 * @return Return RET_OK if registers listener successfully, otherwise refer to the RetError for the failure. 245 */ 246 virtual RetError RegisterAbilityListener(const std::shared_ptr<AccessibleAbilityListener> &listener) = 0; 247 248 /** 249 * @brief Set target bundle names. 250 * @param targetBundleNames The target bundle name 251 * @return Return RET_OK if sets target bundle names successfully, otherwise refer to the RetError for the failure. 252 */ 253 virtual RetError SetTargetBundleName(const std::vector<std::string> &targetBundleNames) = 0; 254 255 /** 256 * @brief Set cache mode. 257 * The mode is used for functions: GetRoot, GetRootByWindow, GetChildElementInfo, 258 * GetChildren, GetSource, GetParentElementInfo. 259 * @param cacheMode The cache mode. It includes: 260 * PREFETCH_PREDECESSORS: cache the parent node info also. 261 * PREFETCH_SIBLINGS: cache the sister/brothers node info also. 262 * PREFETCH_CHILDREN: cache the child node info also. 263 * otherwise: no cache. 264 * @return Return RET_OK if sets cache mode successfully, otherwise refer to the RetError for the failure. 265 */ 266 virtual RetError SetCacheMode(const int32_t cacheMode) = 0; 267 268 /** 269 * @brief Find the node information by accessibility ID. 270 * @param accessibilityWindowId The window id that the component belongs to. 271 * @param elementId: The unique id of the component ID. 272 * @param mode PREFETCH_PREDECESSORS: Need to make the parent node info also. 273 * PREFETCH_SIBLINGS: Need to make the sister/brothers node info also. 274 * PREFETCH_CHILDREN: Need to make the child node info also. 275 * otherwise: Make the node information by elementId only. 276 * @param info[out] The components information matched conditions searched. 277 * @return Return RET_OK if search element info successfully, otherwise refer to the RetError for the failure. 278 */ 279 virtual RetError SearchElementInfoByAccessibilityId(const int32_t windowId, const int64_t elementId, 280 const uint32_t mode, AccessibilityElementInfo &info, bool isFilter = false) = 0; 281 282 /** 283 * @brief Search all child nodes 284 * @param windowId The target window id. 285 * @param elementId The target element id. 286 * @param elementInfos The element infos of specified content. 287 * @return Return RET_OK if gets all child nodes successfully, otherwise refer to the RetError for the failure. 288 */ 289 virtual RetError GetElements(const int32_t windowId, const int64_t elementId, 290 std::vector<AccessibilityElementInfo> &elementInfos) = 0; 291 292 /** 293 * @brief Search Default Focused ElementId 294 * @param windowId The target window id. 295 * @param elementInfos The element infos of specified content. 296 * @return Return RET_OK if gets all Default Focused successfully, otherwise refer to the RetError for the failure. 297 */ 298 virtual RetError GetDefaultFocusedElementIds(const int32_t windowId, 299 std::vector<AccessibilityElementInfo> &elementInfos) = 0; 300 }; 301 } // namespace Accessibility 302 } // namespace OHOS 303 #endif // ACCESSIBLE_ABILITY_CLIENT_H