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, &param_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