En esta página

QGeoPositionInfoSource Class

La clase `QGeoPositionInfoSource` es una clase base abstracta destinada a la distribución de actualizaciones de posición. Más información...

Encabezado: #include <QGeoPositionInfoSource>
CMake: find_package(Qt6 REQUIRED COMPONENTS Positioning)
target_link_libraries(mytarget PRIVATE Qt6::Positioning)
qmake: QT += positioning
Heredado de: QObject
Heredado por:

QNmeaPositionInfoSource

Tipos públicos

enum Error { AccessError, ClosedError, NoError, UnknownSourceError, UpdateTimeoutError }
enum PositioningMethod { NoPositioningMethods, SatellitePositioningMethods, NonSatellitePositioningMethods, AllPositioningMethods }
flags PositioningMethods

Propiedades

Funciones públicas

QGeoPositionInfoSource(QObject *parent)
virtual ~QGeoPositionInfoSource()
(since Qt 5.14) virtual QVariant backendProperty(const QString &name) const
QBindable<QGeoPositionInfoSource::PositioningMethods> bindablePreferredPositioningMethods()
QBindable<int> bindableUpdateInterval()
virtual QGeoPositionInfoSource::Error error() const = 0
virtual QGeoPositionInfo lastKnownPosition(bool fromSatellitePositioningMethodsOnly = false) const = 0
virtual int minimumUpdateInterval() const = 0
QGeoPositionInfoSource::PositioningMethods preferredPositioningMethods() const
(since Qt 5.14) virtual bool setBackendProperty(const QString &name, const QVariant &value)
virtual void setPreferredPositioningMethods(QGeoPositionInfoSource::PositioningMethods methods)
virtual void setUpdateInterval(int msec)
QString sourceName() const
virtual QGeoPositionInfoSource::PositioningMethods supportedPositioningMethods() const = 0
int updateInterval() const

Ranuras públicas

virtual void requestUpdate(int timeout = 0) = 0
virtual void startUpdates() = 0
virtual void stopUpdates() = 0

Señales

void errorOccurred(QGeoPositionInfoSource::Error positioningError)
void positionUpdated(const QGeoPositionInfo &update)
(since Qt 5.12) void supportedPositioningMethodsChanged()

Miembros públicos estáticos

QStringList availableSources()
QGeoPositionInfoSource *createDefaultSource(QObject *parent)
(since Qt 5.14) QGeoPositionInfoSource *createDefaultSource(const QVariantMap &parameters, QObject *parent)
QGeoPositionInfoSource *createSource(const QString &sourceName, QObject *parent)
(since Qt 5.14) QGeoPositionInfoSource *createSource(const QString &sourceName, const QVariantMap &parameters, QObject *parent)

Descripción detallada

La función estática ` QGeoPositionInfoSource::createDefaultSource()` crea una fuente de posición predeterminada adecuada para la plataforma, si hay alguna disponible. De lo contrario, `QGeoPositionInfoSource` comprobará si hay complementos disponibles que implementen la interfaz ` QGeoPositionInfoSourceFactory `.

Los usuarios de una subclase de `QGeoPositionInfoSource` pueden solicitar la posición actual mediante ` requestUpdate()`, o iniciar y detener las actualizaciones periódicas de posición mediante ` startUpdates()` y ` stopUpdates()`. Cuando hay una actualización disponible, se emite ` positionUpdated()`. Se puede acceder a la última posición conocida mediante ` lastKnownPosition()`.

Si se requieren actualizaciones periódicas de la posición, se puede utilizar setUpdateInterval() para especificar la frecuencia con la que deben emitirse dichas actualizaciones. Si no se especifica ningún intervalo, las actualizaciones se proporcionan simplemente cuando están disponibles. Por ejemplo:

// Emit updates every 10 seconds if available
QGeoPositionInfoSource *source = QGeoPositionInfoSource::createDefaultSource(0);
if (source)
    source->setUpdateInterval(10000);

