SyncMessage Function

Format

s = syncmessage(message_nameʃ, message_valueʅ);

Description

The syncmessage function sends a message to a synchronization service. The string expression message_name identifies the message, and an optional string expression message_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 is a CSPro logic function. Similar functionality is available using the Sync.sendMessage action. When using actions, multiple synchronization sessions can be created, whereas using CSPro logic, there is only one session per call to syncconnect.

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 response returned by OnSyncMessage. If no such function exists, an error is shown and the function returns a blank string.

If connected to another synchronization service, the response is a blank string unless the service has been modified to return responses.

Example

// on the Bluetooth client:
syncmessage("STAFF_CODE", STAFF_CODE);

if syncmessage("TRAINING_MODE") <> maketext("%d", TRAINING_MODE) then
errmsg("You cannot sync with a device that is not in the same training mode as your device.");
syncdisconnect();
endif;

// on the Bluetooth server:
PROC GLOBAL

function string OnSyncMessage(string message_name, string message_value)

// store information about the sync in the paradata log
if message_name = "STAFF_CODE" then
logtext("Syncing with %s at %s", message_value, timestring());

// return the training mode
elseif message_name = "TRAINING_MODE" then
exit maketext("%d", TRAINING_MODE);

endif;

end;