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 79 const char *appPath; 80 81 uint32_t mission; 82 #ifndef OHOS_APPEXECFWK_BMS_BUNDLEMANAGER 83 char *actions; 84 char *entities; 85 #endif 86 } Want; 87 88 #ifdef __cplusplus 89 #if __cplusplus 90 extern "C" { 91 #endif 92 #endif // __cplusplus 93 94 /** 95 * @brief Clears the memory of a specified <b>Want</b> object. 96 * 97 * After calling functions such as {@link SetWantElement}, you should call this function to clear the memory. 98 * 99 * @param want Indicates the pointer to the <b>Want</b> object whose memory is to be released. 100 */ 101 void ClearWant(Want *want); 102 103 /** 104 * @brief Sets key and value to the want which would be passed to remote device to start remote ability. 105 * 106 * @param want Indicates the pointer to the <b>Want</b> object to set. 107 * @param key Indicates the pointer to the key which would be added to the want. 108 * @param keyLen Indicates the length of key. 109 * @param value Indicate the int value which would be added to the want. 110 * 111 * @return Returns <b>true</b> if the setting is successful; returns <b>false</b> otherwise. 112 */ 113 bool SetIntParam(Want *want, const char *key, uint8_t keyLen, int32_t value); 114 115 /** 116 * @brief Sets key and value to the want which would be passed to remote device to start remote ability. 117 * 118 * @param want Indicates the pointer to the <b>Want</b> object to set. 119 * @param key Indicates the pointer to the key which would be added to the want. 120 * @param keyLen Indicates the length of key. 121 * @param value Indicate the pointer to the value which would be added to the want. 122 * @param keyLen Indicates the length of value. 123 * 124 * @return Returns <b>true</b> if the setting is successful; returns <b>false</b> otherwise. 125 */ 126 bool SetStrParam(Want *want, const char *key, uint8_t keyLen, const char *value, uint8_t valueLen); 127 128 /** 129 * @brief Sets the <b>element</b> variable for a specified <b>Want</b> object. 130 * 131 * To start a specified ability, you should call this function to set the {@link ElementName} required for starting 132 * the ability. 133 * 134 * @param want Indicates the pointer to the <b>Want</b> object to set. 135 * @param element Indicates the {@link ElementName} containing information required for starting the ability. 136 * 137 * @return Returns <b>true</b> if the setting is successful; returns <b>false</b> otherwise. 138 */ 139 bool SetWantElement(Want *want, ElementName element); 140 141 /** 142 * @brief Sets data to carry in a specified <b>Want</b> object for starting a particular ability. 143 * 144 * @param want Indicates the pointer to the <b>Want</b> object to set. 145 * @param data Indicates the pointer to the data to set. 146 * @param dataLength Indicates the data length to set. The length must be the same as that of the data specified in 147 * <b>data</b>. 148 * 149 * @return Returns <b>true</b> if the setting is successful; returns <b>false</b> otherwise. 150 */ 151 bool SetWantData(Want *want, const void *data, uint16_t dataLength); 152 153 #ifdef OHOS_APPEXECFWK_BMS_BUNDLEMANAGER 154 155 /** 156 * @brief Sets the <b>sid</b> member variable for a specified <b>Want</b> object. 157 * 158 * When starting an ability, you should call this function to set an {@link SvcIdentity} object if a callback needs 159 * to be invoked after the ability is started successfully. 160 * 161 * @param want Indicates the pointer to the <b>Want</b> object to set. 162 * @param sid Indicates the {@link SvcIdentity} object to set. 163 * 164 * @return Returns <b>true</b> if the setting is successful; returns <b>false</b> otherwise. 165 */ 166 bool SetWantSvcIdentity(Want *want, SvcIdentity sid); 167 168 /** 169 * @brief Converts a specified <b>Want</b> object into a character string. 170 * 171 * @param want Indicates the <b>Want</b> object to convert. 172 * 173 * @return Returns the converted character string if the operation is successful; returns <b>nullptr</b> otherwise. 174 */ 175 const char *WantToUri(Want want); 176 177 /** 178 * @brief Converts a specified character string into a <b>Want</b> object. 179 * 180 * @param uri Indicates the pointer to the character string to convert. 181 * 182 * @return Returns the pointer to the converted <b>Want</b> object if the operation is successful; returns 183 * <b>nullptr</b> otherwise. 184 */ 185 Want *WantParseUri(const char *uri); 186 #endif 187 188 #ifdef __cplusplus 189 #if __cplusplus 190 } 191 #endif 192 #endif // __cplusplus 193 194 #endif // OHOS_WANT_H 195 /** @} */