UniKey API Reference for C Language

Find a UniKey dongle

API Prototype
long UniKey_Find( WORD* pHandle ,
DWORD* pSetting1 ,
DWORD* pSetting2 ) ;

Description
Check if a specific UniKey is attached to the USB port. This is the first API to start a UniKey session.

Parameters
Parameter Meaning
*pHandle [out] Dongle handle
*pSetting1 *[in] Working Mode (UniKey PRO only), useless for UniKey STD
[out] Hardware ID
*pSetting2 *[in] Access Mode (UniKey PRO only), useless for UniKey STD(UniKey PRO only)
[out] Number of dongle attached , useless for UniKey STD

Return values
Marco Value Meaning
SUCCESS 0 Success
ERROR_UNIKEY_NO_UNIEKY 200 No UniKey dongle

Find the Next UniKey dongle

API Prototype
Long UniKey_Find_Next( WORD* pHandle ,
DWORD* pSetting1 ,
DWORD* pSetting2 ) ;

Description
Check if another UniKey is attached to the USB port.

Parameters
Parameter Meaning
*pHandle [out] Dongle handle
*pSetting1 *[in] Working Mode (UniKey PRO only), useless for UniKey STD
[out] Hardware ID
*pSetting2 *[in] Access Mode (UniKey PRO only), useless for UniKey STD(UniKeyPro only)
[out] Number of dongle attached , useless for UniKey STD

Return values
Marco Value Meaning
SUCCESS 0 Success
ERROR_UNIKEY_NOMORE 214 No more dongle
ERROR_UNIKEY_NEED_FIND 215 No Find before Find_Next

Logon UniKey Dongle

API Prototype
long UniKey_User_Logon( WORD* pHandle ,
WORD* pPassword1 ,
WORD* pPassword2 ) ;
-------------------------------------------------------------------------------------------

For UniKey Drive, the API Prototype is UniKey_User_Logon (WORD* pHandle, DWORD* pPassword1, DWORD* pPassword2);
-------------------------------------------------------------------------------------------
Description
Logon a UniKey dongle with specified passwords. This API should be called in the released software in order to improve security.

Parameters
Parameter Meaning
*pPassword1 [in]Password 1
*pPassword2 [in]Password 2
*pHandle [out] Dongle handle

Return values
Marco Value Meaning
SUCCESS 0 Success
ERROR_UNIKEY_NOT_FOUND 200 No UniKey dongle
ERROR_UNIKEY_INVALID_PASSWORD 201 UniKey dongle found, but Basic passwords are incorrect
ERROR_UNIKEY_INVALID_PASSWORD_OR_ID 202 Wrong password or UniKey HID

Logon UniKey Dongle in vendor mode

API Prototype
long UniKey_Vender_Logon( WORD* pHandle ,
WORD* pPassword1 ,
WORD* pPassword2 ,
WORD* pPassword3 ,
WORD* pPassword4 ) ;
---------------------------------------------------------------------------------------------------
For UniKey Drive, the API Prototype is UniKey_Vender_Logon(WORD* pHandle, DWORD* pPassword1, DWORD* pPassword2, DWORD* pPassword3, DWORD* pPassword4);
---------------------------------------------------------------------------------------------------

Description
Logon a UniKey dongle in vendor mode with specified passwords. This API helps software vendors to logon the UniKey dongle in vendor mode, and get the full permission to UniKey dongle.
---------------------------------------------------------------------------------------------------
We do NOT advise you to enclose this API in the final released software. This API is only for software vendor’s usage.
--------------------------------------------------------------------------------------------------
If password3 or password4 is wrong while password1 and password2 is correct, the dongle is also logged on in user mode automatically.
---------------------------------------------------------------------------------------------------

Parameters
Parameter Meaning
*pPassword1 [in]Password 1
*pPassword2 [in]Password 2
*pPassword3 [in]Password 3
*pPassword4 [in]Password 4
*pHandle [out] Dongle handle

Return values
Marco Value Meaning
SUCCESS 0 Success
ERROR_UNIKEY_NOT_FOUND 200 No UniKey dongle
ERROR_UNIKEY_INVALID_PASSWORD 201 Found UniKey dongle, but Basic passwords are incorrect
ERROR_UNIKEY_INVALID_PASSWORD_OR_ID 202 Wrong password or UniKey HID

Logoff the UniKey dongle

API Prototype
long UniKey_Logoff( WORD* pHandle ) ;

Description
Logoff a UniKey dongle with a specific handle. This API should be called at the end of UniKey session.

Parameters
Parameter Meaning
*pHandle [in] Dongle handle

Return values
Marco Value Meaning
SUCCESS 0 Success
ERROR_UNIKEY_NOT_FOUND 200 No UniKey dongle
ERROR_UNIKEY_NEED_OPEN 212 No logon dongle before operating dongle

Get the UniKey dongle 's Type

API Prototype
long UniKey_Get_Type( WORD* pHandle ,
DWORD* type ) ;

Description
UniKey_Get_Type can help you get the type of the UniKey dongle.
The return value of type will indicate the type of the UniKey dongle.
UNIKEY_TYPE_TIME 101
UNIKEY_TYPE_PRO 102
UNIKEY_TYPE_STD 103

Parameters
Parameter Meaning
*pHandle [in] Dongle handle
*type [out] The value indicating the type of your UniKey dongle

Return values
Marco Value Meaning
SUCCESS 0 Success
ERROR_GET_TYPE 237 UniKey Get Type Error

Read UniKey dongle memory

API Prototype
long UniKey_Read_Memory( WORD* pHandle ,
WORD* pStartAddress ,
WORD* pBufferLength ,
BYTE* pBuffer ) ;

