1 // Copyright 2015 The Android Open Source Project 2 // 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 #ifndef LIBWEAVED_COMMAND_H_ 16 #define LIBWEAVED_COMMAND_H_ 17 18 #include <string> 19 20 #include <base/macros.h> 21 #include <binder/Status.h> 22 #include <brillo/errors/error.h> 23 #include <brillo/value_conversion.h> 24 #include <libweaved/export.h> 25 #include <utils/StrongPointer.h> 26 27 namespace android { 28 namespace weave { 29 class IWeaveCommand; 30 } // namespace weave 31 } // namespace android 32 33 namespace weaved { 34 35 class ServiceImpl; 36 37 class LIBWEAVED_EXPORT Command final { 38 public: 39 enum class State { 40 kQueued, 41 kInProgress, 42 kPaused, 43 kError, 44 kDone, 45 kCancelled, 46 kAborted, 47 kExpired, 48 }; 49 50 enum class Origin { kLocal, kCloud }; 51 52 ~Command(); 53 54 // Returns the full command ID. 55 std::string GetID() const; 56 57 // Returns the full name of the command. 58 std::string GetName() const; 59 60 // Returns the name of the component this command was sent to. 61 std::string GetComponent() const; 62 63 // Returns the command state. 64 Command::State GetState() const; 65 66 // Returns the origin of the command. 67 Command::Origin GetOrigin() const; 68 69 // Returns the command parameters. 70 const base::DictionaryValue& GetParameters() const; 71 72 // Helper function to get a command parameter of particular type T from the 73 // command parameter list. Returns default value for type T (e.g. 0 for int or 74 // or "" for std::string) if the parameter with the given name is not found or 75 // is of incorrect type. 76 template <typename T> GetParameter(const std::string & name)77 T GetParameter(const std::string& name) const { 78 const base::DictionaryValue& parameters = GetParameters(); 79 T param_value{}; 80 const base::Value* value = nullptr; 81 if (parameters.Get(name, &value)) 82 brillo::FromValue(*value, ¶m_value); 83 return param_value; 84 } 85 86 // Updates the command progress. The |progress| should match the schema. 87 // Returns false if |progress| value is incorrect. 88 bool SetProgress(const base::DictionaryValue& progress, 89 brillo::ErrorPtr* error); 90 91 // Sets command into terminal "done" state. 92 // Updates the command results. The |results| should match the schema. 93 // Returns false if |results| value is incorrect. 94 bool Complete(const base::DictionaryValue& results, 95 brillo::ErrorPtr* error); 96 97 // Aborts command execution. 98 // Sets command into terminal "aborted" state. 99 bool Abort(const std::string& error_code, 100 const std::string& error_message, 101 brillo::ErrorPtr* error); 102 103 // Aborts command execution. 104 // Sets command into terminal "aborted" state and uses the error information 105 // from the |command_error| object. The error codes extracted from 106 // |command_error| are automatically prepended with an underscore ("_"). 107 bool AbortWithCustomError(const brillo::Error* command_error, 108 brillo::ErrorPtr* error); 109 // AbortWithCustomError overload for specifying the error information as 110 // binder::Status. 111 bool AbortWithCustomError(android::binder::Status status, 112 brillo::ErrorPtr* error); 113 114 // Cancels command execution. 115 // Sets command into terminal "canceled" state. 116 bool Cancel(brillo::ErrorPtr* error); 117 118 // Sets command into paused state. 119 // This is not terminal state. Command can be resumed with |SetProgress| call. 120 bool Pause(brillo::ErrorPtr* error); 121 122 // Sets command into error state and assign error. 123 // This is not terminal state. Command can be resumed with |SetProgress| call. 124 bool SetError(const std::string& error_code, 125 const std::string& error_message, 126 brillo::ErrorPtr* error); 127 128 // Sets command into error state and assign error. 129 // This is not terminal state. Command can be resumed with |SetProgress| call. 130 // Uses the error information from the |command_error| object. 131 // The error codes extracted from |command_error| are automatically prepended 132 // with an underscore ("_"). 133 bool SetCustomError(const brillo::Error* command_error, 134 brillo::ErrorPtr* error); 135 // SetError overload for specifying the error information as binder::Status. 136 bool SetCustomError(android::binder::Status status, 137 brillo::ErrorPtr* error); 138 139 protected: 140 explicit Command(const android::sp<android::weave::IWeaveCommand>& proxy); 141 142 private: 143 friend class ServiceImpl; 144 android::sp<android::weave::IWeaveCommand> binder_proxy_; 145 mutable std::unique_ptr<base::DictionaryValue> parameter_cache_; 146 147 DISALLOW_COPY_AND_ASSIGN(Command); 148 }; 149 150 } // namespace weave 151 152 #endif // LIBWEAVED_COMMAND_H_ 153