Card Explorer Extensions Plug-In Interface Specification: Smart Card Toolset Pro

Smart Card ToolSet PRO
Card Explorer Extensions Plug-In

Interface Specification
Document version 1.6

Jul 14, 2019
© 2002-2021 DIGITAL MIND SYSTEMS INC.

Card Explorer Extension Plug-In Interface Specification
All rights reserved. No parts of this work may be reproduced in any form or by any means - graphic, electronic, or
mechanical, including photocopying, recording, taping, or information storage and retrieval systems - without the
written permission of the author.
Products that are referred to in this document may be either trademarks and/or registered trademarks of the
respective owners. The publisher and the author make no claim to these trademarks.
While every precaution has been taken in the preparation of this document, the publisher and the author assume no
responsibility for errors or omissions, or for damages resulting from the use of information contained in this
document or from the use of programs and source code that may accompany it. In no event shall the publisher and
the author be liable for any loss of profit or any other commercial damage caused or alleged to have been caused
directly or indirectly by this document.
Printed: Jul 14, 2019
Digital Mind Systems Inc.
info@DigitalMindSystems.c om
support@DigitalMindSystems.c om
Card Explorer Extensions Plug-In Interface Specification ( Document version 1.6 Jul 14, 2019 ) Contents
Table of Contents
Part I Overview 1
1 Terms
................................................................................................................................... 1
Card Explorer
.........................................................................................................................................................
Extensions Plug-In (Plug-In) 1
Main program
.........................................................................................................................................................
(Program ) 1
Plug-In Dispatcher
......................................................................................................................................................... 1
Program Dispatcher
......................................................................................................................................................... 1
Card Dispatcher
......................................................................................................................................................... 1
2 Data...................................................................................................................................
Types 1
3 Plug-Ins
...................................................................................................................................
Usage Fundamentals 2
Plug-In Loading
.........................................................................................................................................................
Phase 2
Step 1 : Loading
..................................................................................................................................................
the Plug-In library 2
Step 2 : Loading
..................................................................................................................................................
the Plug-In Type 2
Step 3 : Loading
..................................................................................................................................................
the Plug-In Name 3
Step 4 : Loading
..................................................................................................................................................
the Plug-In Description 3
Step 5 : OnRegistered
..................................................................................................................................................
Event 3
Step 6 : Loading
..................................................................................................................................................
the Card Dispatcher Interface 3
Plug-In Activity
.........................................................................................................................................................
Phase 4
OnActivate ..................................................................................................................................................
Event 4
OnExecute ..................................................................................................................................................
Event 4
Plug-In Unloading
.........................................................................................................................................................
Phase 4
OnUnregistered..................................................................................................................................................
Event 4
Part II Dispatchers 5
1 Interface
...................................................................................................................................
Dispatchers 5
Fundam entals
......................................................................................................................................................... 5
Function Form
.........................................................................................................................................................
at 5
Com m ands......................................................................................................................................................... 6
"Get Plug-In..................................................................................................................................................
Type" command 6
"Get Plug-In..................................................................................................................................................
Name" command 7
"Get Plug-In..................................................................................................................................................
Description" command 7
"Get Card Dispatcher"
..................................................................................................................................................
command 7
"Get Plug-In..................................................................................................................................................
Registry Path" command 8
"Hide Program" ..................................................................................................................................................
command 8
"Show Program" ..................................................................................................................................................
command 9
Events ......................................................................................................................................................... 9
"OnRegistered" ..................................................................................................................................................
event 9
"OnError" event
.................................................................................................................................................. 10
"OnActivate" ..................................................................................................................................................
event 10
"OnExecute" ..................................................................................................................................................
event 10
"OnCardWait" ..................................................................................................................................................
event 11
"OnCardReady"..................................................................................................................................................
event 11
"OnUnregistered"
..................................................................................................................................................
event 12
2 Commands
...................................................................................................................................
Dispatcher 12
Fundam entals
......................................................................................................................................................... 12
Function Form
.........................................................................................................................................................
at 12
Index 1

