# Smart Card Shell

- - Home
- - GPError
  - GPSystem
  - ByteString
  - ByteBuffer
  - TLV
  - TLVList
  - Card
  - Atr
  - Key
  - Crypto
  - Application
  - GPApplication
  - GPSecDomain
- - ASN1
  - CardFile
  - IsoSecureChannel
  - ApplFactory
  - GPXML
  - JsScript
  - CardSim
- - X509
  - CRL
  - KeyStore
  - Signed CMS
  - Enveloped CMS
  - CMS Generator
  - XMLSignature
  - SSS
  - OCSPQuery
  - LDAP
  - SOAP
  - URLConnection
- - PKCS11Provider
  - PKCS11Session
  - PKCS11Object
- - OutlineNode
  - Dialog
  - Task
- - Tools
  - Modules
- - OpenSCDP

# Task - Reference Documentation

The Task host class allows to define and control background tasks in the Smart Card Shell.

A background task consists of a user object that implements a run() method and an actionListener() method to receive user notification. A Task object provides for visualization in the task tab of the Smart Card Shell and controls to start and stop the task. It also implements a message queue for asynchronously passing messages from other tasks or scripts.

## Index of Methods

- Task() constructor
- start()
- stop()
- post()
- poll()
- setContextMenu()
- setToolTip()
- setIcon()
- setMessage()
- getTaskList()
- dispose()

## Properties

Type | Name | Description
--- | --- | ---
String | icon | Name of icon selected with setIcon()
String | tooltip | Tooltip set with setToolTip()
String[] | contextMenu | Context menu set with setContextMenu()
Object | userObject | Object registered as user object in constructor
String | status | Task status, one of created, running, failed, passed
Boolean | disposeAtExit | Property that can be set to dispose the task when it finishes.

## Constructor

### Prototype

Task(Object userObject)

### Description

Create a Task object with associated user object. Add task entry in tasks tab.

A newly created task object can be started using the start() method. It can be stopped with stop() method.

A call to dispose() will stop the task, clear the queue and remove the task entry from the task list.

### Arguments

Type | Name | Description
--- | --- | ---
`Object` | userObject | The user object

### Exceptions

Name | Value | Description
--- | --- | ---
GPError | GPError.INVALID_ARGUMENTS | Too many arguments given
GPError | GPError.INVALID_TYPE | On or more arguments are not of the expected type

### Example

    function TaskTest() {
    	this.name = "Task#" + TaskTest.CNT++;
    	this.task = new Task(this);
    	this.task.setContextMenu([ "Start", "Stop", "Trace", "Post", "Dispose" ]);
    	this.task.setToolTip("Tooltip");
    }

    TaskTest.CNT = 1;

    TaskTest.prototype.start = function() {
    	this.task.start();
    }

    TaskTest.prototype.run = function() {
    	var i = 10;
    	do	{
    		print("Hello");
    		GPSystem.trace("Trace");
    		this.task.setMessage("Running " + i);
    		var o = this.task.poll(1000);

    		if (o) {
    			print("Received " + o);
    		}
    	} while (i-- > 0);
    }

    TaskTest.prototype.actionListener = function(source, action) {
    	print("Source / Action: " + source + "/" + action);

    	switch(action) {
    		case "Start":
    			this.task.start();
    			break;
    		case "Stop":
    			this.task.stop();
    			break;
    		case "Trace":
    			print(GPSystem.copyTrace());
    			break;
    		case "Post":
    			this.task.post("Message");
    			break;
    		case "Dispose":
    			this.task.dispose();
    			break;
    	}
    }

    TaskTest.prototype.toString = function() {
    	return this.name;
    }

    for (var i = 0; i < 20; i++) {
    	new TaskTest();
    }

## start()

### Prototype

start()

### Description

Start the task by creating a dynamic scope and calling the run() method of the user object.

Start can be called multiple time, creating subsequent synchronous executions of run().

### Return

`Void` | The method does not return a value

### Exceptions

Name | Value | Description
--- | --- | ---
GPError | GPError.INVALID_ARGUMENTS | Too many arguments in call

### Example

    task.start();

## stop()

### Prototype

stop()

### Description

Stop the task by sending an interupt signal to the running task and clear the queue.

### Return

`Void` | The method does not return a value

### Exceptions

Name | Value | Description
--- | --- | ---
GPError | GPError.INVALID_ARGUMENTS | Too many arguments in call

### Example

    task.stop();

## post()

### Prototype

post(Object object)

### Description

Post an object to the queue maintained for this task.

### Arguments

