Setting and Getting Properties

The QPair service provides a simple way to share data between paired devices without sending Peer Intents. It is called QPair property.

Developers can create a QPair property for a value the peer device needs to know. Values in properties are synchronized when the QPair connection is active. If the QPair connection is lost, the properties remain on the local device and are synchronized as soon as the connection is re-established.

 

The properties are pairs of keys and values.

The key string is a kind of path for describing where the property originated. The rule for key strings is:

 

{location(local|peer)}/{application package}/{key name}

 

The key string consists of three parts. The meaning of each part is described here.

location: It means the owner of the property. It should be either of ‘local’ or ‘peer’. ‘local’ means the property is created by the local device, ‘peer’ means the property is created by the peer device. It is relative. If Device A creates a Property A, the key string of the Property A starts with ‘local’ when the Device A reads it. On the other hand, the key string of Property A starts with ‘peer’ when the Device B which is paired with Device A reads it.

All properties that start with ‘peer’ are read-only.

application package: It is the package name of the QPair-enabled application. You have to use the actual package name of your application. If client package string differs from your package name, the QPair service will deny your request.

key name: It is a name of the property.

 

The property value must be one of the following types:

• floating

• int

• long

• String

 

For example, an application can set a property /local/com.example.qpair/count as 30 or "30".

Using ContentResolver

QPair properties are managed by a content provider. Applications can access the properties using ContentResolver.

The content provider provides the following URI format for accessing the properties:

 

content://com.lge.qpair.property/{property key string}

-- scheme -- --- authority --- ------ path --------

 

The constant strings for the URIs of QPair properties are defined in the QPairConstants class so that developers can use variables instead of raw strings.

QPairConstants.PROPERTY_SCHEME_AUTHORITY contains the scheme string and QPairConstants.PROPERTY_AUTHORITY contains the authority string.

 

The following codes show how to write, modify and delete a property using ContentResolver.

 

 
// write a property
Uri uri = Uri.parse(QPairConstants.PROPERTY_SCHEME_AUTHORITY + 
                                           "/local/com.example.qpair/is_enabled");
ContentValues cv = new ContentValues();
cv.put("", "true");
getContentResolver().insert(uri, cv);

// modify the property
ContentValues cv_update = new ContentValues();
cv_update.put("", "false");
getContentResolver().update(uri, cv_update, null, null);

// delete the property
getContentResolver().delete(uri, null, null);

 

Developers must note the following when writing, modifying, or deleting QPair properties:

1. Generally, ContentValues can have many key-value pairs. However, QPair will take the first item only. Others will be ignored.

2. The value of the ContentValues has to be one the of types the QPair property supports. Otherwise, insert(), update() or delete() will fail to process. In these cases, the methods will return null or 0.

3. The key string of the property needs to start with ‘local’. If it starts with ‘peer’, the process will fail as all properties created by the peer device are read-only. In this case, insert(), update() or delete() will return null or 0.

 

In order to read a property, you need to launch a query for the property and get the first item using the Cursor returned. Developers should know the type of the property value exactly. In the following codes, the value can be read by getString() because the value is a string.

 

 
// read the property
Cursor cursor = getContentResolver().query(uri, null, null, null, null);
String value;
if(cursor != null) {
    try {
        if (cursor.moveToFirst()) {
            value = cursor.getString(0);
        }
    } finally {
        cursor.close();
    }
}

 

Using Metadata

A good solution for creating a QPair property, simply is to declare metadata for the property in AndroidManifest.xml. The QPair service will read the metadata and write it as a QPair property automatically.

Add a <meta-data> tag to your <application> in AndroidManifest.xml as follows:

 

 

 

Properties cannot be read or deleted using metadata. If you want to read or delete a property, you have to use ContentResolver.

 

Monitoring Property Changes

Applications sometimes need to know about changes to properties. For example, if the local application wants to show the logged-in user of the peer device, it needs to check whether the user of the peer device has changed.

This is possible with ContentObserver. The following codes show an example.

 

 
class MyContentObserver extends ContentObserver {
    ...
    @Override
    public void onChange(boolean selfChange) {
        // read the property
        Uri uri = Uri.parse(QPairConstants.PROPERTY_SCHEME_AUTHORITY + 
                                                   "/peer/com.lge.example/user");

        Cursor cursor = getContentResolver().query(
                                                    uri, null, null, null, null);
        String user;
        if(cursor != null) {
            try {
                if (cursor.moveToFirst()) {
                    user = cursor.getString(0);
               }
            } finally {
                cursor.close();
            }
        }
 
       ((TextView) findViewById(R.id.peeruser)).setText(user + "is logged");
    }
}

...

// create a ContentObserver
ContentObserver observer = new MyContentObserver(new Handler());

// register it to the property
Uri uri = Uri.parse(QPairConstants.PROPERTY_SCHEME_AUTHORITY + 
                                               "/peer/com.lge.example/user");
getContentResolver().registerContentObserver(uri, false, observer);

 

For detailed information about ContentObserver, refer to the Android API reference page for the ContentObserver class.

 

The onChange() method will be invoked whenever the property /peer/com.lge.example/user has changed. Developers can do their jobs in that method.

 

Getting QPair Status with Properties

The QPair service provides some default properties to give notification of the QPair status.

The following table provides a list of the default properties.

 

Table 1. QPair Default Properties

Category

Key String

Type

Description

QPair application

/local/qpair/version

int

The version code for the QPair application installed on the local device.

/peer/qpair/version

int

The version code for the QPair application installed on the peer device.

QPair status

/local/qpair/is_on

String

“true” if QPair is on on the local device.

“false” if not.

/local/qpair/is_connected

String

“true” if the two devices are paired.

Local device

/local/qpair/device_type

String

“phone” if the local device is a smartphone.

“tablet” if the local device is a tablet.

Peer device

/peer/qpair/device_type

String

“phone” if the peer device is a smartphone.

“tablet” if the peer device is a tablet.

/peer/qpair/device_name

String

Name of the peer device

/peer/qpair/bluetooth_address

String

Bluetooth MAC address of the peer device

Properties listed in the table above are read-only.

 

Navigation