PpsObject

Since: BlackBerry 10.0.0

#include <bb/PpsObject>

To link against this class, add the following line to your .pro file: LIBS += -lbb

Encapsulates an object in the PPS file system.

See the PPS documentation for more details.


Overview

Public Functions Index

PpsObject (const QString &path, QObject *parent=0)
virtual ~PpsObject ()
boolclose ()
interror () const
QStringerrorString () const
boolisBlocking () const
boolisOpen () const
boolisReadyReadEnabled () const
boolopen (PpsOpenMode::Types mode=PpsOpenMode::PublishSubscribe)
QByteArrayread (bool *ok=0)
boolremove ()
boolsetBlocking (bool enable)
boolwrite (const QByteArray &byteArray)
intwriteMessage (const QString &msg, const QVariantMap &dat)
intwriteMessage (const QString &msg, const QString &id, const QVariantMap &dat)

Static Public Functions Index

QVariantMapdecode (const QByteArray &rawData, bool *ok=0)
QMap< QString, PpsAttribute >decodeWithFlags (const QByteArray &rawData, bool *ok=0)
QMap< QString, PpsAttribute >decodeWithFlags (const QByteArray &rawData, PpsAttribute *objectAttribute, bool *ok=0)
QByteArrayencode (const QVariantMap &ppsData, bool *ok=0)
QByteArrayencodeMessage (const QString &msg, const QVariantMap &dat, bool *ok=0)
QByteArrayencodeMessage (const QString &msg, const QString &id, const QVariantMap &dat, bool *ok=0)
intsendMessage (const QString &path, const QString &message)
intsendMessage (const QString &path, const QVariantMap &message)
intsendMessage (const QString &path, const QString &msg, const QVariantMap &dat)
intsendMessage (const QString &path, const QByteArray &ppsData)

Public Slots Index

voidsetReadyReadEnabled (bool enable)

Signals Index

voidreadyRead ()

Public Functions

