1 /* 2 * Copyright (c) 2020 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 AbilityKit 18 * @{ 19 * 20 * @brief Provides ability-related functions, including ability lifecycle callbacks and functions for connecting to or 21 * disconnecting from Particle Abilities. 22 * 23 * Abilities are classified into Feature Abilities and Particle Abilities. Feature Abilities support the Page template, 24 * and Particle Abilities support the Service template. An ability using the Page template is called a Page ability for 25 * short and that using the Service template is called a Service ability. 26 * 27 * @since 1.0 28 * @version 1.0 29 */ 30 31 /** 32 * @file want.h 33 * 34 * @brief Declares the structure that provides abstract description of the operation to be performed, including the 35 * ability information and the carried data, and functions for setting data in the structure. 36 * 37 * You can use functions provided in this file to specify information about the ability to start. 38 * 39 * @since 1.0 40 * @version 1.0 41 */ 42 #ifndef OHOS_WANT_H 43 #define OHOS_WANT_H 44 45 #ifdef OHOS_APPEXECFWK_BMS_BUNDLEMANAGER 46 #include <serializer.h> 47 #else 48 #include <stdint.h> 49 #endif 50 51 #include "element_name.h" 52 53 /** 54 * @brief Defines the abstract description of an operation, including information about the ability and the extra data 55 * to carry. 56 */ 57 typedef struct { 58 /** 59 * Pointer to the ability information, including the device ID, bundle name, and class name. 60 */ 61 ElementName *element; 62 #ifdef OHOS_APPEXECFWK_BMS_BUNDLEMANAGER 63 /** 64 * Pointer to the ID of the server that listens for ability startup. After the ability is started, the callback 65 * function corresponding to the server will be invoked. 66 */ 67 SvcIdentity *sid; 68 #endif 69 /** 70 * Pointer to the carried data 71 */ 72 void *data; 73 74 /** 75 * Data length 76 */ 77 uint16_t dataLength; 78 } Want; 79 80 #ifdef __cplusplus 81 #if __cplusplus 82 extern "C" { 83 #endif 84 #endif // __cplusplus 85 86 /** 87 * @brief Clears the memory of a specified <b>Want</b> object. 88 * 89 * After calling functions such as {@link SetWantElement}, you should call this function to clear the memory. 90 * 91 * @param want Indicates the pointer to the <b>Want</b> object whose memory is to be released. 92 */ 93 void ClearWant(Want *want); 94 95 /** 96 * @brief Sets key and value to the want which would be passed to remote deive to start remote ability. 97 * 98 * @param want Indicates the pointer to the <b>Want</b> object to set. 99 * @param key Indicates the pointer to the key which would be added to the want. 100 * @param keyLen Indicates the length of key. 101 * @param value Indicate the int value which would be added to the want. 102 * 103 * @return Returns <b>true</b> if the setting is successful; returns <b>false</b> otherwise. 104 */ 105 bool SetIntParam(Want *want, const char *key, uint8_t keyLen, int32_t value); 106 107 /** 108 * @brief Sets key and value to the want which would be passed to remote deive to start remote ability. 109 * 110 * @param want Indicates the pointer to the <b>Want</b> object to set. 111 * @param key Indicates the pointer to the key which would be added to the want. 112 * @param keyLen Indicates the length of key. 113 * @param value Indicate the pointer to the value which would be added to the want. 114 * @param keyLen Indicates the length of value. 115 * 116 * @return Returns <b>true</b> if the setting is successful; returns <b>false</b> otherwise. 117 */ 118 bool SetStrParam(Want *want, const char *key, uint8_t keyLen, const char *value, uint8_t valueLen); 119 120 /** 121 * @brief Sets the <b>element</b> variable for a specified <b>Want</b> object. 122 * 123 * To start a specified ability, you should call this function to set the {@link ElementName} required for starting 124 * the ability. 125 * 126 * @param want Indicates the pointer to the <b>Want</b> object to set. 127 * @param element Indicates the {@link ElementName} containing information required for starting the ability. 128 * 129 * @return Returns <b>true</b> if the setting is successful; returns <b>false</b> otherwise. 130 */ 131 bool SetWantElement(Want *want, ElementName element); 132 133 /** 134 * @brief Sets data to carry in a specified <b>Want</b> object for starting a particular ability. 135 * 136 * @param want Indicates the pointer to the <b>Want</b> object to set. 137 * @param data Indicates the pointer to the data to set. 138 * @param dataLength Indicates the data length to set. The length must be the same as that of the data specified in 139 * <b>data</b>. 140 * 141 * @return Returns <b>true</b> if the setting is successful; returns <b>false</b> otherwise. 142 */ 143 bool SetWantData(Want *want, const void *data, uint16_t dataLength); 144 145 #ifdef OHOS_APPEXECFWK_BMS_BUNDLEMANAGER 146 147 /** 148 * @brief Sets the <b>sid</b> member variable for a specified <b>Want</b> object. 149 * 150 * When starting an ability, you should call this function to set an {@link SvcIdentity} object if a callback needs 151 * to be invoked after the ability is started successfully. 152 * 153 * @param want Indicates the pointer to the <b>Want</b> object to set. 154 * @param sid Indicates the {@link SvcIdentity} object to set. 155 * 156 * @return Returns <b>true</b> if the setting is successful; returns <b>false</b> otherwise. 157 */ 158 bool SetWantSvcIdentity(Want *want, SvcIdentity sid); 159 160 /** 161 * @brief Converts a specified <b>Want</b> object into a character string. 162 * 163 * @param want Indicates the <b>Want</b> object to convert. 164 * 165 * @return Returns the converted character string if the operation is successful; returns <b>nullptr</b> otherwise. 166 */ 167 const char *WantToUri(Want want); 168 169 /** 170 * @brief Converts a specified character string into a <b>Want</b> object. 171 * 172 * @param uri Indicates the pointer to the character string to convert. 173 * 174 * @return Returns the pointer to the converted <b>Want</b> object if the operation is successful; returns 175 * <b>nullptr</b> otherwise. 176 */ 177 Want *WantParseUri(const char *uri); 178 #endif 179 180 #ifdef __cplusplus 181 #if __cplusplus 182 } 183 #endif 184 #endif // __cplusplus 185 186 #endif // OHOS_WANT_H 187 /** @} */