1 /* 2 * Copyright (c) 2021 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 BASE_NOTIFICATION_ANS_STANDARD_KITS_NATIVE_INCLUDE_NOTIFICATION_USER_INPUT_H 17 #define BASE_NOTIFICATION_ANS_STANDARD_KITS_NATIVE_INCLUDE_NOTIFICATION_USER_INPUT_H 18 19 #include "notification_constant.h" 20 #include "notification_json_convert.h" 21 #include "parcel.h" 22 #include "uri.h" 23 #include "want.h" 24 25 namespace OHOS { 26 namespace Notification { 27 class NotificationUserInput : public Parcelable, public NotificationJsonConvertionBase { 28 public: 29 /** 30 * Sets the input source of this NotificationUserInput object. 31 * @param want Indicates the Want to which the input result is to be added. 32 * @param source Indicates the input source. For available values, see NotificationConstant::InputSource. 33 */ 34 static void SetInputsSource(AAFwk::Want &want, NotificationConstant::InputsSource source); 35 36 /** 37 * Obtains the input source of this NotificationUserInput object. 38 * @param want Indicates the Want containing the input result. 39 * @return the input source of this NotificationUserInput object, 40 * as enumerated in NotificationConstant::InputSource. 41 */ 42 static NotificationConstant::InputsSource GetInputsSource(const AAFwk::Want &want); 43 44 /** 45 * Adds a list of NotificationUserInput objects to a Want. This method should only be called by user input 46 * collection services when sending input results to an WantAgent. 47 * @param userInputs Indicates the list of NotificationUserInput objects for which the input results are provided. 48 * @param want Indicates the Want to which the input results are to be added. 49 * @param additional Indicates the AAFwk::WantParams object holding the input results. 50 * The AAFwk::WantParams key must match the keys contained in the objects specified in userInputs. 51 */ 52 static void AddInputsToWant(const std::vector<std::shared_ptr<NotificationUserInput>> &userInputs, 53 AAFwk::Want &want, const AAFwk::WantParams &additional); 54 55 /** 56 * Obtains the input text results from a specified Want. 57 * @param want Indicates the Want object containing one or more user input results. 58 * @return the AAFwk::WantParams object containing the input text results. 59 */ 60 static std::shared_ptr<AAFwk::WantParams> GetInputsFromWant(const AAFwk::Want &want); 61 62 /** 63 * Adds the given NotificationUserInput object of a specified MIME type to an Want. This method is similar to 64 * addInputsToWant(NotificationUserInput, Want, AAFwk::WantParams) except that the MIME type must be specified. 65 * @param userInput Indicates the NotificationUserInput object for which the input results are provided. 66 * @param want Indicates the Want to which the input results are to be added. 67 * @param results Indicates a map containing the MIME type and its URI result. 68 */ 69 static void AddMimeInputToWant(const NotificationUserInput &userInput, AAFwk::Want &want, 70 const std::map<std::string, std::shared_ptr<Uri>> &results); 71 72 /** 73 * Obtains the input results of a particular MIME type from a specified Want. This method is similar to 74 * GetInputsFromWant(Want) but uses the key of the NotificationUserInput. 75 * @param want Indicates the Want object containing one or more user input results. 76 * @param inputKey Indicates the key of the NotificationUserInput results to obtain. 77 * @return a map containing the MIME type and its URI result. 78 */ 79 static std::map<std::string, std::shared_ptr<Uri>> GetMimeInputsFromWant( 80 const AAFwk::Want &want, const std::string &inputKey); 81 82 public: 83 /** 84 * A static function used to create a NotificationUserInput instance with the input parameters passed. 85 * @param inputKey Indicates the AAFwk::WantParams key used to identify this input 86 * when the input is collected from the user. 87 * @return the shared_ptr object owns the created NotificationUserInput object otherwise return empty object if 88 * inputKey is empty. 89 */ 90 static std::shared_ptr<NotificationUserInput> Create(const std::string &inputKey); 91 92 /** 93 * A static function used to create a NotificationUserInput instance with the input parameters passed. 94 * @param inputKey Indicates the AAFwk::WantParams key used to identify this input 95 * when the input is collected from the user. 96 * @param tag Indicates the tag to be displayed. 97 * @param options Indicates the list of predefined options to be provided for user input. 98 * @param permitFreeFormInput Specifies whether to allow arbitrary text values. The default value is true, 99 * indicating that arbitrary text values are allowed. If this parameter is set to false, you must pass a non-empty 100 * std::vector of options or a non-empty std::set of permitMimeTypes. Otherwise, return empty object. 101 * @param permitMimeTypes Indicates the MIME type allowed. 102 * @param additional Indicates the AAFwk::WantParams object containing the additional data. 103 * @param editType Indicates the edit type to set. For details about available values, see 104 * NotificationConstant::InputEditType. 105 * @return the shared_ptr object owns the created NotificationUserInput object otherwise return empty object if 106 * permitFreeFormInput is false but editType is InputEditType::EDIT_ENABLED. 107 */ 108 static std::shared_ptr<NotificationUserInput> Create(const std::string &inputKey, const std::string &tag, 109 const std::vector<std::string> &options, bool permitFreeFormInput, const std::set<std::string> &permitMimeTypes, 110 const std::shared_ptr<AAFwk::WantParams> &additional, NotificationConstant::InputEditType editType); 111 112 /** 113 * Default deconstructor used to deconstruct. 114 */ 115 ~NotificationUserInput() = default; 116 117 /** 118 * Obtains the key of this NotificationUserInput object. 119 * @return the key of this NotificationUserInput object. 120 */ 121 std::string GetInputKey() const; 122 123 /** 124 * Adds additional data to this Builder. 125 * The value of AAFwk::WantParams will replace the existing extras value in this Builder. 126 * @param additional Indicates the AAFwk::WantParams object containing the additional data. 127 */ 128 void AddAdditionalData(AAFwk::WantParams &additional); 129 130 /** 131 * Obtains the additional data included in this NotificationUserInput object. 132 * @return the additional data in this NotificationUserInput object. 133 */ 134 const std::shared_ptr<AAFwk::WantParams> GetAdditionalData() const; 135 136 /** 137 * Sets the edit type of the options provided by this NotificationUserInput object. 138 * The edit type determines whether an option can be edited when the user taps the option. 139 * @param inputEditType Indicates the edit type to set. For details about available values, 140 * see NotificationConstant::InputEditType. 141 */ 142 void SetEditType(NotificationConstant::InputEditType inputEditType); 143 144 /** 145 * Obtains the edit type of the options provided by this NotificationUserInput object. 146 * @return the edit type of options. 147 */ 148 NotificationConstant::InputEditType GetEditType() const; 149 150 /** 151 * Sets the options provided to users to satisfy user input needs. All options are displayed in a single line. 152 * Due to limited space, some or all of the options may be hidden if the options are too long or 153 * there are too many options. 154 * @param options Indicates the list of predefined options to be provided for user input. 155 */ 156 void SetOptions(const std::vector<std::string> &options); 157 158 /** 159 * Obtains the options provided to the user to satisfy user input needs. 160 * @return the list of predefined options. 161 */ 162 std::vector<std::string> GetOptions() const; 163 164 /** 165 * Sets whether users can input values of the given MIME type. 166 * @param mimeType Indicates the MIME type allowed. 167 * @param doPermit Specifies whether to allow the given MIME type. 168 * The value true means to allow it, and the value false means not. 169 */ 170 void SetPermitMimeTypes(const std::string &mimeType, bool doPermit); 171 172 /** 173 * Obtains the MIME types allowed by this NotificationUserInput object. 174 * @return the list of allowed MIME types. 175 */ 176 std::set<std::string> GetPermitMimeTypes() const; 177 178 /** 179 * Checks whether this NotificationUserInput object allows only values of particular MIME types. 180 * @return true if this object allows only values of particular MIME types; returns false otherwise. 181 */ 182 bool IsMimeTypeOnly() const; 183 184 /** 185 * Sets the tag to be displayed to the user when collecting this input from the user. 186 * @param tag Indicates the tag to be displayed. 187 */ 188 void SetTag(const std::string tag); 189 190 /** 191 * Obtains the tag to be displayed to the user when collecting this input from the user. 192 * @return the tag to be displayed to the user. 193 */ 194 std::string GetTag() const; 195 196 /** 197 * Sets whether users can input arbitrary text values. 198 * @param permitFreeFormInput Specifies whether to allow arbitrary text values. The default value is true, 199 * indicating that arbitrary text values are allowed. If this parameter is set to false, you must either call 200 * SetOptions(std::vector<std::string>) to set a non-null and non-empty list or call 201 * SetPermitMimeTypes(std::string, bool) to allow a MIME type. 202 */ 203 void SetPermitFreeFormInput(bool permitFreeFormInput); 204 205 /** 206 * Checks whether users can provide arbitrary values for this NotificationUserInput object. 207 * @return true if this object allows arbitrary values; returns false otherwise. 208 */ 209 bool IsPermitFreeFormInput() const; 210 211 /** 212 * Returns a string representation of the object. 213 * @return a string representation of the object. 214 */ 215 std::string Dump(); 216 217 /** 218 * Converts a NotificationUserInput object into a Json. 219 * @param jsonObject Indicates the Json object. 220 */ 221 bool ToJson(nlohmann::json &jsonObject) const override; 222 223 /** 224 * Creates a NotificationUserInput object from a Json. 225 * @param jsonObject Indicates the Json object. 226 * @return the NotificationUserInput. 227 */ 228 static NotificationUserInput *FromJson(const nlohmann::json &jsonObject); 229 230 /** 231 * Marshal a object into a Parcel. 232 * @param parcel the object into the parcel 233 */ 234 virtual bool Marshalling(Parcel &parcel) const override; 235 236 /** 237 * Unmarshal object from a Parcel. 238 * @return the NotificationUserInput 239 */ 240 static NotificationUserInput *Unmarshalling(Parcel &parcel); 241 242 private: 243 /** 244 * Default constructor used to create a NotificationUserInput instance. 245 */ 246 NotificationUserInput() = default; 247 248 /** 249 * A constructor used to create a NotificationUserInput instance with the input parameters passed. 250 * @param inputKey Indicates the AAFwk::WantParams key used to identify this input 251 * when the input is collected from the user. 252 */ 253 explicit NotificationUserInput(const std::string &inputKey); 254 255 /** 256 * A constructor used to create a NotificationUserInput instance with the input parameters passed. 257 * @param inputKey Indicates the AAFwk::WantParams key used to identify this input 258 * when the input is collected from the user. 259 * @param tag Indicates the tag to be displayed. 260 * @param options Indicates the list of predefined options to be provided for user input. 261 * @param permitFreeFormInput Specifies whether to allow arbitrary text values. The default value is true, 262 * indicating that arbitrary text values are allowed. If this parameter is set to false, you must either call 263 * setOptions(const std::vector<std::string> &) to set a non-empty list or call 264 * setPermitMimeTypes(std::string, bool) to allow a MIME type. 265 * @param permitMimeTypes Indicates the MIME type allowed. 266 * @param additional Indicates the AAFwk::WantParams object containing the additional data. 267 * @param editType Indicates the edit type to set. For details about available values, see 268 * NotificationConstant::InputEditType. 269 */ 270 NotificationUserInput(const std::string &inputKey, const std::string &tag, const std::vector<std::string> &options, 271 bool permitFreeFormInput, const std::set<std::string> &permitMimeTypes, 272 const std::shared_ptr<AAFwk::WantParams> &additional, NotificationConstant::InputEditType editType); 273 274 /** 275 * Read a NotificationUserInput object from a Parcel. 276 * @param parcel the parcel 277 */ 278 bool ReadFromParcel(Parcel &parcel); 279 280 private: 281 std::string inputKey_ {}; 282 std::string tag_ {}; 283 std::vector<std::string> options_ {}; 284 bool permitFreeFormInput_ {true}; 285 std::set<std::string> permitMimeTypes_ {}; 286 std::shared_ptr<AAFwk::WantParams> additionalData_ {}; 287 NotificationConstant::InputEditType editType_ {NotificationConstant::InputEditType::EDIT_AUTO}; 288 }; 289 } // namespace Notification 290 } // namespace OHOS 291 292 #endif // BASE_NOTIFICATION_ANS_STANDARD_KITS_NATIVE_INCLUDE_NOTIFICATION_USER_INPUT_H 293