PpsObject (

Creates a new PpsObject that manages the specified object in the PPS file systems.

Open options may be specified as a suffix to the path, following a question mark ("?"). See the PPS documentation for more details.

Note the PPS object must be opened via a separate call to open() before data can be read or written.

Parameters
path

File system path of the PPS object to encapsulate.

parent

If not 0, the supplied parent will be responsible for deleting this instance.

Since:

BlackBerry 10.0.0

virtual~PpsObject ()

Destructor.

Since:

BlackBerry 10.0.0

bool close ()

Closes the previously opened PPS object.

Return:

A flag indicating the success of the operation. On failure, call error() to identify the cause.

Note:

The PPS object must be open to use this method. Otherwise, this method returns false and error() returns EBADF.

Since:

BlackBerry 10.0.0

int error ()

Returns the POSIX error code for the last API called on this object.

Return:

EOK if the last API call succeeded or the POSIX error code (from errno.h) if the last API call failed.

Since:

BlackBerry 10.0.0

QString errorString ()

Returns a human-readable description of the POSIX error code for the last API called on this object.

Return:

The value returned by strerror() (from string.h) for error().

Since:

BlackBerry 10.0.0

bool isBlocking ()

Checks if the PPS object is in blocking or non-blocking mode.

In blocking mode, calling read() and write() will block until data can be read or written. In non-blocking, read() and write() will fail (error() returns EAGAIN) if data cannot be read or written immediately.

PPS objects are by default opened in non-blocking mode. Appending "?wait" to the file system path defaults to blocking mode.

Note the PPS object must be open to use this method. Otherwise, this method returns false and error() returns EBADF.

Return:

A flag indicating if the PPS object uses blocking or non-blocking I/O.

Since:

BlackBerry 10.0.0

bool isOpen ()

Checks if the PPS object is currently open.

Return:

A flag indicating if the PPS object is open or not.

Since:

BlackBerry 10.0.0

bool isReadyReadEnabled ()

Determine if the readyRead() signal will fire when data is available.

Checks if the readyRead() signal will fire when the PPS object has data available for reading. The readyRead() signal is enabled by default.

Return:

A flag indicating if the readyRead() signal is active.

Since:

BlackBerry 10.0.0

bool open (
  • PpsOpenMode::Typesmode)

Opens the PPS object in the specified mode.

See PpsOpenMode for more details.

Parameters
mode

A bitfield of PpsOpenMode flag values.

Return:

A flag indicating the success of the operation. On failure, call error() to identify the cause.

Note:

The PPS object must be closed to used this method. Otherwise, this method returns false and error() returns EBUSY.

Since:

BlackBerry 10.0.0

QByteArray read (
  • bool *ok)

Reads the current content of PPS object.

If no data is available to read and the PPS object is in blocking mode, then this method will block until data is available for reading. If no data is available to read and the PPS object is in non-blocking mode, then this method will fail and error() returns EAGAIN. Use the readyRead() signal to know when data is available for reading.

Parameters
ok

If not 0: *ok is set to true if the read succeeded; otherwise *ok is set to false. On failure, call error() to identify the cause.

Return:

A buffer containing the data read from the PPS object.

Since:

BlackBerry 10.0.0

bool remove ()

Deletes the object managed by this PpsObject from the PPS file system.

Return:

A flag indicating the success of the operation. On failure, call error() to identify the cause.

Since:

BlackBerry 10.0.0

bool setBlocking (
  • boolenable)

Toggles blocking or non-blocking I/O for the PPS object.

In blocking mode, calling read() and write() will block until data can be read or written. In non-blocking, read() and write() will fail (error() returns EAGAIN) if data cannot be read or written immediately.

PPS objects are by default opened in non-blocking mode. Appending "?wait" to the file system path defaults to blocking mode.

Parameters
enable

A flag indicating if the PPS object should use blocking or non-blocking I/O.

Return:

A flag indicating the success of the operation. On failure, call error() to identify the cause.

Note:

The PPS object must be open to use this method. Otherwise, this method returns false and error() returns EBADF.

Since:

BlackBerry 10.0.0

bool write (

Writes all the data in the provided buffer to the PPS object.

The size of the buffer is determined by calling QByteArray::size().

If no data can be written and the PPS object is in blocking mode, then this method will block until the PPS object becomes writable. If no data can be written and the PPS object is in non-blocking mode, then this method will fail and error() returns EAGAIN.

Parameters
byteArray

The buffer that contains the data to write to the PPS object.

Return:

true if the write succeeded, false otherwise. On failure, call error() to identify the cause.

Since:

BlackBerry 10.0.0

int writeMessage (

Encodes the supplied data and writes it to the opened PPS path.

The msg and dat parameters are encoded as part of the raw PPS data to be sent to the opened PPS path.

The msg parameter will be added as the message type. 'ppsData["msg"] = msg' The dat parameter will be added as the data payload. 'ppsData["dat"] = encode( dat )

If no data can be written and the PPS object is in blocking mode, then this method will block until the PPS object becomes writable. If no data can be written and the PPS object is in non-blocking mode, then this method will fail and error() returns EAGAIN.

Example usage in C++
    bb::PpsObject ppsObject( "/pps/services/sample/control" );

    if (ppsObject.open( bb::PpsOpenMode::Publish )) {
        QVariantMap payload;
        payload["key"] = "value";

        int result = ppsObject.writeMessage( "reset", payload );
        if (result == EOK) {
            // Sending the message was successful
        }
    }

Parameters
msg

The value to be encoded as the 'msg' entry.

dat

The value to be encoded as the 'dat' entry.

Return:

If the entire operation is successful, EOK is returned. If there was an error encoding the supplied data, -1 will be returned. If there was an error writing the data to the PPS path the value available in PpsObject::error() is returned and PpsObject::errorString() will contain a textual description of the error. See PpsObject::error() and PpsObject::errorString() for more details.

Since:

BlackBerry 10.2.0

int writeMessage (

Encodes the supplied data and writes it to the opened PPS path.

The msg, id and dat parameters are encoded as part of the raw PPS data to be sent to the opened PPS path.

The msg parameter will be added as the message type. 'ppsData["msg"] = msg' The id parameter will be added as the message identifier. 'ppsData["id"] = id' The dat parameter will be added as the data payload. 'ppsData["dat"] = encode( dat )

If no data can be written and the PPS object is in blocking mode, then this method will block until the PPS object becomes writable. If no data can be written and the PPS object is in non-blocking mode, then this method will fail and error() returns EAGAIN.

Example usage in C++
    bb::PpsObject ppsObject( "/pps/services/sample/control" );

    if (ppsObject.open( bb::PpsOpenMode::Publish )) {
        QVariantMap payload;
        payload["key"] = "value";

        int result = ppsObject.writeMessage( "reset", "012345", payload );
        if (result == EOK) {
            // Sending the message was successful
        }
    }

Parameters
msg

The value to be encoded as the 'msg' entry.

id

The value to be encoded as the 'id' entry.

dat

The value to be encoded as the 'dat' entry.

Return:

If the entire operation is successful, EOK is returned. If there was an error encoding the supplied data, -1 will be returned. If there was an error writing the data to the PPS path the value available in PpsObject::error() is returned and PpsObject::errorString() will contain a textual description of the error. See PpsObject::error() and PpsObject::errorString() for more details.

Since:

BlackBerry 10.2.0

Static Public Functions

QVariantMap decode (

Read PPS data into a QVariantMap.

Attributes in the PPS file are decoded as follows:
  • number - Decoded to a double. 'doubleVal:n:10.5' is accessed as 'double val = ppsData.value("doubleVal").toDouble();'

  • boolean - Decoded to a bool. 'boolVal:b:true' is accessed as 'bool val = ppsData.value("boolVal").toBool();'

  • string - Decoded as UTF8 data to a QString. 'strVal::test' is accessed as 'QString val = ppsData.value("strVal").toString();'

  • json array - Decoded to a QVariantList. 'arrayVal:json:[10,20]' is accessed as 'QVariantList val = ppsData.value("arrayVal").toList();'

  • json object - Decoded to a QVariantMap. 'objectVal:json:{"val1":10, "val2":20}' is accessed as 'QVariantMap val = ppsData.value("objectVal").toMap();'

  • json null - Decoded as an invalid QVariant.

Parameters
rawData

The raw PPS data.

ok

If not 0: *ok is set to true if the data could be decoded; otherwise *ok is set to false.

Return:

A QVariantMap containing the data in a hierarchical format.

Since:

BlackBerry 10.0.0

QMap< QString, PpsAttribute > decodeWithFlags (

Read PPS data into a PpsAttribute map.

See also:

PpsAttribute

Parameters
rawData

The raw PPS data.

ok

If not 0: *ok is set to true if the data could be decoded; otherwise *ok is set to false.

Return:

A QMap<QString,PpsAttribute> containing the data in a hierarchical format.

Since:

BlackBerry 10.0.0

QMap< QString, PpsAttribute > decodeWithFlags (

Read PPS data into a PpsAttribute map.

Parameters
rawData

The raw PPS data.

objectAttribute

If not 0: On success, *objectAttribute is set to an instance of PpsAttribute that describes the PPS object as a whole. The object will have type String, which will be the name of the PPS object preceded by '@'. The flags will be set to reflect the object state.

ok

If not 0: *ok is set to true if the data could be decoded; otherwise *ok is set to false.

Return:

A QMap<QString,PpsAttribute> containing the data in a hierarchical format.

Since:

BlackBerry 10.0.0

QByteArray encode (

Creates PPS data from the supplied QVariantMap.

Each QVariant value in the map is encoded based on the runtime type:
  • double - Encoded as a number. 'ppsData["doubleVal"] = 10.5;' encodes as 'doubleVal:n:10.5'

  • int - Encoded as a number. 'ppsData["intVal"] = 10;' encodes as 'intVal:n:10'

  • unsigned int - Encoded as a number. 'ppsData["uintVal"] = 10u;' encodes as 'intVal:n:10'

  • bool - Encoded as a boolean. 'ppsData["boolVal"] = true;' encodes as 'boolVal:b:true'

  • QString - Encoded with as a UTF8 string, with default type. 'ppsData["strVal"] = QString("test");' encodes as 'strVal::test'

  • QVariantList - Encoded as a json array. 'ppsData["arrayVal"] = ( QVariantList() << 10 << 20 );' encodes as 'arrayVal:json:[10,20]'

  • QVariantMap - Encoded as a json object. 'QVariantMap map; map["val1"] = 10; map["val2"] = 20; ppsData["objectVal"] = map;' encodes as 'objectVal:json:{"val1":10, "val2":20}'

  • Invalid QVariant - Encoded as a json null. 'ppsData["nullVal"] = QVariant();' encodes as 'nullVal:json:null'

Parameters
ppsData

A QVariantMap containing the data in a hierarchical format.

ok

If not 0: *ok is set to true if the data could be encoded; otherwise *ok is set to false.

Return:

A data buffer containing raw PPS data.

Since:

BlackBerry 10.0.0

QByteArray encodeMessage (

Creates PPS data from the supplied message and data content.

This method can simplify creating the PPS data to send to a PPS path.

The msg parameter will be added as the message type. 'ppsData["msg"] = msg' The dat parameter will be added as the data payload. 'ppsData["dat"] = encode( dat )

For details on how the dat parameter is encoded, see PpsObject::encode.

Example usage in C++
    QVariantMap payload;
    payload["key"] = "value";

    bool ok;
    QByteArray encodedPayload = bb::PpsObject::encodeMessage( "reset", "012345", payload, &ok );
    if (ok) {
        // Encoding was successful
    }
Parameters
msg

The value to be encoded as the 'msg' entry.

dat

The value to be encoded as the 'dat' entry.

ok

If not 0, *ok is set to true if the data could be encoded; otherwise *ok is set to false.

Return:

A data buffer containing raw PPS data.

Since:

BlackBerry 10.2.0

QByteArray encodeMessage (

Creates PPS data from the supplied message and data content.

This method can simplify creating the PPS data to send to a PPS path.

The msg parameter will be added as the message type. 'ppsData["msg"] = msg' The id parameter will be added as the message identifier. 'ppsData["id"] = id' The dat parameter will be added as the data payload. 'ppsData["dat"] = encode( dat )

For details on how the dat parameter is encoded, see PpsObject::encode.

Example usage in C++
    QVariantMap payload;
    payload["key"] = "value";

    bool ok;
    QByteArray encodedPayload = bb::PpsObject::encodeMessage( "reset", "012345", payload, &ok );
    if (ok) {
        // Encoding was successful
    }
Parameters
msg

The value to be encoded as the 'msg' entry.

id

The value to be encoded as the 'id' entry.

dat

The value to be encoded as the 'dat' entry.

ok

If not 0, *ok is set to true if the data could be encoded; otherwise *ok is set to false.

Return:

A data buffer containing raw PPS data.

Since:

BlackBerry 10.2.0

int sendMessage (

Writes the supplied string to the specified PPS path.

Example usage in C++
    int result = bb::PpsObject::sendMessage( "/pps/services/sample/control", "reset:b:true" );
Parameters
path

The PPS path to which the data will be written.

message

The string to be written to the PPS path.

Return:

EOK if the call succeeded or the POSIX error code (from errno.h).

Since:

BlackBerry 10.2.0

int sendMessage (

Encodes the supplied data and writes it to the supplied PPS path.

The supplied message will be encoded using PpsObject::encode() and the resulting PPS data will be written to the supplied path.

Example usage in C++
    QVariantMap payload;
    payload["key"] = "value";
    int result = bb::PpsObject::sendMessage( "/pps/services/sample/control", payload );
Parameters
path

The PPS path to which the data will be written.

message

The value to be encoded and written to the PPS path.

Return:

If the entire operation is successful, EOK is returned. If there was an error encoding the supplied data, -1 will be returned. If the write failed the return value will be one of the POSIX error codes (from errno.h).

Since:

BlackBerry 10.2.0

int sendMessage (

Encodes the supplied data and writes it to the supplied PPS path.

The msg and dat parameters are encoded as part of the raw PPS data to be sent to the supplied PPS path.

The msg parameter will be added as the message type. 'ppsData["msg"] = msg' The dat parameter will be added as the data payload. 'ppsData["dat"] = encode( dat )

Example usage in C++
    QVariantMap payload;
    payload["key"] = "value";
    int result = bb::PpsObject::sendMessage( "/pps/services/sample/control", "reset", payload );
Parameters
path

The PPS path to which the data will be written.

msg

The value to be encoded as the 'msg' entry.

dat

The value to be encoded as the 'dat' entry.

Return:

If the entire operation is successful, EOK is returned. If there was an error encoding the supplied data, -1 will be returned. If the write failed the return value will be one of the POSIX error codes (from errno.h).

Since:

BlackBerry 10.2.0

int sendMessage (

Writes the supplied data to the specified PPS path.

Example usage in C++
    QByteArray payload( "somevalue" );

    int result = bb::PpsObject::sendMessage( "/pps/services/sample/control", "reset", payload );
Parameters
path

The PPS path to which the data will be written.

ppsData

The data to be written to the PPS path.

Return:

EOK if the call succeeded or the POSIX error code (from errno.h).

Since:

BlackBerry 10.2.0

Public Slots

void setReadyReadEnabled (
  • boolenable)

Toggles whether the readyRead() signal will fire when the PPS object has data available for reading.

The readyRead() signal is enabled by default.

Parameters
enable

A flag indicating if the readyRead() signal is active.

Since:

BlackBerry 10.0.0

Signals

void readyRead ()

Indicates the PPS object has data available for reading.

Since:

BlackBerry 10.0.0

Last modified: 2014-03-13

comments powered by Disqus