PlugInsInterface 1.3 PDF

Smart Card ToolSet PRO
Card Explorer Extensions Plug-Ins

Interface Specification
Document version 1.5

Nov.17, 2012
© 2002-2012 Igor V.Kharchenko, SCard SOFT

Card Explorer Extensions Plug-Ins 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: Nov.17, 2012
SCard SOFT
info@scardsoft.com
igor@scardsoft.com
Card Explorer Extensions Plug-Ins Interface Specification ( Document version 1.5 Nov.17, 2012 ) 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 1
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 2
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
Fundamentals......................................................................................................................................................... 5
Function Format
......................................................................................................................................................... 5
Commands......................................................................................................................................................... 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
Fundamentals
......................................................................................................................................................... 12
Function Format
......................................................................................................................................................... 12
Index 1

1 Card Explorer Extensions Plug-Ins Interface Specification ( Document version 1.5 Nov.17, 2012 ) 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 base functionality of the Card Explorer window.
1.1.2 Main program (Program)
The main program is the Smart Card ToolSet PRO which loads this Plug-In and controls it.
1.1.3 Plug-In Dispatcher
It is the exported function named "DispatchInterface".
Plug-In Dispatcher 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;
1.3 Plug-Ins Usage Fundamentals
The Card Explorer Extensions Plug-In is the standard Dynamic Linked Library ( DLL ) and it may
be created by any of development environments like MS Visual Studio, Delphi e.t.c..

Card Explorer Extensions Plug-Ins Interface Specification ( Document version 1.5 Nov.17, 2012 ) Overview 2
Each Card Explorer Extensions Plug-In must export one function named "DispatchInterface". This
function must has predefined parameters format because it should be linked by the main program.
The communication between the main program and Plug-Ins 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 in the case of
this Plug-In is registered to the card type.
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 loading is successful the program attempts to register the Plug-In 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! Only in the case of current command the Command Data is a variable of an Integer type,
not a 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 -
The Plug-In must returns the pointer to its local chars array as a value of the Command Data
parameter.
This chars array should contain the name of this Plug-In followed 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 -
The Plug-In must returns the pointer to its local chars array as a value of the Command Data
parameter.
This chars array should contain the description of this Plug-In followed 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 the received pointer to the Program Dispatcher into its local
variable.
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-Ins Interface Specification ( Document version 1.5 Nov.17, 2012 ) Overview 4
1.3.2 Plug-In Activity Phase
After loading the Plug-In may be activated by the following ways:
1. Automatically by the program:

· 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;
2. Manually by user:
· if the user has clicked on the Plug-In name menu item of 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 wants the Plug-In to show its main window.
10 1 -
On this event the Plug-In must run its activating function and show its main window.
1.3.2.2 OnExecute Event
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 user manually by clicking on the menu item.
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 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 "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" of the dispatcher must be
assigned any time the dispatcher is called. The third parameter "Command Data" may be either
defined or not depending to the command.
Calling the Program Dispatcher
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.
Receiving the program calls by Plug-In Dispatcher
You need to classify the received parameters according to the Commands list using the logical
operators like if, switch, c a s e e.t.c. Please look into the example application code for details.
2.1.2 Function Format
The Plug-In Dispatcher is the integer type function with the following parameters:
N Parameter Name Parameter Type Variable Value Description
1 Command Code Pointer to Integer The Code of the command (Integer)
2 Command Parameter Pointer to Integer The Parameter of the command (Integer)
3 Command Data Pointer to Pointer The pointer to the data buffer (chars array pointer)
The function returns the integer-type Result Code:

Card Explorer Extensions Plug-Ins Interface Specification ( Document version 1.5 Nov.17, 2012 ) Dispatchers 6
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 Type Variable and Value Description
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-Ins Interface Specification ( Document version 1.5 Nov.17, 2012 ) 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 is successfully loaded by the main program. The received
pointer to the Program Dispatcher should be stored to a local variable.

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 wants 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 user manually by clicking on the menu item.
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
Command 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 used to send 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) for preparing of the sending data; 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 using these 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 Type Variable Description

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-Ins Interface Specification ( Document version 1.5 Nov.17, 2012 ) 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 1
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

PlugInsInterface 1.3 PDF

Transféré par

Informations du document

Titre original

Copyright

Formats disponibles

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

Formats disponibles

PlugInsInterface 1.3 PDF

Transféré par

Droits d'auteur :

Formats disponibles

Smart Card ToolSet PRO

Card Explorer Extensions Plug-Ins

Document version 1.5

© 2002-2012 Igor V.Kharchenko, SCard SOFT

© 2002-2012 Igor V.Kharchenko, SCard SOFT

Printed: Nov.17, 2012

© 2002-2012 Igor V.Kharchenko, SCard SOFT

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;

1.3 Plug-Ins Usage Fundamentals

© 2002-2012 Igor V.Kharchenko, SCard SOFT

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.

1.3.1.3 Step 3 : Loading the Plug-In Name

Command Code Command Parameter Command Data

© 2002-2012 Igor V.Kharchenko, SCard SOFT

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-2012 Igor V.Kharchenko, SCard SOFT

1.3.2 Plug-In Activity Phase

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

1. Automatically by the program:

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-2012 Igor V.Kharchenko, SCard SOFT

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

Calling the Program Dispatcher

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

Receiving the program calls by Plug-In Dispatcher

2.1.2 Function Format

N Parameter Name Parameter Type Variable Value Description

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

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

The function returns the integer-type Result Code:

© 2002-2012 Igor V.Kharchenko, SCard SOFT

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.1 "Get Plug-In Type" command