DONSEE東信智能 - 身份證社保卡讀卡智能終端應用服務商

DONSEE系列多功能讀寫器Windows API接口規范V1.8

donsee32.dll（依賴庫：WltRS.dll）

donsee64.dll（依賴庫：DLL_File.dll、license.dat）

廣東東信智能科技有限公司

www.www.yjcsbsb.cn

2023.09.16

DONSEE系列多功能讀寫器1

API接口規范V1.81

1、東信智能讀寫器(SDK)簡介5

2、函數說明5

2.1通用函數5

2.1.1 Donsee_Open打開設備5

2.1.2 Donsee_Clse關閉設備5

2.1.3 Donsee_Beep蜂鳴器函數6

2.1.4 Donsee_Version讀取設備版本6

2.1.5 Donsee_WRSN 讀寫序列號(SN)6

2.2身份證7

2.2.1 Donsee_ReadIDCard讀取身份證信息7

2.2.2 Donsee_ReadSAMID 讀取模塊SAM碼8

2.2.3 Donsee_ReadIDCardUid 讀取身份證UID8

2.3社保卡8

2.3.1 Donsee_ReadSSCard讀取社保卡信息8

2.4非接觸類卡片前置函數9

2.4.1 Donsee_ICRequest請求卡片9

2.4.2 Donsee_ICAnticoll防碰撞9

2.4.3 Donsee_ICSelect選擇卡片9

2.4.4 Donsee_SwitchRF設備天線開關10

2.5 TypeA、TypeB卡10

2.5.1 Donsee_SetTypeA設置為TypeA10

2.5.2 Donsee_SetTypeB設置為TypeB10

2.5.3 Donsee_PowerOnTypeA TypeA卡上電復位11

2.5.4 Donsee_PowerOnTypeB TypeB卡上電復位11

2.5.5 Donsee_APDU執行APDU命令11

2.6 M1卡12

2.6.1 Donsee_M1VerifyPass M1卡認證秘鑰12

2.6.2 Donsee_M1VerifyPassHEX M1卡認證秘鑰12

2.6.3 Donsee_M1Read M1卡讀卡12

2.6.4 Donsee_M1Write M1卡寫卡13

2.6.5 Donsee_M1Initval M1卡初始化13

2.6.6 Donsee_M1Increment M1卡增值13

2.6.7 Donsee_M1Decrement M1卡減值14

2.6.8 Donsee_M1Readval M1卡讀值14

2.6.9 Donsee_M1LoadKey M1卡裝載密鑰14

2.6.10 Donsee_M1Verify M1卡裝載密鑰15

2.6.11 Donsee_ReadICUid讀取M1和CPU卡的Uid卡號15

2.7接觸CPU卡15

2.7.1 Donsee_PowerOn CPU卡上電復位15

2.7.2 Donsee_ColdPowerOn 冷復位16

2.7.3 Donsee_HotPowerOn 熱復位16

2.7.4 Donsee_APDU CPU卡執行APDU命令16

2.7.5 Donsee_PowerOff下電17

2.7.6 Donsee_GetStatus獲取卡座狀態17

2.8 15693卡18

2.8.1 Donsee_15693_Find 15693尋卡18

2.8.2 Donsee_15693_Info 15693獲取卡片詳細信息18

2.8.3 Donsee_15693_Read 15693讀卡18

2.8.4 Donsee_15693_Write 15693寫卡18

2.8.5 Donsee_15693_WriteAFI 15693寫AFI19

2.8.6 Donsee_15693_LockAFI 15693鎖AFI19

2.8.7 Donsee_15693_WriteDSFID 15693寫DSFID19

2.8.8 Donsee_15693_LockDSFID 15693鎖DSFID20

2.8.9 Donsee_15693_LockDataBlock用于鎖定塊內容20

2.9 SLE4442卡20

2.9.1 Donsee_4442_PowerOn 4442卡上電20

2.9.2 Donsee_4442_PowerOff 4442卡下電20

2.9.3 Donsee_4442_Read 4442卡讀數據21

2.9.4 Donsee_4442_Write 4442卡寫數據21

2.9.5 Donsee_4442_Verify 4442卡認證密鑰21

2.9.6 Donsee_4442_Change 4442卡修改密鑰22

2.9.7 Donsee_4442_ReadProtect 4442卡讀保護數據22

2.9.8 Donsee_4442_WriteProtect 4442卡寫保護數據22

2.9.9 Donsee_4442_ReadCount 4442卡密鑰剩余認證次數23

2.10磁條卡23

2.10.1 Donsee_ReadMagCard磁條卡讀卡23

2.10.2 Donsee_ReadMagType設置輸出模式23

2.11北京通24

2.11.1 Donsee_ReadBJTIDCard讀取北京通信息24

2.11.2 Donsee_ReadBJTIDCard_Photo讀取北京通照片25

2.12輔助類函數25

2.12.1 Donsee_HexToStr 16進制數組轉字符串25

2.12.2 Donsee_StrToHex 字符串轉16進制數組25

2.13社保卡加密機26

2.13.1 Donsee_iReadCardBas讀基本信息26

2.13.2 Donsee_iReadCardBas_HSM_Step1加密機步驟126

2.13.3 Donsee_iReadCardBas_HSM_Step2加密機步驟227

2.13.4 Donsee_getTerminalNo獲取終端機編號27

2.13.5 Donsee_ChipSerial獲取芯片序列號，即終端設備號28

3、狀態碼28

4、卡片調用順序30

4.1 TypeA卡30

4.2 TypeB卡30

