1/* 2 * Copyright (c) 2021-2022 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15import tag from '../@ohos.nfc.tag'; 16import { TagSession } from './tagSession'; 17import { AsyncCallback, Callback } from '../basic'; 18 19/** 20 * Provides interfaces to control the read and write of tags that support the NFC-A technology. 21 * 22 * <p>This class is inherited from the {@link TagSession} abstract class, and provides methods to create 23 * {@code NfcATag} objects and obtain the ATQA and SAK. 24 * 25 * @since 7 26 * @syscap SystemCapability.Communication.NFC.Tag 27 */ 28export interface NfcATag extends TagSession { 29 /** 30 * Obtains the SAK of an NFC-A tag. 31 * 32 * @returns Returns the SAK of the NFC-A tag. 33 * @since 7 34 */ 35 getSak(): number; 36 37 /** 38 * Obtains the ATQA of an NFC-A tag. 39 * 40 * @returns Returns the ATQA of the NFC-A tag. 41 * @since 7 42 */ 43 getAtqa(): number[]; 44} 45 46/** 47 * Provides interfaces to create an {@code NfcBTag} and perform I/O operations on the tag. 48 * 49 * <p>This class inherits from the {@link TagSession} abstract class and provides interfaces to create an 50 * {@code NfcBTag} and obtain the tag information. 51 * 52 * @since 7 53 * @syscap SystemCapability.Communication.NFC.Tag 54 */ 55export interface NfcBTag extends TagSession { 56 /** 57 * Obtains the application data of a tag. 58 * 59 * @returns Returns the application data of the tag. 60 * @since 7 61 */ 62 getRespAppData(): number[]; 63 64 /** 65 * Obtains the protocol information of a tag. 66 * 67 * @returns Returns the protocol information of the tag. 68 * @since 7 69 */ 70 getRespProtocol(): number[]; 71} 72 73/** 74 * Provides methods for creating an NFC-F tag, obtaining tag information, and controlling tag read and write. 75 * 76 * <p>This class inherits from the {@link TagSession} abstract class and provides interfaces to create an 77 * {@code NfcFTag} and obtain the tag information. 78 * 79 * @since 7 80 * @syscap SystemCapability.Communication.NFC.Tag 81 */ 82export interface NfcFTag extends TagSession { 83 /** 84 * Obtains the system code from this {@code NfcFTag} instance. 85 * 86 * @returns Returns the system code. 87 * @since 7 88 */ 89 getSystemCode(): number[]; 90 91 /** 92 * Obtains the PMm (consisting of the IC code and manufacturer parameters) from this {@code NfcFTag} instance. 93 * 94 * @returns Returns the PMm. 95 * @since 7 96 */ 97 getPmm(): number[]; 98} 99 100/** 101 * Provides methods for creating an NFC-V tag, obtaining tag information, and controlling tag read and write. 102 * 103 * <p>This class inherits from the {@link TagSession} abstract class and provides interfaces to create an 104 * {@code NfcVTag} and obtain the tag information. 105 * 106 * @since 7 107 * @syscap SystemCapability.Communication.NFC.Tag 108 */ 109export interface NfcVTag extends TagSession { 110 /** 111 * Obtains the response flags from this {@code NfcVTag} instance. 112 * 113 * @returns Returns the response flags. 114 * @since 7 115 */ 116 getResponseFlags(): number; 117 118 /** 119 * Obtains the data storage format identifier (DSFID) from this {@code NfcVTag} instance. 120 * 121 * @returns Returns the DSFID. 122 * @since 7 123 */ 124 getDsfId(): number; 125} 126 127/** 128 * Provides methods for accessing IsoDep tag. 129 * 130 * @since 9 131 * @syscap SystemCapability.Communication.NFC.Tag 132 */ 133export interface IsoDepTag extends TagSession { 134 /** 135 * Gets IsoDep Historical bytes of the tag, which is based on NfcA RF technology. 136 * It could be null if not based on NfcA. 137 * 138 * @returns { number[] } Returns the Historical bytes, the length could be 0. 139 * @since 9 140 */ 141 getHistoricalBytes(): number[]; 142 143 /** 144 * Gets IsoDep HiLayer Response bytes of the tag, which is based on NfcB RF technology. 145 * It could be null if not based on NfcB. 146 * 147 * @returns { number[] } Returns HiLayer Response bytes, the length could be 0. 148 * @since 9 149 */ 150 getHiLayerResponse(): number[]; 151 152 /** 153 * Checks if extended apdu length supported or not. 154 * 155 * @returns { boolean } Returns true if extended apdu length supported, otherwise false. 156 * @permission ohos.permission.NFC_TAG 157 * @throws { BusinessError } 201 - Permission denied. 158 * @throws { BusinessError } 401 - The parameter check failed. 159 * @throws { BusinessError } 3100201 - Tag running state is abnormal in service. 160 * @since 9 161 */ 162 isExtendedApduSupported(): Promise<boolean>; 163 isExtendedApduSupported(callback: AsyncCallback<boolean>): void; 164} 165 166export interface NdefMessage { 167 /** 168 * Obtains all records of an NDEF message. 169 * 170 * @returns { tag.NdefRecord[] } Records the list of NDEF records. 171 * @syscap SystemCapability.Communication.NFC.Tag 172 * @since 9 173 */ 174 getNdefRecords(): tag.NdefRecord[]; 175} 176 177/** 178 * Provides methods for accessing NDEF tag. 179 * 180 * @since 9 181 * @syscap SystemCapability.Communication.NFC.Tag 182 */ 183export interface NdefTag extends TagSession { 184 /** 185 * Gets the type of NDEF tag. 186 * 187 * @returns { tag.NfcForumType } The type of NDEF tag. 188 * @since 9 189 */ 190 getNdefTagType(): tag.NfcForumType; 191 192 /** 193 * Gets the NDEF message that was read from NDEF tag when tag discovery. 194 * 195 * @returns { NdefMessage } The instance of NdefMessage. 196 * @since 9 197 */ 198 getNdefMessage(): NdefMessage; 199 200 /** 201 * Checks if NDEF tag is writable. 202 * 203 * @returns { boolean } Returns true if the tag is writable, otherwise returns false. 204 * @since 9 205 */ 206 isNdefWritable(): boolean; 207 208 /** 209 * Reads NDEF message on this tag. 210 * 211 * @returns { NdefMessage } The NDEF message in tag. 212 * @permission ohos.permission.NFC_TAG 213 * @throws { BusinessError } 201 - Permission denied. 214 * @throws { BusinessError } 401 - The parameter check failed. 215 * @throws { BusinessError } 3100201 - Tag running state is abnormal in service. 216 * @since 9 217 */ 218 readNdef(): Promise<NdefMessage>; 219 readNdef(callback: AsyncCallback<NdefMessage>): void; 220 221 /** 222 * Writes NDEF message into this tag. 223 * 224 * @param { NdefMessage } msg - The NDEF message to be written. 225 * @permission ohos.permission.NFC_TAG 226 * @throws { BusinessError } 201 - Permission denied. 227 * @throws { BusinessError } 401 - The parameter check failed. 228 * @throws { BusinessError } 3100201 - Tag running state is abnormal in service. 229 * @since 9 230 */ 231 writeNdef(msg: NdefMessage): Promise<void>; 232 writeNdef(msg: NdefMessage, callback: AsyncCallback<void>): void; 233 234 /** 235 * Checks NDEF tag can be set read-only. 236 * 237 * @returns { boolean } Returns true if the tag can be set readonly, otherwise returns false. 238 * @permission ohos.permission.NFC_TAG 239 * @throws { BusinessError } 201 - Permission denied. 240 * @throws { BusinessError } 3100201 - Tag running state is abnormal in service. 241 * @since 9 242 */ 243 canSetReadOnly(): boolean; 244 245 /** 246 * Sets the NDEF tag read-only. 247 * 248 * @permission ohos.permission.NFC_TAG 249 * @throws { BusinessError } 201 - Permission denied. 250 * @throws { BusinessError } 401 - The parameter check failed. 251 * @throws { BusinessError } 3100201 - Tag running state is abnormal in service. 252 * @since 9 253 */ 254 setReadOnly(): Promise<void>; 255 setReadOnly(callback: AsyncCallback<void>): void; 256 257 /** 258 * Converts the NFC forum type into string defined in NFC forum. 259 * 260 * @param { tag.NfcForumType } type - NFC forum type of NDEF tag. 261 * @returns { string } The NFC forum string type. 262 * @throws { BusinessError } 401 - The parameter check failed. 263 * @since 9 264 */ 265 getNdefTagTypeString(type: tag.NfcForumType): string; 266} 267 268/** 269 * Provides methods for accessing MifareClassic tag. 270 * 271 * @since 9 272 * @syscap SystemCapability.Communication.NFC.Tag 273 */ 274export interface MifareClassicTag extends TagSession { 275 /** 276 * Authenticates a sector with the key.Only successful authentication sector can be operated. 277 * 278 * @param { number } sectorIndex - Index of sector to authenticate. 279 * @param { number[] } key - The key(6-bytes) to authenticate. 280 * @param { boolean } isKeyA - KeyA flag. true means KeyA, otherwise KeyB. 281 * @permission ohos.permission.NFC_TAG 282 * @throws { BusinessError } 201 - Permission denied. 283 * @throws { BusinessError } 401 - The parameter check failed. 284 * @throws { BusinessError } 3100201 - Tag running state is abnormal in service. 285 * @since 9 286 */ 287 authenticateSector(sectorIndex: number, key: number[], isKeyA: boolean): Promise<void>; 288 authenticateSector(sectorIndex: number, key: number[], isKeyA: boolean, callback: AsyncCallback<void>): void; 289 290 /** 291 * Reads a block, one block size is 16 bytes. 292 * 293 * @param { number } blockIndex - The index of block to read. 294 * @returns { number[] } Returns the block data. 295 * @permission ohos.permission.NFC_TAG 296 * @throws { BusinessError } 201 - Permission denied. 297 * @throws { BusinessError } 401 - The parameter check failed. 298 * @throws { BusinessError } 3100201 - Tag running state is abnormal in service. 299 * @since 9 300 */ 301 readSingleBlock(blockIndex: number): Promise<number[]>; 302 readSingleBlock(blockIndex: number, callback: AsyncCallback<number[]>): void; 303 304 /** 305 * Writes a block, one block size is 16 bytes. 306 * 307 * @param { number } blockIndex - The index of block to write. 308 * @param { number } data - The block data to write. 309 * @permission ohos.permission.NFC_TAG 310 * @throws { BusinessError } 201 - Permission denied. 311 * @throws { BusinessError } 401 - The parameter check failed. 312 * @throws { BusinessError } 3100201 - Tag running state is abnormal in service. 313 * @since 9 314 */ 315 writeSingleBlock(blockIndex: number, data: number[]): Promise<void>; 316 writeSingleBlock(blockIndex: number, data: number[], callback: AsyncCallback<void>): void; 317 318 /** 319 * Increments the contents of a block, and stores the result in the internal transfer buffer. 320 * 321 * @param { number } blockIndex - The index of block to increment. 322 * @param { number } value - The value to increment, none-negative. 323 * @permission ohos.permission.NFC_TAG 324 * @throws { BusinessError } 201 - Permission denied. 325 * @throws { BusinessError } 401 - The parameter check failed. 326 * @throws { BusinessError } 3100201 - Tag running state is abnormal in service. 327 * @since 9 328 */ 329 incrementBlock(blockIndex: number, value: number): Promise<void>; 330 incrementBlock(blockIndex: number, value: number, callback: AsyncCallback<void>): void; 331 332 /** 333 * Decreases the contents of a block, and stores the result in the internal transfer buffer. 334 * 335 * @param { number } blockIndex - The index of block to decrease. 336 * @param { number } value - The value to decrease, none-negative. 337 * @permission ohos.permission.NFC_TAG 338 * @throws { BusinessError } 201 - Permission denied. 339 * @throws { BusinessError } 401 - The parameter check failed. 340 * @throws { BusinessError } 3100201 - Tag running state is abnormal in service. 341 * @since 9 342 */ 343 decrementBlock(blockIndex: number, value: number): Promise<void>; 344 decrementBlock(blockIndex: number, value: number, callback: AsyncCallback<void>): void; 345 346 /** 347 * Writes the contents of the internal transfer buffer to a value block. 348 * 349 * @param { number } blockIndex - The index of value block to be written. 350 * @permission ohos.permission.NFC_TAG 351 * @throws { BusinessError } 201 - Permission denied. 352 * @throws { BusinessError } 401 - The parameter check failed. 353 * @throws { BusinessError } 3100201 - Tag running state is abnormal in service. 354 * @since 9 355 */ 356 transferToBlock(blockIndex: number): Promise<void>; 357 transferToBlock(blockIndex: number, callback: AsyncCallback<void>): void; 358 359 /** 360 * Moves the contents of a block into the internal transfer buffer. 361 * 362 * @param { number } blockIndex - The index of value block to be moved from. 363 * @permission ohos.permission.NFC_TAG 364 * @throws { BusinessError } 201 - Permission denied. 365 * @throws { BusinessError } 401 - The parameter check failed. 366 * @throws { BusinessError } 3100201 - Tag running state is abnormal in service. 367 * @since 9 368 */ 369 restoreFromBlock(blockIndex: number): Promise<void>; 370 restoreFromBlock(blockIndex: number, callback: AsyncCallback<void>): void; 371 372 /** 373 * Gets the number of sectors in MifareClassic tag. 374 * 375 * @returns { number } Returns the number of sectors. 376 * @since 9 377 */ 378 getSectorCount(): number; 379 380 /** 381 * Gets the number of blocks in the sector. 382 * 383 * @param { number } sectorIndex - The index of sector. 384 * @returns { number } Returns the number of blocks. 385 * @throws { BusinessError } 401 - The parameter check failed. 386 * @since 9 387 */ 388 getBlockCountInSector(sectorIndex: number): number; 389 390 /** 391 * Gets the type of the MifareClassic tag. 392 * 393 * @returns { tag.MifareClassicType } Returns type of MifareClassic tag. 394 * @since 9 395 */ 396 getType(): tag.MifareClassicType; 397 398 /** 399 * Gets size of the tag in bytes. 400 * 401 * @returns { number } Returns the size of the tag. 402 * @since 9 403 */ 404 getTagSize(): number; 405 406 /** 407 * Checks if the tag is emulated or not. 408 * 409 * @returns { boolean } Returns true if tag is emulated, otherwise false. 410 * @since 9 411 */ 412 isEmulatedTag(): boolean; 413 414 /** 415 * Gets the first block of the specific sector. 416 * 417 * @param { number } sectorIndex - The index of sector. 418 * @returns { number } Returns index of first block in the sector. 419 * @throws { BusinessError } 401 - The parameter check failed. 420 * @since 9 421 */ 422 getBlockIndex(sectorIndex: number): number; 423 424 /** 425 * Gets the sector index, that the sector contains the specific block. 426 * 427 * @param { number } blockIndex - The index of block. 428 * @returns { number } Returns the sector index. 429 * @throws { BusinessError } 401 - The parameter check failed. 430 * @since 9 431 */ 432 getSectorIndex(blockIndex: number): number; 433} 434 435/** 436 * Provides methods for accessing MifareUltralight tag. 437 * 438 * @since 9 439 * @syscap SystemCapability.Communication.NFC.Tag 440 */ 441export interface MifareUltralightTag extends TagSession { 442 /** 443 * Reads 4 pages, total is 16 bytes. Page size is 4 bytes. 444 * 445 * @param { number } pageIndex - The index of page to read. 446 * @returns { number[] } Returns 4 pages data. 447 * @permission ohos.permission.NFC_TAG 448 * @throws { BusinessError } 201 - Permission denied. 449 * @throws { BusinessError } 401 - The parameter check failed. 450 * @throws { BusinessError } 3100201 - Tag running state is abnormal in service. 451 * @since 9 452 */ 453 readMultiplePages(pageIndex: number): Promise<number[]>; 454 readMultiplePages(pageIndex: number, callback: AsyncCallback<number[]>): void; 455 456 /** 457 * Writes a page, total 4 bytes. 458 * 459 * @param { number } pageIndex - The index of page to write. 460 * @param { number[] } data - The page data to write. 461 * @permission ohos.permission.NFC_TAG 462 * @throws { BusinessError } 201 - Permission denied. 463 * @throws { BusinessError } 401 - The parameter check failed. 464 * @throws { BusinessError } 3100201 - Tag running state is abnormal in service. 465 * @since 9 466 */ 467 writeSinglePage(pageIndex: number, data: number[]): Promise<void>; 468 writeSinglePage(pageIndex: number, data: number[], callback: AsyncCallback<void>): void; 469 470 /** 471 * Gets the type of the MifareUltralight tag. 472 * 473 * @returns { tag.MifareUltralightType } Returns the type of MifareUltralight tag. 474 * @since 9 475 */ 476 getType(): tag.MifareUltralightType; 477} 478 479/** 480 * Provides methods for accessing NdefFormatable tag. 481 * 482 * @since 9 483 * @syscap SystemCapability.Communication.NFC.Tag 484 */ 485export interface NdefFormatableTag extends TagSession { 486 /** 487 * Formats a tag as NDEF tag, writes NDEF message into the NDEF Tag. 488 * 489 * @param { NdefMessage } message - NDEF message to write while format. It can be null, then only format the tag. 490 * @permission ohos.permission.NFC_TAG 491 * @throws { BusinessError } 201 - Permission denied. 492 * @throws { BusinessError } 401 - The parameter check failed. 493 * @throws { BusinessError } 3100201 - Tag running state is abnormal in service. 494 * @since 9 495 */ 496 format(message: NdefMessage): Promise<void>; 497 format(message: NdefMessage, callback: AsyncCallback<void>): void; 498 499 /** 500 * Formats a tag as NDEF tag, writes NDEF message into the NDEF Tag, then sets the tag readonly. 501 * 502 * @param { NdefMessage } message - NDEF message to write while format. It can be null, then only format the tag. 503 * @permission ohos.permission.NFC_TAG 504 * @throws { BusinessError } 201 - Permission denied. 505 * @throws { BusinessError } 401 - The parameter check failed. 506 * @throws { BusinessError } 3100201 - Tag running state is abnormal in service. 507 * @since 9 508 */ 509 formatReadOnly(message: NdefMessage): Promise<void>; 510 formatReadOnly(message: NdefMessage, callback: AsyncCallback<void>): void; 511}