APIs do Android 2.3

Nível da API: 9

Para desenvolvedores, a plataforma Android 2.3 (GINGERBREAD) está disponível como um componente para download do SDK do Android. A plataforma para download inclui uma biblioteca Android e uma imagem do sistema, além de um conjunto de aparências do emulador e muito mais. Para começar a desenvolver ou testar no Android 2.3, use o Android SDK Manager para fazer o download da plataforma no seu SDK.

Visão geral da API

As seções abaixo fornecem uma visão geral técnica das novidades para os desenvolvedores na versão 2.3, incluindo novos recursos e mudanças na API de framework desde a versão anterior.

VoIP baseado em SIP

A plataforma agora inclui uma pilha de protocolos SIP e uma API de framework que permite que os desenvolvedores criem aplicativos de telefonia pela Internet. Com a API, os aplicativos podem oferecer recursos de chamada de voz sem precisar gerenciar sessões, comunicação de nível de transporte ou áudio. Esses recursos são processados de forma transparente pelos serviços e API SIP da plataforma.

A API SIP está disponível no pacote android.net.sip. A classe da chave é SipManager, que os aplicativos usam para configurar e gerenciar perfis SIP, iniciar e receber chamadas de áudio. Depois que uma chamada de áudio é estabelecida, os aplicativos podem silenciar chamadas, ativar o modo de alto-falante, enviar toques DTMF e muito mais. Os aplicativos também podem usar o SipManager para criar conexões SIP genéricas.

A pilha e os serviços SIP subjacentes da plataforma estão disponíveis em dispositivos a critério do fabricante e da operadora associada. Por esse motivo, os aplicativos precisam usar o método isApiSupported() para verificar se o suporte SIP está disponível, antes de expor a funcionalidade de chamada aos usuários.

Para usar a API SIP, os aplicativos precisam solicitar a permissão do usuário declarando <uses-permission android:name="android.permission.INTERNET"> e <uses-permission android:name="android.permission.USE_SIP"> nos arquivos de manifesto.

Além disso, os desenvolvedores podem solicitar filtragem no Google Play, de modo que os aplicativos não sejam detectáveis para usuários com dispositivos que não incluam a pilha e os serviços SIP da plataforma. Para solicitar a filtragem, adicione <uses-feature android:name="android.software.sip" android:required="true"> e <uses-feature android:name="android.software.sip.voip"> ao manifesto do aplicativo.

Para ver mais informações, leia o guia do desenvolvedor para SIP.

Comunicação a curta distância (NFC)

O Android 2.3 inclui uma pilha de NFC e uma API de framework que permite aos desenvolvedores ler tags NDEF descobertas quando o usuário toca em um dispositivo compatível com NFC para marcar elementos incorporados em adesivos, pôsteres inteligentes e até mesmo outros dispositivos.

A plataforma fornece os serviços de NFC subjacentes que funcionam com o hardware do dispositivo para descobrir tags quando elas ficam dentro do alcance. Ao descobrir uma tag, a plataforma notifica os aplicativos transmitindo uma intent, anexando as mensagens NDEF da tag à intent como extras. Os aplicativos podem criar filtros de intent para reconhecer e processar tags e mensagens segmentadas. Por exemplo, depois de receber uma tag por intent, os aplicativos extraem as mensagens NDEF, as armazenam, alertam o usuário ou as processam de outras maneiras.

A API NFC está disponível no pacote android.nfc. As principais classes são:

  • NfcAdapter, que representa o hardware de NFC no dispositivo.
  • NdefMessage, que representa uma mensagem de dados NDEF, o formato padrão em que "registros" que transportam dados são transmitidos entre dispositivos e tags. Os apps podem receber essas mensagens de intents ACTION_TAG_DISCOVERED.
  • NdefRecord, entregue em um NdefMessage, que descreve o tipo de dados que está sendo compartilhado e carrega os dados em si.

A comunicação NFC depende da tecnologia sem fio no hardware do dispositivo. Portanto, o suporte para os recursos de NFC da plataforma em dispositivos específicos é determinado pelos fabricantes. Para determinar o suporte a NFC no dispositivo atual, os aplicativos podem chamar isEnabled() para consultar o NfcAdapter. No entanto, a API NFC está sempre presente, independentemente do suporte de hardware subjacente.

Para usar a API NFC, os aplicativos precisam solicitar a permissão do usuário declarando <uses-permission android:name="android.permission.NFC"> nos arquivos de manifesto.

