Escrever um driver de sensor de localização para Windows 8.1
Importante
Esta documentação e o exemplo de driver de geolocalização para Windows 8.1 foram preteridos.
A Plataforma de Sensor e Localização fornece a API de Localização do Windows para permitir que os desenvolvedores de software adicionem recursos de localização a seus aplicativos. Se você estiver escrevendo um driver para um sensor de localização, deverá entender como tornar o driver compatível com a API de Localização e seguir as diretrizes em Diretrizes de driver de localização para energia e desempenho.
Requisitos do Programa de Certificação de Hardware do Windows
O Programa de Certificação de Hardware do Windows permite que os fabricantes de hardware recebam certificação de que seus dispositivos atendem aos padrões necessários para trabalhar com o Windows. O programa de certificação descreve os requisitos para sensores de localização e outros tipos de sensores. Você deve garantir que o driver do sensor de localização cumpra todos os requisitos do programa de certificação. Esses requisitos incluem o seguinte:
Os sensores de localização devem oferecer suporte ao conjunto necessário de dados e propriedades do sensor.
Os sensores de localização devem oferecer suporte aos campos de dados necessários para pelo menos um tipo de relatório de dados integrado.
Em geral, as recomendações nesta documentação do WDK correspondem aos requisitos do Programa de Certificação. No entanto, você deve analisar a documentação oficial do Programa de Certificação ao criar drivers de sensores que pretende enviar para aprovação. Para obter mais informações sobre o Programa de Certificação de Hardware do Windows, consulte o site Central de Desenvolvedores de Hardware do Windows.
Requisitos de API de localização
Você cria drivers para sensores de localização usando o mesmo modelo de driver e extensão de classe de qualquer outra categoria de sensor. No mínimo, para funcionar como um sensor de localização, o driver deve:
Identifique o sensor de localização como pertencente à categoria Local.
Defina o tipo de sensor para um dos tipos de sensor de localização.
Identifique os campos de dados do relatório de localização fornecidos pelo sensor.
Dê suporte às propriedades necessárias.
Forneça dados, quando solicitados.
Gerencie transições de estado.
Gere eventos atualizados por dados e alterados por estado.
O restante desta seção descreve esses requisitos mínimos
Identificando a categoria
Quando ele for chamado por meio de ISensorDriver::OnGetProperties, defina o valor da propriedade WPD_FUNCTIONAL_OBJECT_CATEGORY como SENSOR_CATEGORY_LOCATION. O exemplo de código a seguir mostra como definir essa constante por meio de um ponteiro para IPortableDeviceValues chamado pValues.
hr = pValues->SetGuidValue(WPD_FUNCTIONAL_OBJECT_CATEGORY, SENSOR_CATEGORY_LOCATION);
Configurar o tipo de sensor de localização
Quando for chamado por meio de ISensorDriver::OnGetProperties, defina o valor da propriedade SENSOR_PROPERTY_TYPE como o valor correto. O exemplo de código a seguir mostra como definir o tipo de sensor usando a constante SENSOR_TYPE_LOCATION_GPS por meio de um ponteiro para IPortableDeviceValues chamado pValues.
hr = pValues->SetGuidValue(SENSOR_PROPERTY_TYPE, SENSOR_TYPE_LOCATION_GPS);
Identificar os campos de dados suportados
A API de localização define dois tipos de relatórios de localização. São objetos que organizam dados de localização. Os relatórios LatLong contêm campos de dados de latitude, longitude e altitude, juntamente com campos de dados com informações de intervalo de erro. Os relatórios de endereço cívico têm campos de dados de endereço, como cidade e código postal. O driver de localização deve oferecer suporte aos campos de dados obrigatórios para pelo menos um desses dois tipos de relatório de dados.
Para oferecer suporte a um relatório LatLong, são necessários os seguintes campos de dados:
SENSOR_DATA_TYPE_LATITUDE_DEGREES
SENSOR_DATA_TYPE_LONGITUDE_DEGREES
SENSOR_DATA_TYPE_ERROR_RADIUS_METERS
Para oferecer suporte a um relatório de endereço cívico, é necessário pelo menos um dos seguintes campos de dados:
- SENSOR_DATA_TYPE_COUNTRY_REGION
Para ver o conjunto completo de campos de dados de localização definidos pela plataforma, consulte SENSOR_CATEGORY_LOCATION na seção Referência do sensor do Windows.
Quando são chamados por meio de ISensorDriver::OnGetSupportedDataFields, adicione as constantes de chave de propriedade de campo de dados com suporte ao IPortableDeviceKeyCollection que você retorna por meio do parâmetro ppSupportedDataFields. O exemplo de código a seguir mostra como adicionar o campo de dados de código postal a IPortableDeviceKeyCollection por meio de uma variável chamada pKeyCollection.
pKeyCollection->Add(SENSOR_DATA_TYPE_POSTALCODE);
Dê suporte às propriedades necessárias
Como outros drivers de sensores, os drivers de localização fornecem informações sobre o próprio sensor por meio de um conjunto de propriedades. O Programa de Certificação de Hardware do Windows especifica o conjunto mínimo necessário de propriedades que um sensor de localização deve suportar. Para obter mais informações sobre as propriedades do sensor, seus significados e quais propriedades são necessárias para drivers de sensor, consulte Propriedades do sensor. A seguinte lista contém as propriedades necessárias:
WPD_FUNCTIONAL_OBJECT_CATEGORY
SENSOR_PROPERTY_TYPE
SENSOR_PROPERTY_STATE
SENSOR_PROPERTY_PERSISTENT_UNIQUE_ID
SENSOR_PROPERTY_MANUFACTURER
SENSOR_PROPERTY_MODEL
SENSOR_PROPERTY_SERIAL_NUMBER
SENSOR_PROPERTY_FRIENDLY_NAME
SENSOR_PROPERTY_MIN_REPORT_INTERVAL
SENSOR_PROPERTY_CURRENT_REPORT_INTERVAL
SENSOR_PROPERTY_LOCATION_DESIRED_ACCURACY
Fornecendo dados
Os drivers de localização fornecem dados por meio dos mesmos mecanismos que outros drivers de sensor. Ou seja, a extensão de classe de sensor chama o driver por meio de ISensorDriver::OnGetDataFields e o driver retorna os valores por meio do parâmetro ppDataValues.
Os seguintes requisitos se aplicam ao fornecimento de dados de um sensor de localização:
Forneça dados por meio de solicitações síncronas e gerando eventos.
Mantenha uma cópia do seu relatório de dados mais recente. Se os novos dados não estiverem disponíveis no momento da solicitação, retorne o relatório armazenado em cache. Não atualize o carimbo de data/hora.
Não forneça valores para SENSOR_DATA_TYPE_LATITUDE_DEGREES e SENSOR_DATA_TYPE_LONGITUDE_DEGREES que estejam fora do intervalo de latitudes e longitudes do mundo real.
Não relate um valor para SENSOR_DATA_TYPE_ERROR_RADIUS_METERS que seja zero ou menor.
Defina o valor de SENSOR_DATA_TYPE_COUNTRY_REGION como um código de país ISO 3166 1-alfa-2 válido.
Se o driver oferecer suporte a relatórios de latitude/longitude e endereço cívico, os dados de localização nesses relatórios deverão corresponder à mesma localização física.
A tabela a seguir descreve os campos de dados do sensor que correspondem aos campos do relatório de dados da API de localização. Use essas constantes de campo de dados ao fornecer relatórios de dados para uma localização.
Gerenciar transições de estado
A qualquer momento um driver de sensor pode estar em um dos diversos estados. Os estados do sensor são definidos pela enumeração SensorState. Para funcionar de forma adequada com a API de localização, os sensores de localização devem seguir estas regras para lidar com transições de estado.
Sempre comece no estado SENSOR_STATE_INITIALIZING, mas não gere um evento de alteração de estado na inicialização.
O driver deve fazer a transição de SENSOR_STATE_INITIALIZING para SENSOR_STATE_READY quando os dados estiverem disponíveis.
O driver deve retornar para SENSOR_STATE_INITIALIZING quando não tiver dados atuais para relatar. O driver deve decidir quando essa transição ocorrerá. Se você perdeu um sinal, mas ainda tem um meio de fornecer dados válidos, permaneça no estado SENSOR_STATE_READY.
Sempre gere eventos na ordem correta. Primeiro, estabeleça se os dados estão disponíveis. Depois, gere um evento de alteração de estado. Finalmente, gere o evento atualizado por dados.
Sempre gere um evento de alteração de estado quando o estado do driver for alterado.
-A API de localização não usa dados de sensores que estão nos seguintes estados: SENSOR_STATE_NO_DATA, SENSOR_STATE_NOT_AVAILABLE, SENSOR_STATE_ERROR.
Os vários estados do sensor para drivers de sensor de localização são descritos na tabela abaixo.
| Valor | Descrição | Estado da API de localização |
|---|---|---|
| SENSOR_STATE_READY | O driver do sensor pode fornecer novos relatórios de localização com dados completos e precisos. Por exemplo, um provedor de Wi-Fi ou celular está conectado e funcionando, ou um sensor de GPS tem uma posição. Um driver de GPS que usou dados de um sensor de triangulação para determinar a localização tem este estado. | REPORT_RUNNING |
| SENSOR_STATE_INITIALIZING | O driver do sensor está tentando obter uma posição. O driver do sensor deve deixar esse estado para fazer a transição para SENSOR_STATE_READY, depois que uma posição for bloqueada e rastreada. Por exemplo, um provedor de Wi-Fi está procurando uma conexão com a Internet, um provedor de celular está procurando rádios ou um sensor de GPS está obtendo uma posição. Os sensores de GPS devem entrar novamente nesse estado ao tentarem obter uma posição. | REPORT_INITIALIZING |
| SENSOR_STATE_NO_DATA | O provedor de localização está disponível, mas não consegue fornecer dados de localização. Por exemplo, um provedor de Wi-Fi tem acesso à Internet, mas o banco de dados não tem dados de localização. | REPORT_ERROR |
| SENSOR_STATE_NOT_AVAILABLE | A funcionalidade que o provedor de localização usa para obter dados está desabilitada. Um sensor de GPS pode estar nesse estado se o rádio estiver desligado. | REPORT_ERROR |
| SENSOR_STATE_ERROR | O sensor encontrou um erro grave. O sensor pode se recuperar desse estado, mas o prazo de recuperação é incerto. | REPORT_ERROR |
O diagrama a seguir mostra como podem ocorrer as transições de estado em um sensor de localização.
Gerar eventos atualizados por dados e alterados por estado
A API de localização requer sensores de localização, como sensores de GPS, para gerar eventos que fornecem dados e informações de alteração de estado. Para obter mais informações sobre como gerar eventos de sensor, consulte Sobre eventos de driver de sensor.
Ao gerar esses eventos, os drivers de localização devem seguir estas regras:
Gere eventos de alteração de estado chamando o método ISensorClassExtension::PostStateChange da extensão de classe do sensor. Não chame PostEvent para gerar eventos de alteração de estado.
Gere eventos atualizados por dados chamando PostEvent.
Só gere um evento atualizado por dados se os dados estiverem atualizados e precisos.
Não gere um evento atualizado por dados duas vezes. Isso significa que você não deve gerar um evento de atualização de dados usando dados armazenados em cache. Você pode fornecer dados armazenados em cache em resposta a uma solicitação síncrona de dados.
Sempre inclua todos os campos de dados obrigatórios ao enviar um relatório de latitude/longitude por meio de um evento.
Sempre gere um evento atualizado por dados quando a precisão do sensor for alterada.
Relate um valor válido para SENSOR_DATA_TYPE_ERROR_RADIUS_METERS antes de gerar eventos ou alterar o valor de SENSOR_PROPERTY_STATE para SENSOR_STATE_READY.
Não forneça relatórios de dados incompletos.
Talvez você não tenha dados atualizados para os campos de dados obrigatórios, como quando um sensor de GPS perde sua posição. Nesse caso, recomenda-se fornecer notificações sobre atualizações de campos de dados estendidos, como SENSOR_DATA_TYPE_NMEA_SENTENCE. Para fornecer essas notificações, você deve usar um tipo de evento personalizado e gerar apenas o evento personalizado até que os dados dos campos de dados necessários sejam disponibilizados. Para obter informações sobre como definir tipos personalizados, consulte Definir valores personalizados para constantes.
Tópicos relacionados
Diretrizes do driver de localização para energia e desempenho