INSTANTMESSAGING
See alsoManage Instant Messaging, including chats, messages and users in chats.
Calls to the instruction INSTANTMESSAGING are executed in the context of the calling user. As a consequence, their effects depend on the current user context, and in particular, user permission level as applied to chats.
| Mode | Mnemonic | Syntax |
| 1 | GETCURRENTCHATNAME | 1 |
| 2 | ENTERCHAT | 2 |
| 3 | ISLOADING | 3 |
| 4 | ADDCHAT | 4 |
| 5 | QUITCHAT | 5 |
| 6 | SENDTEXT | 6 |
| 7 | SENDFILE | 7 |
| 8 | ADDCHATUSER | 8 |
| 9 | REMOVECHATUSER | 9 |
| 10 | LOADCHATS | 10 |
| 11 | GETCHATSCOUNT | 11 |
| 12 | GETCHATNAME | 12 |
| 13 | GETCHATTITLE | 13 |
| 14 | SETCHATTITLE | 14 |
| 15 | GETCHATCOLOR | 13 |
| 16 | SETCHATCOLOR | 15 |
| 17 | GETCHATUSERSCOUNT | 16 |
| 18 | GETCHATUSER | 17 |
| 19 | CANCEL | 18 |
| 20 | GETUSERACCESS | 19 |
| 21 | GETMESSAGESCOUNT | 16 |
| 22 | SETUSERACCESS | 8 |
| 23 | GETMESSAGESENDER | 20 |
| 24 | GETMESSAGEDATE | 20 |
| 25 | GETMESSAGEEXTENSION | 20 |
| 26 | GETMESSAGEZONE | 20 |
| 27 | GETMESSAGETEXT | 20 |
| 28 | LOADMESSAGES | 21 |
| 29 | GETMESSAGEID | 22 |
| 30 | CLEARMESSAGESCACHE | 25 |
| 31 | CLEARCHATSCACHE | 23 |
| 32 | LOADALLMESSAGES | 5 |
| 33 | LOADMESSAGEDATA | 24 |
Modes of the INSTANTMESSAGING instruction are categorized as follow:
- Modes designed to script the Messaging control that you can insert in mimics: ENTERCHAT, ISLOADING and GETCURRENTCHATNAME.
They are easily recognized as they have the typical arguments for scripting a graphic control in a mimic (Window, Branch and Identity). - Modes designed to manage the local storage cache for chats and messages: LOADCHATS, LOADMESSAGES, LOADALLMESSAGES, CLEARCHATSCACHE and CLEARMESSAGESCACHE.
Using these modes is required when you need to script chats in background, typically on event, with no user interaction. - Most of the other modes are designed to script chats in background. They are not effective if the local cache has not been created using the corresponding LOAD modes.
It is not necessary to use the LOAD and CLEAR modes to script the Messaging control or for SnapVue users to be able to use the instant messaging.
When the need is to script chats in background, the LOAD modes shall be called in the script executed upon user login, and the corresponding CLEAR modes shall be called in the script executed upon user logout.
Depending on what exactly you want to script, you may need to call:
-
LOADCHATS and CLEARCHATSCACHE: Required to use modes having the argument ChatName (or chat index).
-
LOADCHATS, LOADMESSAGES (or LOADALLMESSAGES), CLEARMESSAGESCACHE and CLEARCHATSCACHE: Required to use modes having the arguments ChatName (or chat index) and MessageId (or message index).
If you do not properly initialize the local cache, subsequent calls to either fail or be ineffective.
Once initialized, the following chats activity will be automatically updated, both for the existing and new chats.
Example 1:
Calling QUITCHAT or SETCHATTITLE fails if the chat name you pass as argument has not been loaded by a call to LOADCHATS, which caches the list of chats. This is because the chat you pass as argument is unknown to the scripting engine.
Example 2:
Calling GETMESSAGESENDER or GETMESSAGETEXT fails if the message you pass as argument has not been loaded by a call to LOADMESSAGES (or LOADALLMESSAGES), which loaded chats' messages. This is because the message you pass as argument is unknown to the scripting engine.
Properties common to more than one mode
|
Argument |
Meaning |
| StatusVariable | The name of a register variable that will contain the status of the request. Type STR. StatusVariable can take the following values: 0: Success 1: In progress 3: Canceled 10: Failed |
| ChatName | The name of a chat. Type STR. |
| ChatTitle | The title of a chat. Type STR. |
| UserName | The name of a user. Type STR. |
| MessageId | The unique identifier of a message. Type STR. |
| Window | The name of the mimic containing a Messaging control graphic object. Type STR. |
| Branch | The branch of mimic containing a Messaging control graphic object. Type STR. |
| Identity | The message control identifier. Type STR. |
| ViewIndex | The index of the view in the case that multiple views of the same mimic are open. Any numeric type. |
Syntax 1
StrVal = INSTANTMESSAGING(Mode, Window, Branch, Identity[, ViewIndex]);
Return type: STR.
Execution
|
Mode |
Mnemonic |
Action |
| 1 | GETCURRENTCHATNAME |
Get the name of the chat that the user is currently using in the given window. |
Syntax 2
INSTANTMESSAGING (Mode, Window, Branch, Identity, ChatName[, ViewIndex]);
Return type: None.
Execution
|
Mode |
Mnemonic |
Action |
| 2 | ENTERCHAT |
Open the chat named ChatName and let the current user in. Return: None. |
Syntax 3
IntVal = INSTANTMESSAGING (Mode, Window, Branch, Identity[, ViewIndex]);
Return type: INTEGER.
Execution
|
Mode |
Mnemonic |
Action |
| 3 | ISLOADING |
Retrieve the status of the messaging control in a given mimic. Return: 1 if the control is loading messages |
Syntax 4
IntVal = INSTANTMESSAGING (Mode, ChatName, ChatTitle[, StatusVariable]);
Return type: INTEGER.
Execution
|
Mode |
Mnemonic |
Action |
| 4 | ADDCHAT |
Create a new chat, the current user is automatically given the Owner permission. Return: The query number if successful, else 0. |
Syntax 5
IntVal = INSTANTMESSAGING (Mode, ChatName[, StatusVariable]);
Return type: INTEGER.
Execution
|
Mode |
Mnemonic |
Action |
| 5 | QUITCHAT |
Allows the current user to quit the chat ChatName if he/she is currently part of. Return: The query number if successful, else 0. |
| 32 | LOADALLMESSAGES |
Load and store all messages from the chat ChatName and store them locally. Return: The query number if successful, else 0. |
The function LOADALLMESSAGES or LOADMESSAGES must be called upon login, prior to using functions that interact with the chats' messages. The following chats activity will then be automatically updated, both for the existing and new chats. Please refer to explanation at the top of this topic for more information.
Syntax 6
IntVal = INSTANTMESSAGING (Mode, ChatName, Text[, StatusVariable]);
Return type: DOUBLE.
|
Argument |
Meaning |
| Text | A text string. Type STR. |
Execution
|
Mode |
Mnemonic |
Action |
| 6 | SENDTEXT |
Send a text message to the chat ChatName. The user executing the function must have at least Guest permission. Return: The query number if successful, else 0. |
Syntax 7
IntVal = INSTANTMESSAGING (Mode, ChatName, FileName[, StatusVariable]);
Return type: INTEGER.
|
Argument |
Meaning |
| FileName | The full name of a file including the file path. Type STR. |
Execution
|
Mode |
Mnemonic |
Action |
| 7 | SENDFILE |
Send the file FileName into the chat ChatName. The user executing the function must have at least Guest permission. Return: The query number if successful, else 0. |
Syntax 8
IntVal = INSTANTMESSAGING (Mode, ChatName, UserName, AccessLevel[, StatusVariable]);
Return type: INTEGER.
|
Argument |
Meaning |
| AccessLevel | Permission level to grant the user. Type INTEGER. 0 = The user permission level is Owner. 1 = The user permission level is Admin. 2 = The user permission level is Guest. 3 = The user permission level is Read. |
Execution
|
Mode |
Mnemonic |
Action |
| 8 | ADDCHATUSER |
Add the user UserName with permission AccessLevel to the existing chat ChatName. Return: The query number if successful, else 0. |
| 22 | SETUSERACCESS | Modify the permission level of the user UserName for the chat named ChatName. Return: The query number if successful, else 0. |
Syntax 9
IntVal = INSTANTMESSAGING (Mode, ChatName, UserName[, StatusVariable]);
Return type: INTEGER.
Execution
|
Mode |
Mnemonic |
Action |
| 9 | REMOVECHATUSER |
Remove the user UserName from the chat ChatName. The user executing the function must have at least Admin permission. Return: The query number if successful, else 0. |
Syntax 10
IntVal = INSTANTMESSAGING (Mode[, StatusVariable]);
Return type: INTEGER.
Execution
|
Mode |
Mnemonic |
Action |
| 10 | LOADCHATS |
Load and store all of the current user's chats locally. Return: The query number if successful, else 0. |
This function must be called upon login, prior to using functions that interact with the chats. The following chats activity will then be automatically updated, both for the existing and new chats. Please refer to explanation at the top of this topic for more information.
Syntax 11
IntVal = INSTANTMESSAGING (Mode);
Return type: INTEGER.
Execution
|
Mode |
Mnemonic |
Action |
| 11 | GETCHATSCOUNT |
Returns the total number of chats to which the user has access. Return: The number of chats, or -1 if unsuccessful. |
Syntax 12
StrVal = INSTANTMESSAGING (Mode, ChatIndex);
Return type: STR.
|
Argument |
Meaning |
| ChatIndex | Index of the chat ordered by creation date. Type INTEGER. |
Execution
|
Mode |
Mnemonic |
Action |
| 12 | GETCHATNAME |
Get the name of the chat at index ChatIndex. Return: The name of the chat, or an empty string if unsuccessful. |
Syntax 13
StrVal = INSTANTMESSAGING (Mode, ChatName);
Return type: STR.
Execution
|
Mode |
Mnemonic |
Action |
| 13 | GETCHATTITLE |
Get the title of the chat named ChatName. Return: The title of the chat, or an empty string if unsuccessful. |
| 15 | GETCHATCOLOR |
Get the color of the chat. Return: The color of the chat, or an empty string if unsuccessful. |
Syntax 14
IntVal = INSTANTMESSAGING (Mode, ChatName, ChatTitle[, StatusVariable]);
Return type: INTEGER.
Execution
|
Mode |
Mnemonic |
Action |
| 14 | SETCHATTITLE |
Set the title of the chat ChatName to the value ChatTitle. The user executing the function must have at least Admin permission. Return: The query number if successful, else 0. |
Syntax 15
IntVal = INSTANTMESSAGING (Mode, ChatName, ChatColor[, StatusVariable]);
Return type: INTEGER.
|
Argument |
Meaning |
| ChatColor | The new color for the chat. Either a standard color (Red, Blue, etc.) or a hexadecimal value (dc0000, 1400ab, etc.). Type STR. |
Execution
|
Mode |
Mnemonic |
Action |
| 16 | SETCHATCOLOR |
Set the color of the chat ChatName. The user executing the function must have at least Admin permission. Return: The query number if successful, else 0. |
Syntax 16
IntVal = INSTANTMESSAGING (Mode, ChatName);
Return type: INTEGER.
Execution
|
Mode |
Mnemonic |
Action |
| 17 | GETCHATUSERSCOUNT |
Retrieve the number of users currently in the chat ChatName. Return: The number of users in the chat, or -1 if unsuccessful. |
| 21 | GETMESSAGESCOUNT |
Returns the number of messages in the chat ChatName. Return: The number of messages in the chat or -1 if unsuccessful. |
Syntax 17
StrVal = INSTANTMESSAGING (Mode, ChatName, UserIndex);
Return type: STR.
|
Argument |
Meaning |
| UserIndex | Index of the user ordered by time of arrival. Type INTEGER. |
Execution
|
Mode |
Mnemonic |
Action |
| 18 | GETCHATSUSER |
Get the name of the user at index UserIndex. Return: The user's name, or an empty string if unsuccessful. |
Syntax 18
INSTANTMESSAGING (Mode, QueryId);
Return type: None.
Execution
|
Mode |
Mnemonic |
Action |
| 19 | CANCEL |
Cancel the query QueryId. |
Syntax 19
IntVal = INSTANTMESSAGING (Mode, ChatName, UserName);
Return type: INTEGER.
Execution
|
Mode |
Mnemonic |
Action |
| 20 | GETUSERACCESS |
Returns the permission level of the user UserName for the chat ChatName. Return: 0 = Owner |
Syntax 20
StrVal = INSTANTMESSAGING (Mode, MessageId);
Return type: STR.
Execution
|
Mode |
Mnemonic |
Action |
| 23 | GETMESSAGESENDER |
Returns the name of the user who sent the message MessageId. |
| 24 | GETMESSAGEDATE | Return the date of dispatch of the message MessageId. |
| 25 | GETMESSAGEEXTENSION | Return the extension of the message MessageId. |
| 26 | GETMESSAGEZONE | Returns the zone from which the message MessageId was sent. |
| 27 | GETMESSAGETEXT | Returns the text content of the message MessageId if any. |
| For all modes, an empty string is returned if unsuccessful. |
Syntax 21
IntVal= INSTANTMESSAGING (Mode, ChatName, DateFrom, DateTo, Count[, StatusVariable]);
Return type: INTEGER.
|
Argument |
Meaning |
| DateFrom | Earliest date from which to load messages. An empty string can be used to load from the earliest message. Type STR. |
| DateTo | Latest date from which to load messages. An empty string can be used to load down to the latest message. Type STR. |
| Count | Maximum number of messages to load. -1 can be used to indicate no limit. Type INTEGER. |
Execution
|
Mode |
Mnemonic |
Action |
| 28 | LOADMESSAGES |
Load and store messages from the chat ChatName using the supplied criteria. Return: The query number if successful, else 0. |
This function or LOADALLMESSAGES must be called upon login, prior to using functions that interact with the chats' messages. The following chats activity will then be automatically updated, both for the existing and new chats. Please refer to explanation at the top of this topic for more information.
Syntax 22
StrVal = INSTANTMESSAGING (Mode, ChatName, Index);
Return type: STR.
|
Argument |
Meaning |
| Index | Index of the message ordered by date of dispatch. Type INTEGER. |
Execution
|
Mode |
Mnemonic |
Action |
| 29 | GETMESSAGEID |
Get the unique identifier of the message at position Index in the chat named ChatName. Return: The unique Id of the message, or an empty string if unsuccessful. |
Syntax 23
INSTANTMESSAGING (Mode);
Return type: None.
Execution
|
Mode |
Mnemonic |
Action |
| 31 | CLEARCHATSCACHE | Clear all chats stored locally. |
Syntax 24
IntVal = INSTANTMESSAGING (Mode, MessageId, FolderName[, StatusVar]);
Return type: INTEGER.
Execution
|
Mode |
Mnemonic |
Action |
| 33 | LOADMESSAGEDATA |
Save attachments of message MessageId to the directory FolderName. Return: The query number if successful, else 0. |
Syntax 25
INSTANTMESSAGING (Mode[, ChatName]);
Return type: None.
Execution
|
Mode |
Mnemonic |
Action |
| 30 | CLEARMESSAGESCACHE |
Clear all messages stored locally. If ChatName is passed as an argument, only messages of the chat ChatName are cleared. |