Além disso, os desenvolvedores podem solicitar a filtragem no Google Play, de modo que os apps não sejam detectáveis para usuários com dispositivos que não têm suporte para NFC. Para solicitar a filtragem, adicione <uses-feature android:name="android.hardware.nfc" android:required="true"> ao manifesto do aplicativo.

Para ver um aplicativo de exemplo que usa a API NFC, consulte NFCDemo.

Giroscópio e outros sensores

O Android 2.3 adiciona suporte à plataforma e à API para vários novos tipos de leitura de sensores: giroscópio, vetor de rotação, aceleração linear, gravidade e barômetro. Os desenvolvedores podem usar as novas leituras do sensor para criar aplicativos que respondem com rapidez e facilidade a mudanças precisas na posição e no movimento do dispositivo. A API Sensor relata o giroscópio e outras mudanças do sensor nos aplicativos interessados, estejam eles sendo executados no framework do aplicativo ou no código nativo.

O conjunto específico de sensores de hardware disponíveis em qualquer dispositivo varia a critério do fabricante.

Os desenvolvedores podem solicitar filtragem no Google Play para que os aplicativos não sejam detectáveis para usuários com dispositivos que não oferecem um sensor de giroscópio. Para fazer isso, adicione <uses-feature android:name="android.hardware.sensor.gyroscope" android:required="true"> ao manifesto do aplicativo.

Para mais detalhes sobre a API, consulte Sensor.

Suporte a várias câmeras

Os aplicativos agora podem usar qualquer câmera disponível em um dispositivo, para captura de fotos ou vídeos. O Camera permite que os aplicativos consultem o número de câmeras disponíveis e as características exclusivas de cada uma.

  • A nova classe Camera.CameraInfo armazena as características de posicionamento de uma câmera (orientação, voltada para a frente ou para trás).
  • Os novos métodos getNumberOfCameras() e getCameraInfo() na classe Camera permitem que os aplicativos consultem as câmeras disponíveis e abram a câmera necessária.
  • O novo método get() permite que os aplicativos recuperem um CamcorderProfile de uma câmera específica.
  • O novo getJpegEncodingQualityParameter() permite que os aplicativos recebam o nível de qualidade de captura de imagem estática para uma câmera específica.

Para ver o exemplo de código a fim de acessar uma câmera frontal, consulte CameraPreview.java no aplicativo de exemplo ApiDemos.

A API Camera também adiciona:

Efeitos de áudio mixáveis

O framework de mídia da plataforma adiciona suporte a novos efeitos de áudio globais ou por faixa, incluindo realce de graves, virtualização dos fones de ouvido, equalização e reverberação.

Para ver o exemplo de código de efeitos de áudio, consulte AudioFxDemo.java (em inglês) no aplicativo ApiDemos.

A estrutura de mídia também adiciona:

  • Novo suporte para tag de altitude em metadados EXIF para arquivos JPEG. Novo método getAltitude() do método para recuperar o valor da tag de altitude EXIF.
  • O novo método setOrientationHint() permite que um aplicativo informe MediaRecorder da orientação durante a captura de vídeo.

Gerenciador de downloads

A plataforma inclui um novo serviço do sistema DownloadManager que processa downloads HTTP de longa duração. Os aplicativos podem solicitar o download de um URI para um arquivo de destino específico. O DownloadManager conduzirá o download em segundo plano, cuidando das interações HTTP e tentando fazer os downloads novamente após falhas ou entre mudanças de conectividade e reinicializações do sistema.

  • Os aplicativos podem conseguir uma instância da classe DownloadManager chamando getSystemService(String) e transmitindo DOWNLOAD_SERVICE. Os aplicativos que solicitam downloads usando essa API precisam registrar um broadcast receiver para ACTION_NOTIFICATION_CLICKED para processar corretamente quando o usuário clica em um download em execução em uma notificação ou na interface de downloads.
  • A classe DownloadManager.Request permite que um aplicativo forneça todas as informações necessárias para solicitar um novo download, como o URI da solicitação e o destino do download. Um URI de solicitação é o único parâmetro obrigatório. O destino de download padrão é um volume compartilhado em que o sistema pode excluir o arquivo se precisar liberar espaço para uso do sistema. Para armazenamento permanente de um download, especifique um destino de download no armazenamento externo. Consulte setDestinationUri(Uri).
  • A classe DownloadManager.Query fornece métodos que permitem que um aplicativo consulte e filtre downloads ativos.

