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 */ 15 16/** 17 * @file 18 * @kit ConnectivityKit 19 */ 20 21import tag from '../@ohos.nfc.tag'; 22import { AsyncCallback } from '../@ohos.base'; 23 24/** 25 * Controls tag read and write. 26 * <p>Classes for different types of tags inherit from this abstract class to control connections to 27 * tags, read data from tags, and write data to tags. 28 * 29 * @typedef TagSession 30 * @syscap SystemCapability.Communication.NFC.Tag 31 * @since 7 32 */ 33/** 34 * Controls tag read and write. 35 * <p>Classes for different types of tags inherit from this abstract class to control connections to 36 * tags, read data from tags, and write data to tags. 37 * 38 * @typedef TagSession 39 * @syscap SystemCapability.Communication.NFC.Tag 40 * @atomicservice 41 * @since 12 42 */ 43export interface TagSession { 44 /** 45 * Obtains the tag information. 46 * 47 * @permission ohos.permission.NFC_TAG 48 * @returns { tag.TagInfo } Returns the tag information, which is a {@link TagInfo} object. 49 * @syscap SystemCapability.Communication.NFC.Tag 50 * @since 7 51 * @deprecated since 9 52 * @useinstead ohos.nfc.tag/tag#getTagInfo 53 */ 54 getTagInfo(): tag.TagInfo; 55 56 /** 57 * Connects to a tag. 58 * <p>This method must be called before data is read from or written to the tag. 59 * 60 * @permission ohos.permission.NFC_TAG 61 * @returns { boolean } Returns {@code true} if the connection is set up; returns {@code false} otherwise. 62 * @syscap SystemCapability.Communication.NFC.Tag 63 * @since 7 64 * @deprecated since 9 65 * @useinstead tagSession.TagSession#connect 66 */ 67 connectTag(): boolean; 68 69 /** 70 * Connects to a tag. Must be called before data is read from or written to the tag. 71 * 72 * @permission ohos.permission.NFC_TAG 73 * @throws { BusinessError } 201 - Permission denied. 74 * @throws { BusinessError } 801 - Capability not supported. 75 * @throws { BusinessError } 3100201 - Tag running state is abnormal in service. 76 * @syscap SystemCapability.Communication.NFC.Tag 77 * @since 9 78 */ 79 /** 80 * Connects to a tag. Must be called before data is read from or written to the tag. 81 * 82 * @permission ohos.permission.NFC_TAG 83 * @throws { BusinessError } 201 - Permission denied. 84 * @throws { BusinessError } 801 - Capability not supported. 85 * @throws { BusinessError } 3100201 - The tag running state is abnormal in the service. 86 * @syscap SystemCapability.Communication.NFC.Tag 87 * @atomicservice 88 * @since 12 89 */ 90 connect(): void; 91 92 /** 93 * Resets a connection with a tag and restores the default timeout duration for writing data to the tag. 94 * 95 * @permission ohos.permission.NFC_TAG 96 * @syscap SystemCapability.Communication.NFC.Tag 97 * @since 7 98 * @deprecated since 9 99 * @useinstead tagSession.TagSession#resetConnection 100 */ 101 reset(): void; 102 103 /** 104 * Resets a connection with a tag and restores the default timeout duration for writing data to the tag. 105 * 106 * @permission ohos.permission.NFC_TAG 107 * @throws { BusinessError } 201 - Permission denied. 108 * @throws { BusinessError } 801 - Capability not supported. 109 * @throws { BusinessError } 3100201 - Tag running state is abnormal in service. 110 * @syscap SystemCapability.Communication.NFC.Tag 111 * @since 9 112 */ 113 /** 114 * Resets a connection with a tag and restores the default timeout duration for writing data to the tag. 115 * 116 * @permission ohos.permission.NFC_TAG 117 * @throws { BusinessError } 201 - Permission denied. 118 * @throws { BusinessError } 801 - Capability not supported. 119 * @throws { BusinessError } 3100201 - The tag running state is abnormal in the service. 120 * @syscap SystemCapability.Communication.NFC.Tag 121 * @atomicservice 122 * @since 12 123 */ 124 resetConnection(): void; 125 126 /** 127 * Checks whether a connection has been set up with a tag. 128 * 129 * @returns { boolean } Returns {@code true} if a connection has been set up with the tag; 130 * returns {@code false} otherwise. 131 * @syscap SystemCapability.Communication.NFC.Tag 132 * @since 7 133 * @deprecated since 9 134 * @useinstead tagSession.TagSession#isConnected 135 */ 136 isTagConnected(): boolean; 137 138 /** 139 * Checks whether a connection has been set up with a tag. 140 * 141 * @returns { boolean } Returns true if tag connected, otherwise false. 142 * @throws { BusinessError } 801 - Capability not supported. 143 * @syscap SystemCapability.Communication.NFC.Tag 144 * @since 9 145 */ 146 /** 147 * Checks whether a connection has been set up with a tag. 148 * 149 * @returns { boolean } Returns true if tag connected, otherwise false. 150 * @throws { BusinessError } 801 - Capability not supported. 151 * @syscap SystemCapability.Communication.NFC.Tag 152 * @atomicservice 153 * @since 12 154 */ 155 isConnected(): boolean; 156 157 /** 158 * Sets the timeout duration (ms) for sending data to a tag. 159 * <p>If data is not sent to the tag within the duration, data sending fails. 160 * 161 * @permission ohos.permission.NFC_TAG 162 * @param { number } timeout Indicates the timeout duration to be set. 163 * @returns { boolean } Returns {@code true} if the setting is successful; returns {@code false} otherwise. 164 * @syscap SystemCapability.Communication.NFC.Tag 165 * @since 7 166 * @deprecated since 9 167 * @useinstead tagSession.TagSession#setTimeout 168 */ 169 setSendDataTimeout(timeout: number): boolean; 170 171 /** 172 * Sets the timeout duration (ms) for sending data to a tag. 173 * 174 * @permission ohos.permission.NFC_TAG 175 * @param { number } timeout Indicates the timeout duration to be set. 176 * @throws { BusinessError } 201 - Permission denied. 177 * @throws { BusinessError } 401 - The parameter check failed. Possible causes: 178 * <br> 1. Mandatory parameters are left unspecified. 179 * <br> 2. Incorrect parameters types. 180 * <br> 3. Parameter verification failed. 181 * @throws { BusinessError } 801 - Capability not supported. 182 * @throws { BusinessError } 3100201 - Tag running state is abnormal in service. 183 * @syscap SystemCapability.Communication.NFC.Tag 184 * @since 9 185 */ 186 /** 187 * Sets the timeout duration (ms) for sending data to a tag. 188 * 189 * @permission ohos.permission.NFC_TAG 190 * @param { number } timeout Indicates the timeout duration to be set. 191 * @throws { BusinessError } 201 - Permission denied. 192 * @throws { BusinessError } 401 - The parameter check failed. Possible causes: 193 * <br> 1. Mandatory parameters are left unspecified. 194 * <br> 2. Incorrect parameters types. 195 * <br> 3. Parameter verification failed. 196 * @throws { BusinessError } 801 - Capability not supported. 197 * @throws { BusinessError } 3100201 - The tag running state is abnormal in the service. 198 * @syscap SystemCapability.Communication.NFC.Tag 199 * @atomicservice 200 * @since 12 201 */ 202 setTimeout(timeout: number): void; 203 204 /** 205 * Queries the timeout duration (ms) for sending data to a tag. 206 * 207 * @permission ohos.permission.NFC_TAG 208 * @returns { number } Returns the timeout duration. 209 * @syscap SystemCapability.Communication.NFC.Tag 210 * @since 7 211 * @deprecated since 9 212 * @useinstead tagSession.TagSession#getTimeout 213 */ 214 getSendDataTimeout(): number; 215 216 /** 217 * Obtains the timeout duration (ms) for sending data to a tag. 218 * 219 * @permission ohos.permission.NFC_TAG 220 * @returns { number } Returns the timeout duration. 221 * @throws { BusinessError } 201 - Permission denied. 222 * @throws { BusinessError } 801 - Capability not supported. 223 * @throws { BusinessError } 3100201 - Tag running state is abnormal in service. 224 * @syscap SystemCapability.Communication.NFC.Tag 225 * @since 9 226 */ 227 /** 228 * Obtains the timeout duration (ms) for sending data to a tag. 229 * 230 * @permission ohos.permission.NFC_TAG 231 * @returns { number } Returns the timeout duration. 232 * @throws { BusinessError } 201 - Permission denied. 233 * @throws { BusinessError } 801 - Capability not supported. 234 * @throws { BusinessError } 3100201 - The tag running state is abnormal in the service. 235 * @syscap SystemCapability.Communication.NFC.Tag 236 * @atomicservice 237 * @since 12 238 */ 239 getTimeout(): number; 240 241 /** 242 * Writes data to a tag. 243 * 244 * @permission ohos.permission.NFC_TAG 245 * @param { number[] } data Indicates the data to be written to the tag. 246 * @returns { Promise<number[]> } Returns bytes received in response. Or bytes with a length of 0 if the 247 * data fails to be written to the tag. 248 * @syscap SystemCapability.Communication.NFC.Tag 249 * @since 7 250 * @deprecated since 9 251 * @useinstead tagSession.TagSession#transmit 252 */ 253 sendData(data: number[]): Promise<number[]>; 254 255 /** 256 * Writes data to a tag. 257 * 258 * @permission ohos.permission.NFC_TAG 259 * @param { number[] } data Indicates the data to be written to the tag. 260 * @param { AsyncCallback<number[]> } callback The callback. 261 * data fails to be written to the tag. 262 * @syscap SystemCapability.Communication.NFC.Tag 263 * @since 7 264 * @deprecated since 9 265 * @useinstead tagSession.TagSession#transmit 266 */ 267 sendData(data: number[], callback: AsyncCallback<number[]>): void; 268 269 /** 270 * Writes data to a tag. 271 * 272 * @permission ohos.permission.NFC_TAG 273 * @param { number[] } data Indicates the data to be written to the tag. 274 * @returns { Promise<number[]> } Returns bytes received in response. Or bytes with a length of 0 if the 275 * data fails to be written to the tag. 276 * @throws { BusinessError } 201 - Permission denied. 277 * @throws { BusinessError } 401 - The parameter check failed. Possible causes: 278 * <br> 1. Mandatory parameters are left unspecified. 279 * <br> 2. Incorrect parameters types. 280 * <br> 3. Parameter verification failed. 281 * @throws { BusinessError } 801 - Capability not supported. 282 * @throws { BusinessError } 3100201 - Tag running state is abnormal in service. 283 * @syscap SystemCapability.Communication.NFC.Tag 284 * @since 9 285 */ 286 /** 287 * Writes data to a tag. 288 * 289 * @permission ohos.permission.NFC_TAG 290 * @param { number[] } data Indicates the data to be written to the tag. 291 * @returns { Promise<number[]> } Returns bytes received in response. Or bytes with a length of 0 if the 292 * data fails to be written to the tag. 293 * @throws { BusinessError } 201 - Permission denied. 294 * @throws { BusinessError } 401 - The parameter check failed. Possible causes: 295 * <br> 1. Mandatory parameters are left unspecified. 296 * <br> 2. Incorrect parameters types. 297 * <br> 3. Parameter verification failed. 298 * @throws { BusinessError } 801 - Capability not supported. 299 * @throws { BusinessError } 3100201 - The tag running state is abnormal in the service. 300 * @throws { BusinessError } 3100204 - The tag I/O operation failed. 301 * @syscap SystemCapability.Communication.NFC.Tag 302 * @atomicservice 303 * @since 12 304 */ 305 transmit(data: number[]): Promise<number[]>; 306 307 /** 308 * Writes data to a tag. 309 * 310 * @permission ohos.permission.NFC_TAG 311 * @param { number[] } data Indicates the data to be written to the tag. 312 * @param { AsyncCallback<number[]> } callback The callback. 313 * @throws { BusinessError } 201 - Permission denied. 314 * @throws { BusinessError } 401 - The parameter check failed. Possible causes: 315 * <br> 1. Mandatory parameters are left unspecified. 316 * <br> 2. Incorrect parameters types. 317 * <br> 3. Parameter verification failed. 318 * @throws { BusinessError } 801 - Capability not supported. 319 * @throws { BusinessError } 3100201 - Tag running state is abnormal in service. 320 * @syscap SystemCapability.Communication.NFC.Tag 321 * @since 9 322 */ 323 /** 324 * Writes data to a tag. 325 * 326 * @permission ohos.permission.NFC_TAG 327 * @param { number[] } data Indicates the data to be written to the tag. 328 * @param { AsyncCallback<number[]> } callback The callback. 329 * @throws { BusinessError } 201 - Permission denied. 330 * @throws { BusinessError } 401 - The parameter check failed. Possible causes: 331 * <br> 1. Mandatory parameters are left unspecified. 332 * <br> 2. Incorrect parameters types. 333 * <br> 3. Parameter verification failed. 334 * @throws { BusinessError } 801 - Capability not supported. 335 * @throws { BusinessError } 3100201 - The tag running state is abnormal in the service. 336 * @throws { BusinessError } 3100204 - The tag I/O operation failed. 337 * @syscap SystemCapability.Communication.NFC.Tag 338 * @atomicservice 339 * @since 12 340 */ 341 transmit(data: number[], callback: AsyncCallback<number[]>): void; 342 343 /** 344 * Queries the maximum length of data that can be sent to a tag. 345 * 346 * @permission ohos.permission.NFC_TAG 347 * @returns { number } Returns the maximum length of the data to be sent to the tag. 348 * @syscap SystemCapability.Communication.NFC.Tag 349 * @since 7 350 * @deprecated since 9 351 * @useinstead tagSession.TagSession#getMaxTransmitSize 352 */ 353 getMaxSendLength(): number; 354 355 /** 356 * Obtains the maximum length of data that can be sent to a tag. 357 * 358 * @permission ohos.permission.NFC_TAG 359 * @returns { number } Returns the maximum length of the data to be sent to the tag. 360 * @throws { BusinessError } 201 - Permission denied. 361 * @throws { BusinessError } 801 - Capability not supported. 362 * @throws { BusinessError } 3100201 - Tag running state is abnormal in service. 363 * @syscap SystemCapability.Communication.NFC.Tag 364 * @since 9 365 */ 366 /** 367 * Obtains the maximum length of data that can be sent to a tag. 368 * 369 * @permission ohos.permission.NFC_TAG 370 * @returns { number } Returns the maximum length of the data to be sent to the tag. 371 * @throws { BusinessError } 201 - Permission denied. 372 * @throws { BusinessError } 801 - Capability not supported. 373 * @throws { BusinessError } 3100201 - The tag running state is abnormal in the service. 374 * @syscap SystemCapability.Communication.NFC.Tag 375 * @atomicservice 376 * @since 12 377 */ 378 getMaxTransmitSize(): number; 379} 380