Escritura de un controlador de sensor de ubicación para Windows 8.1
Importante
Esta documentación y el ejemplo del controlador de geolocalización para Windows 8.1 han quedado en desuso.
La plataforma de sensor y ubicación proporciona la API de ubicación de Windows para permitir que los desarrolladores de software agreguen características de ubicación a sus aplicaciones. Si va a escribir un controlador para un sensor de ubicación, debe comprender cómo hacer que el controlador sea compatible con la API de ubicación y seguir las instrucciones de Directrices sobre energía y rendimiento para controladores de ubicación.
Requisitos del Programa de certificación de hardware de Windows
El Programa de certificación de hardware de Windows permite a los fabricantes de hardware recibir la certificación de que sus dispositivos cumplen los estándares necesarios para trabajar con Windows. El programa de certificación describe los requisitos para los sensores de ubicación y otros tipos de sensores. Debe hacer que el controlador del sensor de ubicación cumpla todos los requisitos del programa de certificación. Entre estos requisitos figuran los siguientes:
Los sensores de ubicación deben admitir el conjunto necesario de propiedades de datos y sensores.
Los sensores de ubicación deben admitir los campos de datos necesarios para al menos un tipo de informe de datos integrado.
Por lo general, las recomendaciones de esta documentación del WDK coinciden con los requisitos del programa de certificación. Sin embargo, debe revisar la documentación oficial del Programa de certificación al crear controladores de sensor que quiera enviar para su aprobación. Para obtener más información sobre el Programa de certificación de hardware de Windows, consulte el sitio web de Central de desarrolladores de hardware de Windows .
Requisitos de la API de ubicación
Puede crear controladores para sensores de ubicación con el mismo modelo de controlador y la misma extensión de clase que para cualquier otra categoría de sensor. Como mínimo, para que funcione como sensor de ubicación, el controlador debe:
Identificar el sensor de ubicación como perteneciente a la categoría Ubicación.
Establecer el tipo de sensor en uno de los tipos de sensor de ubicación.
Identificar los campos de datos del informe de ubicación que proporciona el sensor.
Admitir las propiedades necesarias.
Proporcionar datos, cuando se solicite.
Administrar transiciones de estado.
Generar eventos de actualización de datos y cambio de estado.
En el resto de esta sección se describen estos requisitos mínimos.
Identificación de la categoría
Cuando se llama a través de ISensorDriver::OnGetProperties, establezca el valor de la propiedad WPD_FUNCTIONAL_OBJECT_CATEGORY en SENSOR_CATEGORY_LOCATION. En el ejemplo de código siguiente se muestra cómo establecer esta constante a través de un puntero a pValues con nombre IPortableDeviceValues.
hr = pValues->SetGuidValue(WPD_FUNCTIONAL_OBJECT_CATEGORY, SENSOR_CATEGORY_LOCATION);
Establecimiento del tipo de sensor de ubicación
Cuando se llama a través de ISensorDriver::OnGetProperties, establezca el valor de la propiedad SENSOR_PROPERTY_TYPE con el valor correcto. En el ejemplo de código siguiente se muestra cómo establecer el tipo de sensor mediante la constante SENSOR_TYPE_LOCATION_GPS a través de un puntero a pValues con nombre IPortableDeviceValues.
hr = pValues->SetGuidValue(SENSOR_PROPERTY_TYPE, SENSOR_TYPE_LOCATION_GPS);
Identificación de los campos de datos admitidos
La API de ubicación define dos tipos de informes de ubicación. Estos son objetos que organizan los datos de ubicación. Los informes LatLong contienen campos de datos de latitud, longitud y altitud, junto con campos de datos que contienen información de intervalo de errores. Los informes de direcciones postales contienen campos de datos de direcciones postales, como ciudad y código postal. El controlador de ubicación debe admitir los campos de datos necesarios para al menos uno de estos dos tipos de informe de datos.
Para admitir un informe latLong, se requieren los siguientes campos de datos:
SENSOR_DATA_TYPE_LATITUDE_DEGREES
SENSOR_DATA_TYPE_LONGITUDE_DEGREES
SENSOR_DATA_TYPE_ERROR_RADIUS_METERS
Para admitir un informe de direcciones postales, se requiere al menos uno de los siguientes campos de datos:
- SENSOR_DATA_TYPE_COUNTRY_REGION
Para ver el conjunto completo de campos de datos de ubicación definidos por la plataforma, consulte SENSOR_CATEGORY_LOCATION en la sección Referencia del sensor de Windows.
Cuando se llama a través de ISensorDriver::OnGetSupportedDataFields, agregue las constantes de clave de propiedad de campo de datos admitidas al IPortableDeviceKeyCollection que devuelve a través del parámetro ppSupportedDataFields. En el ejemplo de código siguiente se muestra cómo agregar el campo de datos de código postal a IPortableDeviceKeyCollection a través de una variable denominada pKeyCollection.
pKeyCollection->Add(SENSOR_DATA_TYPE_POSTALCODE);
Admisión de las propiedades necesarias
Al igual que otros controladores de sensor, los controladores de ubicación proporcionan información sobre el propio sensor a través de un conjunto de propiedades. El Programa de certificación de hardware de Windows especifica el conjunto mínimo necesario de propiedades que debe admitir un sensor de ubicación. Para obtener más información sobre las propiedades del sensor, sus significados y qué propiedades son necesarias para los controladores de sensor, consulte Propiedades del sensor. La lista siguiente contiene las propiedades necesarias:
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
Suministro de datos
Los controladores de ubicación proporcionan datos a través de los mismos mecanismos que otros controladores de sensor. Es decir, la extensión de clase de sensor llama al controlador a través de ISensorDriver::OnGetDataFields y el controlador devuelve los valores a través del parámetro ppDataValues.
Se aplican los siguientes requisitos para proporcionar datos desde un sensor de ubicación:
Proporcione datos tanto a través de solicitudes sincrónicas como mediante la generación de eventos.
Mantenga una copia del informe de datos más reciente. Si los nuevos datos no están disponibles al solicitarlos, devuelva el informe almacenado en caché. No actualice la marca de tiempo.
No proporcione valores para SENSOR_DATA_TYPE_LATITUDE_DEGREES y SENSOR_DATA_TYPE_LONGITUDE_DEGREES que se encuentran fuera del intervalo de latitud y longitudes reales.
No notifique un valor para SENSOR_DATA_TYPE_ERROR_RADIUS_METERS que sea cero o menos.
Establezca el valor de SENSOR_DATA_TYPE_COUNTRY_REGION en un código de país ISO 3166 1-alfa-2 válido.
Si el controlador admite tanto los informes de latitud/longitud como de dirección postal, los datos de ubicación de estos informes deben corresponder a la misma ubicación física.
En la tabla siguiente se describen los campos de datos del sensor que corresponden a los campos de informe de datos de la API de ubicación. Use estas constantes de campo de datos al proporcionar informes de datos para una ubicación.
Administración de transiciones de estado
En cualquier momento, un controlador de sensor puede estar en uno de los estados. Los estados del sensor se definen mediante la enumeración SensorState. Para que funcionen correctamente con la API de ubicación, los sensores de ubicación deben seguir estas reglas para controlar las transiciones de estado.
Empiece siempre por el estado SENSOR_STATE_INITIALIZING, pero no genere un evento de cambio de estado en al empezar.
El controlador debe pasar de SENSOR_STATE_INITIALIZING a SENSOR_STATE_READY cuando los datos estén disponibles.
El controlador debe volver a SENSOR_STATE_INITIALIZING cuando el controlador no tenga datos actuales para notificar. El controlador debe decidir cuándo se produce esa transición. Si ha perdido una señal, pero sigue teniendo un medio para proporcionar datos válidos, permanezca en el estado SENSOR_STATE_READY.
Genere siempre eventos en el orden correcto. En primer lugar, establezca que los datos están disponibles. A continuación, genere un evento de cambio de estado. Por último, genere el evento de actualización de datos.
Genere siempre un evento de cambio de estado cuando cambie el estado del controlador.
-La API de ubicación no usa datos de sensores que se encuentran en los estados siguientes: SENSOR_STATE_NO_DATA, SENSOR_STATE_NOT_AVAILABLE, SENSOR_STATE_ERROR.
Los distintos estados del sensor para los controladores del sensor de ubicación se describen en la tabla siguiente.
| Valor | Descripción | Estado de API de ubicación |
|---|---|---|
| SENSOR_STATE_READY | El controlador del sensor puede proporcionar nuevos informes de ubicación que tengan datos completos y precisos. Por ejemplo, un proveedor de telefonía móvil o Wi-Fi está conectado y funciona, o un sensor GPS tiene una corrección. Un controlador GPS que ha usado datos de un sensor de triangulación para determinar la ubicación tiene este estado. | REPORT_RUNNING |
| SENSOR_STATE_INITIALIZING | El controlador del sensor está intentando adquirir una corrección. El controlador del sensor debe dejar este estado para realizar la transición a SENSOR_STATE_READY, después de bloquear y realizar un seguimiento de una corrección. Por ejemplo, un proveedor de Wi-Fi busca una conexión a Internet, un proveedor de telefonía móvil busca radios o un sensor GPS está obteniendo una corrección. Los sensores GPS deben volver a entrar en este estado cuando intenten volver a adquirir una corrección. | REPORT_INITIALIZING |
| SENSOR_STATE_NO_DATA | El proveedor de ubicación está disponible, pero no puede proporcionar datos de ubicación. Por ejemplo, un proveedor de Wi-Fi tiene acceso a Internet, pero la base de datos no tiene datos de ubicación. | REPORT_ERROR |
| SENSOR_STATE_NOT_AVAILABLE | La funcionalidad que usa el proveedor de ubicación para adquirir datos está deshabilitada. Un sensor GPS podría estar en este estado si la radio está desactivada. | REPORT_ERROR |
| SENSOR_STATE_ERROR | El sensor ha encontrado un error importante. El sensor puede recuperarse de este estado, pero no se conoce el período de tiempo para la recuperación. | REPORT_ERROR |
En el diagrama siguiente se muestra cómo pueden producirse transiciones de estado en un sensor de ubicación.
Generación de eventos de actualización de datos y cambio de estado
La API de ubicación requiere sensores de ubicación, como sensores GPS, para generar eventos que proporcionan información de cambio de datos y estado. Para obtener más información sobre cómo generar eventos de sensor, consulte Acerca de los eventos del controlador del sensor.
Al generar estos eventos, los controladores de ubicación deben seguir estas reglas:
Generar eventos de cambio de estado llamando al método ISensorClassExtension::PostStateChange de la extensión de clase del sensor. No llamar a PostEvent para generar eventos de cambio de estado.
Generar eventos de actualización de datos mediante una llamada a PostEvent.
Generar un evento de actualización de datos solo si los datos están actualizados y precisos.
No generar un evento de actualización de datos dos veces. Esto significa que no debe generar un evento de actualización de datos mediante datos almacenados en caché. Puede proporcionar datos almacenados en caché en respuesta a una solicitud sincrónica de datos.
Incluir siempre todos los campos de datos necesarios al enviar un informe de latitud y longitud a través de un evento.
Generar siempre un evento de actualización de datos cuando cambie la precisión del sensor.
Notificar un valor válido para SENSOR_DATA_TYPE_ERROR_RADIUS_METERS antes de generar eventos o cambiar el valor de SENSOR_PROPERTY_STATE a SENSOR_STATE_READY.
No proporcionar informes de datos incompletos.
Es posible que no tenga datos actuales para los campos de datos necesarios, como cuando un sensor GPS ha perdido su corrección. En este caso, es posible que quiera proporcionar notificaciones sobre las actualizaciones de campos de datos extendidos, como SENSOR_DATA_TYPE_NMEA_SENTENCE. Para proporcionar estas notificaciones, debe usar un tipo de evento personalizado y generar solo el evento personalizado hasta que los datos de los campos de datos necesarios estén disponibles. Para obtener información sobre cómo definir tipos personalizados, consulte Definición de valores personalizados para constantes.
Temas relacionados
Directrices sobre energía y rendimiento para controladores de ubicación