Type | Name | Description
--- | --- | ---
`Object` | object | Object to be added to queue.

### Return

`Void` | The method does not return a value

### Exceptions

Name | Value | Description
--- | --- | ---
GPError | GPError.ARGUMENTS_MISSING | Too few arguments in call
GPError | GPError.INVALID_ARGUMENTS | Too many arguments in call
GPError | GPError.INVALID_TYPE | Type of argument is invalid for method invocation

### Example

    task.post("Message");

## poll()

### Prototype

Object poll(Number timeout)

### Description

Poll for an object from the queue maintained for this task.

### Arguments

Type | Name | Description
--- | --- | ---
`Number` | timeout | Number of milliseconds to wait for object.

### Return

`Object` | The object retrieved from the queue or null, if no object available within specified time.

### Exceptions

Name | Value | Description
--- | --- | ---
GPError | GPError.ARGUMENTS_MISSING | Too few arguments in call
GPError | GPError.INVALID_ARGUMENTS | Too many arguments in call
GPError | GPError.INVALID_TYPE | Type of argument is invalid for method invocation

### Example

    var o = task.poll(1);
    print(o);

## setContextMenu()

### Prototype

setContextMenu(String[] entries)

### Description

Set content of context menu.

Selected actions trigger an actionLister() method call on the user object.

A separator can be defined using "---" as entry.

### Arguments

Type | Name | Description
--- | --- | ---
`String[]` | entries | Array of context menu entries

### Return

`Void` | The method does not return a value

### Exceptions

Name | Value | Description
--- | --- | ---
GPError | GPError.ARGUMENTS_MISSING | Too few arguments in call
GPError | GPError.INVALID_ARGUMENTS | Too many arguments in call
GPError | GPError.INVALID_TYPE | Type of argument is invalid for method invocation

### Example

    task.setContextMenu(["add"]);

## setToolTip()

### Prototype

setToolTip(String toolTipText)

setToolTip()

### Description

Set a text to display as tool tip, which is displayed when the mouse is held over the node.

If no text is defined, the tool tip is removed.

### Arguments

Type | Name | Description
--- | --- | ---
`String` | toolTipText | Text to display

### Return

`Void` | The method does not return a value

### Exceptions

Name | Value | Description
--- | --- | ---
GPError | GPError.ARGUMENTS_MISSING | Too few arguments in call
GPError | GPError.INVALID_ARGUMENTS | Too many arguments in call
GPError | GPError.INVALID_TYPE | Type of argument is invalid for method invocation

### Example

    task.setToolTip("Press the right mouse button to see context menu");

## setIcon()

### Prototype

setIcon(String iconName)

setIcon()

### Description

Change the icon of the node to the named icon or reset to the default.

The name of the icon is mapped to the file name <iconName>.png and located in the icons directory directly underneath the installation directory.

### Arguments

Type | Name | Description
--- | --- | ---
`String` | iconName | Name of icon

### Return

`Void` | The method does not return a value

### Exceptions

Name | Value | Description
--- | --- | ---
GPError | GPError.ARGUMENTS_MISSING | Too few arguments in call
GPError | GPError.INVALID_ARGUMENTS | Too many arguments in call
GPError | GPError.INVALID_TYPE | Type of argument is invalid for method invocation

### Example

    task.setIcon("selected");

## setMessage()

### Prototype

setMessage(String message)

### Description

Change the message of the node to the given string.

### Arguments

Type | Name | Description
--- | --- | ---
`String` | message | Message for node

### Return

`Void` | The method does not return a value

### Exceptions

Name | Value | Description
--- | --- | ---
GPError | GPError.ARGUMENTS_MISSING | Too few arguments in call
GPError | GPError.INVALID_ARGUMENTS | Too many arguments in call
GPError | GPError.INVALID_TYPE | Type of argument is invalid for method invocation

### Example

    task.setMessage("Changed label");

## getTaskList()

### Prototype

Task[] Task.getTaskList()

### Description

Return the list of currently defined tasks

### Return

`Task[]` | The list of tasks.

### Exceptions

Name | Value | Description
--- | --- | ---
GPError | GPError.INVALID_ARGUMENTS | Too many arguments in call

### Example

## dispose()

### Prototype

dispose()

### Description

Stop task, clear queue and remove from task list.

### Return

`Void` | The method does not return a value

### Exceptions

Name | Value | Description
--- | --- | ---
GPError | GPError.INVALID_ARGUMENTS | Too many arguments in call

### Example

    GPSystem.wait(1000);
    task.dispose();

© Copyright 2003 - 2024 CardContact Systems GmbH , Minden, Germany