Member Function Documentation

EnginioClient::EnginioClient(QObject *parent = Q_NULLPTR)

Creates a new EnginioClient with parent as QObject parent.

EnginioClient::~EnginioClient()

Destroys the EnginioClient.

This ends the Enginio session.

EnginioReply *EnginioClient::create(const QJsonObject &object, const Enginio::Operation operation = Enginio::ObjectOperation)

Insert a new object into the database.

The returned EnginioReply indicates the success of the object creation. The object becomes available from the backend if it finishes without errors.

operation determines the kind of object created. For example a regular object or a user or usergroup. By default, Enginio::ObjectOperation is used and regular objects created.

Note: that the objectType is required for regular objects and has to begin with "objects.".

The JSON for the object that will be created must follow this structure:

{
    "objectType": "object.myType",
    "name" : "A thing",
    "price" : "5",
}

Where only the objectType property is required and name and price are examples of custom properties.

Users and all kinds of other objects are created the same way but do not require any objectType.

QJsonObject query;
query["objectType"] = QString::fromUtf8("objects.todos");
query["title"] = QString::fromUtf8("A todo");
query["completed"] = true;
const EnginioReply* response = client.create(query);

To add a new member to a usergroup, the JSON needs to look like the example below.

{
    "id": "groupId",
    "member": { "id": "userId", "objectType": "users" }
}

It can be constructed like this:

QJsonObject query;
query["id"] = groupId;
QJsonObject user;
user["id"] = userId;
user["objectType"] = QString::fromUtf8("users");
query["member"] = user;

EnginioReply *reply = client.create(query, Enginio::UsergroupMembersOperation);

Returns an EnginioReply containing the status and data once it is finished.

See also EnginioReply, query(), update(), remove(), and Enginio::Operation.

EnginioReply *EnginioClient::downloadUrl(const QJsonObject &object)

Get a temporary URL for a file stored in Enginio

From this URL a file can be downloaded. The URL is valid for a certain amount of time as indicated in the reply.

QJsonObject object;
object["id"] = fileId; // ID of an existing object with attached file

const EnginioReply *replyDownload = _client.downloadUrl(object);

The propertyName can be anything, but it must be the same as the one used to upload the file with. This way one object can have several files attached to itself (one per propertyName).

If a file provides several variants, it is possible to request a variant by including it in the object.

{
    "id": "abc123",
    "variant": "thumbnail"
}

[signal] void EnginioClient::error(EnginioReply *reply)

This signal is emitted when a request to the backend returns an error.

The reply contains the details about the error that occured.

See also EnginioReply.

[signal] void EnginioClient::finished(EnginioReply *reply)

This signal is emitted when a request to the backend finishes.

The reply contains the data returned. This signal is emitted for both, successful requests and failed ones.

From this moment on ownership of the reply is moved from EnginioClient, therefore it is the developer's responsibility to delete the reply after this signal is handled. That can be achieved by calling the deleteLater() method of the reply.

See also EnginioReply.

EnginioReply *EnginioClient::fullTextSearch(const QJsonObject &query)

Fulltext search on the Enginio backend

The query is JSON sent to the backend to perform a fulltext search. Note that the search requires the searched properties to be indexed (on the server, configureable in the backend).

Returns EnginioReply containing the status and the result once it is finished.

See also EnginioReply, create(), query(), update(), remove(), Address book example, and JSON request structure.

EnginioReply *EnginioClient::query(const QJsonObject &query, const Enginio::Operation operation = Enginio::ObjectOperation)

Query the database

The query is an object containing the actual query to the backend. The query will be run on the operation part of the backend.

The query has to contain an "objectType" which has to point to a type defined in the backend. Optionally, it can also contain:

• query - describes how objects are queried, allows filtering of results. See {https://engin.io/documentation/rest/parameters/queries} {JSON query structure}
• limit - limits how many objects the server should return (default value is 100).
• offset - how many objects the server should skip from the beginning of the returned results. Note that the server keeps the data in random order so that usage of offset implies using sort as well.
• sort - describes how results are sorted. See JSON sort request structure
• count - if the count is set, the server will return only count of matching objects
• include - describes which other objects are included in the response. See JSON include structure

The JSON to list all objects of type "objects.image":

{
    "objectType": "objects.image"
}

An example using include to get file references and with a query parameter that limits the results to only those objects where the reference is valid:

{
    "objectType": "objects.image",
    "include": {"file": {}},
    "query" : { "file": { "$ne": null } }
}

To query the database for all objects of the type "objects.todo":

QJsonObject query;
query["objectType"] = QString::fromUtf8("objects.todos");
EnginioReply *reply = client.query(query);

Returns an EnginioReply containing the status and the result once it is finished.

See also EnginioReply, create(), update(), and remove().

EnginioReply *EnginioClient::remove(const QJsonObject &object, const Enginio::Operation operation = Enginio::ObjectOperation)

Remove an object from the database.

The object that is to be removed is identified by its object ID and if it is a regular object also objectType.

The JSON that identfies an object looks like this:

{
    "objectType": "objects.images",
    "id": "52b1a94b5a3d8b15b1037ff5"
}

The operation is the area from which the object gets removed. It defaults to Enginio::ObjectOperation to remove regular objects by default.

To remove a todo object:

QJsonObject query;
query["objectType"] = QString::fromUtf8("objects.todos");
query["id"] = objectId;
const EnginioReply *response = client.remove(query);

Returns an EnginioReply containing the status and the data once it is finished.

See also EnginioReply, create(), query(), and update().

[signal] void EnginioClient::sessionAuthenticated(EnginioReply *reply) const

Emitted when a user logs in.

The signal is emitted after a user was successfully logged into the backend. From that point on, all communication with the backend will be using these credentials. The reply contains the information about the login and the user. The details may be different depending on the authentication method used, but a typical reply look like this:

{
  "access_token": "...",              // oauth2 access token
  "refresh_token": "...",             // oauth2 refresh token
  "token_type": "bearer",             // oauth2 token type
  "expires_in": 28799,                // oautth2 token expiry date
  "enginio_data": {
    "user": {
      "id": "...",                    // this user Id
      "createdAt": "...",             // when the user was created
      "creator": {                    // who created the user
        "id": "creatorId",
        "objectType": "users"
      },
      "email": "user@user.com",       // the user's email address
      "firstName": "John",            // the user's first name
      "lastName": "Foo",              // the user's last name
      "objectType": "users",
      "updatedAt": "2013-11-25T14:54:58.957Z",
      "username": "JohnFoo"           // the user's login
    },
    "usergroups": []                  // usergroups to which the user belongs
  }
}

Note: The reply will be deleted automatically after this signal, so it can not be stored.

See also sessionAuthenticationError(), EnginioReply, and EnginioOAuth2Authentication.

[signal] void EnginioClient::sessionAuthenticationError(EnginioReply *reply) const

Emitted when a user login fails.

The reply contains the details about why the login failed.

Note: The reply will be deleted automatically after this signal, so it can not be stored.

See also sessionAuthenticated(), EnginioReply, EnginioClientConnection::identity(), and EnginioOAuth2Authentication.

[signal] void EnginioClient::sessionTerminated() const

Emitted when a user logs out.

See also EnginioClientConnection::identity() and EnginioOAuth2Authentication.

EnginioReply *EnginioClient::update(const QJsonObject &object, const Enginio::Operation operation = Enginio::ObjectOperation)

Update an object in the database.

The operation is the area in which the object gets updated. It defaults to Enginio::ObjectOperation to update regular objects by default.

To change the name property of an object to "New Name", use the following JSON:

{
    "id": "objectId",
    "objectType": "objects.objectType",
    "name": "New Name"
}

All other existing properties of the object are not affected by the update.

To update the access control list of an object, use the following JSON:

{
    "id": "objectId",
    "objectType": "objects.objectType",
    "access": { "read": ["id": "userId", "objectTypes": "users"],
                "update": ["id": "userId", "objectTypes": "users"],
                "admin": ["id": "userId", "objectTypes": "users"] }
}

In C++, the updating of the ACL could be done like this:

QJsonObject aclUpdate;
aclUpdate["objectType"] = obj["objectType"];
aclUpdate["id"] = obj["id"];
QString json = "{ \"read\": [ { \"id\": \"%3\", \"objectType\": \"users\" } ],"
                 "\"update\": [ { \"id\": \"%2\", \"objectType\": \"users\" } ],"
                 "\"admin\": [ { \"id\": \"%1\", \"objectType\": \"users\" } ] }";
json = json.arg(id1, id2, id3);
aclUpdate["access"] = QJsonDocument::fromJson(json.toUtf8()).object();

reqId = client.update(aclUpdate, Enginio::AccessControlOperation);

Returns an EnginioReply containing the status of the query and the data once it is finished.

See also EnginioReply, create(), query(), and remove().

EnginioReply *EnginioClient::uploadFile(const QJsonObject &object, const QUrl &file)

Stores a file attached to an object in Enginio

Each uploaded file needs to be associated with an object in the database.

Note: The upload will only work with the propper server setup: in the dashboard create a property of the type that you will use. Set this property to be a reference to files.

Each uploaded file needs to be associated with an object in the database.

In order to upload a file, first create an object:

QJsonObject obj;
obj["objectType"] = QString::fromUtf8("objects.FilesFileUploadDownload");
const EnginioReply* createReply = _client.create(obj);

Then do the actual upload:

QJsonObject object;
object["id"] = _id;
object["objectType"] = QString::fromUtf8("objects.FilesFileUploadDownload");
object["propertyName"] = QStringLiteral("fileAttachment");

QJsonObject fileObject;
fileObject[QStringLiteral("fileName")] = fileName;

QJsonObject uploadJson;
uploadJson[QStringLiteral("targetFileProperty")] = object;
uploadJson[QStringLiteral("file")] = fileObject;
const EnginioReply *responseUpload = _client.uploadFile(uploadJson, QUrl(filePath));

Note: There is no need to directly delete files. Instead when the object that contains the link to the file gets deleted, the file will automatically be deleted as well.

See also downloadUrl().