Para eliminar un intervalo de actualización establecido previamente, llama a setUpdateInterval() con un valor de 0.

Nota: La fuente de posición puede tener un requisito de valor mínimo para los intervalos de actualización, tal y como devuelve minimumUpdateInterval().

Nota: Para utilizar esta clase desde un servicio de Android, consulta «Qt Positioning » en Android.

Documentación sobre los tipos de miembros

enum QGeoPositionInfoSource::Error

La enumeración «Error» representa los errores que pueden producirse.

ConstanteValorDescripción
QGeoPositionInfoSource::AccessError0Ha fallado el establecimiento de la conexión con el backend de posicionamiento remoto porque la aplicación carecía de los privilegios necesarios.
QGeoPositionInfoSource::ClosedError1El backend de posicionamiento remoto ha cerrado la conexión, lo que ocurre, por ejemplo, cuando el usuario desactiva los servicios de localización. Tan pronto como se vuelvan a activar los servicios de localización, se reanudarán las actualizaciones periódicas.
QGeoPositionInfoSource::NoError3No se ha producido ningún error.
QGeoPositionInfoSource::UnknownSourceError2Se ha producido un error no identificado.
QGeoPositionInfoSource::UpdateTimeoutError (since Qt 6.2)4Si se ha llamado a ` requestUpdate()`, este error indica que no se ha podido recuperar la posición actual dentro del tiempo de espera especificado. Si se ha llamado a ` startUpdates()`, este error indica que esta subclase de ` QGeoPositionInfoSource ` ha determinado que no podrá proporcionar más actualizaciones periódicas. En este último caso, el error no se volverá a mostrar hasta que se reanuden las actualizaciones periódicas.

enum QGeoPositionInfoSource::PositioningMethod
flags QGeoPositionInfoSource::PositioningMethods

Define los tipos de métodos de posicionamiento.

ConstanteValorDescripción
QGeoPositionInfoSource::NoPositioningMethods0x00000000Ninguno de los métodos de posicionamiento.
QGeoPositionInfoSource::SatellitePositioningMethods0x000000ffMétodos de posicionamiento por satélite, como GPS o GLONASS.
QGeoPositionInfoSource::NonSatellitePositioningMethods0xffffff00Otros métodos de posicionamiento, como el identificador de célula 3GPP o el posicionamiento basado en Wi-Fi.
QGeoPositionInfoSource::AllPositioningMethods0xffffffffMétodos de posicionamiento por satélite, siempre que estén disponibles. En caso contrario, métodos que no se basen en satélites.

El tipo PositioningMethods es un typedef para QFlags<PositioningMethod>. Almacena una combinación OR de valores de PositioningMethod.

Documentación de la propiedad

[read-only] minimumUpdateInterval : int

Esta propiedad indica el tiempo mínimo (en milisegundos) necesario para recuperar una actualización de posición.

Este es el valor mínimo aceptado por las funciones ` setUpdateInterval()` y ` requestUpdate()`.

Funciones de acceso:

virtual int minimumUpdateInterval() const = 0

[bindable] preferredPositioningMethods : PositioningMethods

Nota: Esta propiedad admite enlaces de tipo « QProperty ».

Establece los métodos de posicionamiento preferidos para esta fuente.

Si entre los nuevos métodos hay alguno que no sea compatible con la fuente, dicho método no compatible se ignorará.

Si entre los nuevos métodos no hay ninguno disponible o compatible con la fuente, los métodos preferidos se establecerán como el conjunto de métodos de los que dispone la fuente. Si la fuente no dispone de ningún método (por ejemplo, porque su servicio de localización está desactivado o porque no ofrece dicho servicio), los métodos pasados se aceptarán tal cual.

El valor por defecto de esta propiedad es NoPositioningMethods.

Nota: Las implementacionesde subclases deben llamar a la implementación base de ` setPreferredPositioningMethods() ` para garantizar que ` preferredPositioningMethods() ` devuelva el valor correcto.