Description
Read the contents of the Memory. This API needs to be called after logon of a UniKey dongle.

Parameters
Parameter Meaning
*handle*pHandle [in] Dongle handle
*pStartAddress [in] Offset of Memory
*pBufferLenght [in] Number of bytes to read
pBbuffer [out] Pointer to the buffer containing the data to be read

Return values
Marco Value Meaning
SUCCESS 0 Success
ERROR_UNIKEY_INVALID_ADDR_OR_SIZE 204 Read/Write address or length is wrong
ERROR_UNIKEY_READ_MEMORY 207 Read Error
ERROR_UNIKEY_NEED_OPEN 212 No logon dongle before operating dongle
ERROR_UNIKEY_NEED_OPEN 215 No logon dongle before operating dongle

Write to UniKey dongle memory

API Prototype
long UniKey_Write_Memory( WORD* pHandle ,
WORD* pStartAddress ,
WORD* pBufferLength ,
BYTE* pBuffer ) ;

Description
Write data into the memory. This API needs to be called after logging on to a UniKey dongle.

Parameters
Parameter Meaning
*handle*pHandle [in] Dongle handle
*pStartAddress [in] Offset of the memory
*pBufferLength [in] Number of bytes to write
pBbuffer [in] Pointer to the buffer containing the data to be written

Return values
Marco Value Meaning
SUCCESS 0 Success
ERROR_UNIKEY_INVALID_ADDR_OR_SIZE 204 Read/Write address or length is wrong
ERROR_UNIKEY_WRITE_MEMORY 207 Write Error
ERROR_UNIKEY_NEED_OPEN 212 No logon dongle before operating dongle
ERROR_UNIKEY_VERIFY_ADV_PASSWORD 223 Advanced passwords (password3 and passowrd4) not verified

---

To write the last 2k memory (for 2048 – 4096), you need to verify all the 4 passwords （vendor mode） to obtain full permission to the dongle.
--------------------------------------------------------------------------------------------------

UniKey_Read_Memory and UniKey_Write_Memory provide basic reading and writing functions to the dongle. You can store general information via such functions. And various levels of security can be applied too.
--------------------------------------------------------------------------------------------------

Generate a Random Number

API Prototype
long UniKey_Random( WORD* pHandle ,
WORD* pReturn1 ,
WORD* pReturn2 ,
WORD* pReturn3 ,
WORD* pReturn4 ) ;

Description
Generate a random number from the dongle.

Parameters
Parameter Meaning
*pHandle [in] Dongle handle
*pReturn1 [out] Random number
*pReturn2 [out] Random number
*pReturn3 [out] Random number
*pReturn4 [out] Random number

Return values
Marco Value Meaning
SUCCESS 0 Success
ERROR_UNIKEY_NEED_OPEN 212 No logon dongle before operating dongle
ERROR_UNIKEY_RANDOM 209 Random number Error

---

UNIKEY_RANDOM is to generate a random number inside the dongle. The UniKey dongle computing engine generates the number and the hardware of the dongle is the seed for the random number.
--------------------------------------------------------------------------------------------------

Generate Seed Code Return Values

API Prototype
long UniKey_Seed( WORD* pHandle ,
DWORD* pSeed ,
WORD* pReturn1 ,
WORD* pReturn2 ,
WORD* pReturn3 ,
WORD* pReturn4 ) ;

Description
Get return codes from the input of a seed code. This API return for values which are related to pSeed and UniKey dongle’s password.

Parameters
Parameter Meaning
*pHandle [in] Dongle handle
*pSeed [in] Seed Code
*pReturn1 [out] Return Code 1
*pReturn2 [out] Return Code 2
*pReturn3 [out] Return Code 3
*pReturn4 [out] Return Code 4

Return values
Marco Value Meaning
SUCCESS 0 Success
ERROR_UNIKEY_NEED_OPEN 212 No logon dongle before operating dongle
ERROR_UNIKEY_SEED 210 Seed code Error

---

UniKey_Seed generate a set of seed codes. All of these seed codes are based on the password. It provides another method to verify the password and check the insertion of the dongle. Apart from this, the seed codes can be used to involve in other computation, for example, you use the seed returned as a 64-bit long encryption key.
---------------------------------------------------------------------------------------------------

Write the Soft ID

API Prototype
long UniKey_Write_SoftID( WORD* pHandle ,
DWORD* pSoftID ) ;

Description
Write the vendor defined SoftID.

Parameters
Parameter Meaning
*pHandle [in] Dongle handle
*pSoftID [in] Soft ID

Return values
Marco Value Meaning
SUCCESS 0 Success
ERROR_UNIKEY_NEED_OPEN 212 No logon dongle before operating dongle
ERROR_UNIKEY_SET_SOFTID 203 Set UniKey ID wrong
---------------------------------------------------------------------------------------------------

You need to verify all 4 passwords (vendor mode) to write the SoftID.
---------------------------------------------------------------------------------------------------

Read Soft ID
API Prototype
long UniKey_Read_SoftID( WORD* pHandle ,
DWORD* pSoftID ) ;

Description
Read the user defined SoftID.

Parameters
Parameter Meaning
*pHandle [in] Dongle handle
*pSoftID [out] Soft ID

Return values
Marco Value Meaning
SUCCESS 0 Success
ERROR_UNIKEY_NEED_OPEN 212 No logon dongle before operating dongle

---

UniKey_Write_SoftID and UniKey_Read_SoftID provide a means to make a soft (write-able) ID for each software. You can write different software ID for each software and call UNIKEY_READ_SOFTID to check if the software ID is correct.
---------------------------------------------------------------------------------------------------

 

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