1 Card Explorer Extensions Plug-In Interface Specification ( Document version 1.6 Jul 14, 2019 ) Overview
1 Overview
1.1 Terms
1.1.1 Card Explorer Extensions Plug-In (Plug-In)
The Card Explorer Extensions Plug-In is a standard Dynamic Linked Library ( DLL ) which allows
you to expand the Card Explorer base functionality.
1.1.2 Main program (Program)
The main program is the Smart Card ToolSet PRO which loads this Plug-In dynamically and
controls it.
1.1.3 Plug-In Dispatcher
It is the exported function named "DispatchInterface".
Plug-In Dispatcher is used by the program to send commands and events to the Plug-In.
1.1.4 Program Dispatcher
It is the function in the Smart Card ToolSet PRO which is used by the Plug-In to send commands to
the main program.
1.1.5 Card Dispatcher
The Card Dispatcher is a function of Smart Card ToolSet PRO which is used to send APDU
commands from the Plug-In to an opened smart card.
1.2 Data Types
Only the following data types are supported:
· the Integer is: an unsigned 32 bits integer;

· the Pointer is: a 32 bits pointer;
· the String is: a chars array followed by the 0x00 symbol;

Card Explorer Extensions Plug-In Interface Specification ( Document version 1.6 Jul 14, 2019 ) Overview 2
1.3 Plug-Ins Usage Fundamentals
The Card Explorer Extensions Plug-In is the standard Dynamic Linked Library ( DLL ) which can be
created using any of popular development environments like MS Visual Studio, RAD
Development Studio e.t.c..
Every Card Explorer Extensions Plug-In must export one function named "DispatchInterface". This
function must have the predefined format because it will be linked by the main program.
The communication between the main program and Plug-In is based on the dispatchers calls.
The main program calls:

1. Plug-In Dispatcher;
The Plug-In calls:

1. Program Dispatcher;
2. Card Dispatcher;
The program controls the Plug-In by calling the Plug-In Dispatcher sending there the commands
and events.
The Plug-In calls the Program Dispatcher to send the control commands, and it calls the Card
Dispatcher to send the APDU commands.
1.3.1 Plug-In Loading Phase
The Card Explorer window loads the Plug-In library every time the card is opened.
1.3.1.1 Step 1 : Loading the Plug-In library
The program attempts to load the plug-in file as a standard DLL.
In the case of successful loading the program attempts to register its Dispatcher function named
"DispatchInterface".
1.3.1.2 Step 2 : Loading the Plug-In Type
The program sends to the Plug-In Dispatcher the "Get Plug-In Type" command:
Command Code Command Parameter Command Data
1 2 -
The Plug-In must return 10 as a value of the Command Data parameter.
Warning! Now the Command Data is being interpreted an Integer variable, not as the Pointer!

1.3.1.3 Step 3 : Loading the Plug-In Name
The program sends to the Plug-In Dispatcher the "Get Plug-In Name" command:
30 1 -
In the Command Data parameter the Plug-In must return a pointer to its local chars array.
This chars array should contain the name of this Plug-In ending by the 0x00 symbol.
1.3.1.4 Step 4 : Loading the Plug-In Description
The program sends to the Plug-In Dispatcher the "Get Plug-In Description" command:
30 2 -
In the Command Data parameter the Plug-In must return a pointer to its local chars array.
This chars array should contain the description of this Plug-In ending by the 0x00 symbol.
1.3.1.5 Step 5 : OnRegistered Event
The program sends to the Plug-In Dispatcher the "OnRegistered" event :
1 1 the pointer to the

Program Dispatcher
function
On this event the Plug-In must store in the local variable the received pointer to the Program
Dispatcher.
This event is the best place to request the main program for the pointer to the Card Dispatcher.
1.3.1.6 Step 6 : Loading the Card Dispatcher Interface
The Plug-In sends to the Program Dispatcher the "Get Dispatcher" command:
1 1000 the pointer to the

Card Dispatcher
function
The program returns the pointer to the Card Dispatcher function which should be stored by the Plug-
In in its local variable.

Card Explorer Extensions Plug-In Interface Specification ( Document version 1.6 Jul 14, 2019 ) Overview 4
1.3.2 Plug-In Activity Phase
After loading the Plug-In may be activated by the following ways:
1. A uto ma tic a lly b y the p ro g ra m:

· If this Plug-In is a default Plug-In for the opened card and if the check box "Allow activate the default Plug-In ..." of the
Card Type Editor is checked on;
2. Ma nua lly b y us e r:
· if the user has clicked on this Plug-In in the "Plug-Ins" menu;
To activate the Plug-In the main program sends to the Plug-In Dispatcher the "OnActivate" event.
1.3.2.1 OnActivate Event
This event occurs when the main program asks the Plug-In to appear its main window.
10 1 -
On this event the Plug-In must run its activating function and to show its main window.
1.3.2.2 OnExecute Event
This event occurs only after the OnActivate event, and only if the "Allow autoexecute on activate"
switch of the Card Type Editor is checked.
This event does not occur if the Plug-In is activated by the user interface.
10 2 -
On this event the Plug-In must run its main function.
1.3.3 Plug-In Unloading Phase
The main program unloads all Plug-Ins every time the card is closed.
1.3.3.1 OnUnregistered Event
This event occurs when the main program goes to unload the Plug-In.

