command_interpreter.h 5.08 KB
Newer Older
1
// Copyright (C) 2009-2015,2017 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 17 18

/// @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
/// is described here: http://kea.isc.org/wiki/StatsDesign, but also
/// 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;

Tomek Mrugalski's avatar
Tomek Mrugalski committed
41 42 43 44 45 46 47 48
/// @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) {}
};

49 50 51
/// @brief Creates a standard config/command level success answer message
///        (i.e. of the form { "result": 0 }
/// @return Standard command/config success answer message
52
isc::data::ConstElementPtr createAnswer();
53

54 55
/// @brief Creates a standard config/command level answer message
/// (i.e. of the form { "result": 1, "text": "Invalid command received" }
56
///
57 58 59 60 61 62 63 64
/// @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 }
65
///
66
/// @param status_code The return code (0 for success)
67 68
/// @param arg The optional argument for the answer. This can be of
///        any Element type. May be NULL.
69 70 71 72 73
/// @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
74
///
75
/// @param status_code The return code (0 for success)
76
/// @param status textual representation of the status (used mostly for errors)
77 78
/// @param arg The optional argument for the answer. This can be of
///        any Element type. May be NULL.
79 80 81 82 83 84
/// @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.
85
///
86
/// @param status_code This value will be set to the return code contained in
87
///              the message
88
/// @param msg The message to parse
Tomek Mrugalski's avatar
Tomek Mrugalski committed
89
/// @return The optional argument in the message.
90 91
isc::data::ConstElementPtr parseAnswer(int &status_code,
                                       const isc::data::ConstElementPtr& msg);
92

93
/// @brief Creates a standard config/command command message with no
Tomek Mrugalski's avatar
Tomek Mrugalski committed
94
/// argument (of the form { "command": "my_command" })
95
///
96 97
/// @param command The command string
/// @return The created message
98
isc::data::ConstElementPtr createCommand(const std::string& command);
99

100 101
/// @brief Creates a standard config/command command message with the
/// given argument (of the form { "command": "my_command", "arguments": arg }
102
///
103 104
/// @param command The command string
/// @param arg The optional argument for the command. This can be of
105
///        any Element type. May be NULL.
106
/// @return The created message
107 108
isc::data::ConstElementPtr createCommand(const std::string& command,
                                         isc::data::ConstElementPtr arg);
109

110
/// @brief Parses the given command into a string containing the actual
111 112
///        command and an ElementPtr containing the optional argument.
///
113
/// @throw Raises a CtrlChannelError if this is not a well-formed command
114
///
115
/// @param arg This value will be set to the ElementPtr pointing to
116
///        the argument, or to an empty Map (ElementPtr) if there was none.
117
/// @param command The command message containing the command (as made
118
///        by createCommand()
Tomek Mrugalski's avatar
Tomek Mrugalski committed
119
/// @return The command name
120 121
std::string parseCommand(isc::data::ConstElementPtr& arg,
                         isc::data::ConstElementPtr command);
122

123 124
}; // end of namespace isc::config
}; // end of namespace isc
125

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