4.3 M1卡30

4.4 4442卡30

4.5 接觸CPU卡30

1、DONSEE讀卡器SDK簡介

本文檔描述了廣東東信智能科技有限公司DONSEE系列讀寫器SDK的函數定義、調用方法、參數以及返回值說明，供開發人員進行二次開發時使用。

2、函數說明

2.1通用函數

2.1.1 Donsee_Open打開設備

定義：打開設備端口

原型:

long Donsee_Open(char* dev_Name)

參數：

dev_Name[in]windows：USB設備傳入”USB”；串口設備傳入”COM1” “COM2”等

Android：USB設備傳入”USB”；”ttyS0”,”ttyUSB0”,”ttySAC0”等

返回值：

0：打開設備成功；

非0：打開設備失敗，參考狀態碼

2.1.2 Donsee_Close關閉設備

定義：關閉設備端口

原型:

long Donsee_Close()

參數：無

返回值：

0：關閉設備成功；

非0：關閉設備失敗，參考狀態碼

2.1.3 Donsee_Beep蜂鳴器函數

定義：調用設備蜂鳴器

原型:

long Donsee_Beep()

參數：無

返回值：

0：調用蜂鳴器成功；

非0：調用蜂鳴器失敗，參考狀態碼

2.1.4 Donsee_Version讀取設備版本

定義：讀取設備版本號

原型:

long Donsee_Version (char* pszVersion)

參數：

pszVersion [out]設備版本號

返回值：

0：獲取設備版本成功；

非0：獲取設備版本失敗，參考狀態碼

2.1.5 Donsee_WRSN 讀寫序列號(SN)

定義：寫入(讀取)設備序列號

原型:

long Donsee_WRSN (int nType, char* pszSerial)

參數：

nType[in]讀寫類型:0，寫入序列號；1，讀取序列號

pszSerial[in|out]nType = 0時，[in]寫入序列號數據；nType = 1時，[out]讀出序列號數據

返回值：

0：序列號操作成功；

非0：序列號操作失敗，參考狀態碼

2.2身份證

// 支持 0、J、I、Y 四種證件，共計18項，請根據證件類型獲取對應信息

// 0：居民身份證

// J：港澳臺居民居住證

// I：2017版外國人永久居留身份證

// Y：新版外國人永久居留身份證

typedef struct

{

char name[40];/*中文姓名： 0 J I Y */

char ENfullname[40];/*英文姓名（Y時需要和Other英文姓名備用組合起來）： I Y */

char sex[10];/*性別： 0 I J Y */

char people[20];/*民族或國籍， 0 時為民族， I Y 時為國籍*/

char address[200];/*地址： 0 J Y， Y 時為既往版本永居證號碼 */

char birthday[50];/*出生日期（YYYYMMDD）： 0 J I Y */

char signdate[50];/*發證日期（YYYYMMDD）： 0 J I Y */

char validterm[50];/*有效日期（YYYYMMDD）： 0 J I Y */

char number[40];/*證件號碼： 0 I J Y */

char organs[50];    /*發證機關(或外國人永久居證-當次申請受理機關)： 0 J I Y */

char Nationality[200];/*國籍代碼： I Y */

char Photo[2049];/*相片原始信息： 0 J I Y */

char Other[200];/*其他  Y 時為英文姓名備用*/

char passNu[24];/*通行證號碼： J */

char signCount[8];/*簽發數次： J */

char certVersion[8];/* I 時為證件版本號， Y 時為換證次數 */

char certType[6];      /*證件類型： 0 J I Y */

char figData[2049];/*指紋信息： 0 J */

} IDINFO;

2.2.1 Donsee_ReadIDCard讀取身份證信息

定義：讀取身份證信息

原型：long Donsee_ReadIDCard (int nType,char* szPath,IDINFO* idinfo,char* pszMsg);

參數：

nType [in]:設置身份證讀卡類型：0，文本信息；1，文本+照片；2，文本+照片+指紋

szPath[in]:獲取二代證頭像路徑

idinfo [out];獲取的身份證信息

pszMsg [out];錯誤信息

返回值：

0：讀取身份證信息成功；

非0：讀取身份證信息失敗，參考狀態碼

2.2.2 Donsee_ReadSAMID 讀取模塊SAM碼

定義：讀取身份證模塊SAM碼

原型：long Donsee_ReadSAMID (char* pszSAMID);

參數：

pszSAMID [out] 身份證模塊SAM碼

返回值：

0：讀取身份證模塊SAM碼成功；

非0：讀取身份證模塊SAM碼失敗，參考狀態碼

2.2.3 Donsee_ReadIDCardUid 讀取身份證UID

定義：讀取身份證UID

原型：long Donsee_ReadIDCardUid(char* pszUID);

參數：

pszUID [out] 身份證UID碼

返回值：

0：讀取身份證UID成功；

非0：讀取身份證UID失敗，參考狀態碼

2.3社保卡

/*********************社保卡讀取  特別注意事項**********************

1、二代社保卡可以直接讀取，只支持插卡（接觸式）方式讀取。

2、三代社保卡加密了，需要PSAM卡才能讀取，支持插卡（接觸式）和非接觸式兩種讀取方式。

3、如果插PSAM卡了，讀卡失敗，需要留意以下返回值：

-25536、-25537、-25538、-25539、-25540、-25541，外部認證失敗，表示剩余可嘗試次數0~5次，當返回-25536社保卡就鎖卡了。

*********************社保卡讀取  特別注意事項**********************/

typedef struct

