Sync.sendMessage Action

Format

s = CS.Sync.sendMessage(syncId := ...,
name := ...
ʃ, value := ...ʅ)

Argument	Description	Types / Required
syncId	The resource ID returned by Sync.connect.	number recommended
name	A name to identify the message.	string required
value	A value associated with the message.	string, number, boolean, array, object not required

Description

The Sync.sendMessage action sends a message to a synchronization service.

The connection is identified using syncId, a resource ID returned by Sync.connect. While optional, this should generally be specified explicitly. (If there is only one synchronization session active, the resource ID can be calculated implicitly.)

The string argument name identifies the message. An optional argument value defines a value associated with the message.

Typically messages are sent from one device, a Bluetooth client, to another device that is acting as a Bluetooth server. Using the OnSyncMessage callback function, the server can respond to the message.

This action is similar to the CSPro logic function syncmessage.

OnSyncMessage Callback Function

// OnSyncMessage callback function syntax for Bluetooth servers
function string OnSyncMessage(string message_name, string message_value)
exit message_response;
end;

For devices running as a Bluetooth server, you can add a user-defined function with the name OnSyncMessage that has two string parameters and returns a string. While the syncserver function is running, the OnSyncMessage function is called anytime a message is received. The function's return value is returned to the Bluetooth client.

When sending a message using Bluetooth, if OnSyncMessage is not defined in the server's code, both the server and client devices will display an error message.

Return Value

When connected via Bluetooth, the function returns the string response returned by OnSyncMessage. If no such function exists, an error is shown and the function returns undefined.

If connected to another synchronization service, the response is undefined unless the service has been modified to return responses. In such a case, the return value is of the type of the response set by the synchronization service so it can be a string, an object, etc.

Exceptions

The action throws an exception if any of its arguments are not specified in a valid form, or if:

The synchronization connection ID is not valid.
There is a network error while sending or receiving data from the synchronization service.
There is no OnSyncMessage function on the server's device to handle Bluetooth messages.

Example 1 (JavaScript)

This is a full example of using asynchronous action calls to connect to a synchronization service, send a message, display the response, and disconnect.

let syncId;

// connect to CSWeb, supplying the username and password
CS.Sync.connectAsync({
connection: {
url: "https://example.org/csweb/api",
username: "jackw",
password: "MyPa$$w0rd!"
}
})
.then(id => {
// store the resource ID that identifies this synchronization connection
syncId = id;

// send a message to the server
return CS.Sync.sendMessageAsync({
syncId: syncId,
name: "Demonstrating Sync.sendMessage at: " + new Date().toString()
});
})
.then(response => {
print("Successfully sent a message and received: " + JSON.stringify(response));
})
.finally(() => {
// close the synchronization connection
if( syncId != undefined ) {
return CS.Sync.disconnectAsync({
syncId: syncId
});
}
})
.catch(error => {
print("Error syncing: " + error);
})

Example 2 (JavaScript)

This is an example of sending a message with a value.

// ...syncId received from a previous call to Sync.connect

CS.Sync.sendMessage({
syncId: syncId,
name: "NOTIFY_CSPRO_VERSION",
value: {
version: 8.1,
versionFull: "8.1.0",
versionSerializer: 810001
}
});