
JiBAPI - C API for the Java Powered iButton
GetJiBAPIVersion
DWORD GetJiBAPIVersion()
- Returns the API version. Version major in LS WORD and minor in MS WORD.
- Returns:
- The version of this API.
SetDefaultExecTime
void SetDefaultExecTime(WORD p_ExecTimeMS)
- Sets the default execution time.
- Parameters:
p_ExecTimeMS
- default runtime.
SendAPDU
LPRESPONSEAPDU SendAPDU(LPCOMMANDAPDU p_lpCommandAPDU,
WORD p_ExecTimeMS)
- Sends a generic command APDU to the iButton.
- Parameters:
p_lpCommandAPDU
- is configured by the caller.p_ExecTimeMS
- is the estimated runtime in milliseconds. Valid
runtimes range from 64 milliseconds to just under 4 seconds (4000 ms).
Invalid runtimes will be automatically adjusted up or down as necessary.- Returns:
- The ResponseAPDU containing the Status Word of the response.
SW = 0x9000 indicates success.
SetPIN
void SetPIN(LPJIBMASTERPIN p_lpMasterPIN)
- Sets the Local PIN variable that is sent to the iButton as the Master PIN,
in the command data, for commands that require a PIN.
NOTE:This command does not set the iButton's Master PIN.
- Parameters:
p_MasterPIN
- PIN sent with APDUs that require a Master PIN.
Process
LPRESPONSEAPDU Process(BYTE p_CLA,
BYTE p_INS,
BYTE p_P1,
BYTE p_P2,
BYTE p_Lc,
LPBYTE p_lpData,
WORD p_RunTimeMS)
- Runs the process method on the selected applet. Valid CLA, INS, P1 and P2
values are chosen by the applet writer. CLA, INS, P1 and P2 values used
by the API and/or the iButton Command Processor are reserved.
- Parameters:
p_CLA
- Class byte.p_INS
- Instruction byte.p_P1
- Parameter byte 1.p_P2
- Parameter byte 2.p_Lc
- Command data length.p_lpData
- Pointer to command data..p_RunTimeMS
- Suggested runtime in milliseconds.- Returns:
- The ResponseAPDU containing the Status Word of the response.
SW = 0x9000 indicates success.
Select
LPRESPONSEAPDU Select(LPAID p_lpAID)
- Selects an applet to be active on the iButton.
- Returns:
- The ResponseAPDU containing the Status Word of the response.
SW = 0x9000 indicates success.
NOTE: The iButton will return an error if the string is not in the
range 5 to 16 bytes (inclusive).
MasterErase
LPRESPONSEAPDU MasterErase()
- Issues a master erase of the iButton
- Returns:
- A ResponseAPDU object containing the response apdu sent by the
iButton.
SW = 0x9000 indicates success.
GetFreeRam
LPRESPONSEAPDU GetFreeRam()
- Returns:
- A ResponseAPDU that contains the amount of free RAM.
SW = 0x9000 indicates success.
ReadFreeRam
LPRESPONSEAPDU ReadFreeRam()
- Returns:
- A ResponseAPDU that contains the amount of free RAM.
SW = 0x9000 indicates success.
NOTE: Deprecated.
GetFirmwareVersionString
LPRESPONSEAPDU GetFirmwareVersionString()
- Returns:
- A ResponseAPDU containing the Firmware Version String.
SW = 0x9000 indicates success.
ReadFirmwareVersionID
LPRESPONSEAPDU ReadFirmwareVersionID()
- Returns:
- A ResponseAPDU containing the Firmware Version ID.
SW = 0x9000 indicates success.
NOTE: Deprecated.
GetEphemeralGCMode
LPRESPONSEAPDU GetEphemeralGCMode()
- Reads the ephemeral garbage collection mode.
- Returns:
- The ResponseAPDU containing the value of the ephemeral garbage
Collector. A value of 1 indicates the garbage collector is
turned on.
SW = 0x9000 indicates success.
SetEphemeralGCMode
LPRESPONSEAPDU SetEphemeralGCMode(BYTE p_Mode)
- Sets the mode of the ephemeral garbage collector. Setting the mode to
1 turns the collector on, setting it to 0 turns the collector off.
If the iButton is password protected, setPIN() should be called before
invoking this method.
- Parameters:
p_Mode
- 1 - turn the collector on,
0 - turn the collector off.- Returns:
- The ResponseAPDU containing the Status Word of the response.
SW = 0x9000 indicates success.
GetAppletGCMode
LPRESPONSEAPDU GetAppletGCMode()
- Reads the applet garbage collection mode.
- Returns:
- The ResponseAPDU containing the mode of the applet garbage
Collector. A value of 1 indicates the garbage collector is
turned on.
SW = 0x9000 indicates success.
SetAppletGCMode
LPRESPONSEAPDU SetAppletGCMode(BYTE p_Mode)
- Sets the mode of the applet garbage collector. Setting the mode to 1
turns the collector on, setting it to 0 turns the collector off.
If the iButton is password protected, setPIN() should be called before
invoking this method.
- Parameters:
p_Mode
- 1 - turn the collector on,
0 - turn the collector off.- Returns:
- The ResponseAPDU containing the Status Word of the response.
SW = 0x9000 indicates success.
GetCommandPINMode
LPRESPONSEAPDU GetCommandPINMode()
- Returns the mode of the CommandPIN. If a value of 1 is returned by
the iButton, PINs are required to perform all Admistrative commands.
- Returns:
- The ResponseAPDU containing the mode of the CommandPIN.
A value of 1 indicates a PIN is required for all Administrative
commands.
SW = 0x9000 indicates success.
SetCommandPINMode
LPRESPONSEAPDU SetCommandPINMode(BYTE p_Mode)
- Sets the mode of the CommandPIN. Setting the mode to 1 indicates the
the iButton should require a PIN for all Administrative commands.
- Parameters:
p_Mode
- 1 - set the CommandPIN mode to require a PIN for
all Administrative commands.
0 - set the CommandPIN mode to not require a PIN
for Administrative commands.- Returns:
- The ResponseAPDU containing the Status Word of the response.
SW = 0x9000 indicates success.
GetLoadPINMode
LPRESPONSEAPDU GetLoadPINMode()
- Returns the mode of the LoadPIN. If a value of 1 is returned by the
iButton, PINs are required to load applets.
- Returns:
- The ResponseAPDU containing the mode of the LoadPIN.
A value of 1 indicates a PIN is required for loading applets
into the iButton.
SW = 0x9000 indicates success.
SetLoadPINMode
LPRESPONSEAPDU SetLoadPINMode(BYTE p_Mode)
- Sets the mode of the LoadPIN. Setting the mode to 1 indicates the
iButton should require a PIN for all applets loads.
- Parameters:
p_Mode
- 1 - set the LoadPIN mode to require a PIN for applet
load.
0 - set the LoadPIN mode to not require a PIN for
applet load.- Returns:
- The ResponseAPDU containing the Status Word of the response.
SW = 0x9000 indicates success.
GetRestoreMode
LPRESPONSEAPDU GetRestoreMode()
- Returns:
- The ResponseAPDU containing the restore mode.
SW = 0x9000 indicates success.
SetRestoreMode
LPRESPONSEAPDU SetRestoreMode(BYTE p_Mode)
- Setting the mode to 1 enables restoration of fields to previous values
if a transaction was interrupted.
- Parameters:
p_Mode
- 1 - Allow restoration.
0 - Do not allow restoration.- Returns:
- The ResponseAPDU containing the Status Word of the response.
SW = 0x9000 indicates success.
GetExceptionMode
LPRESPONSEAPDU GetExceptionMode()
- Gets the Exception mode of the iButton. If the mode is 1, then VM
exceptions are thrown. If the mode is 0, then VM exceptions are not
thrown.
- Returns:
- The ResponseAPDU containing the Exception mode.
SW = 0x9000 indicates success.
SetExceptionMode
LPRESPONSEAPDU SetExceptionMode(BYTE p_Mode)
- Sets the Exception mode of the iButton. If the mode is 1, then VM
exceptions are thrown. If the mode is 0, then VM exceptions are not
thrown.
- Parameters:
p_Mode
- 1 - set the Exception mode to allow VM thrown
exceptions.
0 - set the Exception mode to not allow the VM to
throw exceptions.- Returns:
- The ResponseAPDU containing the Status Word of the response.
SW = 0x9000 indicates success.
GetISOExceptionMode
LPRESPONSEAPDU GetISOExceptionMode()
- Gets the ISOException mode of the iButton. If the mode is 1,
ISOExceptions are handled differently from all other exceptions.
Instead of returning 0x6f00 for an uncaught ISOException, the reason is
returned in the SW. If the mode is 0, ISOExceptions are handled like
all other exceptions.
- Returns:
- The ResponseAPDU containing the ISOException mode.
SW = 0x9000 indicates success.
NOTE: Requires Firmware Revision 1.00 or greater.
SetISOExceptionMode
LPRESPONSEAPDU SetISOExceptionMode(BYTE p_Mode)
- Sets the ISOException mode of the iButton. If the mode is 1,
ISOExceptions are handled differently from all other exceptions.
Instead of returning 0x6f00 for an uncaught ISOException, the reason is
returned in the SW. If the mode is 0, ISOExceptions are handled like
all other exceptions.
- Parameters:
p_Mode
- 1 - set the ISOException mode.
0 - clear the ISOException mode.- Returns:
- The ResponseAPDU containing the Status Word of the response.
SW = 0x9000 indicates success.
NOTE: Requires Firmware Revision 1.00 or greater.
GetErrorReportMode
LPRESPONSEAPDU GetErrorReportMode()
- Gets the Error Reporting mode of the iButton. If the mode is 1,
GetLastJCREError will return the error byte indicating the reason for
the last "Java Card Runtime Environment" thrown error.
- Returns:
- The ResponseAPDU containing the Error Reporting mode.
SW = 0x9000 indicates success.
NOTE: Requires Firmware Revision 1.00 or greater.
SetErrorReportMode
LPRESPONSEAPDU SetErrorReportMode(BYTE p_Mode)
- Sets the Error Report mode of the iButton. If the mode is 1,
GetLastJCREError will return the error byte indicating the reason for
the last "Java Card Runtime Environment" thrown error.
- Parameters:
p_Mode
- 1 - set the Error Report mode to.
0 - set the Error Report mode to.- Returns:
- The ResponseAPDU containing the Status Word of the response.
SW = 0x9000 indicates success.
NOTE: Requires Firmware Revision 1.00 or greater.
GetCommitBufferSize
LPRESPONSEAPDU GetCommitBufferSize()
- Gets the size of the iButton's Commit Buffer.
- Returns:
- The ResponseAPDU containing the size of the iButton's commit
buffer in bytes. The ResponseAPDU's data field will contain two
bytes representing the size (short).
SW = 0x9000 indicates success.
GetCommitBufferFields
LPRESPONSEAPDU GetCommitBufferFields()
- Gets the number of fields in the iButton's Commit Buffer.
- Returns:
- The ResponseAPDU containing the size of the iButton's commit
buffer in number of fields. The ResponseAPDU's data field will
contain two bytes representing the size (short).
SW = 0x9000 indicates success.
SetCommitBufferSize
LPRESPONSEAPDU SetCommitBufferSize(short p_SizeInBytes)
- Sets the iButtons CommitBufferSize. The value passed in is rounded up
by the iButton to the nearest multiple of COMMIT_BUFFER_BYTES_PER_FIELD.
- Parameters:
p_SizeInBytes
- the new size of the commit buffer in bytes.- Returns:
- The ResponseAPDU containing the Status Word of the response.
SW = 0x9000 indicates success.
SetCommitBufferFields
LPRESPONSEAPDU SetCommitBufferFields(short p_NumberOfFields)
- Calculates the number of bytes that is needed to store p_NumberOfFields
fields in the commit buffer and resizes the buffer accordingly.
- Parameters:
p_NumberOfFields
- the new size of the commit buffer using
number of fields.- Returns:
- The ResponseAPDU containing the Status Word of the response.
SW = 0x9000 indicates success.
GetATR
LPRESPONSEAPDU GetATR()
- Reads the Answer to Reset from the iButton, as defined in ISO7816-5
- Returns:
- Response APDU that contains the iButton's ATR.
SW = 0x9000 indicates success.
GetRealTimeClock
LPRESPONSEAPDU GetRealTimeClock()
- Reads the Real Time Clock of the iButton.
- Returns:
- The ResponseAPDU containing the value of the Real Time Clock.
SW = 0x9000 indicates success.
GetRandomBytes
LPRESPONSEAPDU GetRandomBytes(short p_NumBytes)
- Reads random bytes from the iButton. The maximum number of bytes that
can be reads is MAX_RECEIVE - APDU overhead.
- Parameters:
p_NumBytes
- the number of random bytes to read from the
iButton.- Returns:
- Response APDU that contains the requested number of random
bytes.
SW = 0x9000 indicates success.
GetAIDByNumber
LPRESPONSEAPDU GetAIDByNumber(BYTE p_AIDNum)
- Returns the AID of the applet with the given number. Each applet stored
on the iButton is assigned a number(0 - 15). A directory structure of
applets on an iButton can be built by calling this method iteratively
with parameter values from 0 to 15.
NOTE: - AIDs are not guaranteed to be stored in contiguous locations.
Therefore an exaustive search through all numbers 0 - 15 is
required to enumerate all applets on the iButton.
- Revision 0.03 and below used 2 bytes for the AID length. Later
versions use 1 byte.
- Parameters:
p_AIDNum
- the number of the applet to retrieve the AID.- Returns:
- Response APDU containing the AID of the applet requested.
SW = 0x9000 indicates success.
GetLastJCREError
LPRESPONSEAPDU GetLastJCREError()
- If Error Reporting Mode is enabled, the error byte indicating the reason
for the last JCRE thrown error is returned. Otherwise an error is
returned in the SW (see: GetErrorReportMode,SetErrorReportMode).
- Returns:
- The ResponseAPDU containing the Error Reporting mode.
SW = 0x9000 indicates success.
NOTE: Requires Firmware Revision 1.00 or greater.
GetAllAIDs
LPRESPONSEAPDU GetAllAIDs()
- Gets the list of all installed applets on the iButton.
- Returns:
- the list of all applets installed on the iButton.
SW = 0x9000 indicates success.
NOTE: Requires Firmware Revision 1.10 or greater.
GetActivationTimeRemaining
LPRESPONSEAPDU GetActivationTimeRemaining()
- Gets the amount of time remaining before the iButton will become
inactive.
- Returns:
- the amount of time remaining in the iButton's activation period.
SW = 0x9000 indicates success.
NOTE: Requires Firmware Revision 1.10 or greater.
GetVerifyLoadWithIdMode
LPRESPONSEAPDU GetVerifyLoadWithIdMode()
- Gets the "Verify Applet Load With Id" mode of the iButton.
If the mode is 1, only applets that were signed with the
iButton's unique 64 bit Id will be allowed to load.
- Returns:
- The ResponseAPDU containing the "Verify Applet Load With Id"
mode.
SW = 0x9000 indicates success.
NOTE: Requires Firmware Revision 1.10 or greater.
SetVerifyLoadWithIdMode
LPRESPONSEAPDU SetVerifyLoadWithIdMode(BYTE p_Mode)
- Sets the "Verify Applet Load With Id" mode of the iButton.
If the mode is 1, only applets that were signed with the
iButton's unique 64 bit Id will be allowed to load.
- Parameters:
p_Mode
- 1 - set the "Verify Applet Load With Id" mode.
0 - clear the "Verify Applet Load With Id" mode.- Returns:
- The ResponseAPDU containing the Status Word of the response.
SW = 0x9000 indicates success.
NOTE: Requires Firmware Revision 1.10 or greater.
GetPORCount
LPRESPONSEAPDU GetPORCount()
- Gets the number of Power On Resets the device has experienced since the
last master erase.
- Returns:
- Response APDU containing the number of POR since the last
master erase.
SW = 0x9000 indicates success.
SetMasterPIN
LPRESPONSEAPDU SetMasterPIN(LPJIBMASTERPIN p_lpNewMasterPin)
- Sets the master PIN of the iButton. A call to SetPIN with the old PIN
is required before this method can be called. The PIN to be set is
passed in.
- Parameters:
p_lpNewMasterPin
- the new PIN for the iButton- Returns:
- The ResponseAPDU containing the Status Word of the response.
SW = 0x9000 indicates success.
DeleteSelectedApplet
LPRESPONSEAPDU DeleteSelectedApplet()
- Deletes the currently selected Applet.
- Returns:
- The ResponseAPDU containing the Status Word of the response.
SW = 0x9000 indicates success.
DeleteAppletByNumber
LPRESPONSEAPDU DeleteAppletByNumber(BYTE p_AppletNumber)
- Deletes Applet number p_AppletNumber.
- Parameters:
p_AppletNumber
- number of the applet to be deleted.- Returns:
- The ResponseAPDU containing the Status Word of the response.
SW = 0x9000 indicates success.
DeleteAppletByAID
LPRESPONSEAPDU DeleteAppletByAID(LPAID p_lpAID)
- Deletes the Applet with AID p_lpAID.
- Parameters:
p_lpAID
- AID of the applet to be deleted.- Returns:
- The ResponseAPDU containing the Status Word of the response.
SW = 0x9000 indicates success.
LoadApplet
LPRESPONSEAPDU LoadApplet(LPBYTE p_lpAppletBuffer,
DWORD p_AppletLen,
LPAID p_lpAID)
- Loads the applet stored in p_lpAppletBuffer.
- Parameters:
p_lpAppletBuffer
- Buffer containing the applet (ASSUMPTION:
Buffer was previously loaded with the
contents of a .JiB "dot JiB" file).p_AppletLen
- Length of the applet in the buffer.p_lpAID
- Pointer the the applet's AID.- Returns:
- The ResponseAPDU containing the Status Word of the response.
SW = 0x9000 indicates success.
ReleaseJiBSearchList
static void ReleaseJiBSearchList()
- Releases search list memory.
SetJiBSearchParams
void SetJiBSearchParams(BYTE p_SPNum,
LPBYTE[] p_lpDevName)
- Set parameters for JiB search.
- Parameters:
p_SPNum
- number of serial ports in the search list.p_lpDevName
- pointer to a list of serial port device names.
ReleaseJiBAPIResources
void ReleaseJiBAPIResources()
- Releases API resources -
Should be called just before an application terminates.
FindJiBs
LPBYTE FindJiBs(LPBYTE p_lpJiBNum)
- Find all JiBs on all parallel ports and those serial ports indicated in
the call to SetJiBSearchParams.
- Parameters:
p_lpJiBNum
- pointer to the number of buttons found.- Returns:
- pointer to an array containing contiguous 8 byte iButton Ids.
SelectJiB
BOOL SelectJiB(LPBYTE lpJiBRomPtr)
- Selects the JiB whose ROM matches the data pointed to by
lpJiBRomPtr.
- Parameters:
lpJiBRomPtr
- pointer to the iButton Id that is to be selected.- Returns:
- TRUE if the iButton is selected.
GetJiBError
WORD GetJiBError()
- Gets last error code.
- Returns:
- returns the last error reported.
Notes:
- CTestJiBAPIDlg.OnSelendokCommandCombo() in [JIBKIT_ROOT]/C-API/Win32/jibapi/TestJiBAPI/TestJiBAPIDlg.cpp makes use of most of these functions and may be used as a reference.
- Structures are defined in jibapi.h.