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 16 /** 17 * @addtogroup AbilityBase 18 * @{ 19 * 20 * @brief Describe the functions of want. 21 * 22 * @syscap SystemCapability.Ability.AbilityBase 23 * @since 15 24 */ 25 26 /** 27 * @file want.h 28 * 29 * @brief Defines the want APIs. 30 * 31 * @library libability_base_want.so 32 * @kit AbilityKit 33 * @syscap SystemCapability.Ability.AbilityBase 34 * @since 15 35 */ 36 37 #ifndef ABILITY_BASE_WANT_H 38 #define ABILITY_BASE_WANT_H 39 40 #include <stddef.h> 41 #include <stdint.h> 42 #include "ability_base_common.h" 43 44 #ifdef __cplusplus 45 extern "C" { 46 #endif 47 48 /** 49 * @brief Indicates information of element. 50 * 51 * @since 15 52 */ 53 typedef struct AbilityBase_Element { 54 /** Indicates the name of application. */ 55 char* bundleName; 56 /** Indicates the name of module. */ 57 char* moduleName; 58 /** Indicates the name of ability. */ 59 char* abilityName; 60 } AbilityBase_Element; 61 62 struct AbilityBase_Want; 63 typedef struct AbilityBase_Want AbilityBase_Want; 64 65 /** 66 * @brief Create want. 67 * 68 * @param element Information of element. 69 * @return Returns the newly created AbilityBase_Want object. 70 * 71 * @since 15 72 */ 73 AbilityBase_Want* OH_AbilityBase_CreateWant(AbilityBase_Element element); 74 75 /** 76 * @brief Destroy input want. 77 * 78 * @param want The want to be deleted. 79 * @return The error code. 80 * {@link ABILITY_BASE_ERROR_CODE_NO_ERROR} if the operation is successful. 81 * {@link ABILITY_BASE_ERROR_CODE_PARAM_INVALID} if the want is invalid. 82 * @since 15 83 */ 84 AbilityBase_ErrorCode OH_AbilityBase_DestroyWant(AbilityBase_Want* want); 85 86 /** 87 * @brief Set want element. 88 * 89 * @param want The want that needs to be set element. 90 * @param element Information of element. 91 * @return The error code. 92 * {@link ABILITY_BASE_ERROR_CODE_NO_ERROR} if the operation is successful. 93 * {@link ABILITY_BASE_ERROR_CODE_PARAM_INVALID} if the want is invalid. 94 * @since 15 95 */ 96 AbilityBase_ErrorCode OH_AbilityBase_SetWantElement(AbilityBase_Want* want, AbilityBase_Element element); 97 98 /** 99 * @brief Get want element. 100 * 101 * @param want The want for the element that has been obtained. 102 * @param element The element obtained from want. 103 * @return The error code. 104 * {@link ABILITY_BASE_ERROR_CODE_NO_ERROR} if the operation is successful. 105 * {@link ABILITY_BASE_ERROR_CODE_PARAM_INVALID} if the want or element is invalid. 106 * @since 15 107 */ 108 AbilityBase_ErrorCode OH_AbilityBase_GetWantElement(AbilityBase_Want* want, AbilityBase_Element* element); 109 110 /** 111 * @brief Set want char param. 112 * 113 * @param want The want needs to be set char param. 114 * @param key The key of char param. 115 * @param value The value of char param. 116 * @return The error code. 117 * {@link ABILITY_BASE_ERROR_CODE_NO_ERROR} if the operation is successful. 118 * {@link ABILITY_BASE_ERROR_CODE_PARAM_INVALID} if the input parameters are invalid. 119 * @since 15 120 */ 121 AbilityBase_ErrorCode OH_AbilityBase_SetWantCharParam(AbilityBase_Want* want, const char* key, const char* value); 122 123 /** 124 * @brief Get want char param. 125 * 126 * @param want The want for the char param that has been obtained. 127 * @param key The key of char param. 128 * @param value The value of char param. 129 * @param valueSize Size of the value. 130 * @return The error code. 131 * {@link ABILITY_BASE_ERROR_CODE_NO_ERROR} if the operation is successful. 132 * {@link ABILITY_BASE_ERROR_CODE_PARAM_INVALID} if the input parameters are invalid. 133 * @since 15 134 */ 135 AbilityBase_ErrorCode OH_AbilityBase_GetWantCharParam(AbilityBase_Want* want, const char* key, 136 char* value, size_t valueSize); 137 138 /** 139 * @brief Add fd to want. 140 * 141 * @param want The want needs to be add fd. 142 * @param key The key of the fd. 143 * @param fd File Descriptor. 144 * @return The error code. 145 * {@link ABILITY_BASE_ERROR_CODE_NO_ERROR} if the operation is successful. 146 * {@link ABILITY_BASE_ERROR_CODE_PARAM_INVALID} if the input parameters are invalid. 147 * @since 15 148 */ 149 AbilityBase_ErrorCode OH_AbilityBase_AddWantFd(AbilityBase_Want* want, const char* key, int32_t fd); 150 151 /** 152 * @brief Get fd from want. 153 * 154 * @param want The want that includes fd. 155 * @param key The key of the fd. 156 * @param fd File Descriptor. 157 * @return The error code. 158 * {@link ABILITY_BASE_ERROR_CODE_NO_ERROR} if the operation is successful. 159 * {@link ABILITY_BASE_ERROR_CODE_PARAM_INVALID} if the input parameters are invalid. 160 * @since 15 161 */ 162 AbilityBase_ErrorCode OH_AbilityBase_GetWantFd(AbilityBase_Want* want, const char* key, int32_t* fd); 163 164 /** 165 * @brief Set uri to want. 166 * 167 * @param want The want needs to set uri. 168 * @param uri The uri of the want. 169 * @return The error code. 170 * {@link ABILITY_BASE_ERROR_CODE_NO_ERROR} if the operation is successful. 171 * {@link ABILITY_BASE_ERROR_CODE_PARAM_INVALID} if the input parameters are invalid. 172 * @since 17 173 */ 174 AbilityBase_ErrorCode OH_AbilityBase_SetWantUri(AbilityBase_Want* want, const char* uri); 175 176 /** 177 * @brief Get uri from want. 178 * 179 * @param want The want that includes uri. 180 * @param uri The uri of the want. 181 * @param uriSize Size of the uri. 182 * @return The error code. 183 * {@link ABILITY_BASE_ERROR_CODE_NO_ERROR} if the operation is successful. 184 * {@link ABILITY_BASE_ERROR_CODE_PARAM_INVALID} if the input parameters are invalid. 185 * @since 17 186 */ 187 AbilityBase_ErrorCode OH_AbilityBase_GetWantUri(AbilityBase_Want* want, char* uri, size_t uriSize); 188 189 /** 190 * @brief Set int32_t to want. 191 * 192 * @param want The want needs to set int32_t value. 193 * @param key The key of int32_t param. 194 * @param value The value of int32_t param. 195 * @return The error code. 196 * {@link ABILITY_BASE_ERROR_CODE_NO_ERROR} if the operation is successful. 197 * {@link ABILITY_BASE_ERROR_CODE_PARAM_INVALID} if the input parameters are invalid. 198 * @since 17 199 */ 200 AbilityBase_ErrorCode OH_AbilityBase_SetWantInt32Param(AbilityBase_Want* want, const char* key, int32_t value); 201 202 /** 203 * @brief Get int32_t from want. 204 * 205 * @param want The want includes int32_t value. 206 * @param key The key of int32_t param. 207 * @param value The value of int32_t param. 208 * @return The error code. 209 * {@link ABILITY_BASE_ERROR_CODE_NO_ERROR} if the operation is successful. 210 * {@link ABILITY_BASE_ERROR_CODE_PARAM_INVALID} if the input parameters are invalid. 211 * @since 17 212 */ 213 AbilityBase_ErrorCode OH_AbilityBase_GetWantInt32Param(AbilityBase_Want* want, const char* key, int32_t* value); 214 215 /** 216 * @brief Set bool to want. 217 * 218 * @param want The want needs to set bool value. 219 * @param key The key of bool param. 220 * @param value The value of bool param. 221 * @return The error code. 222 * {@link ABILITY_BASE_ERROR_CODE_NO_ERROR} if the operation is successful. 223 * {@link ABILITY_BASE_ERROR_CODE_PARAM_INVALID} if the input parameters are invalid. 224 * @since 17 225 */ 226 AbilityBase_ErrorCode OH_AbilityBase_SetWantBoolParam(AbilityBase_Want* want, const char* key, bool value); 227 228 /** 229 * @brief Get bool from want. 230 * 231 * @param want The want needs to set bool value. 232 * @param key The key of bool param. 233 * @param value The value of bool param. 234 * @return The error code. 235 * {@link ABILITY_BASE_ERROR_CODE_NO_ERROR} if the operation is successful. 236 * {@link ABILITY_BASE_ERROR_CODE_PARAM_INVALID} if the input parameters are invalid. 237 * @since 17 238 */ 239 AbilityBase_ErrorCode OH_AbilityBase_GetWantBoolParam(AbilityBase_Want* want, const char* key, bool* value); 240 241 /** 242 * @brief Set double to want. 243 * 244 * @param want The want needs to set double value. 245 * @param key The key of double param. 246 * @param value The value of double param. 247 * @return The error code. 248 * {@link ABILITY_BASE_ERROR_CODE_NO_ERROR} if the operation is successful. 249 * {@link ABILITY_BASE_ERROR_CODE_PARAM_INVALID} if the input parameters are invalid. 250 * @since 17 251 */ 252 AbilityBase_ErrorCode OH_AbilityBase_SetWantDoubleParam(AbilityBase_Want* want, const char* key, double value); 253 254 /** 255 * @brief Get double from want. 256 * 257 * @param want The want needs to set double value. 258 * @param key The key of double param. 259 * @param value The value of double param. 260 * @return The error code. 261 * {@link ABILITY_BASE_ERROR_CODE_NO_ERROR} if the operation is successful. 262 * {@link ABILITY_BASE_ERROR_CODE_PARAM_INVALID} if the input parameters are invalid. 263 * @since 17 264 */ 265 AbilityBase_ErrorCode OH_AbilityBase_GetWantDoubleParam(AbilityBase_Want* want, const char* key, double* value); 266 267 #ifdef __cplusplus 268 } // extern "C" 269 #endif 270 271 /** @} */ 272 #endif // ABILITY_BASE_WANT_H 273