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: