Выполнение команд

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

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

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

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

Некоторые предустановленные значения могут используются как значения аргументов команды, а некоторые - как значение результата выполнения команды. Все значения хранятся в 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.gost:
                console.log('applet GOST');
                break;
            case JCWebClient2.Vars.TokenType.pro:
                console.log('applet PRO');
                break;
            case JCWebClient2.Vars.TokenType.gost2:
                console.log('applet GOST 2');
                break;
            default:
                console.log('Некорректный applet: ' + tokenType);
                break;
        }
    }
});

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

Для выполнения команд наравне с функцией 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); }
});

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

Использование 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); }
});

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

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

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

  1. Использование 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); }
    });
    

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

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

Использование 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);
}