Funciones de acceso:

QGeoPositionInfoSource::PositioningMethods preferredPositioningMethods() const
virtual void setPreferredPositioningMethods(QGeoPositionInfoSource::PositioningMethods methods)

Véase también ` supportedPositioningMethods()`.

[read-only] sourceName : QString

Esta propiedad contiene el nombre único de la implementación de la fuente de posición que se está utilizando.

Se trata del mismo nombre que se puede pasar a ` createSource()` para crear una nueva instancia de una implementación concreta de fuente de posición.

Funciones de acceso:

QString sourceName() const

[bindable] updateInterval : int

Nota: Esta propiedad admite enlaces de tipo « QProperty ».

Esta propiedad contiene el intervalo solicitado, en milisegundos, entre cada actualización.

Si no se establece el intervalo de actualización (o se establece en 0), la fuente proporcionará actualizaciones con la frecuencia que sea necesaria.

Si se establece el intervalo de actualización, la fuente proporcionará actualizaciones en un intervalo lo más cercano posible al intervalo solicitado. Si el intervalo solicitado es menor que el de minimumUpdateInterval(), se utilizará en su lugar el intervalo mínimo.

Los cambios en el intervalo de actualización se aplicarán tan pronto como sea posible; sin embargo, el tiempo que tarda el cambio puede variar según la implementación. El hecho de que el tiempo transcurrido desde el intervalo anterior se cuente o no como parte del nuevo intervalo también depende de la implementación.

El valor por defecto de esta propiedad es 0.

Nota: Las implementacionesde subclases deben llamar a la implementación base de ` setUpdateInterval() ` para que ` updateInterval() ` devuelva el valor correcto.

Nota: Esta propiedad no se puede utilizar para ajustar la frecuencia de actualización en iOS y macOS, ya que sus API no ofrecen esa posibilidad. En estos sistemas, este parámetro solo se utiliza para establecer ` UpdateTimeoutError ` y activar una señal ` errorOccurred ` si la actualización no se recibe dentro del intervalo deseado.

Funciones de acceso:

int updateInterval() const
virtual void setUpdateInterval(int msec)

Documentación de funciones de miembro

[explicit] QGeoPositionInfoSource::QGeoPositionInfoSource(QObject *parent)

Crea una fuente de posición con el « parent » especificado.

[virtual noexcept] QGeoPositionInfoSource::~QGeoPositionInfoSource()

Elimina la fuente de posición.

[static] QStringList QGeoPositionInfoSource::availableSources()

Devuelve una lista de los complementos de origen disponibles. Esto incluye cualquier complemento de backend predeterminado para la plataforma actual.

[virtual, since Qt 5.14] QVariant QGeoPositionInfoSource::backendProperty(const QString &name) const

Devuelve el valor de la propiedad específica del backend denominada « name », si existe. De lo contrario, el valor devuelto no será válido. Las propiedades específicas de los backends compatibles se enumeran y describen en Qt Positioning plugins#Default plugins.

Esta función se introdujo en Qt 5.14.

Véase también setBackendProperty.

[static] QGeoPositionInfoSource *QGeoPositionInfoSource::createDefaultSource(QObject *parent)

Crea y devuelve una fuente de posición con la configuración predeterminada de « parent » que lee de las fuentes predeterminadas de datos de ubicación del sistema, o del complemento con la prioridad más alta disponible.

Devuelve ` nullptr ` si el sistema no dispone de ninguna fuente de posición predeterminada, no se han encontrado complementos válidos o el usuario no tiene permiso para acceder a la posición actual.

[static, since Qt 5.14] QGeoPositionInfoSource *QGeoPositionInfoSource::createDefaultSource(const QVariantMap &parameters, QObject *parent)

Crea y devuelve una fuente de posición con el « parent » especificado, que lee los datos de ubicación de las fuentes predeterminadas del sistema o del complemento con la prioridad más alta disponible.

