command_interpreter.h 7.3 KB
Newer Older
1
// Copyright (C) 2009-2018 Internet Systems Consortium, Inc. ("ISC")
JINMEI Tatuya's avatar
JINMEI Tatuya committed
2
//
3 4 5
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at http://mozilla.org/MPL/2.0/.
JINMEI Tatuya's avatar
JINMEI Tatuya committed
6

Tomek Mrugalski's avatar
Tomek Mrugalski committed
7 8
#ifndef COMMAND_INTERPRETER_H
#define COMMAND_INTERPRETER_H
9

10
#include <cc/data.h>
11
#include <string>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
12 13 14 15 16

/// @file command_interpreter.h
///
/// This file contains several functions and constants that are used for
/// handling commands and responses sent over control channel. The design
17
/// is described here: http://oldkea.isc.org/wiki/StatsDesign, but also
Tomek Mrugalski's avatar
Tomek Mrugalski committed
18
/// in @ref ctrlSocket section in the Developer's Guide.
19

20 21 22
namespace isc {
namespace config {

Tomek Mrugalski's avatar
Tomek Mrugalski committed
23
/// @brief String used for commands ("command")
24 25
extern const char *CONTROL_COMMAND;

Tomek Mrugalski's avatar
Tomek Mrugalski committed
26
/// @brief String used for result, i.e. integer status ("result")
27
extern const char *CONTROL_RESULT;
Tomek Mrugalski's avatar
Tomek Mrugalski committed
28 29

/// @brief String used for storing textual description ("text")
30
extern const char *CONTROL_TEXT;
Tomek Mrugalski's avatar
Tomek Mrugalski committed
31 32

/// @brief String used for arguments map ("arguments")
33 34
extern const char *CONTROL_ARGUMENTS;

Tomek Mrugalski's avatar
Tomek Mrugalski committed
35
/// @brief Status code indicating a successful operation
36
const int CONTROL_RESULT_SUCCESS = 0;
Tomek Mrugalski's avatar
Tomek Mrugalski committed
37 38

/// @brief Status code indicating a general failure
39 40
const int CONTROL_RESULT_ERROR = 1;

41 42 43
/// @brief Status code indicating that the specified command is not supported.
const int CONTROL_RESULT_COMMAND_UNSUPPORTED = 2;

44 45 46 47 48
/// @brief Status code indicating that the specified command was completed
///        correctly, but failed to produce any results. For example, get
///        completed the search, but couldn't find the object it was looking for.
const int CONTROL_RESULT_EMPTY = 3;

Tomek Mrugalski's avatar
Tomek Mrugalski committed
49 50 51 52 53 54 55 56
/// @brief A standard control channel exception that is thrown if a function
/// is there is a problem with one of the messages
class CtrlChannelError : public isc::Exception {
public:
    CtrlChannelError(const char* file, size_t line, const char* what) :
        isc::Exception(file, line, what) {}
};

57 58 59
/// @brief Creates a standard config/command level success answer message
///        (i.e. of the form { "result": 0 }
/// @return Standard command/config success answer message
60
isc::data::ConstElementPtr createAnswer();
61

62 63
/// @brief Creates a standard config/command level answer message
/// (i.e. of the form { "result": 1, "text": "Invalid command received" }
64
///
65 66 67 68 69 70 71 72
/// @param status_code The return code (0 for success)
/// @param status_text A string to put into the "text" argument
/// @return Standard command/config answer message
isc::data::ConstElementPtr createAnswer(const int status_code,
                                        const std::string& status_text);

/// @brief Creates a standard config/command level answer message
/// (i.e. of the form { "result": status_code, "arguments": arg }
73
///
74
/// @param status_code The return code (0 for success)
75 76
/// @param arg The optional argument for the answer. This can be of
///        any Element type. May be NULL.
77 78 79 80 81
/// @return Standard command/config answer message
isc::data::ConstElementPtr createAnswer(const int status_code,
                                        const isc::data::ConstElementPtr& arg);

/// @brief Creates a standard config/command level answer message
82
///
83
/// @param status_code The return code (0 for success)
84
/// @param status textual representation of the status (used mostly for errors)
85 86
/// @param arg The optional argument for the answer. This can be of
///        any Element type. May be NULL.
87 88 89 90 91 92
/// @return Standard command/config answer message
isc::data::ConstElementPtr createAnswer(const int status_code,
                                        const std::string& status,
                                        const isc::data::ConstElementPtr& arg);

/// @brief Parses a standard config/command level answer message.
93
///
94
/// @param status_code This value will be set to the return code contained in
95
///              the message
96
/// @param msg The message to parse
Tomek Mrugalski's avatar
Tomek Mrugalski committed
97
/// @return The optional argument in the message.
98 99
isc::data::ConstElementPtr parseAnswer(int &status_code,
                                       const isc::data::ConstElementPtr& msg);
100

101 102 103 104 105 106
/// @brief Converts answer to printable text
///
/// @param msg answer to be parsed
/// @return printable string
std::string answerToText(const isc::data::ConstElementPtr& msg);

107
/// @brief Creates a standard command message with no
Tomek Mrugalski's avatar
Tomek Mrugalski committed
108
/// argument (of the form { "command": "my_command" })
109
///
110 111
/// @param command The command string
/// @return The created message
112
isc::data::ConstElementPtr createCommand(const std::string& command);
113

114
/// @brief Creates a standard command message with the
115
/// given argument (of the form { "command": "my_command", "arguments": arg }
116
///
117 118
/// @param command The command string
/// @param arg The optional argument for the command. This can be of
119
///        any Element type. May be NULL.
120
/// @return The created message
121 122
isc::data::ConstElementPtr createCommand(const std::string& command,
                                         isc::data::ConstElementPtr arg);
123

124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146
/// @brief Creates a standard config/command command message with no
/// argument and with the given service (of the form
/// { "command": "my_command", "service": [ service ] })
///
/// @param command The command string
/// @param service The target service. May be empty.
/// @return The created message
 isc::data::ConstElementPtr createCommand(const std::string& command,
                                          const std::string& service);

/// @brief Creates a standard config/command command message with the
/// given argument and given service (of the form
/// { "command": "my_command", "arguments": arg, "service": [ service ] }
///
/// @param command The command string
/// @param arg The optional argument for the command. This can be of
///        any Element type. May be NULL.
/// @param service The target service. May be empty.
/// @return The created message
isc::data::ConstElementPtr createCommand(const std::string& command,
                                         isc::data::ConstElementPtr arg,
                                         const std::string& service);

147
/// @brief Parses the given command into a string containing the actual
148 149
///        command and an ElementPtr containing the optional argument.
///
150
/// @throw Raises a CtrlChannelError if this is not a well-formed command
151
///
152
/// @param arg This value will be set to the ElementPtr pointing to
153
///        the argument, or to an empty Map (ElementPtr) if there was none.
154
/// @param command The command message containing the command (as made
155
///        by createCommand()
Tomek Mrugalski's avatar
Tomek Mrugalski committed
156
/// @return The command name
157 158
std::string parseCommand(isc::data::ConstElementPtr& arg,
                         isc::data::ConstElementPtr command);
159

Francis Dupont's avatar
Francis Dupont committed
160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176
/// @brief Combines lists of commands carried in two responses.
///
/// This method is used to combine list of commands returned by the
/// two command managers.
///
/// If the same command appears in two responses only a single
/// instance is returned in the combined response.
///
/// @param response1 First command response.
/// @param response2 Second command response.
///
/// @return Pointer to the 'list-commands' response holding combined
/// list of commands.
isc::data::ConstElementPtr
combineCommandsLists(const isc::data::ConstElementPtr& response1,
                     const isc::data::ConstElementPtr& response2);

177 178
}; // end of namespace isc::config
}; // end of namespace isc
179

Tomek Mrugalski's avatar
Tomek Mrugalski committed
180
#endif // COMMAND_INTERPRETER_H