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 disponível para download inclui uma biblioteca Android e uma imagem do sistema, além de um conjunto de skins de 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 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 na Internet. Com ela, os aplicativos podem oferecer recursos de chamada de voz sem precisar gerenciar sessões, comunicação no nível de transporte ou áudio. Esses recursos são processados de forma transparente pela API e os serviços 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 e, em seguida, iniciar e receber chamadas de áudio. Depois que uma chamada de áudio é estabelecida, os apps podem silenciar chamadas, ativar o modo 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 a 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 para 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 mais informações, leia o guia do desenvolvedor para SIP.

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

O Android 2.3 inclui uma pilha 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 NFC subjacentes que funcionam com o hardware do dispositivo para descobrir tags quando elas entram no alcance. Ao descobrir uma tag, a plataforma notifica os aplicativos transmitindo uma intent, anexando as mensagens NDEF da tag a essa 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, armazenam-as, alertam o usuário ou tratam-as 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 apps 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 filtragem no Google Play para que os aplicativos não sejam detectáveis para usuários com dispositivos sem suporte à 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, como 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 de forma rápida e suave a mudanças precisas na posição e no movimento do dispositivo. A API Sensor relata o giroscópio e outros sensores 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 as câmeras disponíveis 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 posicionais de uma câmera, como orientação frontal ou traseira.
  • 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 para 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 intensificação de graves, virtualização dos fones de ouvido, equalização e reverberação.

Para ver exemplos de código para efeitos de áudio, consulte AudioFxDemo.java no aplicativo de exemplo ApiDemos.

A estrutura de mídia também adiciona:

  • Novo suporte à tag de altitude em metadados EXIF para arquivos JPEG. Novo método getAltitude() para recuperar o valor da tag de altitude EXIF.
  • O novo método setOrientationHint() permite que um aplicativo informe a 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 realizará 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 receber 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 app forneça todas as informações necessárias para solicitar um novo download, como URI da solicitação e destino. 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 recuperar espaço para uso. 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 captura 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 operações de interface são recebidas e animações. Os desenvolvedores podem avaliar os problemas de uso de rede e disco gerados no StrictMode e corrigi-los, se necessário, mantendo a linha de execução principal mais responsiva e impedindo que as caixas de diálogo ANR sejam exibidas aos usuários.

  • StrictMode é a classe principal e é o principal ponto de integração com o sistema e a VM. A classe oferece métodos convenientes para gerenciar as políticas de linha de execução e de VM que se aplicam à instância.
  • StrictMode.ThreadPolicy e StrictMode.VmPolicy contêm as políticas que você define e aplica a instâncias de linha de execução e de 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 à rolagem.
    • Novo suporte à rolagem em visualizações e widgets Nas visualizações, os aplicativos podem ativar/desativar a rolagem para 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.
  • Suporte à filtragem por toque
    • Novo suporte à filtragem por toque, que permite que um aplicativo melhore a segurança de 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 View.
    • O novo atributo filterTouchesWhenObscured para elementos de visualização, que declara se os toques precisam ser filtrados quando a janela da visualização é encoberta por outra janela visível. Quando definido como "true", a visualização não receberá toques sempre que um aviso, uma caixa de diálogo ou outra janela aparecer acima da janela da visualização. Consulte a documentação de segurança para mais detalhes.

    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, consultando o InputDevice de onde 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.
  • Eventos de movimento aprimorados
    • A API MotionEvent foi estendida para incluir informações de "ID de ponteiro", que permitem aos aplicativos rastrear dedos individuais à medida que eles se movem para cima e para baixo. A 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 conforme novos ponteiros ficam inativos. 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 composto, 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 exibir âncoras de seleção de texto e o estilo da janela que contém.
  • Controles de atividade
  • Estilos de ícone e texto de notificações

    • Telas extragrandes

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

    Gráficos

    Provedores de conteúdo

    • Nova classe de provedor AlarmClock para definir um alarme ou gerenciar 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 despertador usar.
    • A 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 que a contém e nos subdiretórios dela. Os desenvolvedores podem usar isso para evitar que gráficos 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 app mostre a tela de detalhes de um app específico ou a tela "Gerenciar apps".
    • O provedor ContactsContract adiciona o tipo de dados ContactsContract.CommonDataKinds.SipAddress para armazenar o endereço SIP (telefonia pela Internet) de um contato.

    Localização

    • 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 sobre eles 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 Wi-Fi iniciados por um aplicativo e os adiciona ao uso da bateria do aplicativo informado em "Gerenciar aplicativos".

    • O LocationManager adiciona vários métodos novos que permitem que uma atividade seja registrada para receber atualizações de localização únicas ou periódicas com base em critérios especificados (confira 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 direção, e o 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 oferece 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 estiver disponível. Um método de conveniência, isExternalStorageRemovable(), permite que os apps determinem se um cartão SD físico está presente.

    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, janelas

    O Android 2.3 expõe um amplo conjunto de APIs para aplicativos que usam código nativo. As classes de framework 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. Uma NativeActivity e o código nativo dela são executados no sistema assim como outras atividades. Especificamente, elas são executadas no processo do sistema do app Android e na linha de execução de interface principal do aplicativo e 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() no Window permitem que o código nativo gerencie eventos e plataformas.

    Para ver informações completas sobre como trabalhar com código nativo ou fazer o download do NDK, consulte a página do Android NDK.

    Tempo 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, virada 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 colocar a tela na orientação paisagem, mas pode usar o sensor para mudar a direção voltada para a tela.
      • "sensorPortrait": a atividade quer deixar 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ísico. 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 fará normalmente (por exemplo, alguns dispositivos não usam 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.

    Constantes de novos atributos

    A plataforma adiciona vários novos recursos de hardware que os desenvolvedores podem declarar nos manifestos como obrigatórios. Isso permite que os desenvolvedores controlem como os aplicativos deles 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 de API

    Para ter uma visão detalhada de todas as mudanças na API no Android 2.3 (nível 9 da API), 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 de framework. A API do Android 2.3 recebe um identificador inteiro ( 9) que é armazenado no próprio sistema. Esse identificador, chamado de "nível da API", permite que o sistema determine corretamente se um aplicativo é compatível com ele antes da instalação.

    Para usar as APIs introduzidas no Android 2.3, você precisa compilar o aplicativo 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 for projetado para ser executado apenas no Android 2.3 e versões mais recentes, a declaração do atributo vai impedir que o aplicativo seja instalado em versões anteriores da plataforma.

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