Devuelve ` nullptr ` si el sistema no tiene ninguna fuente de posición predeterminada, no se han encontrado complementos válidos o el usuario no tiene permiso para acceder a la posición actual.

Este método pasa ` parameters ` a la fábrica para configurar la fuente.

Esta función se introdujo en Qt 5.14.

[static] QGeoPositionInfoSource *QGeoPositionInfoSource::createSource(const QString &sourceName, QObject *parent)

Crea y devuelve una fuente de posición con el parent especificado, cargando el complemento denominado sourceName.

Devuelve nullptr si no se encuentra el complemento.

[static, since Qt 5.14] QGeoPositionInfoSource *QGeoPositionInfoSource::createSource(const QString &sourceName, const QVariantMap &parameters, QObject *parent)

Crea y devuelve una fuente de posición con el parent especificado, cargando el complemento denominado sourceName.

Devuelve « nullptr » si no se encuentra el complemento.

Este método pasa parameters a la fábrica para configurar la fuente.

Esta función se introdujo en Qt 5.14.

[pure virtual] QGeoPositionInfoSource::Error QGeoPositionInfoSource::error() const

Devuelve el tipo de error que se ha producido por última vez.

Nota: A partir de Qt6, el último error siempre se restablece al llamar a startUpdates() o requestUpdate().

[signal] void QGeoPositionInfoSource::errorOccurred(QGeoPositionInfoSource::Error positioningError)

Esta señal se emite cuando se produce un error. El parámetro « positioningError » describe el tipo de error que se ha producido.

[pure virtual] QGeoPositionInfo QGeoPositionInfoSource::lastKnownPosition(bool fromSatellitePositioningMethodsOnly = false) const

Devuelve una actualización que contiene la última posición conocida, o una actualización nula si no hay ninguna disponible.

Si « fromSatellitePositioningMethodsOnly » es verdadero, devuelve la última posición conocida recibida mediante un método de posicionamiento por satélite; si no hay ninguna disponible, se devuelve una actualización nula.

[signal] void QGeoPositionInfoSource::positionUpdated(const QGeoPositionInfo &update)

Si se llama a ` startUpdates()` o a ` requestUpdate()`, esta señal se emite cuando hay una actualización disponible.

La variable ` update ` contiene el valor de la nueva actualización.

[pure virtual slot] void QGeoPositionInfoSource::requestUpdate(int timeout = 0)

Intenta obtener la posición actual y emite un positionUpdated() con esta información. Si no se puede encontrar la posición actual dentro del timeout especificado (en milisegundos) o si timeout es menor que el valor devuelto por minimumUpdateInterval(), se emite una señal errorOccurred() con el UpdateTimeoutError.

Si el tiempo de espera es cero, se establece por defecto un periodo de tiempo de espera razonable, adecuado para la fuente.

Esto no tiene ningún efecto si hay otra solicitud de actualización en curso. Sin embargo, se puede llamar incluso si ya se ha llamado a startUpdates() y hay actualizaciones periódicas en curso.

Si la fuente utiliza varios métodos de posicionamiento, intenta obtener la posición actual a partir del método de posicionamiento más preciso dentro del tiempo de espera establecido.

Nota: A partir de Qt6, este método siempre restablece el último error a ` NoError ` antes de solicitar la posición.

Nota: Para comprender cómo utilizar este método desde un servicio de Android, consulta Qt Positioning en Android.

[virtual, since Qt 5.14] bool QGeoPositionInfoSource::setBackendProperty(const QString &name, const QVariant &value)

Establece la propiedad específica del backend denominada « name » en « value ». Devuelve « true » si se realiza correctamente y « false » en caso contrario. Las propiedades específicas del backend se pueden utilizar para configurar el comportamiento del subsistema de posicionamiento en tiempo de ejecución. Las propiedades específicas del backend compatibles se enumeran y describen en Qt Positioning plugins#Default plugins.

Esta función se introdujo en Qt 5.14.

Véase también backendProperty.