{

char name[40];        /*姓名*/

char sex[10];/*性別*/

char nation[20];/*民族*/

char birthday[50];   /*出生日期（YYYYMMDD）*/

char signdate[50];    /*發證日期（YYYYMMDD）*/

char validterm[50];        /*有效日期（YYYYMMDD）*/

char cardnumber[40];/*卡號*/

char idnumber[40];/*社會保障號碼(身份證號)*/

char city[64] ;/*城市代碼*/

char cardveVrsion[8] ;/*社保卡版本*/

char Other[200];/*其他*/

} SSCard_IDINFO;

2.3.1 Donsee_ReadSSCard讀取社保卡信息

定義：讀取二代、三代社保卡

原型：

long Donsee_ReadSSCard (int nSlotPsam,

SSCard_IDINFO* cardInfo,

char* pszChMsg);

參數：

nSlotPsam [int] PSAM存放卡座，0x11 SAM1, 0x12 SAM2, 0x13 SAM3, 0x14 SAM4

cardInfo [out] 社保卡信息

pszChMsg [out] 錯誤信息

返回值：

0：讀取社保卡成功；

非0：讀取社保卡失敗，參考狀態碼

備注：二代社保卡無需PSAM卡，只支持接觸式讀取。三代社保卡必須配備PSAM卡，支持接觸、非接兩種方式讀取。

2.4非接觸類卡片前置函數

2.4.1 Donsee_ICRequest請求卡片

定義：請求卡片

原型:

long Donsee_ICRequest ()

參數：

返回值：

0：請求卡片成功；

非0：請求卡片失敗，參考狀態碼

2.4.2 Donsee_ICAnticoll防碰撞

定義：卡片防碰撞

原型:

long Donsee_ICAnticoll (char* pszUID)

參數：

pszUID [out]卡片序列號Uid

返回值：

0：卡片防碰撞成功；

非0：卡片防碰撞失敗，參考狀態碼

2.4.3 Donsee_ICSelect選擇卡片

定義：選擇卡片

原型:

long Donsee_ICSelect (unsigned char nCardType)

參數：

nCardType [in]0x41 表示 typeA 及M1 卡，0x42 表示 typeB卡

返回值：

0：選擇卡片成功；

非0：選擇卡片失敗，參考狀態碼

2.4.4 Donsee_SwitchRF設備天線開關

定義：設備天線開關

原型:

long Donsee_SwitchRF (int nFlag)

參數：

nType1，打開設備天線；0，關閉設備天線

返回值：

0：天線開關操作成功；

非0：天線開關操作失敗，參考狀態碼

2.5 TypeA、TypeB卡

2.5.1 Donsee_SetTypeA設置為TypeA

定義：設置為TypeA卡

原型:

long Donsee_SetTypeA ()

參數：

返回值：

0：設置為TypeA卡成功；

非0：設置為TypeA卡失敗，參考狀態碼

2.5.2 Donsee_SetTypeB設置為TypeB

定義：設置為TypeB卡

原型:

long Donsee_SetTypeB ()

參數：

返回值：

0：設置為TypeB卡成功；

非0：設置為TypeB卡失敗，參考狀態碼

2.5.3 Donsee_PowerOnTypeA TypeA卡上電復位

定義：TypeA上電

原型:

long Donsee_ PowerOnTypeA (char* pszAtr)

參數：

pszAtr [out]卡片復位信息(ATR)

返回值：

0：TypeA上電成功；

非0：TypeA上電失敗，參考狀態碼

2.5.4 Donsee_PowerOnTypeB TypeB卡上電復位

定義：TypeB上電

原型:

long Donsee_PowerOnTypeB(char* pszAtr)

參數：

pszAtr [out]卡片復位信息(ATR)

返回值：

0：TypeB上電成功；

非0：TypeB上電失敗，參考狀態碼

2.5.5 Donsee_APDU執行APDU命令

定義：TypeA|TypeB執行APDU命令

原型:

long Donsee_APDUType(char* szAPDUCmd, char* pszAPDUResult);

參數：

szAPDUCmd [in]下發APDU命令(字符串”0084000008”)

pszAPDUResult [out]執行APDU相應數據(字符串如”9000”)

返回值：

0：執行APDU命令成功；

非0：執行APDU命令失敗，參考狀態碼

2.6 M1卡

2.6.1 Donsee_M1VerifyPass M1卡認證秘鑰

定義：M1卡認證秘鑰

原型:

long Donsee_M1VerifyPass (unsigned char nMode,unsigned char nSecNr,char *szPassKey)

參數：

nMode [in]認證模式，0x60認證KeyA， 0x61認證KeyB

nSecNr [in]扇區號 (0~15)

szPassKey [in]密鑰(如:”FFFFFFFFFFFF”)

返回值：

0：M1卡認證秘鑰成功；

非0：M1卡認證秘鑰失敗，參考狀態碼

2.6.2 Donsee_M1VerifyPassHEX M1卡認證秘鑰

定義：M1卡認證秘鑰

原型:

long Donsee_M1VerifyPassHex (unsigned char nMode, unsigned char nSecNr,unsigned char * szPassKey))

參數：

nMode [in]認證模式，0x60認證KeyA， 0x61認證KeyB

nSecNr [in]扇區號 (0~15)

szPassKey [in]密鑰(如:{0xff,0xff,0xff ,0xff ,0xff ,0xff })

返回值：

0：M1卡認證秘鑰成功；

非0：M1卡認證秘鑰失敗，參考狀態碼

2.6.3 Donsee_M1Read M1卡讀卡

定義：M1卡讀卡

