CheckVoiceMessages

Purpose

Use CheckVoiceMessages to retrieve all messages of a certain type for a specified application profile and mailbox ID.

Description

Once a list of messages is retrieved, you can use CheckVoiceMessages with the Next Message option to step through the messages, one at a time.

Before a message in a mailbox can be played, forwarded, annotated, or the attributes changed, it must be retrieved from the disk by CheckVoiceMessages. The status of all New messages retrieved is changed to Checked, and the first message is placed in workspace and in the mailbox. A retrieved message remains Checked until it is listened to (using PlayVoiceMessage), saved (using SaveVoiceMessage), or deleted (using DeleteVoiceMessage).

When you successfully retrieve messages, the first message in the list is the current message. When you step through the messages, the next message in the list becomes the current message. Every time the current message is set, that message is copied into the message workspace.

To select a specific message in the list, you can use AssignData to assign a value to a Message system variable that defines the message you want. For example, to select the third message in a list retrieved by CheckVoiceMessages, you can use AssignData to assign the Message : Message number system variable (SV21) a value of 3. This automatically updates the current message to the third message in the CheckVoiceMessages list.

You can also select a specific message based on the transaction ID of the message. By setting the Message : Transaction ID system variable (SV126) to a value, the list is searched for a message with a transaction ID that matches the value. If the first message in a newly retrieved list matches, that message remains the current message. Subsequent AssignData actions select and refresh the workspace information with subsequent matching messages in the list. In other words, subsequent checks for matches with the same transaction ID begin following the current message, not starting with the current message.

If the sender requested acknowledgment of the message (using the Receipt Acknowledgment parameter of ChangeMessageAttributes), the Message : Receipt acknowledgment status system variable (SV161) has a value of 1.

Before using CheckVoiceMessages, you must set the Caller - Profile ID (SV20) and Caller : Mailbox - ID (SV32) system variables.

Next to each result listed under Result State Transfer, leave a blank field to fall through to the next state, or click the field to identify the state that should be performed next by typing the label or selecting it from the State Table Labels window.

Parameters

The parameters for CheckVoiceMessages identify which messages in the mailbox are of interest.

• First Incoming New. Includes all incoming New, Checked, Listened, or Undeliverable messages.

  When you use this parameter, SV25 is reset to SV20, and SV33 is reset to SV32.

• First Incoming Saved. Includes all incoming Saved messages.
• First Outgoing To All Recipients. Includes all outgoing messages (the messages that have a status of New or Future that have not been checked by the recipient).
• First Outgoing To Selected Recipient. Includes outgoing messages sent to a specific mailbox (the messages that have a status of New or Future that have not been checked by the recipient).

  Before using this parameter, you must first set the Out Mail - Profile ID (SV25) and Out Mail : Mailbox - ID (SV33) system variables.

• Next Message. Retrieves the next message in the list.

Possible results

CheckVoiceMessages can have one of the following results:

No Messages

There are no messages that match the selected parameter, or the end of the list has been reached.

Message Retrieved

The next message on the list was retrieved.

Failed

The state table could not access the mailbox.

ASCII syntax

When using an ASCII editor, code this action with one of the following parameters

• "NEXT"
• or "FIRST_IN_NEW"
• or "FIRST_IN_SAVED"
• or "FIRST_OUT_TO_ALL"
• or "FIRST_OUT_TO_SELECTED"

For example:

label: "Check Edges"
	CheckVoiceMessages("NEXT")
	  edge EDGE_CHK_MBOX_NONE: 				none
	  edge EDGE_CHK_MBOX_MSG_RETRIEVED: 	   msg_retrieved
	  edge EDGE_CHK_MBOX_FAILED:				failed
	;
	CheckVoiceMessages("FIRST_IN_NEW");
	CheckVoiceMessages("FIRST_IN_SAVED");
	CheckVoiceMessages("FIRST_OUT_TO_ALL");
	CheckVoiceMessages("FIRST_OUT_TO_SELECTED");

The parameters and edges are described above under "Parameters" and "Possible results". For more information, see Testing a state table using the debugger.