Modo estrito

Para ajudar os desenvolvedores a monitorar e melhorar o desempenho dos aplicativos, a plataforma oferece um novo recurso do sistema chamado StrictMode. Quando implementado em um aplicativo, o StrictMode detecta e notifica o desenvolvedor sobre atividades acidentais de disco ou rede que podem prejudicar o desempenho do aplicativo, como atividades que ocorrem na linha de execução principal do aplicativo, em que as operações da interface são recebidas e as animações também ocorrem. Os desenvolvedores podem avaliar os problemas de uso de rede e disco gerados no StrictMode e corrigi-los, se necessário, para manter a linha de execução principal mais responsiva e impedir que as caixas de diálogo ANR sejam mostradas aos usuários.

  • StrictMode é a classe principal e é o principal ponto de integração com o sistema e a VM. Ela oferece métodos convenientes para gerenciar as políticas de linha de execução e VM que se aplicam à instância.
  • StrictMode.ThreadPolicy e StrictMode.VmPolicy mantêm as políticas que você define e aplica a instâncias de linha de execução e VM.

Para mais informações sobre como usar o StrictMode para otimizar seu aplicativo, consulte a documentação da classe e o exemplo de código em android.os.StrictMode.

Framework da interface

  • Suporte a rolagem.
    • Novo suporte à rolagem esticada em visualizações e widgets Nas visualizações, os aplicativos podem ativar/desativar a rolagem excessiva de uma determinada visualização, definir o modo de overscoll, controlar a distância de rolagem e processar os resultados.
    • Em widgets, os aplicativos podem controlar características de rolagem, como animação, springback e distância de rolagem. Para saber mais, consulte android.view.View e android.widget.OverScroller.
    • ViewConfiguration também fornece os métodos getScaledOverflingDistance() e getScaledOverscrollDistance().
    • Novos atributos overScrollMode, overScrollFooter e overScrollHeader para elementos <ListView>, para controlar o comportamento de rolagem.
  • Compatibilidade com filtragem de toque
    • Novo suporte à filtragem por toque, que permite que um aplicativo melhore a segurança das visualizações que oferecem acesso a funcionalidades confidenciais. Por exemplo, a filtragem de toque é adequada para garantir a segurança das ações do usuário, como conceder uma solicitação de permissão, fazer uma compra ou clicar em um anúncio. Para mais detalhes, consulte a documentação da classe.
    • Novo atributo filterTouchesWhenObscured para elementos de visualização, que declara se os toques serão filtrados quando a janela da visualização for obscurecida por outra janela visível. Quando definida como "true", a visualização não vai receber toques sempre que um aviso, uma caixa de diálogo ou outra janela aparecer acima da janela da visualização. Para saber mais detalhes, consulte a documentação de segurança.

    Para ver o exemplo de código para filtragem de toque, consulte SecureView.java no aplicativo de exemplo ApiDemos.

  • Gerenciamento aprimorado de eventos
    • Nova classe de base para eventos de entrada, InputEvent. A classe fornece métodos que permitem que os aplicativos determinem o significado do evento, por exemplo, a consulta do InputDevice de que o evento foi originado. KeyEvent e MotionEvent são subclasses de InputEvent.
    • Nova classe de base para dispositivos de entrada, InputDevice. A classe armazena informações sobre os recursos de determinado dispositivo de entrada e fornece métodos que permitem que os aplicativos determinem como interpretar eventos de um dispositivo de entrada.
  • Melhorias nos eventos de movimento.
    • A API MotionEvent foi estendida para incluir informações do "ID de ponteiro", que permitem aos aplicativos monitorar dedos individuais à medida que eles se movem para cima e para baixo. Essa classe adiciona vários métodos que permitem que um aplicativo funcione de maneira eficiente com eventos de movimento.
    • O sistema de entrada agora tem lógica para gerar eventos de movimento com as novas informações do ID de ponteiro, sintetizando identificadores à medida que novos ponteiros são desativados. O sistema rastreia vários IDs de ponteiro separadamente durante um evento de movimento e garante a continuidade adequada dos ponteiros avaliando a distância entre o último e o próximo conjunto de ponteiros.
  • Controles de seleção de texto
    • Um novo método setComposingRegion permite que um aplicativo marque uma região de texto como texto de composição, mantendo o estilo atual. Um método getSelectedText retorna o texto selecionado para o aplicativo. Os métodos estão disponíveis em BaseInputConnection, InputConnection e InputConnectionWrapper.
    • Novos atributos textSelectHandle, textSelectHandleLeft, textSelectHandleRight e textSelectHandleWindowStyle para <TextView>, para referenciar drawables que serão usados para mostrar âncoras de seleção de texto e o estilo da janela que contém.
  • Controles de atividade
  • Estilos de texto e ícone da notificação

    • Telas extragrandes

    Agora, a plataforma oferece suporte a tamanhos de tela muito grandes, como as encontradas em tablets. Os desenvolvedores podem indicar que os aplicativos foram projetados para oferecer suporte a tamanhos de tela extra grandes adicionando um elemento <supports screens ... android:xlargeScreens="true"> aos arquivos de manifesto. Os aplicativos podem usar um novo qualificador de recurso, xlarge, para marcar recursos específicos para telas muito grandes. Para saber mais sobre como oferecer suporte a telas muito grandes e outros tamanhos de tela, consulte Suporte a várias telas.

    Gráficos

    Provedores de conteúdo

    • Nova classe de provedor AlarmClock para definir um alarme ou processar um alarme. O provedor contém uma ação de intent ACTION_SET_ALARM e extras que podem ser usados para iniciar uma atividade para definir um novo alarme em um app de despertador. Os apps que quiserem receber a intent SET_ALARM precisam criar uma atividade que exija a permissão SET_ALARM. Os aplicativos que querem criar um novo alarme precisam usar Context.startActivity(), para que o usuário tenha a opção de escolher qual app de despertador usar.
    • MediaStore oferece suporte a uma nova ação de intent, PLAY_FROM_SEARCH, que permite que um app pesquise mídia de música e reproduza conteúdo do resultado automaticamente quando possível. Por exemplo, um app pode disparar essa intent como resultado de um comando de reconhecimento de voz para ouvir música.
    • O MediaStore também adiciona uma nova flag MEDIA_IGNORE_FILENAME que instrui o scanner a ignorar a mídia no diretório e nos subdiretórios que contém. Os desenvolvedores podem usar esse recurso para evitar que imagens apareçam na Galeria e também impedir que sons e músicas do aplicativo apareçam no app Música.
    • O provedor Settings adiciona as novas ações de atividade APPLICATION_DETAILS_SETTINGS e MANAGE_ALL_APPLICATIONS_SETTINGS, que permitem que um aplicativo mostre a tela de detalhes de um aplicativo específico ou a tela "Gerenciar aplicativos".
    • O provedor ContactsContract adiciona o tipo de dados ContactsContract.CommonDataKinds.SipAddress para armazenar o endereço SIP (telefonia pela Internet) de um contato.

    Local

    • O LocationManager agora rastreia solicitações de aplicativos que resultam em wake locks ou bloqueios de Wi-Fi de acordo com WorkSource, uma classe gerenciada pelo sistema que identifica o aplicativo.

      O LocationManager monitora todos os clientes que solicitam atualizações periódicas e informa aos provedores como um parâmetro WorkSource ao definir os tempos mínimos de atualização. O provedor de localização de rede usa o WorkSource para rastrear os bloqueios de ativação e do Wi-Fi iniciados por um app e os adiciona ao uso da bateria dele relatado em "Gerenciar aplicativos".

    • O LocationManager adiciona vários novos métodos que permitem que uma atividade receba atualizações de localização periódicas ou únicas com base em critérios especificados (veja abaixo).
    • Uma nova classe Criteria permite que um aplicativo especifique um conjunto de critérios para selecionar um provedor de localização. Por exemplo, os provedores podem ser ordenados de acordo com a precisão, o uso de energia, a capacidade de informar altitude, velocidade e rolamento, além do custo monetário.

    Armazenamento

    • O Android 2.3 adiciona um novo StorageManager que oferece suporte a arquivos OBB (Opaque Binary Blob). Embora o suporte da plataforma para OBB esteja disponível no Android 2.3, as ferramentas de desenvolvimento para criar e gerenciar arquivos OBB não estarão disponíveis até o início de 2011.
    • A plataforma Android 2.3 adiciona suporte oficial para dispositivos que não incluem cartões SD, embora ofereça partição de cartão SD virtual, quando nenhum cartão SD físico está disponível. Um método de conveniência, isExternalStorageRemovable(), permite que os aplicativos determinem se há um cartão SD físico.

    Gerenciador de pacotes

    Telefonia

    • O TelephonyManager adiciona a constante NETWORK_TYPE_EVDO_B para especificar o tipo de rede CDMA EVDO Rev B.
    • O novo método getPsc() retorna o código de embaralhamento principal da célula de exibição em uma rede UMTS.

    Acesso nativo ao ciclo de vida da atividade, ao Windows

    O Android 2.3 expõe um amplo conjunto de APIs para aplicativos que usam código nativo. As classes de estrutura de interesse para esses aplicativos incluem:

    • NativeActivity é um novo tipo de classe de atividade, cujos callbacks do ciclo de vida são implementados diretamente no código nativo. Um NativeActivity e o código nativo dele são executados no sistema assim como em outras atividades. Especificamente, eles são executados no processo do sistema do app Android e na linha de execução de interface principal do aplicativo. Eles recebem os mesmos callbacks de ciclo de vida que outras atividades.
    • A nova classe InputQueue e a nova interface de callback permitem que o código nativo gerencie o enfileiramento de eventos.
    • A nova interface SurfaceHolder.Callback2 permite que o código nativo gerencie um SurfaceHolder.
    • Os novos métodos takeInputQueue e takeSurface() em Window permitem que o código nativo gerencie eventos e superfícies.

    Para saber mais sobre como trabalhar com código nativo ou fazer o download do NDK, consulte a página do Android NDK.

    Ambiente de execução Dalvik

    Novos elementos e atributos do manifesto

    • Novo atributo xlargeScreens para o elemento <supports-screens>, para indicar se o aplicativo oferece suporte a formatos de tela extra grandes. Para mais detalhes, consulte Suporte a várias telas.
    • Novos valores para o atributo android:screenOrientation do elemento <activity>:
      • "reverseLandscape": a atividade quer que a tela fique na orientação paisagem, girada na direção oposta da paisagem normal.
      • "reversePortrait": a atividade quer que a tela fique na orientação retrato, virada na direção oposta do retrato normal.
      • "sensorLandscape": a atividade quer deixar a tela na orientação paisagem, mas pode usar o sensor para mudar a direção da tela.
      • "sensorPortrait": a atividade quer colocar a tela na orientação retrato, mas pode usar o sensor para mudar a direção para a tela.
      • "fullSensor": a orientação é determinada por um sensor de orientação física. A tela vai girar de acordo com a forma como o usuário move o dispositivo. Isso permite qualquer uma das quatro rotações possíveis, independentemente do que o dispositivo faça normalmente. Por exemplo, alguns dispositivos não costumam usar a rotação de 180 graus.

    Novas permissões

    • com.android.permission.SET_ALARM: permite que um app transmita uma intent para definir um alarme para o usuário. Uma atividade que processa a ação da intent SET_ALARM precisa exigir essa permissão.
    • android.permission.USE_SIP: permite que um app use SIP API para fazer ou receber chamadas pela Internet.
    • android.permission.NFC: permite que um app use o NFC API para ler tags NFC.

    Novas constantes de atributos

    A plataforma adiciona vários novos recursos de hardware que os desenvolvedores podem declarar nos manifestos de aplicativos como obrigatórios. Isso permite que os desenvolvedores controlem como os aplicativos são filtrados quando publicados no Google Play.

    Para informações completas sobre como declarar recursos e usá-los para filtragem, consulte a documentação de <uses-feature>.

    Relatório de diferenças da API

    Para ter uma visão detalhada de todas as mudanças da API no Android 2.3 (API de nível 9), consulte o Relatório de diferenças da API.

    Nível de API

    A plataforma Android 2.3 oferece uma versão atualizada da API do framework. A API do Android 2.3 recebe um identificador de números inteiros (9) que é armazenado no próprio sistema. Esse identificador, chamado de "nível de API", permite que o sistema determine corretamente se um aplicativo é compatível com ele antes de instalá-lo.

    Para usar as APIs introduzidas no Android 2.3 no seu aplicativo, é necessário compilá-lo na biblioteca Android fornecida na plataforma SDK do Android 2.3. Dependendo das suas necessidades, talvez também seja necessário adicionar um atributo android:minSdkVersion="9" ao elemento <uses-sdk> no manifesto do aplicativo. Se o aplicativo foi projetado para ser executado apenas no Android 2.3 e versões mais recentes, a declaração do atributo evita que o aplicativo seja instalado em versões anteriores da plataforma.

    Para mais informações, leia O que é o nível da API?.