1 100 -
On this event the Plug-In must stop the execution and must free all the resources used.
2 Dispatchers
2.1 Interface Dispatchers
2.1.1 Fundamentals
The Plug-In Dispatcher is the DLL function exported by the Plug-In with the "DispatchInterface"
name. It used by the program to send commands and events to the Plug-In.
The Program Dispatcher is the program function with the same parameters like the Plug-In
Dispatcher. It used by the Plug-In to send the commands to the main program.
Any command is a combination of three parameters passed to the dispatcher function.
The first two parameters "Command Code" and "Command Parameter" must be assigned every
time the dispatcher is called. The third parameter "Command Data" may be either assigned or not
depending to the command.
Ca lling the P ro g ra m D is p a tc he r
To call the dispatcher you need to prepare the following data:
1. define the local variable of an integer type and assign to it the Command Code value of the selected command;
2. define the local variable of an integer type and assign to it the Command Parameter value of the selected command;
3. define the local variable of a pointer type and assign to it the address of the data buffer according to current command if
need;
4. define the three pointer variables and assign them addresses of the previous three variables; you must use only pointers
as the dispatcher's parameters;
Call the dispatcher using the prepared pointers. The function will return the result code. In some
cases the dispatcher may return in the Command Data parameter the pointer to a data buffer.
R e c e iv ing the p ro g ra m c a lls b y P lug -In D is p a tc he r
You need to classify the received parameters according to the Commands list using the logical
operators like if, s witc h, c a s e e.t.c. Please look into the example application code for more
details.
2.1.2 Function Format
The Plug-In Dispatcher is the integer type function with the following parameters:
N Parameter Name Parameter T ype Variable Value Desc ription
1 Command Code Pointer to Integer The Code of the command (Integer)
2 Command Parameter Pointer to Integer The Parameter of the command (Integer)

Card Explorer Extensions Plug-In Interface Specification ( Document version 1.6 Jul 14, 2019 ) Dispatchers 6
3 Command Data Pointer to Pointer The pointer to the data buffer (chars array pointer)
The function returns the integer-type Result Code:
Value Result
1 Success
2 The Command Code is invalid or assigned to unsupported value
3 The Command Parameter is invalid or assigned to unsupported value
2.1.3 Commands
Both Program- and Plug-In Dispatchers are based on the same set of commands.
2.1.3.1 "Get Plug-In Type" command
Caller : Program
Receiver : Plug-In
Parameter Name Parameter T ype Variable and Value Desc ription
Command Code pointer 1

to the variable Integer
of the Integer type
Command Parameter pointer 2

of the Integer type
Command Data pointer 10

of the Integer type

7 Card Explorer Extensions Plug-In Interface Specification ( Document version 1.6 Jul 14, 2019 ) Dispatchers
2.1.3.2 "Get Plug-In Name" command
Caller : Program
Receiver : Plug-In

of the Integer type

of the Integer type
Command Data pointer the address of the Plug-In must assign to this
to the variable the local chars array; variable the address of the local
of the Pointer type Pointer chars array which contains the Plug-
In Name string followed by the 0x00
char;
2.1.3.3 "Get Plug-In Description" command
Caller : Program
Receiver : Plug-In

of the Integer type

of the Integer type
Command Data pointer the address of the Plug-In must assign to this
to the variable the local chars array; variable the address of the local
of the Pointer type Pointer chars array which contains the Plug-
In Description string followed by the
0x00 char;
2.1.3.4 "Get Card Dispatcher" command
Caller : Plug-In
Receiver : Program


of the Integer type

of the Integer type
Command Data pointer the address of the address of the

to the variable the function; Card Dispatcher
of the Pointer type Pointer function;
The Plug-In sends this command to get an address of the Card Dispatcher function.
2.1.3.5 "Get Plug-In Registry Path" command
Caller : Plug-In
Receiver : Program

of the Integer type

of the Integer type
Command Data pointer the address of the address of the Program local
to the variable the local chars array; chars array which contains the full
of the Pointer type Pointer registry path to the key which
contains the Plug-In preferences
followed by the 0x00 char;
The Plug-In sends this command to get the registry key to store the preferences there, if need.
2.1.3.6 "Hide Program" command
Caller : Plug-In
Receiver : Program

