Home - Documentation

Javascript QDatastream (de)serializer.

List of types handled for (de)serialization: QBool, QShort, QInt, QInt64, QUInt, QUInt64, QDouble, QMap, QList, QString, QVariant, QStringList, QByteArray, QUserType, QDateTime, QTime, QChar, QInvalid

Getting Started

Install the module with npm install node-qtdatastream --production, or npm install node-qtdatastream for development purpose.

Documentation

Technical documentation

Type inference

Javascript types can be automatically converted to Qt Types, and here is the default behavior

javascript to QClass

javascript	QClass
string	QString
number	QUInt (this can be overloaded)
boolean	QBool
Array	QList<QVariant<?>>
Date	QDateTime
Map	QMap<QString, QVariant<?>>
Object	QMap<QString, QVariant<?>>

You can always force any type to be coerced to any Qt type

const { QByteArray } = require('qtdatastream').types;
const s = "hello"; // If given to the writer, it will be coerced to QString
const qbytearray = QByteArray.from(s); // This will write the same string but as a QByteArray

NB: you can change default behavior for number

const { QVariant, Types } = require('qtdatastream').types;
const n = 1; // Would be written as QUInt
QVariant.coerceNumbersTo(Types.DOUBLE); // Will now write any number as QDouble

QClass to javascript

Qt Types are also converted to native javascript type automatically upon reading

QClass	javascript
QString	string
QUInt	number
QInt	number
QUInt64	number
QInt64	number
QDouble	number
QShort	number
QBool	number
QList	Array
QStringList	Array<string>
QByteArray	Buffer
QMap	Object
QUserType	Object
QDateTime	Date
QTime	number
QChar	string
QInvalid	undefined

QUserType special treatment

QUserType are special types defined by user (QVariant::UserType).

QUserType are defined like this <size:uint32><bytearray of size>. bytearray can be casted to string (but it is not a string as intended by Qt, because it is UTF8 and not UTF16) : bytearray.toString(). The resulting string is the QUserType key.

Reader

The Reader use an internal mechanism to know which parser must be used for each QUserType. They are defined like this:

const { QUserType } = require('qtdatastream').types;
QUserType.register("NetworkId", qtdatastream.Types.INT); //NetworkId here is our key

This tell the reader to decode NetworkId bytearray like and INT. But those structures can be much more complicated:

const { QUserType } = require('qtdatastream').types;
QUserType.register("BufferInfo", [
    {id: qtdatastream.Types.INT},
    {network: qtdatastream.Types.INT},
    {type: qtdatastream.Types.SHORT},
    {group: qtdatastream.Types.INT},
    {name: qtdatastream.Types.BYTEARRAY}
]);

The bytearray corresponding to this structure look like this :

  <int32><int32><int16><int32><qbytearray>

The whole new type will be put in a new Object, the id key will contain the first <int32>, the network key will contain the second <int32>, etc. The definition is contained into an array to force a parsing order (here, id will always be the first <int32> block).

UserTypes can also be nested, by specifying the usertype name instead of Qt type :

QUserType.register("BufferInfoContainer", [
    {id: qtdatastream.Types.INT},
    {bufferInfo: "BufferInfo"} // here we reference the BufferInfo QUserType
]);

Keep in mind that if a usertype X references usertype Y, Y should be declared before X.

Writer

Custom usertypes can be defined as for Reader, with the help of QUserType.register method.

Writing UserType is done as follow:

const { Socket } = require('qtdatastream').socket;
const { QUserType } = require('qtdatastream').types;
const qtsocket = new Socket(myRealSocket);

const data = {
    "BufferInfo": new QUserType("BufferInfo", {
        id: 2,
        network: 4,
        type: 5,
        group: 1,
        name: "BufferInfo name"
    })
});

qtsocket.write(data);

Some more examples can be found in test folder.

ES6/7

ES7 decorators can be used to simplify serializable data representation

const { types: { QUserType, QString, QUInt, Types }, serialization: { Serializable, serialize } } = require('qtdatastream');
// Register usertype
QUserType.register('Network::Server', Types.MAP);

@Serializable('Network::Server')
export class Server {
    @serialize(QString, {in: 'HostIn', out: 'HostOut'))
    host;

    @serialize(QUInt, 'Port')
    port = 6667;

    @serialize(QUInt)
    sslVersion = 0;

    constructor(args) {
        this.blob = true; // will not be serialized at export
        Object.assign(this, args);
    }
}

const parsedUserType = {
    HostIn: 'myHost',
    Port: 1234
}; // This usually comes from qtsocket
const server = new Server(parsedUserType);
// server == {
//     host: 'myHost',
//     port: 1234,
//     sslVersion: 0
// }

// This will call server.export() method before sending to the server,
// which exports the object as dictated by Server class and 'Network::Server' usertype
qtsocket.write(server)

Serializable parameter (usertype) is optionnal. If unspecified, it will be exported as a QMap.

If Serializable class implements _export method, the return of this function will be used instead of object own attributes.

@Serializable()
export class Server {
  _export() {
    return {
      'a': 'b'
    };
  }
}

Example

const { Socket } = require('qtdatastream').socket;
const { QUserType } = require('qtdatastream').types;
const net = require('net');

var client = net.Socket();

// Connect to a Qt socket
// and write something into the socket
client.connect(65000, "domain.tld", function(){
    const qtsocket = new Socket(client);

    // Here data is the already parsed response
    qtsocket.on('data', function(data) {
        //...
    });

    // Write something to the socket
    qtsocket.write({
        "AString": "BString",
        "CString": 42
    });
});

Debugging

Debug mode can be activated by setting environment variable DEBUG in your shell before launching your program:

export DEBUG="qtdatastream:*"