原型:

long Donsee_M1Read(unsigned char nAddr, unsigned char *pszData)

參數：

nAddr [in]塊號(S50該值范圍0~63| S70該值范圍0~255)

pszData [out]讀取數據

返回值：

0：M1卡讀卡成功；

非0：M1卡讀卡失敗，參考狀態碼

2.6.4 Donsee_M1Write M1卡寫卡

定義：M1卡寫卡

原型:

long Donsee_M1Write(unsigned char nAddr, char *pszData)

參數：

nAddr [in]塊號(S50該值范圍0~63| S70該值范圍0~255)

pszData [in]讀取數據

塊地址計算公式：塊地址=扇區號*4+當前塊號

返回值：

0：M1卡寫卡成功；

非0：M1卡寫卡失敗，參考狀態碼

2.6.5 Donsee_M1Initval M1卡初始化

定義：M1卡初始化

原型:

long Donsee_M1Initval (unsigned char nAddr, unsigned long nValue)

參數：

nAddr[in]塊號(S50該值范圍0~63| S70該值范圍0~255)

nValue [in]數值

返回值：

0：M1卡初始化成功；

非0：M1卡初始化失敗，參考狀態碼

2.6.6 Donsee_M1Increment M1卡增值

定義：M1卡增值

原型:

long Donsee_M1Increment (unsigned char nAddr, unsigned long nValue)

參數：

nAddr[in]塊號(S50該值范圍0~63| S70該值范圍0~255)

nValue [in]數值

返回值：

0：M1卡增值成功；

非0：M1卡增值失敗，參考狀態碼

2.6.7 Donsee_M1Decrement M1卡減值

定義：M1卡減值

原型:

long Donsee_M1Decrement (unsigned char nAddr, unsigned long nValue)

參數：

nAddr[in]塊號(S50該值范圍0~63| S70該值范圍0~255)

nValue [in]數值

返回值：

0：M1卡減值成功；

非0：M1卡減值失敗，參考狀態碼

2.6.8 Donsee_M1Readval M1卡讀值

定義：M1卡讀值

原型:

long Donsee_M1Readval (unsigned char nAddr, unsigned long* nValue)

參數：

nAddr[in]塊號(S50該值范圍0~63| S70該值范圍0~255)

nValue [out]數值

返回值：

0：M1卡讀值成功；

非0：M1卡讀值失敗，參考狀態碼

2.6.9 Donsee_M1LoadKey M1卡裝載密鑰

定義：裝載M1卡密鑰到設備

原型:

long Donsee_M1LoadKey (unsigned char nMode, unsigned char nSecNr,char *PassWord);;

)

參數：

nMode [in]認證模式，0x60認證KeyA， 0x61認證KeyB

nSecNr [in]扇區號 (0~15)

PassWord [in]待下載到設備的密鑰，如”FFFFFFFFFFFF”

例子：

char key[16]= ”FFFFFFFFFFFF”;

int nRe = Donsee_M1LoadKey (0,0,key);//下載扇區0的KeyA密鑰至設備里

返回值：

0：M1卡裝載密鑰成功；

非0：M1卡裝載密鑰失敗，參考狀態碼

2.6.10 Donsee_M1Verify M1卡裝載密鑰

定義：裝載M1卡密鑰到設備

原型:

long Donsee_M1Verify(unsigned char nMode, unsigned char nSecNr)

參數：

nMode [in]認證模式，0x60認證KeyA， 0x61認證KeyB

nSecNr [in]扇區號 (0~15)

返回值：

0：M1卡認證裝載密鑰成功；

非0：M1卡認證裝載密鑰失敗，參考狀態碼

2.6.11 Donsee_ReadICUid讀取M1和CPU卡的Uid卡號

定義：讀取M1和CPU卡UID，僅僅用于串口設備，不支持USB讀取。USB請用M1卡尋卡功能。

原型:

long Donsee_ReadICUid (char* pszUID)

參數：

pszUID[out]卡片UID

返回值：

0：讀取M1和CPU卡的Uid卡號成功；

非0：讀取M1和CPU卡的Uid卡號失敗，參考狀態碼

2.7接觸CPU卡

2.7.1 Donsee_PowerOn CPU卡上電復位

定義：CPU卡上電復位

原型:

long Donsee_PowerOn (unsigned char nSlotNo, char* pszAtr)

參數：

nSlotNo[in]卡座選擇：0x01 大卡座, 0x02：副卡座 ；

0x11：SAM1卡座；0x12：SAM2卡座；

0x13：SAM3卡座；0x14：SAM4卡座

pszAtr [out]卡片返回復位信息數據

返回值：

0：卡片復位成功；

非0：卡片復位失敗，參考狀態碼

2.7.2 Donsee_ColdPowerOn 冷復位

定義：接觸CPU卡冷復位

原型:

long Donsee_ColdPowerOn (unsigned char nSlotNo, char* pszAtr)

參數：

nSlotNo[in]卡座選擇：0x01 大卡座, 0x02：副卡座 ；

0x11：SAM1卡座；0x12：SAM2卡座；

0x13：SAM3卡座；0x14：SAM4卡座

pszAtr [out]卡片返回復位信息數據

返回值：

0：卡片復位成功；

非0：卡片復位失敗，參考狀態碼

2.7.3 Donsee_HotPowerOn 熱復位

定義：接觸CPU卡熱復位

原型:

long Donsee_HotPowerOn (unsigned char nSlotNo, char* pszAtr)

參數：

nSlotNo[in]卡座選擇：0x01 大卡座, 0x02：副卡座 ；

