# 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

# GPXML - Reference Documentation

Core XML parser for Global Platform Profiles.

XML profiles are deserialized into a tree of ECMAScript objects. Child elements are created as a property under the parent object with the name of the XML element. Attributes are created as a property with the same name and of type String.

Namespaces are silently ignored (e.g. gp:Key is stored as property Key).

If an element contains a value, then the characters are collected into the elementValue property.

If an element contains CDATA, then the characters are collected into the elementValue property.

If a Script element is found and there is no explicit script definition using defineScriptElement(), then the content of the element is evaluated as an ECMAScript function without parameter and stored under the Script property of the parent element.

If a parent element defines the arrayElement and arrayIndex attributes, then client elements with the same name are deserialized as an array.

## Index of Methods

- GPXML() constructor
- defineArrayElement()
- defineScriptElement()
- parse()
- parseApplicationProfile()

## Constructor

### Prototype

GPXML()

### Description

Create a parser object to parse the specified XML file.

The actual parsing is done using the GPXML.prototype.parse() method.

### Exceptions

Name | Value | Description
--- | --- | ---
GPError | GPError.INVALID_ARGUMENTS | Too many arguments given

### Example

    var parser = new GPXML();

## defineArrayElement()

### Prototype

defineArrayElement(String path, String arrayElement)

defineArrayElement(String path, String arrayElement, String arrayIndex)

### Description

Define which XML child nodes must be deserialized as JavaScript array.

This has the same effect as specifying an arrayElement and arrayIndex attribute at an XML node.

Multiple values for arrayElement and arrayIndex can be specified in a comma separated list.

The array can be either indexed by integer ("#") or using an attribute as key value.

### Arguments

Type | Name | Description
--- | --- | ---
`String` | path | Path to the XML node that contains array elements.
`String` | arrayElement | Comma separated list of array elements.
`String` | arrayIndex | "#" to index array with integer offset starting at 0 or attribute containing key value.

### Return

`` |

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

    parser.defineArrayElement("/Root/Child3/Child4", "Array1");
    parser.defineArrayElement("/Root/Child3/Child5", "Array1", "name");
    parser.defineArrayElement("/Root/Child3/Child6", "Array1,Array2", "#,name");

## defineScriptElement()

### Prototype

defineScriptElement(String path)

defineScriptElement(String path, Boolean asFunction)

### Description

Define which XML nodes are to be interpreted as script code.

By default all <Script> elements are parsed as script code.

### Arguments

Type | Name | Description
--- | --- | ---
`String` | path | Path to the XML node that shall be interpreted as script code.
`Boolean` | asFunction | if set to true, then the script fragment is treated as function.

### Return

`` |

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

    parser.defineScriptElement("/Root/AnonymousFunction/Script");
    parser.defineScriptElement("/Root/Function/Script", true);
    parser.defineScriptElement("/Root/FunctionNoScript", true);
    parser.defineScriptElement("/Root/Script", false);
    parser.defineScriptElement("/Root/PlainScript", false);

## parse()

### Prototype

Object parse(String filename)

Object parse(ByteString file)

### Description

Parse the XML formatted file specified by filename and create a tree of ECMAScript objects.

The file can be provided as ByteString. If the ByteString starts with 1F8B, then it is treated as GZIP file.

The parse() method without arguments can be used with an instance object, the other two variants are static methods.

### Arguments

Type | Name | Description
--- | --- | ---
`String` | filename | File name of XML file. Will be mapped to a physical file by the runtime environment.

### Return

