Registros de texto NDEF: UTF-8 vs UTF-16 e códigos de idioma
O primeiro byte de um registro de texto NDEF indica se o texto está em UTF-8 ou UTF-16 e qual é o tamanho do código de idioma. Veja o layout, com exemplos em hexadecimal e um jeito rápido de verificar uma tag.
Um registro de texto NDEF armazena o texto em UTF-8 ou em UTF-16, e o primeiríssimo byte do payload diz qual dos dois. Esse mesmo byte também guarda o tamanho do código de idioma que vem a seguir. Se uma tag aparece com caracteres estranhos em um celular e normal em outro, é nesse primeiro byte que você deve olhar.
O layout do payload: byte de status, idioma, texto
Um registro de texto é um registro Well Known com o tipo T. O Android chama esse tipo de RTD_TEXT e o usa com TNF_WELL_KNOWN, como mostra o código de exemplo do guia básico de NFC do Android. O payload tem três partes, nesta ordem:
- Um byte de status.
- O código de idioma, em bytes US-ASCII.
- O texto em si, na codificação indicada pelo byte de status.
Pegue a palavra "Hello" em inglês, em UTF-8. O payload começa com 02 65 6E, que é o byte de status seguido das letras ASCII "en", e depois vêm os bytes do texto 48 65 6C 6C 6F. Não há mais nada entre as partes. Não existe terminador depois do código de idioma nem campo de tamanho para o texto, porque o próprio tamanho do payload do registro já cobre isso.
O byte de status: bit 7 e o tamanho do idioma
O exemplo do Android monta o byte de status somando um flag de UTF ao tamanho do idioma. O flag é 0 para UTF-8 e 1 << 7 para UTF-16. Em termos simples:
- Bit 7: 0 significa UTF-8, 1 significa UTF-16.
- Bit 6: reservado. O código de referência open source do ndeflib nunca o define na escrita e o ignora na leitura.
- Bits 0 a 5: o tamanho do código de idioma. O ndeflib os lê com a máscara
0x3F.
Então um registro em inglês com UTF-8 começa com 0x02. O mesmo registro em UTF-16 começa com 0x82. Com um código de idioma de duas letras, esses são os dois valores que você mais vai ver. A documentação do ndeflib diz que um registro de texto carrega "a UTF-8 or UTF-16 encoded text string" (uma string de texto codificada em UTF-8 ou UTF-16), e essas são as únicas duas codificações aceitas.
Não citamos aqui a especificação de registro de texto do próprio NFC Forum, então encare as posições dos bits acima como o que o exemplo do Android e o ndeflib fazem, e não como uma citação do padrão.
Códigos de idioma
O idioma é um identificador IANA ou ISO, como en ou de, escrito em ASCII. O decodificador do ndeflib rejeita um tamanho de idioma igual a zero e um tamanho maior que o payload, e o setter aceita de 1 a 63 caracteres. Ele não confere o código com o registro da IANA, então um erro de digitação como ne no lugar de en é gravado sem reclamar.
No Android, você pode deixar o idioma de fora. A referência de NdefRecord diz que createTextRecord usa "the language code corresponding to the current default locale" (o código de idioma correspondente à localidade padrão atual) quando você não informa nenhum. Isso é conveniente, mas uma tag gravada em um celular configurado em alemão vai indicar de mesmo que o texto esteja em inglês. Se quem lê filtra ou exibe por idioma, defina-o você mesmo.
UTF-16 e a marca de ordem de bytes
O UTF-16 armazena cada caractere em dois bytes, então é preciso saber qual byte vem primeiro. Uma marca de ordem de bytes (BOM) responde isso: FE FF para big-endian, FF FE para little-endian. Segundo o artigo da Wikipedia sobre a marca de ordem de bytes, o UTF-16 "may or may not begin with a BOM" (pode ou não começar com um BOM), e, quando não há nenhum, o Unicode manda presumir big-endian, embora o artigo acrescente que essa presunção é "widely ignored" (amplamente ignorada).
Por isso o UTF-16 é a escolha frágil para uma tag. Um software de gravação pode incluir o BOM, outro pode omiti-lo, e um leitor pode supor a outra ordem de bytes. O ndeflib, por exemplo, usa o codec UTF-16 genérico do Python, que escreve um BOM ao codificar e depende dele ao decodificar. O UTF-8 não tem nada disso: os bytes são lidos em ordem, e texto ASCII simples tem os mesmos bytes em UTF-8 e em ASCII.
Por que o Android usa UTF-8 por padrão
O método auxiliar do próprio Android, NdefRecord.createTextRecord(languageCode, text), é documentado como criador de "a new NDEF record containing UTF-8 text data" (um novo registro NDEF contendo dados de texto em UTF-8). O exemplo mais longo do guia básico de NFC permite escolher UTF-16, mas o método de uma linha não permite.
Um problema relatado com UTF-16 no iPhone
Dois desenvolvedores nos fóruns da Apple, em uma discussão chamada "coreNFC write NDEF with utf8", dizem que NFCNDEFPayload.wellKnownTypeTextPayload(string:locale:) grava em UTF-16 e que o resultado ficou ilegível em um app Android. O primeiro post é de 2019 e um segundo desenvolvedor faz a mesma pergunta em 2020. Nenhum engenheiro da Apple respondeu, e a discussão não traz solução alternativa nem mensagem de erro.
Essa discussão não nos diz o que as versões atuais do iOS fazem. Encare-a como um motivo para testar, e não como uma regra confirmada: grave uma tag com a sua ferramenta no iPhone, leia em um celular Android e olhe o primeiro byte.
Verificando o que sua tag realmente guarda
Leia o payload bruto do registro e olhe o primeiro byte. 02 seguido de 65 6E é UTF-8 com "en". 82 significa que o texto está em UTF-16, e você deve esperar um BOM logo depois do código de idioma. Se você só quer levar a mensagem para outra tag, veja como copiar a mensagem NDEF em vez de um dump bruto, e, se uma regravação falhar, verifique primeiro se a tag é somente leitura.
Um app NFC que mostra os registros brutos transforma isso em uma checagem de dez segundos. O NFCore lê e grava NDEF no iPhone e no Android. Se uma tag mostrar 82, regrave-a em UTF-8 com uma ferramenta que permita escolher a codificação.
Resumindo
Olhe o bit 7 do primeiro byte: 0 é UTF-8, 1 é UTF-16. Prefira UTF-8, defina o código de idioma de propósito e, quando uma tag for lida errado em um celular, verifique a codificação antes de culpar o chip.
Perguntas frequentes
Um registro de texto NDEF precisa ser UTF-8?
Não. O registro permite UTF-8 ou UTF-16, escolhido pelo bit 7 do byte de status. UTF-8 é a escolha mais segura, porque é o que o método auxiliar de registro de texto do próprio Android grava.
Qual o tamanho máximo do código de idioma?
O tamanho fica nos bits baixos do byte de status. O ndeflib lê seis bits, ou seja, até 63 caracteres, e rejeita zero. Na prática, códigos como en ou de têm poucos caracteres ASCII.
Por que um registro de texto seria lido normalmente em um celular e não em outro?
Uma causa comum é o bit de codificação. Um leitor que presume UTF-8, ou que trata mal a marca de ordem de bytes do UTF-16, pode mostrar caracteres sem sentido. Confira o primeiro byte do payload: 02 significa UTF-8 com idioma de duas letras, e 82 significa UTF-16.