0x11：SAM1卡座；0x12：SAM2卡座；

0x13：SAM3卡座；0x14：SAM4卡座

chResponse [out]卡片返回復位信息數據

返回值：

0：卡片復位成功；

非0：卡片復位失敗，參考狀態碼

2.7.4 Donsee_APDU CPU卡執行APDU命令

定義：執行APDU命令

原型:

long Donsee _APDU(unsigned char nSlotNo,

char* szAPDUCmd,

char* pszAPDUResult)

參數：

nSlotNo[in]卡座選擇：0x01 大卡座, 0x02：副卡座 ；

0x11：SAM1卡座；0x12：SAM2卡座；

0x13：SAM3卡座；0x14：SAM4卡座

szAPDUCmd [in]下發APDU命令(字符串”0084000008”)

pszAPDUResult [out]執行APDU相應數據(字符串如”9000”)

返回值：

0：執行APDU命令成功；

非0：執行APDU命令失敗，參考狀態碼

2.7.5 Donsee_PowerOff下電

定義：CPU卡下電

原型:

long Donsee_PowerOff (unsigned char nSlotNo)

參數：

nSlotNo[in]卡座選擇：0x01 大卡座, 0x02：副卡座 ；

0x11：SAM1卡座；0x12：SAM2卡座；

0x13：SAM3卡座；0x14：SAM4卡座

返回值：

0：CPU卡下電成功；

非0：CPU卡下電失敗，參考狀態碼

2.7.6 Donsee_GetStatus獲取卡座狀態

定義：獲取卡座狀態

原型:

long Donsee_GetStatus(unsigned char nSlotNo,int* nStatus)

參數：

nSlotNo[in]卡座選擇：0x01 大卡座, 0x02：副卡座 ；

0x11：SAM1卡座；0x12：SAM2卡座；

0x13：SAM3卡座；0x14：SAM4卡座

nStatus[out]卡座狀態：為 0 表示有卡上電，1表示有卡未上，2表示無卡

返回值：

0：獲取卡座狀態成功；

非0：獲取卡座狀態失敗，參考狀態碼

2.8 15693卡

2.8.1 Donsee_15693_Find 15693尋卡

定義：15693尋卡

原型:

long Donsee_15693_Find (char* pszUID)

參數：

pszUID [out]尋卡得到8字節卡片數據；

返回值：

0：15693尋卡成功；

非0：15693尋卡失敗，參考狀態碼

2.8.2 Donsee_15693_Info 15693獲取卡片詳細信息

定義：獲取15693卡詳細信息

原型:

long Donsee_15693_Info (char* pszCardInfo)

參數：

pszCardInfo [out]14字節卡片數據；

返回值：

0：獲取15693卡詳細信息成功；

非0：獲取15693卡詳細信息失敗，參考狀態碼

2.8.3 Donsee_15693_Read 15693讀卡

定義：15693讀卡

原型:

long Donsee_15693_Read (unsigned char nBlkAdd, char* pszValue)

參數：

nBlkAdd[in]塊地址

pszValue [out]4字節卡片數據；

返回值：

0：15693讀卡成功；

非0：15693讀卡失敗，參考狀態碼

2.8.4 Donsee_15693_Write 15693寫卡

定義：15693寫卡

原型:

long Donsee_15693_Write (unsigned char nBlkAdd, char* szData)

參數：

nBlkAdd[in]塊地址

szData [in]要寫入的4字節卡片數據；

返回值：

0：15693寫卡成功；

非0：15693寫卡失敗，參考狀態碼

2.8.5 Donsee_15693_WriteAFI 15693寫AFI

定義：15693寫AFI

原型:

long Donsee_15693_WriteAFI (unsigned char szValue, char* pszValue)

參數：

szValue [in]寫入的值

pszValue [in]NULL

返回值：

0：15693寫AFI成功；

非0：15693寫AFI失敗，參考狀態碼

2.8.6 Donsee_15693_LockAFI 15693鎖AFI

定義：15693寫AFI

原型:

long Donsee_15693_LookAFI (char* pszValue)

參數：

pszValue [in]返回的值

返回值：

0：15693鎖AFI成功；

非0：15693鎖AFI失敗，參考狀態碼

2.8.7 Donsee_15693_WriteDSFID 15693寫DSFID

定義：15693寫DSFID

原型:

long Donsee_15693_WriteDSFID (unsigned char szValue, char* pszValue)

參數：

szValue [in]寫入的值

pszValue [in]NULL

返回值：

0：15693寫DSFID成功；

非0：15693寫DSFID 失敗，參考狀態碼

2.8.8 Donsee_15693_LockDSFID 15693鎖DSFID

定義：15693鎖DSFID

原型:

long Donsee_15693_LockDSFID (char* pszValue )

參數：

pszValue [in]返回的值

返回值：

0：15693鎖DSFID成功；

非0：15693鎖DSFID失敗，參考狀態碼

2.8.9 Donsee_15693_LockDataBlock用于鎖定塊內容

定義：用于鎖定塊內容。注意：此過程不可逆（不能解鎖）塊鎖定后內容不能在修改。

原型:

long Donsee_15693_LockDataBlock(unsigned char nBlk_add, char* pszValue)

參數：

nBlk_add [in]塊地址

pszValue [out]返回數據

返回值：

0：15693鎖塊內容成功；

非0：15693鎖塊內容失敗，參考狀態碼

2.9 SLE4442卡

2.9.1 Donsee_4442_PowerOn 4442卡上電