of the Integer type

of the Integer type
Command Data pointer null

not used Pointer
The Plug-In sends this command to hide the main program window, if need.

2.1.3.7 "Show Program" command
Caller : Plug-In
Receiver : Program

of the Integer type

of the Integer type

not used Pointer
The Plug-In sends this command to show the main program window, if need.
2.1.4 Events
The program notifies the Plug-In by sending an events using the Plug-In Dispatcher interface.
2.1.4.1 "OnRegistered" event
Caller : Program
Receiver : Plug-In

of the Integer type

of the Integer type
Command Data pointer the address of The address of the Program

to the variable the function; Dispatcher
of the Pointer type Pointer
This event occurs after the Plug-In has been successfully loaded. The received pointer to the
Program Dispatcher should be stored to a local variable for the future usage.

2.1.4.2 "OnError" event
Caller : Program
Receiver : Plug-In

of the Integer type

on the variable Integer
of an Integer type
Command Data pointer the address of The address of the local chars array
to the variable the local chars array; which contains an error string
of the Pointer type Pointer followed by the 0x00 char;
This event occurs if any error is detected.
2.1.4.3 "OnActivate" event
Caller : Program
Receiver : Plug-In

of the Integer type

of the Integer type

not used Pointer
This event occurs when the main program asks the Plug-In to show its main window, as follows
· if user has clicked on the Plug-In name menu item of the "Plug-Ins" menu;
· this Plug-In is a default Plug-In for the opened card and if the "Allow activate the default Plug-In ..." check box of the
Card Type Editor is checked;
On this event the Plug-In must run its activating function and show its main window.
2.1.4.4 "OnExecute" event
Caller : Program
Receiver : Plug-In


of the Integer type

of the Integer type

not used Pointer
This event occurs only after the OnActivate event is fired, and only if the "Allow autoexecute on
activate" switch of the Card Type Editor is checked.
This event does not occur if the Plug-In is activated by the user interface.
On this event the Plug-In must run its main function.
2.1.4.5 "OnCardWait" event
Caller : Program
Receiver : Plug-In

of the Integer type
C ommand pointer 10
Parameter to the variable Integer
of the Integer type

not used Pointer
This event occurs when the reader becomes empty.
The Plug-In must stop all card operations.
2.1.4.6 "OnCardReady" event
Caller : Program
Receiver : Plug-In

of the Integer type

of the Integer type

not used Pointer

This event occurs when the card is successfully opened in the reader.
2.1.4.7 "OnUnregistered" event
Caller : Program
Receiver : Plug-In

of the Integer type

of the Integer type

not used Pointer
This event occurs when the main program goes to unload the Plug-In.
On this event the Plug-In must stop the execution and must free all resources used.
2.2 Commands Dispatcher

2.2.1 Fundamentals
The Card Dispatcher is a function of Smart Card ToolSet PRO which is attended to use for sending
APDU commands from the Plug-In to an opened smart card.
To get its address call the "Get Card Dispatcher" function.
How to send the APDU command into a card:
1. define the Plug-In local buffer (Send Buffer); prepare the APDU command and store it in the Send Buffer;
2. define the local variable of the Integer type and assign to it the length of the APDU command data stored in the Send
Buffer;
3. define the local variable of the Pointer type; the program will assign it to the address of the card response buffer;
4. define the local variable of the Integer type; the program will assign it to the length value of the card response buffer;
5. define four variables of the Pointer type and assign them to the addresses of four previously defined variables; call the
Card Dispatcher with those four pointers as parameters;
6. if your APDU command has been sent successfully the Card Dispatcher returns "0" and the Received Buffer parameter
points to the response data buffer, otherwise it returns "-1";
2.2.2 Function Format
The Card Dispatcher is the integer type function with the following parameters:
N Parameter Name Parameter T ype Variable Desc ription

1 Send Buffer Pointer to Pointer Pointer to the Plug-In local data buffer which
contains the command APDU data to send;
2 Send Buffer Length Pointer to Integer Length of the Send Buffer data in bytes;
3 Received Buffer Pointer to Pointer Pointer to the Program local data buffer which
contains the received card response data
4 Received Buffer Length Pointer to Integer Length of the Received Buffer data in bytes;
The function returns the integer type Result Code:
Value Result
0 The command data has been sent to the opened card successfully;
-1 The error has been detected while sending the data

