Servicios de Android
Puedes crear servicios para Android utilizando Qt. Un servicio es un componente que se ejecuta en segundo plano, por lo que no tiene interfaz de usuario. Resulta útil para realizar operaciones de larga duración, como el registro de datos GPS, la espera de notificaciones de redes sociales, etc. Un servicio seguirá ejecutándose incluso si la aplicación que lo inició se cierra.
Configurar el servicio
Para empezar, crea un directorio de paquetes de Android tal y como se indica en «Ampliar Qt con funciones de Android». Este directorio contiene el archivo « AndroidManifest.xml ». Dentro del directorio del paquete, crea un directorio « src », donde se crearán todos tus paquetes y clases de Java.
Crear la clase del servicio
A la hora de decidir si utilizar « QtService » o «Android Service», se aplica el mismo razonamiento que con «Activity ». A menos que utilices funciones que requieran la carga de las bibliotecas de Qt, como las llamadas nativas de Qt y la gestión de eventos, la extensión de « Service » debería funcionar.
Puedes crear un servicio extendiendo la clase ` QtService ` o `Service` a tu clase Java. Dependiendo de si deseas utilizar funciones de Qt en tu servicio o llamar a funciones nativas de C++ desde Java, deberás extender ` QtService ` o ` Service`. Empecemos con un servicio sencillo, como se muestra a continuación:
import android.content.Context;
import android.content.Intent;
import android.util.Log;
import org.qtproject.qt.android.bindings.QtService;
public class QtAndroidService extends QtService
{
private static final String TAG = "QtAndroidService";
@Override
public void onCreate() {
super.onCreate();
Log.i(TAG, "Creating Service");
}
@Override
public void onDestroy() {
super.onDestroy();
Log.i(TAG, "Destroying Service");
}
@Override
public int onStartCommand(Intent intent, int flags, int startId) {
int ret = super.onStartCommand(intent, flags, startId);
// Do some work
return ret;
}
}Iniciar el servicio
Android permite iniciar servicios bajo demanda o en el momento del arranque. También puedes hacer ambas cosas utilizando Qt.
Iniciar un servicio bajo demanda
Puedes iniciar el servicio de las siguientes maneras:
- Directamente desde C++ utilizando QAndroidIntent y QJniObject, creando un Intent de servicio y llamando al método startService() de la actividad principal de la aplicación:
// Outside of the function body Q_DECLARE_JNI_CLASS(Intent, "android/content/Intent") Q_DECLARE_JNI_CLASS(ComponentName, "android/content/ComponentName") Q_DECLARE_JNI_CLASS(QtAndroidService, "org/qtproject/example/qtandroidservice/QtAndroidService") // Inside function body using namespace QtJniTypes; using namespace QNativeInterface; auto *androidApp = qGuiApp->nativeInterface<QAndroidApplication>(); Q_ASSERT(androidApp); Context context = androidApp->context(); QJniEnvironment env; auto serviceClass = env.findClass(Traits<QtAndroidService>::className()); Intent serviceIntent(context, serviceClass); context.callMethod<ComponentName>("startService", serviceIntent); - Inicia el servicio llamando a un método de Java. La forma más sencilla es crear un método estático en la clase del servicio:
public static void startQtAndroidService(Context context) { context.startService(new Intent(context, QtAndroidService.class)); }A continuación, puedes llamarlo desde C++ utilizando la siguiente llamada JNI:
using namespace QtJniTypes; using namespace QNativeInterface; // ... auto *androidApp = qGuiApp->nativeInterface<QAndroidApplication>(); Q_ASSERT(androidApp); Context context = androidApp->context(); QtAndroidService::callStaticMethod<void>("startQtAndroidService", context);
Iniciar un servicio al arrancar el sistema
Para ejecutar un servicio al arrancar el sistema, necesitas un BroadcastReceiver.
Crea una clase Java personalizada:
public class QtBootServiceBroadcastReceiver extends BroadcastReceiver {
@Override
public void onReceive(Context context, Intent intent) {
Intent startServiceIntent = new Intent(context, QtAndroidService.class);
context.startService(startServiceIntent);
}
}Añade el siguiente código « uses-permission » en el cuerpo de la sección « <manifest> » del archivo « AndroidManifest.xml »:
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />Además, añade la definición de receiver en el cuerpo de la sección <application>:
<receiver android:name=".QtBootServiceBroadcastReceiver" android:exported="true">
<intent-filter>
<action android:name="android.intent.action.BOOT_COMPLETED" />
</intent-filter>
</receiver>Limitaciones
- Android 15.0 introdujo algunas limitaciones en la ejecución de servicios en primer plano tras recibir BOOT_COMPLETED. Para obtener más información, consulta Restricciones sobre BOOT_COMPLETED.
- Android 8.0 introdujo algunas limitaciones en la ejecución de servicios en segundo plano, lo que significa que es posible que no funcione el uso de una clase `
Service` normal. Para obtener más información, consulta la recomendación de Android de utilizar servicios en primer plano o `JobIntentService`.
Gestionar el servicio en AndroidManifest.xml
Para que el servicio se pueda utilizar en una aplicación de Android, debes declararlo en el archivo AndroidManifest.xml. Empecemos por añadir la sección del servicio:
- Al ampliar el archivo `
Service`, basta con declarar la sección del servicio como un servicio normal de Android. Añade lo siguiente dentro de la sección `<application>`:<service android:name=".QtAndroidService" android:exported="true"> <meta-data android:name="android.app.background_running" android:value="true"/> </service>De esta forma, el servicio se iniciará en el mismo proceso que
QtActivity, lo que te permite utilizar llamadas nativas de C++ desde código Java. Puedes ejecutarlo en un proceso independiente, pero en ese caso no podrás utilizar llamadas nativas para la comunicación, ya que las bibliotecas Qt no se cargan para ese proceso. Para ejecutarlo en un proceso independiente, añade esto a la etiqueta del servicio:android:process=":qt_service" - Al extender
QtService, debes declarar otros elementos para cargar todas las bibliotecas necesarias para Qt, principalmente los mismos elementos que en la sección<activity>paraQtActivity. Añade lo siguiente:<service android:process=":qt_service" android:name=".QtAndroidService" android:exported="true"> <meta-data android:name="android.app.lib_name" android:value="service"/> <meta-data android:name="android.app.background_running" android:value="true"/> </service>
Nota: Asegúrate de definir lo siguiente para que el servicio se ejecute en segundo plano:
<meta-data android:name="android.app.background_running" android:value="true"/>Existen varias formas de declarar los servicios. Algunas de ellas ya se han utilizado en el fragmento de manifiesto anterior. Dependiendo de tu caso de uso, ejecuta el servicio en el mismo proceso que QtActivity o en un proceso independiente.
Servicio en el mismo proceso que QtActivity
Para ejecutar un servicio en el mismo proceso que QtActivity, declara el encabezado del servicio de la siguiente manera:
<service android:name=".QtAndroidService" android:exported="true">Servicio en un proceso independiente
Para ejecutar un servicio en un proceso dedicado, declara el encabezado del servicio de la siguiente manera:
<service android:process=":qt_service" android:name=".QtAndroidService" android:exported="true">.so android.app.lib_name meta-data main() android.app.arguments meta-dataLorsque le service est exécuté dans un processus indépendant, vous pouvez l'initier en utilisant le même fichier «lib» que l'activité principale ou un fichier «lib» indépendant.
Utilizar el mismo archivo .so de biblioteca
Utilizar el mismo archivo «lib» .so que la actividad principal significa que el servicio utilizará el mismo punto de entrada con un argumento adicional para distinguirlo de la actividad principal. Puedes gestionar la ejecución de tu aplicación en la función « main() » según los argumentos proporcionados. Añade la siguiente declaración de argumento al cuerpo de tu servicio:
<meta-data android:name="android.app.arguments" android:value="-service"/>A continuación, asegúrate de que el servicio android.app.lib_name sea el mismo que el de la actividad principal; añade lo siguiente:
<meta-data android:name="android.app.lib_name" android:value="-- %%INSERT_APP_LIB_NAME%% --"/>Al utilizar el mismo archivo de biblioteca « .so », la función « main() » de tu aplicación se ejecuta dos veces: una para iniciar la actividad principal y otra para iniciar el servicio. Por lo tanto, debes gestionar cada ejecución en función del argumento proporcionado. Una forma de hacerlo es la siguiente:
if (argc <= 1) {
// código para gestionar la ejecución de la actividad principal
} else if (argc > 1&& strcmp(argv[1], "-service")== 0) {
qDebug() << "Service starting with from the same .so file";
QAndroidService app(argc, argv);
return app.exec();
} else {
qWarning() << "Unrecognized command line argument";
return-1;
}Utiliza un archivo .so independiente
En este caso, es necesario disponer de un subproyecto con una plantilla lib que proporcione un ejecutable diferente para el servicio. A continuación se muestra un proyecto de ejemplo:
- En CMake:
find_package(Qt6 REQUIRED COMPONENTS Core) qt_add_library(service SHARED servicemessenger.h service_main.cpp ) target_link_libraries(service PRIVATE Qt::Core Qt::CorePrivate ) - En qmake:
TEMPLATE = lib TARGET = service CONFIG += dll QT += core core-private SOURCES += \ service_main.cpp HEADERS += servicemessenger.h
En el archivo « service_main.cpp » podrías incluir lo siguiente:
#include <QDebug>
#include <QAndroidService>
#include <QtCore/private/qandroidextras_p.h>
int main(int argc, char *argv[])
{
qWarning() << "Service starting from a separate .so file";
QAndroidService app(argc, argv);
return app.exec();
}Define el android.app.lib_name para el servicio en el archivo AndroidManifest.xml:
<meta-data android:name="android.app.lib_name" android:value="service"/>Comunicación con el servicio
Qt para Android ofrece diversos métodos de comunicación entre procesos (IPC) para comunicarse con los servicios de Android. Dependiendo de la estructura de tu proyecto, puedes utilizar llamadas nativas en C++ desde el servicio Java o desde un BroadcastReceiver de Android.
Llamadas nativas en C++ desde un servicio Java
Esto funciona con servicios que se ejecutan en el mismo proceso que QtActivity e incluso si se hereda de Service.
Para obtener más información, consulta el ejemplo «Qt for Android Notifier».
Uso de BroadcastReceiver en Android
El BroadcastReceiver de Android permite el intercambio de mensajes entre el sistema Android, las aplicaciones, las actividades y los servicios. Al igual que con otras funciones de Android, Qt puede utilizar receptores de difusión para intercambiar mensajes entre QtActivity y tu servicio. Empecemos con la lógica para enviar un mensaje desde tu servicio. Añade lo siguiente en la implementación de tu servicio, que llama a sendBroadcast():
@Override
public int onStartCommand(Intent intent, int flags, int startId) {
int ret = super.onStartCommand(intent, flags, startId);
Intent sendToUiIntent = new Intent();
sendToUiIntent.setAction(ActivityUtils.BROADCAST_CUSTOM_ACTION);
sendToUiIntent.putExtra("message", "simple_string");
Log.i(TAG, "Service sending broadcast");
sendBroadcast(sendToUiIntent);
return ret;
}A continuación, debe crear y registrar el receptor de difusión desde la actividad principal de Qt. La forma más sencilla es crear una clase personalizada con un método e implementar toda esa lógica en Java. En el siguiente ejemplo, el servicio envía un mensaje « "simple_string" » a Qt llamando al método nativo sendToQt():
public class ServiceBroadcastUtils {
private static native void sendToQt(String message);
private static final String TAG = "ActivityUtils";
public static final String BROADCAST_CUSTOM_ACTION = "org.qtproject.example.qtandroidservice.broadcast.custom";
public void registerServiceBroadcastReceiver(Context context) {
IntentFilter intentFilter = new IntentFilter();
intentFilter.addAction(BROADCAST_CUSTOM_ACTION);
context.registerReceiver(serviceMessageReceiver, intentFilter);
Log.i(TAG, "Registered broadcast receiver");
}
private BroadcastReceiver serviceMessageReceiver = new BroadcastReceiver() {
@Override
public void onReceive(Context context, Intent intent) {
Log.i(TAG, "In OnReceive()");
if (BROADCAST_CUSTOM_ACTION.equals(intent.getAction())) {
String message = intent.getStringExtra("message");
sendToQt(message);
Log.i(TAG, "Service sent back message to C++: " + message);
}
}
};
}Para aprovechar todo esto, inicia tu servicio tal y como se muestra en «Iniciar el servicio» y, a continuación, registra el receptor de difusión llamando al método registerServiceBroadcastReceiver():
QJniEnvironment env;
jclass javaClass = env.findClass("org/qtproject/example/qtandroidservice/ActivityUtils");
QJniObject classObject(javaClass);
const QJniObject context(QNativeInterface::QAndroidApplication::context());
classObject.callMethod<void>("registerServiceBroadcastReceiver",
"(Landroid/content/Context;)V",
context.object());Uso de Qt Remote Objects
Qt Remote Objects ofrece una forma sencilla de compartir API entre procesos Qt. La idea principal consiste en ejecutar el servidor en el proceso de servicio y tener una réplica en la aplicación Qt; de este modo, ambas partes pueden intercambiar datos entre sí mediante señales y ranuras.
Preparar la réplica
Veamos un ejemplo de servicio con un archivo .lib independiente llamado « .so ». Define un archivo « .rep » que defina nuestra clase de comunicación:
class ServiceMessenger {
SLOT(void ping(const QString &message));
SIGNAL(pong(const QString &message));
}A continuación, definimos la clase en el subproyecto del servicio como servicemessenger.h:
#include "rep_servicemessenger_source.h"
class ServiceMessenger : public ServiceMessengerSource {
public slots:
void ping(const QString &name) override {
emit pong("Hello " + name);
}
};A continuación, añade el archivo « .rep » tanto a la aplicación principal como al servicio de la aplicación principal.
- En CMake:
find_package(Qt6 REQUIRED COMPONENTS RemoteObjects) qt_add_repc_replicas(service ../servicemessenger.rep ) target_link_libraries(service PRIVATE Qt6::RemoteObjects) - En qmake:
QT += remoteobjects REPC_REPLICA += servicemessenger.rep
Y en el subproyecto «service»:
- En CMake:
find_package(Qt6 REQUIRED COMPONENTS RemoteObjects) qt_add_repc_sources(service ../servicemessenger.rep ) target_link_libraries(service PRIVATE Qt6::RemoteObjects) - En qmake:
QT += remoteobjects REPC_SOURCE += servicemessenger.rep
Conecta la fuente y la réplica
Define el nodo de origen « Qt Remote Objects » en la función « main() » del subproyecto «service»:
#include "servicemessenger.h"
#include <QDebug>
#include <QAndroidService>
#include <QtCore/private/qandroidextras_p.h>
int main(int argc, char *argv[])
{
qWarning() << "QtAndroidService starting from separate .so";
QAndroidService app(argc, argv);
QRemoteObjectHost srcNode(QUrl(QStringLiteral("local:replica")));
ServiceMessenger serviceMessenger;
srcNode.enableRemoting(&serviceMessenger);
return app.exec();
}A continuación, en la función main() de la aplicación, conéctate al nodo de origen:
QRemoteObjectNode repNode;
repNode.connectToNode(QUrl(QStringLiteral("local:replica")));
QSharedPointer<ServiceMessengerReplica> rep(repNode.acquire<ServiceMessengerReplica>());
bool res = rep->waitForSource();
Q_ASSERT(res);
QObject::connect(rep.data(), &ServiceMessengerReplica::pong, [](const QString&message){
qDebug() << "Service sent: " << message;
});
rep->ping("¡Qt y Android son amigos!");Este ejemplo envía un mensaje desde el proceso de la aplicación principal al servicio. El servicio responde con el mismo mensaje, que se muestra en el logcat de depuración.
Nota: Se podría utilizarel mismo método al emplear el mismo archivo de biblioteca .so. Para obtener más información, consulta «Utilizar el mismo archivo de biblioteca .so».
Uso de QAndroidBinder
QAndroidBinder es una clase de conveniencia que permite la comunicación entre procesos mediante la implementación de los métodos más importantes de Binder. Permite enviar objetos de tipo « QByteArray » o « QVariant » entre procesos.
Nota: Qt para Android tiene una limitación que obliga a ejecutar solo un servicio a la vez cuando se ejecutan varios servicios en un mismo proceso. Por lo tanto, se recomienda ejecutar cada servicio en su propio proceso. Para más información, véase QTBUG-78009.
© 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.