UniToken API Reference

UT_GetLibraryVersion

API Prototype

unsigned long UT_API UT_GetLibraryVersion().

Description

To get the version of the present library

Parameters

n/a

Returned value

RETURNED VALUE	DESCRIPTION
Library version	the version of the current library

Sample

unsigned long ulLibraryVersion;
ulLibraryVersion = UT_GetLibraryVersion();

UT_Initialize

API Prototype

UT_RV UT_API UT_Initialize()

Description

To initialize the UniToken. It should be called before all the other functions except UT_GetLibraryVersion.

Parameters

n/a

Returned value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_ALREADY_INITIALIZE	Library already initialized

Sample

UT_RV ret;
ret = UT_Initialize();

UT_Finalize

API Prototype

UT_RV UT_API UT_Finalize()

Description

Call this function to end any interaction with UniToken and free the memory.

Parameters

n/a

Returned value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized

Sample

UT_RV ret;
ret = UT_Finalize();

UT_GetTokenList

API Prototype

UT_RV UT_API UT_GetTokenList(UT_SLOT_ID* lpSlotID, unsigned long* lpTokenCount)

Description

To get the list of Slot ID and the number of Slot ID

Parameters

PARAMETERS	DESCRIPTION
lpSlotID	[out] slot ID list
lpTokenCount	[in] size of buffer (0~32 bytes) [out]number of token

Returned value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized

Sample

UT_RV ret;
UT_HANDLE utHandle;
UT_SLOT_ID* lpSlotID = NULL;
unsigned long ulTokenCount = 0;
ret = UT_GetTokenList(lpSlotID,&ulTokenCount);
if (ret == UT_BUFFER_TOO_SMALL){
     lpSlotID = new UT_SLOT_ID[ulTokenCount];
     ret = UT_GetTokenList(lpSlotID,&ulTokenCount);
}
ret = UT_OpenDevice(lpSlotID[0],&utHandle);
ret = UT_GetHandle(lpSlotID[0],&utHandle);
ret = UT_GetSlotID(utHandle,&lpSlotID[0]);
ret = UT_CloseDevice(utHandle);

UT_OpenDevice

Prototype

UT_RV UT_API UT_OpenDevice(
UT_SLOT_ID SlotID,
UT_HANDLE* lputHandle
)

Description

To open the device in the specified slot

Parameters

PARAMETERS DESCRIPTION
SlotID [in] the specified slot
lputHandle [out] device handle

Returned value

RETURNED VALUE DESCRIPTION
UT_OK Successful operation
UT_NOT_INITIALIZE Library not initialized
UT_ARGUMENTS_BAD Invalid argument
UT_SLOT_ID_INVALUD Invalid slot ID

Usage note

SlotID should be gotten from UT_GetTokenList instead of manually input.
Therefore, this function cannot be called before UT_GetTokenList.

Sample

See also the sample of UT_GetTokenList

UT_CloseDevice

Prototype

UT_RV UT_API UT_CloseDevice(UT_HANDLE utHandle)

Description

To close the specified device

Parameters

n/a

Returned value

RETURNED VALUE DESCRIPTION
UT_OK Successful operation
UT_NOT_INITIALIZE Library not initialized
UT_TOKEN_HANDLE_INVALID Invalid token handle

Sample

See also the sample of UT_GetTokenList

UT_GetHandle

Prototype
UT_RV UT_API UT_GetHandle(
UT_SLOT_ID SlotID,
UT_HANDLE* lputHandle
)

Description
To get device handle by Slot ID

Parameters
PARAMETERS DESCRIPTION
SlotID [in] the specified slot
lputHandle [out] device handle

Returned value
RETURNED VALUE DESCRIPTION
UT_OK Successful operation
UT_NOT_INITIALIZE Library not initialized
UT_ARGUMENTS_BAD Invalid argument

Sample
See also the sample of UT_GetTokenList

UT_GetSlotID

Prototype
UT_RV UT_API UT_GetSlotID(
UT_HANDLE utHandle,
UT_SLOT_ID* lpSlotID
)

Description
To get Slot ID by device handle

Parameters
PARAMETERS DESCRIPTION
utHandle [in] the specified handle
lpSlotID [out] Slot ID

Returned value

RETURNED VALUE DESCRIPTION

UT_OK Successful operation
UT_NOT_INITIALIZE Library not initialized
UT_ARGUMENTS_BAD Invalid argument
UT_TOKEN_HANDLE_INVALID Invalid token handle

Sample
See also the sample of UT_GetTokenList

UT_GetSlotStatus

Prototype
UT_RV UT_API UT_GetSlotStatus(
UT_STATUS* lpStatus,
UT_SLOT_ID* lpSlotID
)