Card Explorer Extensions Plug-In Interface Specification ( Document version 1.6 Jul 14, 2019 ) Index
Index
-P-
Plug-In Active Phase 4
Plug-In Command "Get Card Dispatcher" 7
Plug-In Command "Get Plug-In Description" 7
Plug-In Command "Get Plug-In Name" 7
Plug-In Command "Get Plug-In Registry Path" 8
Plug-In Command "Get Plug-In Type" 6
Plug-In Command "Hide Program" 8
Plug-In Command "Show Program" 9
Plug-In Commands Parameters 6
Plug-In Data Types 1
Plug-In Event "OnActivate" 10
Plug-In Event "OnCardReady" 11
Plug-In Event "OnCardWait" 11
Plug-In Event "OnError" 10
Plug-In Event "OnExecute" 10
Plug-In Event "OnRegistered" 9
Plug-In Event "OnUnregistered" 12
Plug-In Events Parameters 9
Plug-In Function Format : Card Dispatcher 12
Plug-In Function Format : Interface Dispatcher 5
Plug-In Fundamentals : Card Dispatcher 12
Plug-In Fundamentals : Interface Dispatchers 5
Plug-In Fundamentals : Plug-Ins Using 2
Plug-In Loading Phase 2
Plug-In Terms: Card Dispatcher 1
Plug-In Terms: Main Program 1
Plug-In Terms: Plug-In Dispatcher 1
Plug-In Terms: Program Dispatcher 1
Plug-In Unloading Phase 4

Card Explorer Extensions Plug-In Interface Specification: Smart Card Toolset Pro

Uploaded by

Copyright:

Available Formats

You might also like

Card Explorer Extensions Plug-In Interface Specification: Smart Card Toolset Pro

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Card Explorer Extensions Plug-In Interface Specification: Smart Card Toolset Pro

Uploaded by

Copyright:

Available Formats

Smart Card ToolSet PRO

Card Explorer Extensions Plug-In

Document version 1.6

© 2002-2021 DIGITAL MIND SYSTEMS INC.

© 2002-2021 DIGITAL MIND SYSTEMS INC.

Printed: Jul 14, 2019

Digital Mind Systems Inc.

© 2002-2021 DIGITAL MIND SYSTEMS INC.

1.1.2 Main program (Program)

1.1.3 Plug-In Dispatcher

It is the exported function named "DispatchInterface".

1.1.4 Program Dispatcher

1.1.5 Card Dispatcher

1.2 Data Types

Only the following data types are supported:

· the Integer is: an unsigned 32 bits integer;

© 2002-2021 DIGITAL MIND SYSTEMS INC.

1.3 Plug-Ins Usage Fundamentals

The main program calls:

The Plug-In calls:

1.3.1 Plug-In Loading Phase

1.3.1.1 Step 1 : Loading the Plug-In library

The program attempts to load the plug-in file as a standard DLL.

1.3.1.2 Step 2 : Loading the Plug-In Type

Command Code Command Parameter Command Data

The Plug-In must return 10 as a value of the Command Data parameter.

© 2002-2021 DIGITAL MIND SYSTEMS INC.

1.3.1.3 Step 3 : Loading the Plug-In Name

Command Code Command Parameter Command Data

1.3.1.4 Step 4 : Loading the Plug-In Description

Command Code Command Parameter Command Data

1.3.1.5 Step 5 : OnRegistered Event

The program sends to the Plug-In Dispatcher the "OnRegistered" event :

Command Code Command Parameter Command Data

1 1 the pointer to the

1.3.1.6 Step 6 : Loading the Card Dispatcher Interface

Command Code Command Parameter Command Data

1 1000 the pointer to the

© 2002-2021 DIGITAL MIND SYSTEMS INC.

1.3.2 Plug-In Activity Phase

After loading the Plug-In may be activated by the following ways:

1. A uto ma tic a lly b y the p ro g ra m:

1.3.2.1 OnActivate Event

Command Code Command Parameter Command Data

1.3.2.2 OnExecute Event

Command Code Command Parameter Command Data

On this event the Plug-In must run its main function.

1.3.3 Plug-In Unloading Phase

1.3.3.1 OnUnregistered Event

Command Code Command Parameter Command Data

© 2002-2021 DIGITAL MIND SYSTEMS INC.

Any command is a combination of three parameters passed to the dispatcher function.

To call the dispatcher you need to prepare the following data:

R e c e iv ing the p ro g ra m c a lls b y P lug -In D is p a tc he r

2.1.2 Function Format

N Parameter Name Parameter T ype Variable Value Desc ription

1 Command Code Pointer to Integer The Code of the command (Integer)

2 Command Parameter Pointer to Integer The Parameter of the command (Integer)