En esta página

Qt Remote Objects Compilador

Descripción general de REPC

El compilador Replica(repc) genera archivos de cabez QObject es basados en un archivo de definición de la API. El archivo (denominado «archivo rep») utiliza una sintaxis específica (de texto) para describir la API. Por convención, a estos archivos se les asigna la extensión .rep, abreviatura de Replica. Cuando repc procesa estos archivos, genera tanto archivos de encabezado «Source» como «Replica ».

El módulo « Qt Remote Objects » también incluye funciones de CMake y variables de qmake que se pueden añadir al archivo de proyecto para ejecutar automáticamente repc y añadir los archivos resultantes a la lista de archivos procesados por el Meta-Object Compiler durante el proceso de compilación, lo que facilita el uso de « Qt Remote Objects » en tus proyectos.

Aunque Qt Remote Objects admite compartir cualquier objeto « QObject » a través de la red (utilizando «enableRemoting» en el lado «Source» y «acquireDynamic» en el lado «Replica»), hay un par de ventajas en dejar que repc defina tus objetos. En primer lugar, aunque los « DynamicReplicas » son útiles, resultan más engorrosos de manejar. La API no se conoce hasta que se inicializa el objeto, y utilizar la API desde C++ requiere búsquedas de cadenas a través de los métodos de QMetaObject. En segundo lugar, conocer la interfaz en tiempo de compilación permite detectar cualquier problema durante la compilación, en lugar de en tiempo de ejecución. En tercer lugar, el formato REP admite valores por defecto, lo cual puede resultar útil si no puedes garantizar que el «Source» esté disponible cuando se instancie la «Replica».

Consulta la documentación aquí para obtener información sobre cómo utilizar los archivos generados en tu código. Aquí nos centraremos en el formato repc y sus opciones.

El formato de archivo «rep»

El formato de archivo «rep» es un lenguaje específico de dominio (DSL) sencillo para describir una interfaz compatible con QtRO ( Qt Remote Objects ). Dado que QtRO es un sistema basado en objetos, estas interfaces se definen mediante API disponibles a través de objetos, es decir, clases con propiedades, señales y ranuras.

Comentarios

