- Enginio Manual
- Enginio QML Types and Examples
- EnginioClient QML Type
- Enginio 1.0.6 Reference Documentation

# EnginioClient QML Type

Client interface to access Enginio service More...

Import Statement: | `import Enginio 1.0`
Since: | Qt 5.3

- List of all members, including inherited members

## Properties

- authenticationState : Enginio::AuthenticationState
- backendId : string
- identity : EnginioIdentity

## Signals

- error(QJSValue reply)
- finished(QJSValue reply)
- sessionAuthenticated(QJSValue reply)
- sessionAuthenticationError(QJSValue reply)
- sessionTerminated()

## Methods

- EnginioReply create(QJSValue object, Operation operation)
- EnginioReply downloadUrl(QJSValue object)
- EnginioReply fullTextSearch(QJSValue query)
- EnginioReply query(QJSValue query, Operation operation)
- EnginioReply remove(QJSValue query, Operation operation)
- EnginioReply update(QJSValue query, Operation operation)
- EnginioReply uploadFile(QJSValue object, QUrl file)

## Detailed Description

    import Enginio 1.0

EnginioClient is the heart of the QML API for Enginio. It is used for all communication with the Enginio backend. EnginioModel compliments it to make handling of multiple objects simple.

The backend is identified by backend ID.

    EnginioClient {
        id: client
        backendId: "YOUR_BACKEND_ID" // from Enginio Dashboard
    }

Once the backend is configured, it is possible to run queries by calling query on EnginioClient. For example to get all objects stored with the type "objects.image" run this query:

    EnginioClient {
        // ...
        Component.onCompleted: query({"objectType": "objects.image"})
    }

EnginioClient gives you a convenient way to handle the responses to your queryies as well:

    EnginioClient {
        // ...
        onFinished: console.log("Engino request finished." + reply.data)
        onError: console.log("Enginio error " + reply.errorCode + ": " + reply.errorString)
    }

## Property Documentation

authenticationState : Enginio::AuthenticationState

The state of the authentication.

Enginio provides convenient user management. The authentication state reflects whether the current user is authenticated.

See also identity and EnginioOAuth2Authentication.

backendId : string

Enginio backend ID. This can be obtained from the Enginio dashboard.

identity : EnginioIdentity

Property that represents a user. Setting the property will create an asynchronous authentication request, the result of it updates authenticationState

It is allowed to assign a null pointer to the property to terminate the session.

See also authenticationState, sessionAuthenticated, sessionAuthenticationError, and EnginioOAuth2Authentication.

## Signal Documentation

error(QJSValue reply)

This signal is emitted when a reply finishes and contains an error.

finished(QJSValue reply)

This signal is emitted when a reply finishes.

Note: that this signal is alwasy emitted, independent of whether the reply finished successfully or not.

sessionAuthenticated(QJSValue reply)

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 used authentication method, but a typical reply may look like that:

    {
      "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
      }
    }

See also EnginioClient::sessionAuthenticationError(), EnginioReply, and EnginioOAuth2Authentication.

sessionAuthenticationError(QJSValue reply) const

Emitted when a user login fails.

The reply contains the details about why the login failed.

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

sessionTerminated() const

Emitted when a user logs out.

See also EnginioOAuth2Authentication.

## Method Documentation

EnginioReply create(QJSValue object, Operation operation)

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

To create a new user:

    var reply = enginioClient.create(
                { "username": login.text,
                  "password": password.text,
                  "email": userEmail.text,
                  "firstName": userFirstName.text,
                  "lastName": userLastName.text
                }, Enginio.UserOperation)

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

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

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

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

EnginioReply downloadUrl(QJSValue object)

Get the download URL for a file

    var downloadData = {
        "id": uploadReply.data.id,
    }
    var downloadReply = enginio.downloadUrl(downloadData)

The response contains the download URL and the duration how long the URL will be valid.

    downloadReply.data.expiringUrl
    downloadReply.data.expiresAt

See also uploadFile().

EnginioReply fullTextSearch(QJSValue query)

Perform a full text search on the database

The query is an object 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, EnginioClient::create(), EnginioClient::query(), EnginioClient::update(), EnginioClient::remove(), and JSON request structure.

EnginioReply query(QJSValue query, Operation operation)

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 find a usergroup named "allUsers":

    var groupQuery = enginioClient.query({ "query": { "name" : "allUsers" } }, Enginio.UsergroupOperation)

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

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

EnginioReply remove(QJSValue query, Operation operation)

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.

Returns an EnginioReply containing the status once it is finished.

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

EnginioReply update(QJSValue query, Operation operation)

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"] }
    }

Returns an EnginioReply containing the status once it is finished.

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

EnginioReply uploadFile(QJSValue object, 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.

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

    var fileObject = {
        "objectType": AppConfig.testObjectType,
        "title": "Example object with file attachment",
    }
    var reply = enginio.create(fileObject);

Then do the actual upload:

    var objectId = reply.data.id
    var uploadData = {
        "file":{
            "fileName":"test.png"
        },
        "targetFileProperty": {
            "objectType": AppConfig.testObjectType,
            "id": objectId,
            "propertyName": "fileAttachment"
        },
    }
    var uploadReply = enginio.uploadFile(uploadData, fileName)

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().