Description
To get the status of Slot

Parameters
PARAMETERS DESCRIPTION
lpStatus [out]the current status of slot
lpSlotID [out] Slot ID

Notes:
lpStatus can be
a. Inserted, when UniToken is inserted into the slot;
b. Removed, when UniToken is removed from the slot;
c. No change, when there’s no change to the status of slot. In this case, lpSlotID is undefined.

Returned value
RETURNED VALUE DESCRIPTION
UT_OK Successful operation
UT_NOT_INITIALIZE Library not initialized
UT_ARGUMENTS_BAD Invalid argument

Sample
UT_RV rv;
UT_STATUS status;
UT_SLOT_ID slotID;
rv = UT_GetSlotStatus(&status,& slotID);
if ( rv == UT_OK ){
if ( status == TOKEN_NO_EVENT ) {
// no change of status
} else if ( status == TOKEN_INSERT ) {
// token inserted
} else if ( status == TOKEN_REMOVE ) {
// token removed
}
}

UT_GetTokenType

Prototype
UT_RV UT_API UT_GetTokenType(
UT_HANDLE utHandle,
char* lpszTokenType
)

Description
To get the type of the current device, e.g. UniToken STD, PRO

Parameters
PARAMETERS DESCRIPTION
utHandle [in]device handle
lpszTokenType [out]UniToken type (string, 32
bytes)

Returned value
RETURNED VALUE DESCRIPTION
UT_OK Successful operation
UT_NOT_INITIALIZE Library not initialized
UT_ARGUMENTS_BAD Invalid argument
UT_TOKEN_HANDLE_INVALID Invalid token handle

Sample
UT_RV ret;
UT_HANDLE utHandle;
char TokenType[33]={0};
ret = UT_GetTokenType(utHandle,(char *)TokenType);

UT_GetFirmwareVersion

Prototype
UT_RV UT_API UT_GetFirmwareVersion(
UT_HANDLE utHandle,
unsigned long* lpVersion
)

Description
To get the version of firmware

Parameters
PARAMETERS DESCRIPTION
utHandle [in] device handle
lpVersion [out] firmware version

Returned value
RETURNED VALUE DESCRIPTION
UT_OK Successful operation
UT_NOT_INITIALIZE Library not initialized
UT_ARGUMENTS_BAD Invalid argument
UT_TOKEN_HANDLE_INVALID Invalid token handle

Sample
UT_RV ret;
UT_HANDLE utHandle;
unsigned long Version;
ret = UT_GetFirmwareVersion(utHandle,&Version);

UT_Logoff

Prototype
UT_RV UT_API UT_Logoff(UT_HANDLE utHandle)

Description
To log off the specified Token

Parameters
PARAMETERS DESCRIPTION
utHandle [in]device handle

Returned value
RETURNED VALUE DESCRIPTION
UT_OK Successful operation
UT_NOT_INITIALIZE Library not initialized
UT_TOKEN_HANDLE_INVALID Invalid token handle

Sample
See also the sample of UT_Logon

UT_Logon

Prototype
UT_RV UT_API UT_Logon(
UT_HANDLE utHandle,
unsigned long UserLevel,
unsigned char* lpszPin
)

Description
To logon the specified token

Parameters
PARAMETERS DESCRIPTION
utHandle [in]device handle
UserLevel [in] levels of permission
lpszPin [in]the corresponding password with
certain permission level

Note:
lpszPin is made up with strings, and the minimum size is 1 byte.

Returned value
RETURNED VALUE DESCRIPTION
UT_OK Successful operation
UT_NOT_INITIALIZE Library not initialized
UT_ARGUMENTS_BAD Invalid argument
UT_TOKEN_HANDLE_INVALID Invalid token handle
UT_PIN_ERROR Wrong password
UT_USER_FULL No more sessions
allowed
UT_USER_LOCKED Token locked

Usage note
UniToken provides three levels of user permission: GUEST permission, USER
permission and ADMIN permission.

The default permission is GUEST. To log on as USER or ADMIN, the
corresponding PINs are required.

Sample
UT_RV ret;
UT_HANDLE utHandle;
unsigned char Pin[] = UT_DEFAULT_USER;
unsigned long UserLevel;
ret = UT_Logon(
utHandle,
UT_USER_LEVEL_USER,
(unsigned char*)Pin
);
ret = UT_GetCurrentUserLevel(utHandle,&UserLevel);
ret = UT_Logoff(utHandle);

UT_GetCurrentUserLevel

Prototype
UT_RV UT_API UT_GetCurrentUserLevel(
UT_HANDLE utHandle,
unsigned long* lpUserLevel
)

