This thread will be a running log of my efforts to learn/reverse-engineer how to create Synergy synchronization connectors, starting with a Messaging app bridge. This augments the official documentation. I'll update this first post as my notes expand…
# Synergy Notes
## Futures
- webOS was built before async ES6, and even before promises. Palm had their own solution called futures.
- They work like async -- the argument for a future-enabled function is the "call back" function that will be invoked with the async call is completed.
- Thus futures can be nested within another futures callback...
futuristicFunction(futuristicCallback {
futuristicFunction2(futuristicCallBack2 {
//do stuff
});
});
## Kinds
- Not to be confused with Enyo's kinds (which are usually user-oriented) DB8 will only store data of a pre-declared structure **kind**.
- These structures usually (always?) derive from a pre-existing kind.
- Apps many usually only interact with their own kinds. But the kind owner may grant another app permission to interact with its own kinds.
- Since apps can't interact with Palm's kinds, they need to derive a sub-kind that they *can* interact with.- Thus an app that wants to sync contacts must derive its own sub-kind of contacts which it can control -- without effecting the contacts that Palm's contact kind created.
- I suspect (but do not know) that parent kind owners can probably also interact with descended kinds.
## Storing/Retreiving Data
- Data is stored in DB8 and you can put or get with JSON queries like: var q ={ "query":{ "from":"com.wosa.imessage.immessage:1", "where":[{"prop":"accountId","op":"=","val":args.accountId}] }};
- You can interact with DB8 using Palm calls and Futures like: PalmCall.call("palm://com.palm.db/", "get", q).then( function(futureResult) {});
- Foundations includes an abstraction library called DB that makes things a little easier: DB.find(q, false, false).then(function(futureResult) {});
- If you use DB. your queries should *not* be wrapped in query:{} -- you just need the contents of the query.
## Adding Messages
- The Messages app uses two kinds (and their registered derivations): `com.palm.chatthread:1` and `com.palm.message:1`
- As noted above, only Palm apps can insert new data of these base kinds, but your app can derive its own sub-kinds and insert/delete/update those.
- All kinds and subkinds records in DB8 from the two base messaging kinds will be automatically rendered in the messaging app -- as long as their structure and required fields are *perfectly* populated!
- `chatthread` records are the data for the chat list on the left of the Messages UI
- `message` records are data for the individual messages in a chat thread
- `message` records include a field called `conversations` that is a (single item) array that is the id of the chatthread the message belongs to
- If a `message` record is inserted that does have the `conversations` array populated, a new `chatthread` will be created -- be careful with your own message kinds, as its the apps responsibility to link messages to the newly created `chatthread`
- You can see the behavior on the command line by instructing the OS to create standard messaging records via the Luna servicebus -- you cannot do this in your own app, however, because your app can only interact with its own kinds (see above)...
#outbound unthreaded message
luna-send -n 1 -a com.palm.app.messaging palm://com.palm.db/put '{"objects":[ {"_kind":"com.palm.smsmessage:1","_sync":true,"flags":{"visible":true},"folder":"outbox","localTimestamp":1530497493511,"messageText":"Sending a message that has no chat thread","serviceName":"type_iMessage","status":"successful","to":[{"addr":"555-1234","name":"Some Recipient"}]}]}'
#inbound unthreaded message
luna-send -n 1 -a com.palm.app.messaging palm://com.palm.db/put '{"objects":[ {"_kind":"com.palm.smsmessage:1","_sync":true,"flags":{"visible":true},"folder":"inbox","localTimestamp":1707599949529,"messageText":"Receiving a message that has no chat thread","serviceName":"type_iMessage","status":"successful","replyAddress":"555-1234","displayName":"Sender Name","from":[{"addr":"5551234","name":"This Sender"}],"to":[{"addr":"5551234","name":"This Recipient"}]}]}'
#outbound threaded message
luna-send -n 1 -a com.palm.app.messaging palm://com.palm.db/put '{"objects":[ {"_kind":"com.palm.smsmessage:1","_sync":true,"conversations":["++NG2jk9ODNPXe6E"],"flags":{"visible":true},"folder":"outbox","localTimestamp":1428816144250,"messageText":"Sending a message that belongs to an existing chat thread with conversation ID ++NG2jk9ODNPXe6E","readRevSet":1774230,"serviceName":"sms","status":"pending","to":[{"_id":"1b1297","addr":"5551234","name":"This Sender"}]}]}'
Thanks to grabber for the sample luna commands.
