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
27namespace android {
28namespace weave {
29class IWeaveCommand;
30}  // namespace weave
31}  // namespace android
32
33namespace weaved {
34
35class ServiceImpl;
36
37class 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>
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