1 /* 2 * Copyright (C) 2024 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 package android.nfc; 17 18 import android.annotation.FlaggedApi; 19 import android.annotation.IntDef; 20 import android.annotation.IntRange; 21 import android.annotation.NonNull; 22 import android.annotation.Nullable; 23 import android.annotation.RequiresPermission; 24 import android.annotation.SystemApi; 25 import android.annotation.WorkerThread; 26 27 import java.lang.annotation.Retention; 28 import java.lang.annotation.RetentionPolicy; 29 30 /** 31 * This class is used for performing T4T (Type-4 Tag) NDEF (NFC Data Exchange Format) 32 * NFCEE (NFC Execution Environment) operations. 33 * This can be used to write NDEF data to emulate a T4T tag in an NFCEE 34 * (NFC Execution Environment - eSE, SIM, etc). Refer to the NFC forum specification 35 * "NFCForum-TS-NCI-2.3 section 10.4" and "NFCForum-TS-T4T-1.1 section 4.2" for more details. 36 * @hide 37 */ 38 @FlaggedApi(Flags.FLAG_NFC_OEM_EXTENSION) 39 @SystemApi 40 public final class T4tNdefNfcee { 41 private static final String TAG = "NdefNfcee"; 42 static T4tNdefNfcee sNdefNfcee; 43 T4tNdefNfcee()44 private T4tNdefNfcee() { 45 } 46 47 /** 48 * Helper to get an instance of this class. 49 * 50 * @return 51 * @hide 52 */ 53 @NonNull getInstance()54 public static T4tNdefNfcee getInstance() { 55 if (sNdefNfcee == null) { 56 sNdefNfcee = new T4tNdefNfcee(); 57 } 58 return sNdefNfcee; 59 } 60 61 /** 62 * Return flag for {@link #writeData(int, byte[])}. 63 * It indicates write data is successful. 64 */ 65 public static final int WRITE_DATA_SUCCESS = 0; 66 /** 67 * Return flag for {@link #writeData(int, byte[])}. 68 * It indicates write data fail due to unknown reasons. 69 */ 70 public static final int WRITE_DATA_ERROR_INTERNAL = -1; 71 /** 72 * Return flag for {@link #writeData(int, byte[])}. 73 * It indicates write data fail due to ongoing rf activity. 74 */ 75 public static final int WRITE_DATA_ERROR_RF_ACTIVATED = -2; 76 /** 77 * Return flag for {@link #writeData(int, byte[])}. 78 * It indicates write data fail due to Nfc off. 79 */ 80 public static final int WRITE_DATA_ERROR_NFC_NOT_ON = -3; 81 /** 82 * Return flag for {@link #writeData(int, byte[])}. 83 * It indicates write data fail due to invalid file id. 84 */ 85 public static final int WRITE_DATA_ERROR_INVALID_FILE_ID = -4; 86 /** 87 * Return flag for {@link #writeData(int, byte[])}. 88 * It indicates write data fail due to invalid length. 89 */ 90 public static final int WRITE_DATA_ERROR_INVALID_LENGTH = -5; 91 /** 92 * Return flag for {@link #writeData(int, byte[])}. 93 * It indicates write data fail due to core connection create failure. 94 */ 95 public static final int WRITE_DATA_ERROR_CONNECTION_FAILED = -6; 96 /** 97 * Return flag for {@link #writeData(int, byte[])}. 98 * It indicates write data fail due to empty payload. 99 */ 100 public static final int WRITE_DATA_ERROR_EMPTY_PAYLOAD = -7; 101 /** 102 * Returns flag for {@link #writeData(int, byte[])}. 103 * It indicates write data fail due to invalid ndef format. 104 */ 105 public static final int WRITE_DATA_ERROR_NDEF_VALIDATION_FAILED = -8; 106 /** 107 * Returns flag for {@link #writeData(int, byte[])}. 108 * It indicates write data fail if a concurrent NDEF NFCEE operation is ongoing. 109 */ 110 public static final int WRITE_DATA_ERROR_DEVICE_BUSY = -9; 111 112 /** 113 * Possible return values for {@link #writeData(int, byte[])}. 114 * 115 * @hide 116 */ 117 @IntDef(prefix = { "WRITE_DATA_" }, value = { 118 WRITE_DATA_SUCCESS, 119 WRITE_DATA_ERROR_INTERNAL, 120 WRITE_DATA_ERROR_RF_ACTIVATED, 121 WRITE_DATA_ERROR_NFC_NOT_ON, 122 WRITE_DATA_ERROR_INVALID_FILE_ID, 123 WRITE_DATA_ERROR_INVALID_LENGTH, 124 WRITE_DATA_ERROR_CONNECTION_FAILED, 125 WRITE_DATA_ERROR_EMPTY_PAYLOAD, 126 WRITE_DATA_ERROR_NDEF_VALIDATION_FAILED, 127 WRITE_DATA_ERROR_DEVICE_BUSY, 128 }) 129 @Retention(RetentionPolicy.SOURCE) 130 public @interface WriteDataStatus{} 131 132 /** 133 * This API performs writes of T4T data to NFCEE. 134 * 135 * <p>This is an I/O operation and will block until complete. It must 136 * not be called from the main application thread.</p> 137 * <p>Applications must send complete Ndef Message payload, do not need to fragment 138 * the payload, it will be automatically fragmented and defragmented by 139 * {@link #writeData} if it exceeds max message length limits</p> 140 * 141 * @param fileId File id (Refer NFC Forum Type 4 Tag Specification 142 * Section 4.2 File Identifiers and Access Conditions 143 * for more information) to which to write. 144 * @param data This should be valid Ndef Message format. 145 * Refer to Nfc forum NDEF specification NDEF Message section 146 * @return status of the operation. 147 * @hide 148 */ 149 @SystemApi 150 @WorkerThread 151 @RequiresPermission(android.Manifest.permission.WRITE_SECURE_SETTINGS) writeData(@ntRangefrom = 0, to = 65535) int fileId, @NonNull byte[] data)152 public @WriteDataStatus int writeData(@IntRange(from = 0, to = 65535) int fileId, 153 @NonNull byte[] data) { 154 return NfcAdapter.callServiceReturn(() -> 155 NfcAdapter.getNdefNfceeService().writeData(fileId, data), WRITE_DATA_ERROR_INTERNAL); 156 } 157 158 /** 159 * This API performs reading of T4T content of Nfcee. 160 * 161 * <p>This is an I/O operation and will block until complete. It must 162 * not be called from the main application thread.</p> 163 * 164 * @param fileId File Id (Refer 165 * Section 4.2 File Identifiers and Access Conditions 166 * for more information) from which to read. 167 * @return - Returns complete Ndef message if success 168 * Refer to Nfc forum NDEF specification NDEF Message section 169 * @throws IllegalStateException if read fails because the fileId is invalid 170 * or if a concurrent operation is in progress. 171 * @hide 172 */ 173 @SystemApi 174 @WorkerThread 175 @NonNull 176 @RequiresPermission(android.Manifest.permission.WRITE_SECURE_SETTINGS) readData(@ntRangefrom = 0, to = 65535) int fileId)177 public byte[] readData(@IntRange(from = 0, to = 65535) int fileId) { 178 return NfcAdapter.callServiceReturn(() -> 179 NfcAdapter.getNdefNfceeService().readData(fileId), null); 180 } 181 182 /** 183 * Return flag for {@link #clearNdefData()}. 184 * It indicates clear data is successful. 185 */ 186 public static final int CLEAR_DATA_SUCCESS = 1; 187 /** 188 * Return flag for {@link #clearNdefData()}. 189 * It indicates clear data failed due to internal error while processing the clear. 190 */ 191 public static final int CLEAR_DATA_FAILED_INTERNAL = 0; 192 /** 193 * Return flag for {@link #clearNdefData()}. 194 * It indicates clear data failed if a concurrent NDEF NFCEE operation is ongoing. 195 */ 196 public static final int CLEAR_DATA_FAILED_DEVICE_BUSY = -1; 197 198 199 /** 200 * Possible return values for {@link #clearNdefData()}. 201 * 202 * @hide 203 */ 204 @IntDef(prefix = { "CLEAR_DATA_" }, value = { 205 CLEAR_DATA_SUCCESS, 206 CLEAR_DATA_FAILED_INTERNAL, 207 CLEAR_DATA_FAILED_DEVICE_BUSY, 208 }) 209 @Retention(RetentionPolicy.SOURCE) 210 public @interface ClearDataStatus{} 211 212 /** 213 * This API will set all the T4T NDEF NFCEE data to zero. 214 * 215 * <p>This is an I/O operation and will block until complete. It must 216 * not be called from the main application thread. 217 * 218 * <p>This API can be called regardless of NDEF file lock state. 219 * </p> 220 * @return status of the operation 221 * 222 * @hide 223 */ 224 @SystemApi 225 @WorkerThread 226 @RequiresPermission(android.Manifest.permission.WRITE_SECURE_SETTINGS) clearData()227 public @ClearDataStatus int clearData() { 228 return NfcAdapter.callServiceReturn(() -> 229 NfcAdapter.getNdefNfceeService().clearNdefData(), CLEAR_DATA_FAILED_INTERNAL); 230 } 231 232 /** 233 * Returns whether NDEF NFCEE operation is ongoing or not. 234 * 235 * @return true if NDEF NFCEE operation is ongoing, else false. 236 * @hide 237 */ 238 @SystemApi 239 @RequiresPermission(android.Manifest.permission.WRITE_SECURE_SETTINGS) isOperationOngoing()240 public boolean isOperationOngoing() { 241 return NfcAdapter.callServiceReturn(() -> 242 NfcAdapter.getNdefNfceeService().isNdefOperationOngoing(), false); 243 } 244 245 /** 246 * This Api is to check the status of NDEF NFCEE emulation feature is 247 * supported or not. 248 * 249 * @return true if NDEF NFCEE emulation feature is supported, else false. 250 * @hide 251 */ 252 @SystemApi 253 @RequiresPermission(android.Manifest.permission.WRITE_SECURE_SETTINGS) isSupported()254 public boolean isSupported() { 255 return NfcAdapter.callServiceReturn(() -> 256 NfcAdapter.getNdefNfceeService().isNdefNfceeEmulationSupported(), false); 257 } 258 259 /** 260 * This API performs reading of T4T NDEF NFCEE CC file content. 261 * 262 * Refer to the NFC forum specification "NFCForum-TS-T4T-1.1 section 4.4" for more details. 263 * 264 * @return Returns CC file content if success or null if failed to read. 265 * @throws IllegalStateException if the device is busy. 266 * @hide 267 */ 268 @SystemApi 269 @WorkerThread 270 @RequiresPermission(android.Manifest.permission.WRITE_SECURE_SETTINGS) 271 @Nullable readCcfile()272 public T4tNdefNfceeCcFileInfo readCcfile() { 273 return NfcAdapter.callServiceReturn(() -> 274 NfcAdapter.getNdefNfceeService().readCcfile(), null); 275 } 276 } 277