`Object` | Root element of document object model

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

    // Dynamic variant
    var profile = parser.parse("parsertest2.xml");
    dumpxml(profile, "");
    assert(profile);
    assert(profile.rootAttr1 == "rootAttr1");
    assert(profile.rootAttr2 == "rootAttr2");
    assert(profile.Child1);
    assert(profile.Child1.child1Attr1 == "child1Attr1");
    assert(profile.Child1.child1Attr2 == "child1Attr2");

    assert(profile.Child2);
    assert(profile.Child2.child2Attr1 == "child2Attr1");
    assert(profile.Child2.elementValue == "child2Value");

    assert(profile.Child3);
    assert(profile.Child3.Child4);
    assert(profile.Child3.Child4.Array1);
    assert(profile.Child3.Child4.Array1.length == 3);
    assert(profile.Child3.Child4.Array1[0].name == "a1");
    assert(profile.Child3.Child4.Array1[1].arrayAttr1 == "arrayAttr1");
    assert(profile.Child3.Child4.Array1[2].name == "a2");

    assert(profile.Child3);
    assert(profile.Child3.Child5);
    assert(profile.Child3.Child5.Array1);
    assert(profile.Child3.Child5.Array1["a1"].name == "a1");
    assert(profile.Child3.Child5.Array1["a2"].arrayAttr2 == "arrayAttr2");
    assert(profile.Child3.Child5.Array1["a3"].name == "a3");

    assert(profile.Child3);
    assert(profile.Child3.Child6);
    assert(profile.Child3.Child6.Array1);
    assert(profile.Child3.Child6.Array1[0].name == "a1");
    assert(profile.Child3.Child6.Array1[1].arrayAttr1 == "arrayAttr1");
    assert(profile.Child3.Child6.Array1[2].name == "a2");
    assert(profile.Child3.Child6.Array2);
    assert(profile.Child3.Child6.Array2["b1"].name == "b1");
    assert(profile.Child3.Child6.Array2["b2"].arrayAttr5 == "arrayAttr5");
    assert(profile.Child3.Child6.Array2["b3"].name == "b3");

    assert(profile.AnonymousFunction.Script instanceof Function);
    globalResult = "";
    profile.AnonymousFunction.Script();
    assert(globalResult == "globalResult");

    assert(profile.Function.Script instanceof Function);
    assert(profile.Function.Script(1, 2) == 3);

    assert(profile.FunctionNoScript.Script instanceof Function);
    assert(profile.FunctionNoScript.Script(1, 2) == 3);

    assert(profile.PlainScript.Script instanceof JsScript);

    profile.PlainScript.Script.execute(this);
    assert(f(1 ,2) == 3);

    // Static variant

    var profile = GPXML.parse("parsertest.xml");
    dumpxml(profile, "");
    assert(profile);
    assert(profile.rootAttr1 == "rootAttr1");
    assert(profile.rootAttr2 == "rootAttr2");
    assert(profile.Child1);
    assert(profile.Child1.child1Attr1 == "child1Attr1");
    assert(profile.Child1.child1Attr2 == "child1Attr2");

    assert(profile.Child2);
    assert(profile.Child2.child2Attr1 == "child2Attr1");
    assert(profile.Child2.elementValue == "child2Value");

    assert(profile.Child3);
    assert(profile.Child3.Child4);
    assert(profile.Child3.Child4.Array1);
    assert(profile.Child3.Child4.Array1.length == 3);
    assert(profile.Child3.Child4.Array1[0].name == "a1");
    assert(profile.Child3.Child4.Array1[1].arrayAttr1 == "arrayAttr1");
    assert(profile.Child3.Child4.Array1[2].name == "a2");

    assert(profile.Child3);
    assert(profile.Child3.Child5);
    assert(profile.Child3.Child5.Array1);
    assert(profile.Child3.Child5.Array1["a1"].name == "a1");
    assert(profile.Child3.Child5.Array1["a2"].arrayAttr2 == "arrayAttr2");
    assert(profile.Child3.Child5.Array1["a3"].name == "a3");

    assert(profile.AnonymousFunction.Script instanceof Function);
    globalResult = "";
    profile.AnonymousFunction.Script();
    assert(globalResult == "globalResult");

    assert(profile.Function.Script instanceof Function);
    assert(profile.Function.Script(1, 2) == 3);

## parseApplicationProfile()

### Prototype

Object parse(String filename)

### Description

Parse the XML formatted application profile specified by filename and create a tree of ECMAScript objects.

The elements Key, DataElement, Function and ScriptFragment are deserialized as arrays.

### Arguments

Type | Name | Description
--- | --- | ---
`String` | filename | File name of XML file. Will be mapped to a physical file by the runtime environment.

### Return

`Object` | Root element of document object model

### 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 profile = GPXML.parseApplicationProfile("appl.xml");
    // dumpxml(profile, "");

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