GBXX/T ××××-2009 7.2.4 获取PIN信息
函数原型 ULONG DEVAPI SKF_GetPINInfo(HAPPLICATION hApplication, ULONG ulPINType,
ULONG *pulMaxRetryCount, ULONG *pulRemainRetryCount, BOOL *pbDefaultPin)
功能描述 获取PIN码信息，包括最大重试次数、当前剩余重试次数，以及当前PIN码是否为出
厂默认PIN码。
参数 hApplication [IN] 应用句柄
ulPINType [IN] PIN类型
pulMaxRetryCount [OUT] 最大重试次数
pulRemainRetryCount [OUT] 当前剩余重试次数，当为0时表示已锁死。 pbDefaultPin [OUT] 是否为出厂默认PIN码 SAR_OK表示成功，其它表示失败。 可能的错误值：
SAR_USER_TYPE_INVALID PIN类型错误； SAR_INVALIDHANDLEERR 句柄无效。
返回值
7.2.5 校验PIN
函数原型 ULONG DEVAPI SKF_VerifyPIN (HAPPLICATION hApplication, ULONG ulPINType,
LPSTR szPIN, ULONG *pulRetryCount)
功能描述 校验PIN码。校验成功后，会获得相应的权限，如果PIN码错误，会返回PIN码的重
试次数，当重试次数为0时表示PIN码已经锁死。
参数 hApplication [IN] 应用句柄 ulPINType [IN] PIN类型
szPIN [IN] PIN值
pulRetryCount [OUT] 出错后返回的重试次数
返回值 SAR_OK表示成功，其它表示失败。
可能的错误值：
SAR_MEMORYERR 发生内存错误； SAR_UNKNOWNERR 发生未知错误； SAR_PIN_INCORRECT PIN错误； SAR_PIN_INVALID PIN无效；
SAR_PIN_LEN_RANGE PIN长度错误； SAR_PIN_LOCKED PIN锁死；
SAR_USER_ALREADY_LOGGED_IN PIN已经获得权限； SAR_USER_PIN_NOT_INITIALIZED PIN为初始化错误； SAR_USER_TYPE_INVALID PIN类型错误； SAR_INVALIDHANDLEERR 句柄无效。
7.2.6 解锁PIN
函数原型 ULONG DEVAPI SKF_UnblockPIN (HAPPLICATION hApplication, LPSTR szAdminPIN,
LPSTR szNewUserPIN, ULONG *pulRetryCount)
功能描述 当用户的PIN码锁死后，通过调用该函数来解锁用户PIN码。
解锁后，用户PIN码被设置成新值，用户PIN码的重试次数也恢复到原值。
参数 hApplication [IN] 应用句柄
szAdminPIN [IN] 管理员PIN码 szNewUserPIN [IN] 新的用户PIN码
pulRetryCount [OUT] 管理员PIN码错误时，返回剩余重试次数
返回值 SAR_OK表示成功，其它表示失败。 20
GBXX/T ××××-2009
可能的错误值：
SAR_MEMORYERR 发生内存错误； SAR_UNKNOWNERR 发生未知错误； SAR_PIN_INCORRECT PIN错误； SAR_PIN_INVALID PIN无效；
SAR_PIN_LEN_RANGE PIN长度错误； SAR_PIN_LOCKED, PIN锁死；
SAR_USER_PIN_NOT_INITIALIZED PIN为初始化错误； SAR_INVALIDHANDLEERR 句柄无效。
备注 权限要求：验证完管理员PIN才能够解锁用户PIN码，如果输入的Administrator PIN
不正确或者已经锁死，会调用失败，并返回Administrator PIN的重试次数。
7.2.7 清除应用安全状态
函数原型 ULONG DEVAPI SKF_ClearSecureState (HAPPLICATION hApplication) 功能描述 清除应用当前的安全状态。 参数 hApplication [IN] 应用句柄 返回值
SAR_OK表示成功，其它表示失败。
可能的错误值：
SAR_MEMORYERR 发生内存错误； SAR_UNKNOWNERR 发生未知错误； SAR_INVALIDHANDLEERR 句柄无效。
7.3 应用管理
应用管理主要完成应用的创建、枚举、删除、打开、关闭等操作。应用管理系列函数如表18所示：
表18 函数名称 SKF_CreateApplication SKF_EnumApplication SKF_DeleteApplication SKF_OpenApplication SKF_CloseApplication 功能 创建应用 枚举应用 删除应用 打开应用 关闭应用 备注 7.3.1 创建应用 函数原型 ULONG DEVAPI SKF_CreateApplication(DEVHANDLE hDev, LPSTR szAppName, LPSTR
szAdminPin, DWORD dwAdminPinRetryCount,LPSTR szUserPin, DWORD dwUserPinRetryCount,DWORD dwCreateFileRights, HAPPLICATION *phApplication)
功能描述 创建一个应用。 参数 hDev [IN] 连接设备时返回的设备句柄
szAppName [IN] 应用名称 szAdminPin [IN] 管理员PIN
dwAdminPinRetryCount [IN] 管理员PIN最大重试次数 szUserPin [IN] 用户PIN
dwUserPinRetryCount [IN] 用户PIN最大重试次数
dwCreateFileRights phApplication
返回值
[IN] 在该应用下创建文件和容器的权限，参见6.4.9权限类型。为各种权限的或值。 [OUT] 应用的句柄
SAR_OK表示成功，其它表示失败。
21
GBXX/T ××××-2009
可能的错误值：
SAR_MEMORYERR 发生内存错误； SAR_UNKNOWNERR 发生未知错误； SAR_INVALIDHANDLEERR 句柄无效；
SAR_APPLICATION_NAME_INVALID应用名称无效； SAR_APPLICATION_EXISTS 应用已经存在；
备注 权限要求：需要设备权限。 7.3.2 枚举应用
函数原型 ULONG DEVAPI SKF_EnumApplication(DEVHANDLE hDev, LPSTR szAppName,ULONG
*pulSize)
功能描述 枚举设备中所存在的所有应用。 参数 hDev [IN] 连接设备时返回的设备句柄
szAppName [OUT] 返回应用名称列表, 如果该参数为空，将由pulSize返
回所需要的内存空间大小。每个应用的名称以单个‘\\0’结束，以双‘\\0’表示列表的结束。
pulSize [IN,OUT] 输入参数，输入应用名称的缓冲区长度，输出参数， 返回szAppName所占用的的空间大小。
返回值 SAR_OK表示成功，其它表示失败。
可能的错误值：
SAR_MEMORYERR 发生内存错误； SAR_UNKNOWNERR 发生未知错误。
7.3.3 删除应用
函数原型 ULONG DEVAPI SKF_DeleteApplication(DEVHANDLE hDev, LPSTR szAppName) 功能描述 删除指定的应用。 参数 hDev [IN] 连接设备时返回的设备句柄
szAppName [IN] 应用名称
返回值 SAR_OK表示成功，其它表示失败。
可能的错误值：
SAR_MEMORYERR 发生内存错误； SAR_UNKNOWNERR 发生未知错误；
SAR_APPLICATION_NOT_EXISTS 应用不存在。
备注 权限要求：需要设备权限。 7.3.4 打开应用
函数原型 ULONG DEVAPI SKF_OpenApplication(DEVHANDLE hDev, LPSTR szAppName,
HAPPLICATION *phApplication)
功能描述 打开指定的应用。 参数 hDev [IN] 连接设备时返回的设备句柄
szAppName [IN] 应用名称 phApplication [OUT] 应用的句柄
返回值 SAR_OK表示成功，其它表示失败。
可能的错误值：
SAR_MEMORYERR 发生内存错误； SAR_UNKNOWNERR 发生未知错误；
SAR_APPLICATION_NOT_EXISTS 应用不存在。
7.3.5 关闭应用
函数原型 ULONG DEVAPI SKF_CloseApplication(HAPPLICATION hApplication) 22
GBXX/T ××××-2009
功能描述 参数 返回值
关闭应用并释放应用句柄。 hApplication [IN]应用句柄 SAR_OK表示成功，其它表示失败。 可能的错误值：
SAR_MEMORYERR 发生内存错误； SAR_UNKNOWNERR 发生未知错误；
SAR_USER_NOT_LOGGED_IN 尚未校验用户PIN； SAR_INVALIDHANDLEERR 句柄无效。
备注 此函数不影响应用安全状态。 7.4 文件管理
本规范提供的文件管理函数用以满足用户扩展开发的需要，包括创建文件、删除文件、枚举文件、获取文件信息、文件读写操作。文件管理系列函数如表19所示：
表19 函数名称 SKF_CreateFile SKF_DeleteFile SKF_EnumFiles SKF_GetFileInfo SKF_ReadFile SKF_WriteFile 功能 创建文件 删除文件 枚举文件 获取文件信息 读文件 写文件 备注 7.4.1 创建文件
函数原型 ULONG DEVAPI SKF_CreateFile (HAPPLICATION hApplication, LPSTR szFileName,
ULONG ulFileSize, ULONG ulReadRights，ULONG ulWriteRights)
功能描述 创建文件时要指定文件的名称，大小，以及文件的读写权限。 参数 hApplication [IN] 应用句柄 [IN] 文件名称，长度不得大于32个字节
[IN] 文件大小
[IN] 文件读权限，参见6.4.9 权限类型。可为各种权限的或值
ulWriteRights [IN] 文件读权限，参见6.4.9权限类型。可为各种权限的
或值
返回值 SAR_OK表示成功，其它表示失败。
可能的错误值：
SAR_MEMORYERR 发生内存错误； SAR_UNKNOWNERR 发生未知错误；
SAR_USER_NOT_LOGGED_IN 尚未校验用户PIN； SAR_INVALIDHANDLEERR 句柄无效； SAR_FILEERR 文件错误；
SAR_NAMELENERR 文件名称长度错误； SAR_FILE_ALREADY_EXIST 文件已经存在； SAR_NO_ROOM 剩余空间不够。
备注 创建文件需要应用指定的创建文件权限。 7.4.2 删除文件
函数原型 ULONG DEVAPI SKF_DeleteFile (HAPPLICATION hApplication, LPSTR szFileName) 功能描述 删除指定文件：
文件删除后，文件中写入的所有信息将丢失。
23
szFileName ulFileSize ulReadRights
GBXX/T ××××-2009
文件在设备中的占用的空间将被释放。
参数 hApplication [IN] 要删除文件所在的应用句柄
szFileName [IN] 要删除文件的名称
返回值 SAR_OK表示成功，其它表示失败。
可能的错误值：
SAR_MEMORYERR 发生内存错误； SAR_UNKNOWNERR 发生未知错误；
SAR_USER_NOT_LOGGED_IN 尚未校验用户PIN； SAR_INVALIDHANDLEERR 句柄无效； SAR_FILEERR 文件错误。
备注 权限要求：删除一个文件应具有对该文件的创建权限。 7.4.3 枚举文件
函数原型 ULONG DEVAPI SKF_EnumFiles (HAPPLICATION hApplication, LPSTR szFileList,
ULONG *pulSize)
功能描述 枚举一个应用下存在的所有文件。 参数 hApplication [IN] 应用句柄
szFileList [OUT] 返回文件名称列表，该参数为空，由pulSize返回文件信
息所需要的空间大小。每个文件名称以单个‘\\0’结束，以双‘\\0’表示列表的结束。
pulSize [IN, OUT] 输入为数据缓冲区的大小，输出为实际文件名称的大
小
返回值 SAR_OK表示成功，其它表示失败。
可能的错误值：
SAR_MEMORYERR 发生内存错误； SAR_UNKNOWNERR 发生未知错误； SAR_INVALIDHANDLEERR 句柄无效； SAR_BUFFER_TOO_SMALL 缓冲区不足。
7.4.4 获取文件属性
函数原型 ULONG DEVAPI SKF_GetFileInfo (HAPPLICATION hApplication, LPSTR szFileName,
FILEATTRIBUTE *pFileInfo)
功能描述 获取文件信息：
获取应用文件的属性信息，例如文件的大小、权限等。
参数 hApplication [IN] 文件所在应用的句柄
szFileName [IN] 文件名称 pFileInfo [OUT] 文件信息，指向文件属性结构的指针 返回值
SAR_OK表示成功，其它表示失败。 可能的错误值：
SAR_MEMORYERR 发生内存错误； SAR_UNKNOWNERR 发生未知错误； SAR_INVALIDHANDLEERR 句柄无效； SAR_FILEERR 文件错误；
SAR_FILE_NAME_INVALID 文件名称无效。
7.4.5 读文件
函数原型 ULONG DEVAPI SKF_ReadFile (HAPPLICATION hApplication， LPSTR szFileName,
ULONG ulOffset, ULONG ulSize, BYTE * pbOutData, ULONG *pulOutLen)
功能描述 读取文件内容。 24