[pure virtual slot] void QGeoPositionInfoSource::startUpdates()

Comienza a emitir actualizaciones a intervalos regulares, tal y como se especifica en setUpdateInterval().

Si no se ha llamado a setUpdateInterval(), la fuente emitirá actualizaciones tan pronto como estén disponibles.

Se emitirá una señal errorOccurred() con el UpdateTimeoutError si esta subclase de QGeoPositionInfoSource determina que no podrá proporcionar actualizaciones periódicas. Esto podría ocurrir si se pierde la señal del satélite o si se detecta un error de hardware. Las actualizaciones de posición se reanudarán si los datos vuelven a estar disponibles más adelante. El error UpdateTimeoutError no se volverá a emitir hasta que se reanuden las actualizaciones periódicas.

Nota: A partir de Qt6, este método siempre restablece el último error a « NoError » antes de iniciar las actualizaciones.

Nota: Para comprender cómo utilizar este método desde un servicio de Android, consulta «Qt Positioning » en Android.

En iOS, a partir de la versión 8, el marco Core Location requiere entradas adicionales en el archivo Info.plist de la aplicación con las claves NSLocationAlwaysUsageDescription o NSLocationWhenInUseUsageDescription y una cadena que se mostrará en el mensaje de autorización. La clave NSLocationWhenInUseUsageDescription se utiliza al solicitar permiso para utilizar los servicios de localización mientras la aplicación está en primer plano. La clave NSLocationAlwaysUsageDescription se utiliza al solicitar permiso para utilizar los servicios de localización siempre que la aplicación esté en ejecución (tanto en primer plano como en segundo plano). Si se definen ambas entradas, NSLocationWhenInUseUsageDescription tiene prioridad en el modo de primer plano.

[pure virtual slot] void QGeoPositionInfoSource::stopUpdates()

Deja de enviar actualizaciones a intervalos regulares.

[pure virtual] QGeoPositionInfoSource::PositioningMethods QGeoPositionInfoSource::supportedPositioningMethods() const

Devuelve los métodos de posicionamiento disponibles para esta fuente. La disponibilidad se define como la posibilidad de utilizarlos en el momento de llamar a esta función. Por lo tanto, esta función refleja los ajustes del usuario, como el servicio de localización desactivado o las limitaciones de los proveedores de posicionamiento por satélite. Se pueden obtener notificaciones en tiempo de ejecución cuando cambia el estado mediante supportedPositioningMethodsChanged().

No todas las plataformas distinguen entre los diferentes métodos de posicionamiento ni comunican la configuración actual del dispositivo por parte del usuario. La siguiente tabla ofrece una visión general de la situación actual de las plataformas:

PlataformaBreve descripción
AndroidSe conoce y se comunica el estado de cada proveedor y el estado general del servicio de localización cuando este está activo.
GeoClueProgramado para devolver siempre « AllPositioningMethods ».
GeoClue2No se pueden distinguir los proveedores individuales, pero se refleja la desactivación de los servicios de localización.
iOSConfigurado de forma fija para devolver siempre AllPositioningMethods.
macOSSe ha programado de forma fija para que siempre devuelva « AllPositioningMethods ».
Windows (UWP)No se pueden distinguir los proveedores individuales, pero se refleja que los servicios de localización están desactivados.

Véase también supportedPositioningMethodsChanged() y setPreferredPositioningMethods().

[signal, since Qt 5.12] void QGeoPositionInfoSource::supportedPositioningMethodsChanged()

Esta señal se emite cuando cambian los métodos de posicionamiento compatibles. La causa del cambio podría ser que un usuario active o desactive los servicios de localización, o que restrinja dichos servicios a determinados tipos (por ejemplo, solo GPS). Ten en cuenta que los cambios en los métodos de posicionamiento compatibles no se pueden detectar en todas las plataformas. La función ` supportedPositioningMethods()` ofrece una visión general de la compatibilidad actual con las distintas plataformas.

Esta función se introdujo en Qt 5.12.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.