定義：4442卡上電

原型:

long Donsee_4442_PowerOn (char* pszUID)

參數：

pszUID [out]上電返回數據，4字節廠商代碼

返回值：

0：4442卡上電成功；

非0：4442卡上電失敗，參考狀態碼

2.9.2 Donsee_4442_PowerOff 4442卡下電

定義：4442卡下電

原型:

long Donsee_4442_PowerOff ()

參數：

返回值：

0：4442卡下電成功；

非0：4442卡下電失敗，參考狀態碼

2.9.3 Donsee_4442_Read 4442卡讀數據

定義：4442卡讀取數據

原型:

long Donsee_4442_Read (int nOffset, int nLen, char* pszData)

參數：

nOffset[in]起始地址

nLen[in]讀取數據長度

pszData [iout]讀取的數據內容

返回值：

0：4442卡讀取數據成功；

非0：4442卡讀取數據失敗，參考狀態碼

2.9.4 Donsee_4442_Write 4442卡寫數據

定義：4442卡寫入數據

原型:

long Donsee_4442_Write (int nOffset, int nLen, char* szData)

參數：

nOffset[in]起始地址

nLen[in]寫入數據長度

szData [in]寫入的數據內容

返回值：

0：4442卡寫入數據成功；

非0：4442卡寫入數據失敗，參考狀態碼

2.9.5 Donsee_4442_Verify 4442卡認證密鑰

定義：4442卡認證秘鑰

原型:

long Donsee_4442_Verify(char* szKey)

參數：

szKey [in]秘鑰數據，如unsigned  char chKey [4]={0xff,0xff,0xff};

返回值：

0：4442卡認證秘鑰成功；

非0：4442卡認證秘鑰失敗，參考狀態碼

2.9.6 Donsee_4442_Change 4442卡修改密鑰

定義：4442卡修改秘鑰

原型:

long Donsee_4442_Change (char *szNewKey)

參數：

szNewKey [in]秘鑰數據，如unsigned  char chNewKey [4]={0xff,0xff,0xff};

返回值：

0：4442卡修改密鑰成功；

非0：4442卡修改密鑰失敗，參考狀態碼

2.9.7 Donsee_4442_ReadProtect 4442卡讀保護數據

定義：4442卡讀取保護數據

原型:

long Donsee_4442_ReadProtect (int nOffset, int nLen, char* pszData)

參數：

nOffset[in]起始地址，起始地址 需小于32

nLen[in]讀取數據長度，數據長度 需小于32

pszData [iout]讀取的數據內容，返回值為一串00或01的數據串，如果為00代表已寫保護，如果為01代表未寫保護

返回值：

0：4442卡讀保護數據成功；

非0：4442卡讀保護數據失敗，參考狀態碼

2.9.8 Donsee_4442_WriteProtect 4442卡寫保護數據

定義：4442卡寫入保護數據，即固化數據，一旦寫保護，數據將不能再修改

原型:

long Donsee_4442_WriteProtect (int nOffset, int nLen, char* szData)

參數：

nOffset[in]起始地址，起始地址 需小于32

nLen[in]讀取數據長度，數據長度 需小于32

szData [in]讀取的數據內容，返回值為一串00或01的數據串，如果為00代表已寫保護，如果為01代表未寫保護

返回值：

0：4442卡寫保護數據成功；

非0：4442卡寫保護數據失敗，參考狀態碼

2.9.9 Donsee_4442_ReadCount 4442卡密鑰剩余認證次數

定義：4442卡密鑰剩余認證次數

原型:

long Donsee_4442_ReadCount (int* nCount)

參數：

nCount [out]4442卡密鑰剩余認次數

返回值：

0：獲取4442卡密鑰剩余認證次數成功；

非0：獲取4442卡密鑰剩余認證次數失敗，參考狀態碼

2.10磁條卡

2.10.1 Donsee_ReadMagCard磁條卡讀卡

定義：磁條卡讀卡

原型:

long Donsee_ReadMagCard (unsigned char nTime,int nTrack,char *pszTrackData)

參數：

ctime[in]超時時間，單位：秒

track [in]磁道（1~3）磁道1~~磁道3，track=4時表示全軌一次性刷出

為TLV格式，例如：010101020201020303010203

getdata [out]返回的數據

返回值：

0：磁條卡讀卡成功；

非0：磁條卡讀卡失敗，參考狀態碼

2.10.2 Donsee_ReadMagType設置輸出模式

定義：磁條卡設置輸出模式

原型:

long Donsee_ReadMagType (int nMode, unsigned char* szConfig)

參數：

nMode [in]0表示主動讀卡，1表示被動讀

szConfig [in]字符數組

szConfig [0]:0x01 磁道1

           0x02 磁道2

           0x03 磁道3

           0x04 磁道2\3

szConfig [1]:0x00 全部輸出

           0x01除去起始接收符輸出

           0x02只輸出數據

szConfig [2]：0x00不換行輸出

           0x01換行輸出

返回值：

0：磁條卡設置輸出模式成功；

非0：磁條卡設置輸出模式失敗，參考狀態碼

2.11北京通

typedef struct

{

char name[40];    /*姓名*/

char sex[10];/*性別*/

char cardnumber[40];/*北京通號*/

char nType[32] ;/*卡片類型*/

char cardName[40];/*證件名稱*/

char organs[50];/*發卡機構*/

} BJT_IDINFO;

2.11.1 Donsee_ReadBJTIDCard讀取北京通信息

定義：讀取北京通信息

原型：

