華旭HX-FDX3S/HX-FDX5安卓Android二次開發包SDK開發包測試程序下載
華旭HX-FDX3S/HX-FDX5安卓Android二次開發包SDK開發包測試程序下載
J13 Android API 使用說明文檔 目錄 J13 Android API使用說明文檔........................................................................................... 1
一、前言................................................................................................................................... 2
二、系統要求........................................................................................................................... 2
三、Jar 使用說明 ..................................................................................................................... 2
3.1 基礎配置確認................................................................................................................ 2
3.2Jar 文件的使用方法 ....................................................................................................... 3
四、函數詳細說明................................................................................................................... 4
4.1 構造函數......................................................................................................................... 4
4.2 獲取模塊狀態................................................................................................................. 5
4.3 身份證卡驗證................................................................................................................. 5
4.4 讀卡（居民身份證+港澳臺居民居住證+外國人永久居留證） ................................. 5
4.5 身份證讀卡（通過參數返回文字+照片數據）........................................................... 6
4.6 身份證讀卡（通過參數返回文字+照片數據+指紋數據）......................................... 7
4.7 圖像輔助函數（將 bmp 字節流轉換為彩色）............................................................ 8
4.8 get 函數........................................................................................................................... 8
六、調用 API 讀卡流程說明.................................................................................................... 9
七、錯誤代碼......................................................................................................................... 10
廣州千景信息科技有限公司 2018年08月
一、前言
本手冊是千景J13居民身份證身份閱讀器關于 Android 開發 時的使用說明，適用于使用本產品的Android 開發人員。 二、系統要求
--使用本 API 的設備，必須滿足下列條件：
--Android 設備
--Android 設備支持 USB Host
--Android 設備已經開放了 USB 訪問權限
--至少一個空閑 USB 口。 三、Jar 使用說明 3.1 基礎配置確認 1）確認 Android 設備支持 USB Host。 2) 確認 Android 設備已經開放 USB 訪問權限。確認目錄 “/system/ect/permissions”下 存在文件“android.hardware.usb.host.xml”，若沒有，則創建 一個同名文件，內容如下： <permissions> <feature name=”android.hardware.usb.host”/>
</permissions>
3) 確 認 “ /system/etc/permissions ” 下 的
“handheld_core_hardware.xml （手機）
或 者 tablet_core_hardware.xml （ 平 板 ）” 文 件 中 的
<permissions>結點存在下面的子結點：
<feature name="android.hardware.usb.host" />
若沒有，補充上述一行。
4)重啟 Android 設備。
3.2Jar 文件的使用方法
1 ）使用本開發庫，需要將 publicSecurityIDCardLib 、
sdtapi-v*.*.jar ，以及相應的so庫，放到新建android 工程的libs
目錄下。
2）本接口為居民身份證安全模塊的 USB 使用接口，需要確保
android 工程的
AndroidManifest.xml 文件正確標明使用權限如下：
<intent-filter>
<action
android:name="android.hardware.usb.action.USB_DEVICE_ATTACH
ED" />
</intent-filter>
<meta-data
android:name="android.hardware.usb.action.USB_DEVICE_ATTACH
ED"
android:resource="@xml/device_filter"/>
3）在 android 工程的 res 目錄下新建 xml 文件夾，并新建文
件 device_filter.xml ，文件
內容如下：
<?xml version="1.0" encoding="utf-8"?>
<resources>
<usb-device vendor-id="1024" product-id="50010"/>
</resources>
上述的 vendor-id、product-id 就是 USB 設備即居民身份證安
全模塊的 vid 和 pid。 4）調用 Jar 中的函數之前，需要進行對象的初始化，例如在
MainActivity.java 中：
publicSecurityIDCardLib hdReaderDevice= new
publicSecurityIDCardLib (MainActivity.this);
四、函數詳細說明
4.1 構造函數
public publicSecurityIDCardLib(Context context);
參數說明：
Context：[IN] MainActivit
返回值：
無
4.2 獲取模塊狀態
public int getSAMStatus();
參數說明：
無
返回值：
0x90 表示成功
4.3 身份證卡驗證
public int ID_Authenticate(boolean bFlag);
參數說明：
bFlag：[IN] 是否需要連續讀卡，true=不連續讀同一張卡（需
拿開重新放置才能讀第二次），false=可反復連續讀同一張卡
返回值：
0x90 表示成功, bFlag 為 false 時不需要判斷返回值。
4.4 讀卡（居民身份證+港澳臺居民居住證+外國人永久居留
證）
public int ID_ReadCardBaseMsg();
參數說明：
無
返回值：
0x90 表示成功，讀取成功之后通過各個 get 函數獲取信息。
4.5 身份證讀卡（通過參數返回文字+照片數據）
public int readBaseMsgToStr(String pkName,
byte[] BmpFile,
byte[] pName,
byte[] pSex,
byte[] pNation,
byte[] pBirth,
byte[] pAddress,
byte[] pIDNo,
byte[] pDepartment,
byte[] pEffectDate,
byte[] pExpireDate);
參數：
pBmpFile： [OUT]bmp 格式數據，需 38862 字節空間
pName： [OUT]姓名，50 字節
pSex： [OUT]性別，10 字節
pNation： [OU]民族，10 字節
pBirth： [OUT]出生日期，30 字節
pAddress： [OUT]家庭住址，100 字節
pIDNo： [OUT]身份號，50 字節
pDepartment： [OUT]簽發機關，50
pEffectDate： [OUT]有效起始日期，30 字節
pExpireDate： [OUT]有效截止日期，30 字節
pkName： [OUT]包名，例如:
String pkName=this.getPackageName();
返回值：
0x90 返回成功
4.6 身份證讀卡（通過參數返回文字+照片數據+指紋數據）
public int readBaseMsgToStr_Fp(String pkName,
byte[] BmpFile,
byte[] Fpmsg,
byte[] pName,
byte[] pSex,
byte[] pNation,
byte[] pBirth,
byte[] pAddress,
byte[] pIDNo,
byte[] pDepartment,
byte[] pEffectDate,
byte[] pExpireDate);
參數：
pBmpFile： [OUT]bmp 格式數據，需 38862 字節空間
Fpmsg： [OUT]指紋特征數據，需 1024 字節空間
pName： [OUT]姓名，50 字節
pSex： [OUT]性別，10 字節
pNation： [OU]民族，10 字節
pBirth： [OUT]出生日期，30 字節
pAddress： [OUT]家庭住址，100 字節
pIDNo： [OUT]身份號，50 字節
pDepartment： [OUT]簽發機關，50
pEffectDate： [OUT]有效起始日期，30 字節
pExpireDate： [OUT]有效截止日期，30 字節
pkName： [OUT]包名，例如:
String pkName=this.getPackageName();
返回值：
0x90 返回成功
4.7 圖像輔助函數（將 bmp 字節流轉換為彩色）
public int[] convertByteToColor(byte[] data);
參數：
Data：bmp 數據流，例如:getBmpfileData 函數的返回值
返回值：
彩色數據流，可用來生成 bmp 圖片，可參照示例代碼
4.8 get 函數
函數名
(返回數據類型：String，
紅色標記的為 int 型)
獲取信息功能 包含證件類型
GetCardType 根據返回值判斷：
0：居民身份證
1：外國人永久居留證
2：港澳臺居民居住證
getName 姓名(類型為 1 時表示：
外國人中文姓名) 0、1、2
getSex 性別 0、1、2
getNation 民族 0
getBirth 出生日期 0、1、2
getAddress 住址 0、2
getIDNo 公民身份證號碼(類型為 1 時
表示：外國人居留證號碼) 0、1、2
getDepartment 簽發機關 0、2
getEffectDate 有效起始日期 0、1、2
getExpireDate 有效截止日期 0、1、2
getBmpfileData bmp 格式照片數據 0、1、2
IsFingerExist 根據返回值判斷：
0：無指紋信息
512：一根手指數據長度
1024：兩根手指數據長度
0、2
getFingerPrint 指紋數據 0、2
getEnName 外國人英文姓名 1
getNationalityCode 外國人國籍代碼 ， 符 合
GB/T2659-2000 規定
1
getTXZHM 港澳臺通行證號碼 2
getTXZQFCS 港澳臺通行證簽發次數 2 注： 以上函數須在 “ID_ReadCardBaseMsg” 函數執行成功之后調用，否則獲取不到有效
信息。
六、調用 API 讀卡流程說明
根據本接口實際情況，可分為以下兩種方案讀卡：
1） ID_Authenticate ? ID_ReadCardBaseMsg ?各 get 函數。 2） readBaseMsgToStr/ readBaseMsgToStr_Fp 直接讀取即可（函
數內部會自行調用 ID_Authenticate，僅支持居民身份證）。 3） 其它模塊函數單獨調用即可。
七、錯誤代碼
函數返回值列表
返回值,16 進 制
意義
0x90 操作成功
0x91 居民身份證中此項無內容
0x9F 尋找居民身份證成功
0x02 接收超時，在規定的時間內未接收到規定長度的數據
0x03 數據傳輸錯誤
0x10 接收業務終端數據的校驗和錯
0x11 接收業務終端數據的長度錯
0x21 接收業務終端的命令錯誤，包括命令中的各種數值或邏輯搭
配錯誤
0x23 越權操作
0x24 無法識別的錯誤
0x80 尋找證/卡失敗
0x81 選取證/卡失敗
0x31 證/卡證認 SAM 失敗
0x32 SAM 認證證/卡失敗
0x33 信息驗證錯誤
0x40 無法識別的居民身份證類型
0x41 讀取居民身份證操作失敗
0x47 讀取隨機數失敗
0x60 SAM 自檢失敗，不能接收命令
0x66 SAM 沒經過授權,無法使用