Description
To get the current permission level

Parameters
PARAMETERS DESCRIPTION
utHandle [in]device handle
lpUserLevel [out] permission level

Returned value
RETURNED VALUE DESCRIPTION
UT_OK Successful operation
UT_NOT_INITIALIZE Library not initialized
UT_ARGUMENTS_BAD Invalid argument
UT_TOKEN_HANDLE_INVALID Invalid token handle

Sample
See also the sample of UT_Logon

UT_ChangePin

Prototype
UT_RV UT_API UT_ChangePin(
UT_HANDLE utHandle,
unsigned char UserLevel,
unsigned long ChangeMode,
unsigned char* OldPin,
unsigned char* NewPin
)

Description
To change password

Parameters
PARAMETERS DESCRIPTION
utHandle [in]device handle
UserLevel [in]permission level
ChangeMode [in]mode of changing
OldPin [in] old PIN
NewPin [in]new PIN

Notes:
Change Mode an be UT_CHANGE_PIN_MODE_BYSELF or
UT_CHANGE_PIN_MODE_ADMIN_CHANGE_USER

Returned value
RETURNED VALUE DESCRIPTION
UT_OK Successful operation
UT_NOT_INITIALIZE Library not initialized
UT_ARGUMENTS_BAD Invalid argument
UT_TOKEN_HANDLE_INVALID Invalid token handle
UT_NOT_ALLOWED Operation not allowed

Usage note

Two ways of changing password:

1. User/Admin changes his own password
Log on as USER or ADMIN and type in the old password and the new one.
Here, the mode of changing PIN is UT_CHANGE_PIN_MODE_BYSELF
2. Admin resets user password
Log on as ADMIN and type in new password of USER. Here, the mode of changing PIN is UT_CHANGE_PIN_MODE_ADMIN_CHANGE_USER.In this case, OldPin is not required.

Sample
UT_RV ret;
UT_HANDLE utHandle;
unsigned char Pin[] = UT_DEFAULT_USER;
unsigned char NewPin[] = "1234";
unsigned long UserLevel;
ret = UT_Logon(
utHandle,
UT_USER_LEVEL_USER,
(unsigned char*)Pin
);
ret = UT_ChangePin(
utHandle,
UT_USER_LEVEL_USER,
UT_CHANGE_PIN_MODE_BYSELF,
(unsigned char*)Pin,
(unsigned char*)newPin
);

UT_GetID

Prototype
UT_RV UT_API UT_GetID(
UT_HANDLE utHandle,
char* lpszId
)

Description
To get the token ID of specified device

Parameters
PARAMETERS DESCRIPTION
utHandle [in]device handle
lpszId [out] UniToken ID (string, 32
bytes)

Returned value
RETURNED VALUE DESCRIPTION
UT_OK Successful operation
UT_NOT_INITIALIZE Library not initialized
UT_ARGUMENTS_BAD Invalid argument
UT_TOKEN_HANDLE_INVALID Invalid token handle

Sample
See also the sample of UT_SetID

UT_SetID

Prototype
UT_RV UT_API UT_SetID(
UT_HANDLE utHandle,
char* lpszId
)

Description
To set the token ID of the specified device

Parameters
PARAMETERS DESCRIPTION
utHandle [in]device handle
lpszId [out] UniToken ID (string, 32
bytes)

Returned value
RETURNED VALUE DESCRIPTION
UT_OK Successful operation
UT_NOT_INITIALIZE Library not initialized
UT_ARGUMENTS_BAD Invalid argument
UT_TOKEN_HANDLE_INVALID Invalid token handle

Sample
UT_RV ret;
UT_HANDLE utHandle;
char Id[33] = "UniTokenPRO";
unsigned long UserLevel;
ret = UT_SetID(utHandle,Id);
ret = UT_GetID(utHandle,Id);

UT_GetHID

Prototype
UT_RV UT_API UT_GetHID(
UT_HANDLE utHandle,
unsigned long* lpHid
)

Description
To get the Hardware ID of the specified device

Parameters
PARAMETERS DESCRIPTION
utHandle [in]device handle
lpHid [out] Hardware ID

Returned value
RETURNED VALUE DESCRIPTION
UT_OK Successful operation
UT_NOT_INITIALIZE Library not initialized
UT_ARGUMENTS_BAD Invalid argument
UT_TOKEN_HANDLE_INVALID Invalid token handle

Sample
UT_RV ret;
UT_HANDLE utHandle;
unsigned long Hid;
ret = UT_GetHID(utHandle,&Hid);

UT_FS_CloseFile

<a _fcknotitle="true" href="Category:UniToken_APIs">UniToken_APIs</a>