Synchronization Messages

Overview

When connected to a synchronization service, it is possible to send a message to the service using the function syncmessage or the action Sync.sendMessage. The message is identified by a name and it can have an optional value with additional details.

Typically, a client will send a message with some information to log, or with some information that informs an expected response.

Because a Bluetooth server is passive—only responding to requests from a Bluetooth client—a message can be sent to the server with the server responding via a special user-defined function with the name OnSyncMessage. This allows information from the passive server to inform the synchronization process.

On CSWeb, messages are stored in the cspro_messages database table. By default, CSWeb returns an undefined response, but users can modify the CSWeb source file MessagesController.php to customize what value is returned.

The file-based synchronization services (Dropbox, FTP, and Local Files) store the message in a file in the directory /CSPro/messages/ and return an undefined response.

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.

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;