Director Console Output¶

The console output should handle different API modes.

As the initial design of the Director Console connection did allow various forms of output (in fact: free text with some helper functions) the introduction of another API mode (API mode JSON) did require to change the creation of output.

Output can be send to a console connection (UserAgent Socket) or the command is executed in a job
free text (with the use of some helper functions)
Signals
Different Message types
- Types
  - UAContext::send_msg
  - UAContext::info_msg
  - UAContext::warning_msg
  - UAContext::error_msg
- indicated by a signal packet and than the text packet
see Daemon Protocols

The OUTPUT_FORMATTER class have been introduced to consolidate the interface to generate Console output.

The basic idea is to provide an object, array and key-value based interface.

object_key_value¶

A main member function of OUTPUT_FORMATTER are the object_key_value(…) functions, like

void OUTPUT_FORMATTER::object_key_value(const char *key, const char *key_fmt, const char *value, const char *value_fmt, int wrap = -1);

API mode 0 and 1 get the key and value, and write them as defined in the key_fmt and value_fmt strings. If the key_fmt string is not given, the key will not be written. If the value_fmt string is not given, the value will not be written.

In API mode 2 (JSON), OUTPUT_FORMATTER stores the key value pair in its internal JSON object, to delivers it, when the response object is finished. The keys will be transformed to lower case strings.

decoration¶

Additional output can be created by the void OUTPUT_FORMATTER::decoration(const char *fmt, ...) function. This strings will only be written in API mode 0 and is intended to make an output prettier.

messages¶

For messages, the UAContext function should be used:

UAContext::send_msg
UAContext::info_msg
UAContext::warning_msg
UAContext::error_msg

Internally, these redirect to the void OUTPUT_FORMATTER::message(const char *type, POOL_MEM &message) function.

API mode 0
- packet 1: message is send to the user console
API mode 1
- packet 1: message signal is send
- packet 2: message is send to the user console
API mode 2:
- packet 1: message signal is send (TODO: this might change)
- message is stored in the corresponding message object
  - if an error message is send, the result of the command will switch to error

Objects and Arrays¶

To structure data, the OUTPUT_FORMATTER class offers functions:

void object_start(const char *name = NULL);
void object_end(const char *name = NULL);
void array_start(const char *name);
void array_end(const char *name);

These functions define the structure of the reult object in API mode 2, but are ignored in API mode 0 and 1.

named objects¶

named objects (object_start(NAME))
- can be added to objects (named and nameless objects)

nameless objects¶

nameless objects (object_start(NULL))
- can be added to arrays

arrays¶

arrays (array_start(NAME))
- can be added by name to an object
- contain nameless objects (object_start(NULL))

Example¶

LockRes();
ua->send->array_start("storages");
foreach_res(store, R_STORAGE) {
    if (acl_access_ok(ua, Storage_ACL, store->name())) {
        ua->send->object_start();
        ua->send->object_key_value("name", store->name(), "%s\n");
        ua->send->object_end();
    }
}
ua->send->array_end("storages");
UnlockRes();

results to

*.api 2
{
  "jsonrpc": "2.0",
  "id": null,
  "result": {
    "api": 2
  }
}
*.storages
{
  "jsonrpc": "2.0",
  "id": null,
  "result": {
    "storages": [
      {
        "name": "File"
      },
      {
        "name": "myTapeLibrary"
      }
    ]
  }
}

Example with 3 level structure¶

ua->send->array_start("files");
for(int i=0; file[i]; i++) {
    ua->send->object_start();
    ua->send->object_key_value("Name", "%s=", file[i]->name, "%s");
    ua->send->object_key_value("Type", "%s=", file[i]->type, "%s");
    decode_stat(file[i]->lstat, &statp, sizeof(statp), LinkFI);
    ua->send->object_start("stat");
    ua->send->object_key_value("dev", "%s=", statp.st_dev, "%s");
    ua->send->object_key_value("ino", "%s=", statp.st_ino, "%s");
    ua->send->object_key_value("mode", "%s=", statp.st_mode, "%s");
    ...
    ua->send->object_end("stat");
    ua->send->object_end();
}
ua->send->array_end("files");