Se admiten comentarios de una sola línea al estilo C++ (// text ), así como comentarios de varias líneas al estilo C (/* text * / ).

El tipo de clase

Cada clase definida en un archivo «rep» se convierte en un ` QObject ` en los archivos de encabezado generados, con la API descrita generada automáticamente.

Para definir una clase, utiliza la palabra clave « class », seguida del nombre que desees para tu tipo, y luego encierra tu API entre corchetes de la siguiente manera

class MyType
{
    //PROP/CLASS/MODEL/SIGNAL/SLOT/ENUM declarations to define your API
};

Al utilizar los archivos de cabecera generados dentro de una biblioteca, puede ser necesario definir atributos de clase para establecer la visibilidad de los símbolos. Esto se puede hacer de forma similar a C++ definiendo el atributo después de la palabra clave ` class `. En el siguiente ejemplo se utiliza la macro ` MYSHAREDLIB_EXPORT `, que está definida en "mysharedlib_global.h". Consulta «Creación de bibliotecas compartidas» para obtener más información sobre cómo funciona esto.

#include "mysharedlib_global.h"
class MYSHAREDLIB_EXPORT MyType
{
    ...
};

Los elementos

Q_PROPERTY se crean utilizando la palabra clave PROP en el archivo rep. La sintaxis consiste en la palabra clave « PROP » seguida de la definición entre paréntesis, donde la definición incluye el tipo, el nombre y (opcionalmente) un valor por defecto o atributos.

PROP(bool simpleBool)                // boolean named simpleBool
PROP(bool defaultFalseBool=false)    // boolean named defaultFalseBool, with false
                                     // as the default value

PROP(int lifeUniverseEverything=42)  // int value that defaults to 42
PROP(QByteArray myBinaryInfo)        // Qt types are fine, may need #include
                                     // additional headers in your rep file

PROP(QString name CONSTANT)          // Property with the CONSTANT attribute
PROP(QString setable READWRITE)      // Property with the READWRITE attribute
                                     // note: Properties default to READPUSH
                                     // (see description below)

PROP(SomeOtherType myCustomType)     // Custom types work. Needs #include for the
                                     // appropriate header for your type, make
                                     // sure your type is known to the metabject
                                     // system, and make sure it supports Queued
                                     // Connections (see Q_DECLARE_METATYPE and
                                     // qRegisterMetaType)

Aquí puede encontrar más información sobre cómo crear tipos personalizados.

Por defecto, las propiedades tendrán definidos getter y una ranura «push», así como una señal «notify» que se emite cuando se cambia el valor. Qt Remote Objects requiere que la señal «notify» del objeto «Source» active el envío de actualizaciones a las réplicas asociadas. En versiones anteriores de QtRO, las propiedades eran por defecto de lectura y escritura, es decir, contaban con métodos getter y setter. Sin embargo, debido a la naturaleza asíncrona de QtRO, esto provocaba en ocasiones un comportamiento poco intuitivo. Al establecer el atributo READWRITE en la propiedad PROP se recuperará el comportamiento anterior (con métodos getter y setter).

// In .rep file, old (setter) behavior
PROP(int myVal READWRITE)             // Old behavior with setMyVal(int myVal) method

// In code...  Assume myVal is initially set to 0 in Source
int originalValue = rep->myVal();     // Will be 0
rep->setMyVal(10);                    // Call setter, expecting a blocking/
                                      // non-asynchronous return

if (rep->myVal() == 10) ...           // Test will usually fail

Si es necesario bloquear hasta que se modifique el valor, hay que hacer algo como lo que se muestra a continuación.

// In .rep file, old (setter) behavior
PROP(int myVal READWRITE)             // Old behavior with setMyVal(int myVal) method

// In code...  Assume myVal is initially set to 0 in Source
bool originalValue = rep->myVal();    // Will be 0

// We can wait for the change using \l QSignalSpy
QSignalSpy spy(rep, SIGNAL(myValChanged(int)));

rep->setMyVal(10);                    // Call setter, expecting a blocking/
                                      // non-asynchronous return

spy.wait();                           // spy.wait() blocks until changed signal
                                      // is received
if (rep->myVal() == 10) ...           // Test will succeed assuming
                                      // 1. Source object is connected
                                      // 2. Nobody else (Source or other Replica)
                                      //    sets the myVal to something else (race
                                      //    condition)
// Rather than use QSignalSpy, the event-driven practice would be to connect the
// myValChanged notify signal to a slot that responds to the changes.

QtRO ahora utiliza READPUSH de forma predeterminada, lo que proporciona una ranura generada automáticamente para solicitar un cambio en la propiedad.

// In .rep file, defaults to READPUSH
PROP(bool myVal)                      // No setMyVal(int myVal) on Replica, has
                                      // pushMyVal(int myVal) instead

// In code...  Assume myVal is initially set to 0 in Source
bool originalValue = rep->myVal();    // Will be 0

// We can wait for the change using \l QSignalSpy
QSignalSpy spy(rep, SIGNAL(myValChanged(int)));

rep->pushMyVal(10);                   // Call push method, no expectation that change
                                      // is applied upon method completion.

// Some way of waiting for change to be received by the Replica is still necessary,
// but hopefully not a surprise with the new pushMyVal() Slot.
spy.wait();                           // spy.wait() blocks until changed signal
                                      // is received
if (rep->myVal() == 10) ...           // Test will succeed assuming
                                      // 1. Source object is connected
                                      // 2. Nobody else (Source or other Replica)
                                      //    set the myVal to something else (race
                                      //    condition)

También se pueden utilizar las palabras clave « CONSTANT », « READONLY », « PERSISTED », « READWRITE », « READPUSH » o « SOURCEONLYSETTER » en la declaración de la PROP, lo que afecta a la forma en que se implementa la propiedad. «READPUSH» es el valor por defecto si no se especifica ninguno.

PROP(int lifeUniverseEverything=42 CONSTANT)
PROP(QString name READONLY)

Ten en cuenta que aquí hay algunas sutilezas. Una PROP CONSTANTE tiene un Q_PROPERTY declarado como CONSTANTE en el lado SOURCE. Sin embargo, las réplicas no pueden conocer el valor correcto hasta que se inicialicen, lo que significa que debe permitirse que el valor de la propiedad cambie durante la inicialización. En el caso de READONLY, la fuente no tendrá ni un setter ni un push slot, y en el lado de la réplica no se generará ningún push slot. Al añadir el rasgo PERSISTED a una PROP, esta utilizará la instancia de QRemoteObjectAbstractPersistedStore establecida en un nodo (si la hay) para guardar o restaurar los valores de la PROP.

Otro valor matizado es SOURCEONLYSETTER, que ofrece otra forma de especificar un comportamiento asimétrico, en el que la fuente (concretamente la clase auxiliar SimpleSource) tendrá un getter y un setter públicos para la propiedad, pero será de solo lectura (con una señal de notificación) en el lado de la réplica. De este modo, la propiedad puede controlarse por completo desde el lado de la Fuente, pero solo observarse desde el lado de la Réplica. SOURCEONLYSETTER es el modo utilizado por repc para las instancias de MODEL y CLASS, lo que significa que la Fuente puede modificar el objeto al que apunta, pero la Réplica no puede proporcionar un nuevo objeto, ya que no se genera ningún método set<Prop> ni push<Prop>. Ten en cuenta que esto no afecta al comportamiento de las propiedades del tipo al que apunta, sino únicamente a la capacidad de modificar el propio puntero.

CLASS

La palabra clave CLASS genera elementos especiales de tipo « Q_PROPERTY » para objetos derivados de QObject. Estas propiedades tienen la misma semántica que SOURCEONLYSETTER. La sintaxis es la palabra clave CLASS seguida del nombre de la propiedad y, a continuación, del tipo de subobjeto entre paréntesis.

// In .rep file
class OtherClass
{
    PROP(int value)
}

class MainClass
{
    CLASS subObject(OtherClass)
}

MODEL

La palabra clave MODEL genera elementos especiales de tipo « Q_PROPERTY » para objetos derivados de QAbstractItemModel. Estas propiedades tienen la misma semántica que SOURCEONLYSETTER. La sintaxis es la palabra clave MODEL seguida del nombre de la propiedad y, a continuación, paréntesis que encierran los roles (separados por comas) que deben exponerse a la réplica.

// In .rep file
class CdClass
{
    PROP(QString title READONLY)
    MODEL tracks(title, artist, length)
}

SIGNAL

Los métodosde señal se crean utilizando la palabra clave SIGNAL en el archivo rep.

Para utilizarlos, hay que declarar « SIGNAL » seguido de la firma deseada entre paréntesis. Se debe omitir el valor de retorno «void».

SIGNAL(test())
SIGNAL(test(QString foo, int bar))
SIGNAL(test(QMap<QString,int> foo))
SIGNAL(test(const QString &foo))
SIGNAL(test(QString &foo))

Al igual que en las funciones « queued connections » de Qt XML, los parámetros de las señales que sean referencias se copiarán al pasárselos a las réplicas.

SLOT

Los métodosde ranura se crean utilizando la palabra clave SLOT en el archivo rep.

Para utilizarlos, hay que declarar « SLOT », seguido de la firma deseada entre paréntesis. El valor de retorno puede incluirse en la declaración. Si se omite el valor de retorno, se utilizará «void» en los archivos generados.

SLOT(test())
SLOT(void test(QString foo, int bar))
SLOT(test(QMap<QString,int> foo))
SLOT(test(QMap<QString,int> foo, QMap<QString,int> bar))
SLOT(test(QMap<QList<QString>,int> foo))
SLOT(test(const QString &foo))
SLOT(test(QString &foo))
SLOT(test(const QMap<QList<QString>,int> &foo))
SLOT(test(const QString &foo, int bar))

Al igual que en las « queued connections » de Qt XML y las «SIGNALS» de QtRO, los parámetros de las «slots» que sean referencias se copiarán al pasarlos a las réplicas.

ENUM

Las enumeraciones (que utilizan una combinación de la enumeración de C++ y « Q_ENUM » de Qt en QtRO) se describen mediante la palabra clave ENUM.

ENUM MyEnum {Foo}
ENUM MyEnum {Foo, Bar}
ENUM MyEnum {Foo, Bar = -1}
ENUM MyEnum {Foo=-1, Bar}
ENUM MyEnum {Foo=0xf, Bar}
ENUM MyEnum {Foo=1, Bar=3, Bas=5}

Temas relacionados: El tipo ENUM, la palabra clave USE_ENUM

El tipo POD

«Plain Old Data» (POD) es un término que describe una colección de datos simple, similar a una estructura de C++. Por ejemplo, si tienes una API para una agenda telefónica, es posible que quieras utilizar el concepto de «dirección» en su interfaz (donde la dirección podría incluir calle, ciudad, provincia, país y código postal). Puedes utilizar la palabra clave POD para definir objetos como este, que luego pueden utilizarse en las definiciones de PROP/SIGNAL/SLOT dentro de las definiciones de tus clases.

Para utilizarlo, hay que declarar « POD », seguido del nombre del tipo generado y, a continuación, de pares de tipo y nombre separados por comas, en los que los pares de tipo/nombre van entre paréntesis.

POD Foo(int bar)
POD Foo(int bar, double bas)
POD Foo(QMap<QString,int> bar)
POD Foo(QList<QString> bar)
POD Foo(QMap<QString,int> bar, QMap<double,int> bas)

Un ejemplo completo quedaría así

POD Foo(QList<QString> bar)
class MyType
{
    SIGNAL(sendCustom(Foo foo));
};

El código generado por repc crea una clase ` Q_GADGET ` para cada POD, con los miembros ` Q_PROPERTY ` correspondientes para cada tipo definido para el POD.

Al utilizar los archivos de cabecera generados dentro de una biblioteca, puede ser necesario definir atributos de clase para establecer la visibilidad de los símbolos. Esto se puede hacer definiendo el atributo después de la palabra clave « POD ». En el siguiente ejemplo se utiliza la macro « MYSHAREDLIB_EXPORT », que está definida en "mysharedlib_global.h". Consulta «Creación de bibliotecas compartidas» para obtener más información sobre cómo funciona esto.

#include "mysharedlib_global.h"
POD MYSHAREDLIB_EXPORT Foo(int bar)

El tipo ENUM

A menudo resulta más sencillo y limpio definir un ENUM dentro de una clase (véase ENUM), pero si necesitas un tipo ENUM independiente, puede resultar útil utilizar la palabra clave ENUM fuera de la definición de una clase. Esto generará una nueva clase en tus archivos de cabecera que se encargará del marshalling, etc. La sintaxis es idéntica a la de ENUM, con la excepción de que, en este caso, la declaración no está contenida en una declaración « class ».

Temas relacionados: ENUM, palabra clave USE_ENUM

Palabra clave USE_ENUM

La palabra clave USE_ENUM se implementó antes de que se añadiera la generación automática mediante la palabra clave ENUM. Se mantiene por motivos de compatibilidad con versiones anteriores.

Temas relacionados: ENUM, el tipo ENUM

Directivas

El archivo rep define una interfaz, pero las interfaces suelen requerir elementos externos. Para dar soporte a esto, repc incluirá cualquier directiva (de una sola línea) al principio de los archivos generados. Esto te permite, por ejemplo, utilizar directivas #include o #define que den soporte a la lógica o los tipos de datos necesarios.

Actualmente, la herramienta repc ignora todo lo que hay desde el símbolo «#» hasta el final de la línea y lo añade a los archivos generados. Por lo tanto, no se admiten las sentencias #if/#else/#endif de varias líneas ni las macros de varias líneas.

Existen dos directivas especiales: #HEADER y #FOOTER. Estas directivas pueden utilizarse para definir contenido que debe incluirse tal cual en el código generado, ya sea antes (HEADER) o después (FOOTER) de la declaración de las interfaces. Se eliminan los tokens iniciales #HEADER y #FOOTER, junto con un carácter de espacio en blanco.

En el siguiente ejemplo, las clases repc generadas se colocan dentro de un espacio de nombres.

#HEADER namespace MyNamespace {
class MyType
{
    ...
};
#FOOTER } // namespace MyNamespace

Funciones de CMake

A continuación se enumeran las funciones de CMake para generar tipos de origen y réplica.

qt_add_repc_merged

Crea archivos de cabecera de C++ para tipos de origen y réplica a partir de los archivos .rep de Qt Remote Objects.

qt_add_repc_replicas

Crea archivos de cabecera de C++ para tipos de réplica a partir de los archivos .rep de Qt Remote Objects.

qt_add_repc_sources

Crea archivos de cabecera de C++ para los tipos de origen a partir de los archivos .rep de Qt Remote Objects.

qt_reps_from_headers

Crea archivos .rep a partir de los archivos de cabecera de QObject.

Variables de qmake

REPC_REPLICA

Especifica los nombres de todos los archivos .rep del proyecto que deben utilizarse para generar archivos de cabecera de réplica.

Por ejemplo:

REPC_REPLICA = media.rep \
               location.rep

Los archivos generados tendrán el formato rep_<replica file base>_replica.h.

REPC_SOURCE

Especifica los nombres de todos los archivos rep del proyecto que deben utilizarse para generar los archivos de cabecera de código fuente.

Por ejemplo:

REPC_SOURCE = media.rep \
              location.rep

Los archivos generados tendrán el formato rep_<replica file base>_source.h.

REPC_MERGED

Especifica los nombres de todos los archivos «rep» del proyecto que deben utilizarse para generar archivos de cabecera combinados (de código fuente y réplica).

Por ejemplo:

REPC_MERGED = media.rep \
              location.rep

Los archivos generados tendrán el formato rep_<replica file base>_merged.h.

Nota: Normalmente , las fuentes y las réplicas se encuentran en procesos o dispositivos distintos, por lo que esta variable no se utiliza habitualmente.

QOBJECT_REP

Especifica los nombres de los archivos de cabecera « QObject » existentes que deben utilizarse para generar los archivos .rep correspondientes.

Véase también QRemoteObjectAbstractPersistedStore.

© 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.