long Donsee_ReadBJTIDCard (BJT_IDINFO* cardInfo,char* arrChMsg);

參數：

cardInfo [out] 北京通信息

arrChMsg [out] 錯誤信息

返回值：

0：讀取北京通信息成功；

非0：讀取北京通信息失敗，參考狀態碼

2.11.2 Donsee_ReadBJTIDCard_Photo讀取北京通照片

定義：讀取北京通信息

原型：

long Donsee_ReadBJTIDCard_Photo (char* cardInfoPhoto,char* arrChMsg);

參數：

cardInfoPhoto[in] 北京通照片保存路徑

arrChMsg [out] 錯誤信息

返回值：

0：讀取北京通照片信息成功；

非0：讀取北京通照片信息失敗，參考狀態碼

2.12輔助類函數

2.12.1 Donsee_HexToStr 16進制數組轉字符串

定義：16進制數組轉字符串

原型：

long Donsee_HexToStr(unsigned char *Src,int len,unsigned char *Des );

參數：

Src[in]:十六進制數組

Len[in]:數據長度

Des[out]:轉換好的hexstr格式字符串。

返回值：

0：16進制數組轉字符串成功；

非0：16進制數組轉字符串失敗，參考狀態碼

2.12.2 Donsee_StrToHex 字符串轉16進制數組

定義：字符串轉16進制數組

原型：long Donsee_StrToHex(unsigned char *Src, int len,unsigned char *Des);

參數：

Src[in]:hexstr格式字符串

Len[in]:字節長度

Des[out];轉換好的數據

返回值：

0：字符串轉16進制數組成功；

非0：字符串轉16進制數組失敗，參考狀態碼

2.13社保卡加密機

2.13.1 Donsee_iReadCardBas讀基本信息

/*********************社保卡讀取  特別注意事項**********************

1、二代社保卡可以直接讀取，只支持插卡（接觸式）方式讀取。

2、三代社保卡加密了，需要PSAM卡才能讀取，支持插卡（接觸式）和非接觸式兩種讀取方式。

3、如果插PSAM卡了，讀卡失敗，需要留意以下返回值：

-25536、-25537、-25538、-25539、-25540、-25541，外部認證失敗，表示剩余可嘗試次數0~5次，當返回-25536社保卡就鎖卡了。

*********************社保卡讀取  特別注意事項**********************/

定義：讀基本信息

原型:

long Donsee_iReadCardBas(int nType, char *pOutInfo)

參數：

nType [in]卡片類型默認3， 接觸+非接（接觸優先）

info [out]返回的數據

返回值：

0：讀卡成功；

非0：讀卡失敗，參考狀態碼

//返回格式：發卡地區行政區劃代碼（卡識別碼前6位）|社會保障號碼|卡號|卡識別碼|姓名|卡復位信息（僅取歷史字節）|規范版本|發卡日期|卡有效期|終端機編號|終端設備號|

//返回舉例：

360700|360700199907151372|890642628|360700D156003335690999604657ED2D|張無忌|0081544B44869B160818107861|2.00|20180701|20280701|310000309109|65884835323437175132|

說明：此函數讀三代社保卡需要psam卡，否則返回-2201，二代社保卡可以直接讀取

2.13.2 Donsee_iReadCardBas_HSM_Step1加密機步驟1

定義：加密機步驟1

原型:

long Donsee_iReadCardBas_HSM_Step1(int nType,char *pOutInfo)

參數：

nType [in]卡片類型默認3， 1接觸、2非接、3接觸+非接（接觸優先）

info [out]返回的數據

返回值：

0：讀卡成功；

非0：讀卡失敗，參考狀態碼

//返回格式：發卡地行政區劃代碼|卡復位信息|算法標識|卡識別碼|內部認證過程因子|內部認證鑒別所需的原始信息|外部認證過程因子|外部認證鑒別所需的原始信息|

//返回舉例：

440100|00814A66678660440100AC8FE3|03|440100D15600880600AC8FE3257118AC|7EFCD0C331DA50AC|0102030405060708|DB25A7E8ABD59B1B|0102030405060708|

2.13.3 Donsee_iReadCardBas_HSM_Step2加密機步驟2

定義：加密機步驟2

原型:

long Donsee_iReadCardBas_HSM_Step2 (char *key, char *pOutInfo)

參數：

key [in]    密鑰，即加密機返回的信息

info [out]返回的數據

返回值：

0：讀卡成功；

非0：讀卡失敗，參考狀態碼

key為加密機返回的內部認證和外部認證結果數據，依次為：內部認證結果數據（即內部認證鑒別數據（16 位）和內部認證鑒別所需的原始信息（16 位）拼接組成）、外部認證結果數據（即外部認證鑒別數據（16 位）和外部認證鑒別所需的原始信息（16 位）拼接組成）。各數據項之間以“|”分割，且最后一個數據項以“|”結尾。

例如：96BBD0687A1667AD0102030405060708|A52BFF7396EEE45F0102030405060708|

//返回格式（和Donsee_iReadCardBas一樣）：發卡地區行政區劃代碼（卡識別碼前6位）|社會保障號碼|卡號|卡識別碼|姓名|卡復位信息（僅取歷史字節）|規范版本|發卡日期|卡有效期|終端機編號|終端設備號|

//返回舉例：

360700|360700199907151372|890642628|360700D156003335690999604657ED2D|張無忌|0081544B44869B160818107861|2.00|20180701|20280701|310000309109|65884835323437175132|

2.13.4 Donsee_getTerminalNo獲取終端機編號

定義：讀取設備版本號

原型:

long Donsee_getTerminalNo (unsigned char nSlotNo,char* szTerminalNo)

參數：

nSlotNo[in]     PSAM存放卡座，0x11 SAM1, 0x12 SAM2, 0x13 SAM3, 0x14 SAM4

szTerminalNo[out] 社保加密PSAM卡卡號，即終端機編號，12位數據，例如310000309109

返回值：

0：獲取終端機編號成功；

非0：獲取終端機編號失敗，參考狀態碼

2.13.5 Donsee_ChipSerial獲取芯片序列號，即終端設備號

定義：讀取設備版本號

原型:

long Donsee_ChipSerial(char* pszChipSerial)

參數：

pszChipSerial[out] 獲取芯片序列號，即終端設備號，20位數據，例如65884835323437175132

返回值：

0：獲取終端設備號成功；

非0：獲取終端設備號失敗，參考狀態碼

3、狀態碼

IFD_OK0執行成功

IFD_ICC_TypeError-1卡片類型不對

IFD_ICC_NoExist-2無卡

IFD_ICC_NoPower-3有卡未上電

IFD_ICC_NoResponse-4卡片無應答

IFD_ConnectError-11讀卡器連接錯

IFD_UnConnected-12未建立連接(沒有執行打開設備函數)

IFD_BadCommand-13(動態庫)不支持該命令

IFD_ParameterError-14(發給動態庫的)命令參數錯

IFD_CheckSumError-15信息校驗和出錯

社保卡狀態碼

返回值錯誤信息描述

-1卡類型不對

-2無卡

-3有卡未上電

-4卡無應答

-5加載動態庫錯

-11讀卡器連接錯

-12未建立連接

-13（動態庫）不支持該命令

-14（發給動態庫的）命令參數錯

-15信息校驗和出錯

-20卡識別碼格式錯

-21內部認證失敗（用戶卡不合法）

-22傳入數據與卡內不符

-23傳入數據不合法

-24PSAM卡密鑰級別不夠

-31用戶取消密碼輸入

-32密碼輸入操作超時

-33輸入密碼長度錯

-34兩次輸入密碼不一致

-35（預留）初始密碼不能交易

-36（預留）不能改為初始密碼

-41運算數據含非法字符

-42運算數據長度錯

-51PIN校驗失敗，剩余次數N次（根據卡返回信息）

-52PIN鎖定

-2201無PSAM卡

-2202PSAM卡算法不支持（即PSAM卡內沒有SSF33算法或SM4算法）

-2203PSAM卡內沒有RKSSSE密鑰（3.0卡讀個人基本信息需要RKSSSE密鑰外部認證）

-2204不需要加密機認證

-25536、-25537、-25538、-25539、-25540、-25541外部認證失敗，剩余可嘗試次數0~5次

-26368Lc/Le不正確

-26881命令不接受（無效狀態）

-27009命令與文件結構不相符、當前文件非所需文件

-27010不滿足安全條件

-27011密鑰鎖定（算法鎖定）鑒別方法鎖定

-27012引用數據無效、隨機數無效

-27013不滿足使用條件、應用被鎖定、應用未選擇、余額上溢

-27016安全報文數據項不正確、MAC不正確

-27264數據域參數不正確

-27265不支持該功能、卡中無MF、卡被鎖定、應用鎖定

-27266未找到文件、文件標識相重、SFI不正確

-27267未找到記錄

-27272未找到引用數據、未找到密鑰

-37634MAC無效

-37635應用已被永久鎖定、卡片鎖定

-37891PSAM卡不支持消費交易

-37894所需MAC（或/和TAC）不可用

其他未知錯誤

4、卡片調用順序（注意USB和串口部分不同）

4.1 TypeA卡

USB：

1、設置為TypeA卡片：Donsee_SetTypeA

2、請求卡片：Donsee_ICRequest

3、防碰撞：Donsee_ICAnticoll //這里可以出來卡片的UID，8位16進制

4、選擇卡片：Donsee_ICSelect

5、TypeA上電：Donsee_PowerOnTypeA

6、APDU命令：Donsee_APDUType

串口：

1、TypeA上電：Donsee_PowerOnTypeA

2、APDU命令：Donsee_APDUType

4.2 TypeB卡

USB：

1、設置為TypeB卡片：Donsee_SetTypeB

2、上電：Donsee_PowerOnTypeB

3、選卡：Donsee_ICSelect

4、APDU 命令：Donsee_APDUType

串口：

1、上電：Donsee_PowerOnTypeB

2、APDU 命令：Donsee_APDUType

4.3 M1卡

USB方式：

1、設置為TypeA卡片：Donsee_SetTypeA

2、請求卡片：Donsee_ICRequest

3、防碰撞：Donsee_ICAnticoll //這里可以出來卡片的UID，8位16進制

4、選擇卡片：Donsee_ICSelect

5、認證密鑰：Donsee_M1VerifyPass//0x60認證KeyA， 0x61認證KeyB

6、讀/寫：Donsee_M1Read/Donsee_M1Write

串口方式：

1、尋卡：Donsee_ReadICUid //出來UID，8位16進制

2、認證密鑰：Donsee_M1VerifyPass

3、讀/寫：Donsee_M1Read/Donsee_M1Write

4.4 4442卡

1、上電復位：Donsee_4442_PowerOn

2、卡認證：Donsee_4442_Verify

3、讀/寫：Donsee_4442_Read/Donsee_4442_Write

4.5 接觸CPU卡

1、上電復位：Donsee_PowerOn

2、APDU 命令：Donsee_APDU