001 /*
002 * ===========================================================================================
003 * = COPYRIGHT
004 *          PAX Computer Technology (Shenzhen) Co., Ltd. PROPRIETARY INFORMATION
005 *   This software is supplied under the terms of a license agreement or nondisclosure
006 *   agreement with PAX Computer Technology (Shenzhen) Co., Ltd. and may not be copied or
007 *   disclosed except in accordance with the terms in that agreement.
008 *     Copyright (C) 2017-2023 PAX Computer Technology (Shenzhen) Co., Ltd. All rights reserved.
009 * Description: // Detail description about the function of this module,
010 *             // interfaces with the other modules, and dependencies.
011 * Revision History:
012 * Date                         Author                        Action
013 * 2017/04/01                   PAX                     Create/Add/Modify/Delete
014 * ===========================================================================================
015 */
016 
017package com.pax.dal;
018
019import com.pax.dal.entity.ApduRespInfo;
020import com.pax.dal.entity.ApduSendInfo;
021import com.pax.dal.entity.IccPara;
022import com.pax.dal.exceptions.IccDevException;
023import com.pax.dal.memorycard.ICardAT24Cxx;
024import com.pax.dal.memorycard.ICardAT88SC102;
025import com.pax.dal.memorycard.ICardAT88SC153;
026import com.pax.dal.memorycard.ICardAT88SC1608;
027import com.pax.dal.memorycard.ICardSle4428;
028import com.pax.dal.memorycard.ICardSle4442;
029
030/**
031 *  <div class="zh">关于 POS IC卡的API。 如果开启权限检查，需在AndroidManifest下添加权限:"com.pax.permission.ICC"</div>
032 *  <div class="en">API for POS IC cards. If permission check is enabled, you need to add permission under AndroidManifest: "com.pax.permission.ICC".</div>
033 */
034public interface IIcc {
035    /**
036     * <div class="zh"> 复位IC卡片，并返回卡片的复位应答内容 </div> <div class="en"> Reset IC card and return the content of answer to
037     * reset </div>
038     * 
039     * @param slot
040     *            <div class="zh"> 需要初始化卡通道号
041     *            <ul>
042     *            <li>bit[2:0]：0~7 编号的通道号</li>
043     *            <li>bit[4:3]：表示操作条件 <i> 00：5V</i> <i> 01：1.8V</i><i> 10：3V</i><i> 11：5V</i></li>
044     *            <li>bit[5]：表示对 PPS 协议支持 <i>0 表示不支持</i><i>1 表示支持</i></li>
045     *            <li>bit[6]：表示上电复位使用速率<i>0 默认(9600)</i><i>1 38400</i></li>
046     *            <li>bit[7]：表示支持的规范类型<i>0 EMV</i><i>1 ISO7816-3</i></li>
047     *            </ul>
048     *            </div> <div class="en"> the number of card channel which should be initialized
049     *            <ul>
050     *            <li>bit[2:0] : the number of card channel <i>0:bank card channel</i> <i>2:SAM1 card channel</i>
051     *            <i>3:SAM2 card channel</i> <i>4:SAM3 card channel</i> <i>5:SAM4 card channel</i></li>
052     *            <li>bit[4:3] : Operating conditions<i>00:5V</i> <i>01:1.8V</i> <i>10:3V</i> <i>11:5V</i></li>
053     *            <li>bit[5] :Whether to support the PPS protocol<i>0:false</i><i>1:true</i></li>
054     *            <li>bit[6] :use velocity for power on reset<i>0:9600(default)</i><i>1:38400</i></li>
055     *            <li>bit[7] :Whether to support the specification type<i>0:EMV</i><i>1:ISO7816-3</i></li>
056     *            </ul>
057     *            </div>
058     * 
059     * @return <div class="zh"> 卡片复位应答 内容。</div> <div class="en"> Answer to reset of card.</div>
060     * 
061     * @throws IccDevException
062     */
063    public byte[] init(byte slot) throws IccDevException;
064
065    /**
066     * <div class="zh"> 对指定卡座中的卡片下电 </div> <div class="en"> Power off the specified IC card in the card slot </div>
067     * 
068     * @param slot
069     *            <div class="zh"> 通道号
070     *            <ul>
071     *            <li>bit[2:0]：0~7 编号的通道号</li>
072     *            <li>bit[4:3]：表示操作条件 <i> 00：5V</i> <i> 01：1.8V</i><i> 10：3V</i><i> 11：5V</i></li>
073     *            <li>bit[5]：表示对 PPS 协议支持 <i>0 表示不支持</i><i>1 表示支持</i></li>
074     *            <li>bit[6]：表示上电复位使用速率<i>0 默认(9600)</i><i>1 38400</i></li>
075     *            <li>bit[7]：表示支持的规范类型<i>0 EMV</i><i>1 ISO7816-3</i></li>
076     *            </ul>
077     *            </div> <div class="en"> the number of card channel which should be initialized
078     *            <ul>
079     *            <li>bit[2:0] : the number of card channel <i>0:bank card channel</i> <i>2:SAM1 card channel</i>
080     *            <i>3:SAM2 card channel</i> <i>4:SAM3 card channel</i> <i>5:SAM4 card channel</i></li>
081     *            <li>bit[4:3] : Operating conditions<i>00:5V</i> <i>01:1.8V</i> <i>10:3V</i> <i>11:5V</i></li>
082     *            <li>bit[5] :Whether to support the PPS protocol<i>0:false</i><i>1:true</i></li>
083     *            <li>bit[6] :use velocity for power on reset<i>0:9600(default)</i><i>1:38400</i></li>
084     *            <li>bit[7] :Whether to support the specification type<i>0:EMV</i><i>1:ISO7816-3</i></li>
085     *            </ul>
086     *            </div>
087     * 
088     * @throws IccDevException
089     */
090    public void close(byte slot) throws IccDevException;
091
092    /**
093     * <div class="zh"> 设置isoCommand函数是否自动发送GET RESPONSE指令 </div> <div class="en"> Configure IsoCommand method to decide
094     * whether sends 'Get Response command automatically or not. </div>
095     * 
096     * @param slot
097     *            <div class="zh"> 通道号
098     *            <ul>
099     *            <li>bit[2:0]：0~7 编号的通道号</li>
100     *            <li>bit[4:3]：表示操作条件 <i> 00：5V</i> <i> 01：1.8V</i><i> 10：3V</i><i> 11：5V</i></li>
101     *            <li>bit[5]：表示对 PPS 协议支持 <i>0 表示不支持</i><i>1 表示支持</i></li>
102     *            <li>bit[6]：表示上电复位使用速率<i>0 默认(9600)</i><i>1 38400</i></li>
103     *            <li>bit[7]：表示支持的规范类型<i>0 EMV</i><i>1 ISO7816-3</i></li>
104     *            </ul>
105     *            </div> <div class="en"> the number of card channel which should be initialized
106     *            <ul>
107     *            <li>bit[2:0] : the number of card channel <i>0:bank card channel</i> <i>2:SAM1 card channel</i>
108     *            <i>3:SAM2 card channel</i> <i>4:SAM3 card channel</i> <i>5:SAM4 card channel</i></li>
109     *            <li>bit[4:3] : Operating conditions<i>00:5V</i> <i>01:1.8V</i> <i>10:3V</i> <i>11:5V</i></li>
110     *            <li>bit[5] :Whether to support the PPS protocol<i>0:false</i><i>1:true</i></li>
111     *            <li>bit[6] :use velocity for power on reset<i>0:9600(default)</i><i>1:38400</i></li>
112     *            <li>bit[7] :Whether to support the specification type<i>0:EMV</i><i>1:ISO7816-3</i></li>
113     *            </ul>
114     *            </div>
115     * 
116     * @param isAutoResp
117     *            <div class="zh">
118     *            <ul>
119     *            <li>true:自动发送</li>
120     *            <li>false:不自动发送</li>
121     *            </ul>
122     *            </div> <div class="en">
123     *            <ul>
124     *            <li>true -- send automatically</li>
125     *            <li>false -- does not send automatically</li>
126     *            </ul>
127     *            </div>
128     * 
129     * @throws IccDevException
130     * 
131     */
132    public void autoResp(byte slot, boolean isAutoResp) throws IccDevException;
133
134    /**
135     * <div class="zh"> IC卡操作函数。该函数支持IC卡通用接口协议(T=0及T=1) </div> <div class="en"> IC card operation function. This
136     * function supports IC card universal interface protocol (T=0 and T=1). </div>
137     * 
138     * @param slot
139     *            <div class="zh"> 通道号
140     *            <ul>
141     *            <li>bit[2:0]：0~7 编号的通道号</li>
142     *            <li>bit[4:3]：表示操作条件 <i> 00：5V</i> <i> 01：1.8V</i><i> 10：3V</i><i> 11：5V</i></li>
143     *            <li>bit[5]：表示对 PPS 协议支持 <i>0 表示不支持</i><i>1 表示支持</i></li>
144     *            <li>bit[6]：表示上电复位使用速率<i>0 默认(9600)</i><i>1 38400</i></li>
145     *            <li>bit[7]：表示支持的规范类型<i>0 EMV</i><i>1 ISO7816-3</i></li>
146     *            </ul>
147     *            </div> <div class="en"> the number of card channel which should be initialized
148     *            <ul>
149     *            <li>bit[2:0] : the number of card channel <i>0:bank card channel</i> <i>2:SAM1 card channel</i>
150     *            <i>3:SAM2 card channel</i> <i>4:SAM3 card channel</i> <i>5:SAM4 card channel</i></li>
151     *            <li>bit[4:3] : Operating conditions<i>00:5V</i> <i>01:1.8V</i> <i>10:3V</i> <i>11:5V</i></li>
152     *            <li>bit[5] :Whether to support the PPS protocol<i>0:false</i><i>1:true</i></li>
153     *            <li>bit[6] :use velocity for power on reset<i>0:9600(default)</i><i>1:38400</i></li>
154     *            <li>bit[7] :Whether to support the specification type<i>0:EMV</i><i>1:ISO7816-3</i></li>
155     *            </ul>
156     *            </div>
157     * 
158     * @param apduSend
159     *            <div class="zh"> 发送的IC卡命令数据
160     *            <ul>
161     *            <li>byte Command[4];// Command[] = {CLA,INS,P1,P2}</li>
162     *            <li>short Lc;//Lc = DataIn 的长度。</li>
163     *            <li>byte DataIn[512];//DataIn = 要发送到 IC 卡的数据。</li>
164     *            <li>short Le;//Le = 期望返回数据的长度,实际返回数据长度卡片返回与具体命令有关,这里只是期望长度,实际的返回长度可由响应结构参数的 LenOut 获得。</li>
165     *            </ul>
166     *            </div> <div class="en"> -Data structure of command send to IC card.
167     *            <ul>
168     *            <li>byte Command[4]; // Command[] : {CLA,INS,P1,P2}</li>
169     *            <li>short Lc; // Lc : DataIn length.</li>
170     *            <li>byte DataIn[512]; // DataIn : Data to be sent to IC card</li>
171     *            <li>short Le; // Le : Expected length for the returns data</li>
172     *            </ul>
173     *            </div>
174     * 
175     * @return <div class="zh"> IC卡返回的命令数据{DataOut,SWA,SWB} </div> <div class="en"> data structure received from IC card. {DataOut,SWA,SWB}</div>
176     * 
177     * @throws IccDevException
178     */
179    public byte[] isoCommand(byte slot, byte[] apduSend) throws IccDevException;
180
181    /**
182     * <div class="zh"> 检查指定的卡座内是否有卡，对于0-1卡座使用到位检测。对于2-5卡座做上电复位检测 </div> <div class="en"> Check whether card is inserted
183     * in specified slot. In-place check will take place for No.0-1 slots. Power-on and resetting will take place for
184     * No. 2-5 slots. </div>
185     * 
186     * @param slot
187     *            <div class="zh"> 通道号
188     *            <ul>
189     *            <li>bit[2:0]：0~7 编号的通道号</li>
190     *            <li>bit[4:3]：表示操作条件 <i> 00：5V</i> <i> 01：1.8V</i><i> 10：3V</i><i> 11：5V</i></li>
191     *            <li>bit[5]：表示对 PPS 协议支持 <i>0 表示不支持</i><i>1 表示支持</i></li>
192     *            <li>bit[6]：表示上电复位使用速率<i>0 默认(9600)</i><i>1 38400</i></li>
193     *            <li>bit[7]：表示支持的规范类型<i>0 EMV</i><i>1 ISO7816-3</i></li>
194     *            </ul>
195     *            </div> <div class="en"> the number of card channel which should be initialized
196     *            <ul>
197     *            <li>bit[2:0] : the number of card channel <i>0:bank card channel</i> <i>2:SAM1 card channel</i>
198     *            <i>3:SAM2 card channel</i> <i>4:SAM3 card channel</i> <i>5:SAM4 card channel</i></li>
199     *            <li>bit[4:3] : Operating conditions<i>00:5V</i> <i>01:1.8V</i> <i>10:3V</i> <i>11:5V</i></li>
200     *            <li>bit[5] :Whether to support the PPS protocol<i>0:false</i><i>1:true</i></li>
201     *            <li>bit[6] :use velocity for power on reset<i>0:9600(default)</i><i>1:38400</i></li>
202     *            <li>bit[7] :Whether to support the specification type<i>0:EMV</i><i>1:ISO7816-3</i></li>
203     *            </ul>
204     *            </div>
205     * 
206     * @return <div class="zh">
207     *         <ul>
208     *         <li>true:有卡插入</li>
209     *         <li>false:没有卡插入</li>
210     *         </ul>
211     *         </div> <div class="en">
212     *         <ul>
213     *         <li>true:Card-inserted</li>
214     *         <li>false:No card</li>
215     *         </ul>
216     *         </div>
217     * 
218     * @throws IccDevException
219     */
220    public boolean detect(byte slot) throws IccDevException;
221
222    /**
223     * <div class="zh"> IC卡插卡亮灯控制 </div> <div class="en"> Light controller of inserted IC card. </div>
224     * 
225     * @param onOff
226     *            <div class="zh">
227     *            <ul>
228     *            <li>true:亮灯</li>
229     *            <li>false:灭灯</li>
230     *            </ul>
231     *            </div> <div class="en">
232     *            <ul>
233     *            <li>true -- Light's on</li>
234     *            <li>false -- Light's off</li>
235     *            </ul>
236     *            </div>
237     * 
238     * @throws IccDevException
239     */
240    public void light(boolean onOff) throws IccDevException;
241
242    /**
243     * <div class="zh"> IC卡操作函数。该函数支持IC卡通用接口协议(T=0及T=1) </div> <div class="en"> IC card operation function. This
244     * function supports IC card universal interface protocol (T=0 and T=1). </div>
245     * 
246     * @param slot
247     *            <div class="zh"> 通道号
248     *            <ul>
249     *            <li>bit[2:0]：0~7 编号的通道号</li>
250     *            <li>bit[4:3]：表示操作条件 <i> 00：5V</i> <i> 01：1.8V</i><i> 10：3V</i><i> 11：5V</i></li>
251     *            <li>bit[5]：表示对 PPS 协议支持 <i>0 表示不支持</i><i>1 表示支持</i></li>
252     *            <li>bit[6]：表示上电复位使用速率<i>0 默认(9600)</i><i>1 38400</i></li>
253     *            <li>bit[7]：表示支持的规范类型<i>0 EMV</i><i>1 ISO7816-3</i></li>
254     *            </ul>
255     *            </div> <div class="en"> the number of card channel which should be initialized
256     *            <ul>
257     *            <li>bit[2:0] : the number of card channel <i>0:bank card channel</i> <i>2:SAM1 card channel</i>
258     *            <i>3:SAM2 card channel</i> <i>4:SAM3 card channel</i> <i>5:SAM4 card channel</i></li>
259     *            <li>bit[4:3] : Operating conditions<i>00:5V</i> <i>01:1.8V</i> <i>10:3V</i> <i>11:5V</i></li>
260     *            <li>bit[5] :Whether to support the PPS protocol<i>0:false</i><i>1:true</i></li>
261     *            <li>bit[6] :use velocity for power on reset<i>0:9600(default)</i><i>1:38400</i></li>
262     *            <li>bit[7] :Whether to support the specification type<i>0:EMV</i><i>1:ISO7816-3</i></li>
263     *            </ul>
264     *            </div>
265     * 
266     * @param apduSendInfo
267     *            <div class="zh">
268     *            <ul>
269     *            <li>command -CLA, INS, P1, P2.</li>
270     *            <li>dataIn -发送给ICC的数据</li>
271     *            <li>lc -发送的数据的长度</li>
272     *            <li>le -期望接收到的数据长度</li>
273     *            </ul>
274     *            注意：底层通过传入le的值为256的方式来表示发送给卡片的APDU le为0，而传入le为0表示APDU不包含le </div> <div class="en"> {@link ApduSendInfo} <br/>
275     *            Note: set apduSendInfo.le value to 256 to make LE 0 in the command(i.e. expect response data as much
276     *            as possible) ; setting apduSendInfo.le value to 0 means no response data expected. </div>
277     * 
278     * @return <div class="zh"> ICC返回的数据
279     *         <ul>
280     *         <li>dataOut -从ICC返回的数据</li>
281     *         <li>lenOut -返回的数据的长度</li>
282     *         <li>swA -ICC 状态1</li>
283     *         <li>swB -ICC 状态2</li>
284     *         </ul>
285     *         </div> <div class="en"> Receiving data structure of ICC, {@link ApduSendInfo} </div>
286     * 
287     * @throws IccDevException
288     */
289    public ApduRespInfo isoCommandByApdu(byte slot, ApduSendInfo apduSendInfo) throws IccDevException;
290
291    /**
292     * <div class="zh"> 获取ICardAT24Cxx </div> <div class="en"> get interface ICardAT24Cxx </div>
293     * 
294     * @since V2.00.01
295     * @return {@link com.pax.dal.memorycard.ICardAT24Cxx}
296     */
297    public ICardAT24Cxx getCardAT24Cxx();
298
299    /**
300     * <div class="zh"> 获取ICardAT88SC102 </div> <div class="en"> get interface ICardAT88SC102 </div>
301     * 
302     * @since V2.00.01
303     * @return {@link com.pax.dal.memorycard.ICardAT88SC102}
304     */
305    public ICardAT88SC102 getCardAT88SC102();
306
307    /**
308     * <div class="zh"> 获取ICardAT88SC153 </div> <div class="en"> get interface ICardAT88SC153 </div>
309     * 
310     * @since V2.00.01
311     * @return {@link com.pax.dal.memorycard.ICardAT88SC153}
312     */
313    public ICardAT88SC153 getCardAT88SC153();
314
315    /**
316     * <div class="zh"> 获取ICardSle4428 </div> <div class="en"> get interface ICardSle4428 </div>
317     * 
318     * @since V2.00.01
319     * @return {@link com.pax.dal.memorycard.ICardSle4428}
320     */
321    public ICardSle4428 getCardSle4428();
322
323    /**
324     * <div class="zh"> 获取ICardAT88SC1608 </div> <div class="en"> get interface ICardAT88SC1608 </div>
325     * 
326     * @since V2.00.01
327     * @return {@link com.pax.dal.memorycard.ICardAT88SC1608}
328     */
329    public ICardAT88SC1608 getCardAT88SC1608();
330
331    /**
332     * <div class="zh"> 获取ICardSle4442 </div> <div class="en"> get interface ICardSle4442 </div>
333     * 
334     * @since V2.00.01
335     * @return {@link com.pax.dal.memorycard.ICardSle4442}
336     */
337    public ICardSle4442 getCardSle4442();
338    
339    /**
340     * <div class="zh">读取IC读卡器参数。</div> <div class="en">Read IC card reader parameters.</div>
341     * 
342     * @param slot <div class="zh">卡通道号。</div> <div class="en"> The number of card channel.</div>
343     * 
344     * @return {@link IccPara}
345     * @since V3.10.00
346     */
347    IccPara readParam(byte slot) throws IccDevException;
348    
349    /**
350     * <div class="zh">设置IC读卡器参数。</div> <div class="en">Set IC card reader parameters.</div>
351     * 
352     * @param slot <div class="zh">卡通道号。</div> <div class="en"> The number of card channel.</div>
353     * 
354     * @param para {@link IccPara}
355     * @since V3.10.00
356     */
357    void setParam(byte slot, IccPara para) throws IccDevException;
358
359    /**
360     * <div class="zh">与卡片进行APDU数据交互，终端将dataIn中的数据直接发送给卡片，并接收卡片的应答数据。</div>
361     * <div class="en">Perform APDU data interaction with the card. The terminal sends the data in dataIn directly to the card and receives the response data from the card.</div>
362     *
363     * @param slot <div class="zh">需要复位的卡通道号。
364     *               <ul>
365     *                 <li>bit[2:0]: 0~7编号的通道号。</li>
366     *                 <li>bit[4:3]: 操作条件。
367     *                   <ul>
368     *                     <li>00: 5V</li>
369     *                     <li>01: 1.8V</li>
370     *                     <li>10: 3V</li>
371     *                     <li>11: 5V</li>
372     *                   </ul>
373     *                 </li>
374     *                 <li>bit[5]: 对 PPS 协议是否支持。
375     *                   <ul>
376     *                     <li>0: 不支持。</li>
377     *                     <li>1：支持。</li>
378     *                   </ul>
379     *                 </li>
380     *                 <li>bit[6]: 上电复位使用速率。
381     *                   <ul>
382     *                     <li>0: 默认，9600。</li>
383     *                     <li>1: 38400。</li>
384     *                   </ul>
385     *                 </li>
386     *                 <li>bit[7]: 支持的规范类型。
387     *                   <ul>
388     *                     <li>0: EMV。</li>
389     *                     <li>1: ISO7816-3。</li>
390     *                   </ul>
391     *                 </li>
392     *               </ul>
393     *             </div>
394     *             <div class="en">The channel number of the card to be reset.
395     *               <ul>
396     *                 <li>bit[2:0]: Channel number numbered 0~7.</li>
397     *                 <li>bit[4:3]: Operating conditions.
398     *                   <ul>
399     *                     <li>00: 5V</li>
400     *                     <li>01: 1.8V</li>
401     *                     <li>10: 3V</li>
402     *                     <li>11: 5V</li>
403     *                   </ul>
404     *                 </li>
405     *                 <li>bit[5]: Whether to support the PPS protocol.
406     *                   <ul>
407     *                     <li>0: Not support.</li>
408     *                     <li>1：Support.</li>
409     *                   </ul>
410     *                 </li>
411     *                 <li>bit[6]: Power-on reset usage rate.
412     *                   <ul>
413     *                     <li>0: Default, 9600.</li>
414     *                     <li>1: 38400.</li>
415     *                   </ul>
416     *                 </li>
417     *                 <li>bit[7]: Supported specification types.
418     *                   <ul>
419     *                     <li>0: EMV.</li>
420     *                     <li>1: ISO7816-3.</li>
421     *                   </ul>
422     *                 </li>
423     *               </ul>
424     *             </div>
425     * @param dataIn <div class="zh">待发送的命令数据。</div> <div class="en">The command data to be sent.</div>
426     * @return <div class="zh">接收到的卡片数据。</div> <div class="en">Data received from the card.</div>
427     * @throws IccDevException IccDevException
428     * @since V3.25.00
429     */
430    byte[] cmdExchange(byte slot, byte[] dataIn) throws IccDevException;
431
432    /**
433     * <div class="zh">锁IC卡</div>
434     * <div class="en">Lock IC card</div>
435     *
436     */
437    void iccLockCard() throws IccDevException;
438
439    /**
440     * <div class="zh">解锁IC卡</div>
441     * <div class="en">Unlock IC card</div>
442     *
443     */
444    void iccUnlockCard() throws IccDevException;
445
446    /**
447     * <div class="zh">开启/关闭自动锁IC卡功能</div>
448     * <div class="en">Enable/Disable the automatic IC card lock function</div>
449     *
450     * @param enable <div class="zh">true: 开启, flase: 关闭</div>
451     *               <div class="en">true: Enable, flase: Disable</div>
452     */
453    void iccEnableAutoLockCard(boolean enable) throws IccDevException;
454
455    /**
456     * <div class="zh">判断IC卡是否锁住</div>
457     * <div class="en">Determine whether the IC card is locked</div>
458     *
459     * @return <div class="zh">true: 已锁, flase: 未锁</div>
460     *          <div class="en">true: Lock, flase: Unlock</div>
461     */
462    boolean iccIsCardLocked() throws IccDevException;
463
464}