# 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

# ApplicationFactory - Reference Documentation

Repository for application and key profiles, as well as factory to create instances of Application, GPApplication or GPSecurityDomain objects, which resemble the execution environment for Global Platform Scripts.

## Index of Methods

- ApplicationFactory() constructor
- addKeyProfile()
- addApplicationProfile()
- getApplicationInstance()

## Constructor

### Prototype

ApplicationFactory(Crypto crypto)

ApplicationFactory(Crypto crypto, Function scope)

### Description

Create an instance of the ApplicationFactory.

The application factory is used as a repository of application and key profiles. It can create instances of the Application, GPApplication and GPSecurityDomain objects using the getApplicationInstance() method.

If used in a module, then the argument scope allows to pass a function from the module scope. Script fragments in the application profile will have the same module scope as the function.

### Arguments

Type | Name | Description
--- | --- | ---
`Crypto` | crypto | Crypto object to be associated with applications
`Function` | scope | A function in the module scope in which application profile script shall be created

### 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

    var crypto = new Crypto();

    var af = new ApplicationFactory(crypto);
    assert(af != null);

## addKeyProfile()

### Prototype

Void addKeyProfile(String profileName)

### Description

Deserialize the key profile stored in the file specified by profileName and store it under the UniqueId in an internal repository.

### Arguments

Type | Name | Description
--- | --- | ---
`String` | profileName | Name of key profile. Will be mapped to a physical file by the runtime environment.

### 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

    af.addKeyProfile("profiles/kp_single_des_1.xml");
    af.addKeyProfile("profiles/kp_double_des.xml");
    af.addKeyProfile("profiles/kp_triple_des.xml");

## addApplicationProfile()

### Prototype

Void addApplicationProfile(String profileName)

### Description

Deserialize the application profile stored in the file specified by profileName and store it under the UniqueId in an internal repository.

### Arguments

Type | Name | Description
--- | --- | ---
`String` | profileName | Name of application profile. Will be mapped to a physical file by the runtime environment.

### 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

    af.addApplicationProfile("profiles/ap_test.xml");

## getApplicationInstance()

### Prototype

Application getApplicationInstance(Object dataMapper, ByteString aid, ByteString uniqueId)

Application getApplicationInstance(Object dataMapper, ByteString aid, Card card)

Application getApplicationInstance(Object dataMapper, ByteString aid, Card card, ByteString uniqueId)

### Description

Create and initialize an Application, GPApplication or GPSecurityDomain object based on the the definition in the XML profile.

The dataMapper object is used to read and write data element from an external source. The object must provide a get(name, fixed, length) function that returns a ByteString object. The arguments name, fixed and length are initialized from the respective fields in the application profile. The dataMapper will be associated with the application instance.

The aid is used to initialize the aid property of the Application objects. It is furthermore used to locate an application instance if a card object is provided as argument.

The optional card argument can be used to define the card property of the Application object. If a card object is defined, then the list of application instances in the card profile can be used to locate the appropriate application profile in the application factory.

The optional uniqueId can be used to identify an application profile previously registered in the application factory. If the uniqueId is not given as argument, then it is determined from the list of application instances in the card profile.

Use the run() method to execute scripts defined in the application profile.

### Arguments

Type | Name | Description
--- | --- | ---
`Object` | dataMapper | Object to provide mapping of data element from an external source to data element accessible from within scripts
`ByteString` | aid | Application identifier for instance
`Card` | card | Card object to be used for instance or null
`ByteString` | uniqueId | UniqueID of application profile to be used

### Return

`Application` | The method returns an Application object

### 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 card = new Card(_scsh3.reader);
    var aid = new ByteString("A0000002471001", HEX);
    var id = new ByteString("2B0601040181C31F0000", HEX);

    // Simple data mapper that returns the name of the data element as value
    var dataMapper = new Object();
    dataMapper.get = function(name, fixed, length, encoding) {
        return new ByteString("DE " + name + " Fixed=" + fixed + " Length=" + length +
        " Encoding=" + encoding, ASCII); };
    dataMapper.put = function(name, value, encoding) {
        print("DE " + name + " Value=" + value.toString(encoding) +
        " Encoding=" + encoding); };

    var appl = af.getApplicationInstance(dataMapper, aid, card, id);

    appl.run("Hello World Test");

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