Технический портал

JC-WebClient API предоставляет функцию exec для выполнения команд, которая может работать как синхронно, так и асинхронно. Для небольшого упрощения запуска выполнения команд существуют функции – псевдонимы (или просто псевдонимы).

За переключение между синхронным / асинхронным вызовом отвечает параметр async в exec и псевдонимах. Этот параметр может задаваться как напрямую при выполнении каждой команды, так и через defaults для всех вызовов команды на выполнение (см. Установка режима выполнения команд).

Для удобства JC-WebClient API предоставляет набор предустановленных значений, которые доступны через объект JCWebClient2.Vars.

7.2.1 Использование предустановленных значений

Некоторые предустановленные значения могут используются как значения аргументов команды, а некоторые - как значение результата выполнения команды. Все значения хранятся в JCWebClient2.Vars.

Пример использования значения как аргумента команды

// Получение типа ОС.
// Используемое предустановленное значение: JCWebClient2.Vars.OsInfo.osType
JCWebClient2.getSystemInfo({
    args: {
        info: JCWebClient2.Vars.OsInfo.osType
    },
    onError: function (error) { console.log('onError: ' + error); },
    onSuccess: function (result) { console.log('onSuccess: ' + result); }
});

Пример использования значения как результата выполнения команды

// Получение информации о токене
JCWebClient2.getTokenInfo({
    args: {
        tokenID: 0
    },
    onError: function (error) {
        console.log('onError: ' + error);
    },
    onSuccess: function (result) {
 
        // Получение типа токена
        var tokenType = result.type;
 
        // Обработка типа токена.
        // Используются предустановленные значения из объекта: JCWebClient2.Vars.TokenType
        switch (tokenType) {
                case JCWebClient2.Vars.TokenType.pki:
                console.log('token PKI');
                break;
            case JCWebClient2.Vars.TokenType.gost2:
                console.log('token GOST 2');
                break;
            default:
                console.log('Некорректный token: ' + tokenType);
                break;
        }
    }
});

7.2.2 Использование псевдонимов

Для выполнения команд наравне с функцией exec в JC-WebClient API предусмотрены псевдонимы для каждой команды для небольшого упрощения их вызова. Каждый псевдоним представляет из себя функцию, которая внутри себя вызывает exec с уже заданным параметром cmd.

Таким образом, вызовы

// Использование функции exec для выполнения команды getTokenInfo
JCWebClient2.exec({
    cmd: JCWebClient2.Cmds.getTokenInfo,
    args: {
        tokenID: 0
    },
    onResult: function(result, error) { console.log('Result: ' + result + ' \nError: ' + error); }
});

и

// Использование псевдонима для выполнения команды getTokenInfo
JCWebClient2.getTokenInfo({
    args: {
        tokenID: 0
    },
    onResult: function(result, error) { console.log('Result: ' + result + ' \nError: ' + error); }
});

эквивалентны.

7.2.3 Использование defaults

defaults содержит значения по умолчанию, которые используются если не был указан соответствующий параметр в exec или псевдонимах.

Пример

// Установка режима асинхронного выполнения команд
JCWebClient2.defaults({
    async: true
});
 
// Команда будет выполняться асинхронно, т.к. отсутствует установка async
// и его значение берется из JCWebClient2.defaults().async
JCWebClient2.getTokenInfo({
    args: {
        tokenID: "невалидное значение аргумента"
    },
    onResult: function(result, error) { console.log('Result: ' + result + ' \nError: ' + error); }
});
 
// Команда будет выполняться синхронно, т.к. async задан явно
JCWebClient2.getTokenInfo({
    async: false,
    args: {
        tokenID: 0
    },
    onResult: function(result, error) { console.log('Result: '+result+' \nError: '+error); }
});
 
// Команда будет выполняться асинхронно, т.к. отсутствует установка async
// и его значение берется из JCWebClient2.defaults().async
JCWebClient2.exec({
    cmd: JCWebClient2.Cmds.getTokenInfo,
    args: {
        tokenID: 0
    },
    onResult: function (result, error) { console.log('Result: ' + result + ' \nError: ' + error); }
});

7.2.4 Установка режима выполнения команд

Для синхронного / асинхронного выполнения команд необходимо установить параметр async в false / true соответственно.

Для установки параметра можно использовать следующие подходы:

Использование defaults. Этот вариант наиболее предпочтителен, т.к. требует один раз указать в каком режиме выполнять команды и эта настройка будет использована для всех вызываемых команд.

Пример установки синхронного режима

// Установка режима синхронного выполнения команд
JCWebClient2.defaults({
    async: false
});
 
// ... код ...
 
JCWebClient2.getJCWebClientVersion({
    onResult: function (result, error) { console.log('Result: ' + result + ' \nError: ' + error); }
});

Пример установки асинхронного режима

// Установка режима асинхронного выполнения команд
JCWebClient2.defaults({
    async: true
});
 
// ... код ...
 
JCWebClient2.getJCWebClientVersion({
    onResult: function (result, error) { console.log('Result: ' + result + ' \nError: ' + error); }
});

2. Использование параметра async в exec и псевдонимах. Требуется при каждом вызове указывать режим. Если async указан не был, то автоматически используется JCWebClient2.defaults().async;

Пример установки синхронного режима

// ... код ...
 
JCWebClient2.getJCWebClientVersion({
    async: false,
    onResult: function (result, error) { console.log('Result: ' + result + ' \nError: ' + error); }
});

Пример установки асинхронного режима

// ... код ...
 
JCWebClient2.getJCWebClientVersion({
    async: true,
    onResult: function (result, error) { console.log('Result: ' + result + ' \nError: ' + error); }
});

7.2.5 Примеры выполнения команд

Использование callback-функций onSuccess / onError.

Результат будет передан в аргумент result callback-функции в параметре onSuccess, а в случае ошибки она будет передана в аргумент error callback-функции в параметре onError.

// Установка режима выполнения команд
JCWebClient2.defaults({
    async: true                 // true - асинхронное выполнение команды, false - синхронное
});
 
// ... код ...
 
JCWebClient2.getTokenInfo({
    args: {
        tokenID: 0
    },
    onSuccess: function (result) { console.log('onSuccess: ' + result); },
    onError: function (error) { console.log('onError: ' + error); },
});

Использование callback-функции onResult

Результат будет передан в аргумент result и аргумент error, в случае ошибки, callback-функции в параметре onResult.

Примечание: Если еще дополнительно указаны onSuccess и (или) onError, то они игнорируются.

// Установка режима выполнения команд
JCWebClient2.defaults({
    async: true                 // true - асинхронное выполнение команды, false - синхронное
});
 
// ... код ...
 
JCWebClient2.getTokenInfo({
    args: {
        tokenID: 0
    },
    onResult: function (result, error) { console.log('Result: ' + result + ' \nError: ' + error); }
});

Использование без callback-функций onSuccess / onError / onResult

Данный вариант использования подходит только для синхронного режима, т.к. при асинхронном если не указаны ни onResult, ни пара onSuccess и onError, то будет сгенерировано исключение.

Результат будет передан переменной result, а в случае ошибки она будет передана в аргумент error блока catch.

// Установка режима синхронного выполнения команд
JCWebClient2.defaults({
    async: false
});
 
// ... код ...
 
try {
    var result = JCWebClient2.getTokenInfo({
        args: {
            tokenID: 0
        }
    });
 
    console.log('Result: ' + result);
}
catch(error) {
    console.log('Error: ' + error.message);
}