Prosody speech processing: API: sm_play_digits

Prototype Definition

int sm_play_digits(struct sm_play_digits_parms *digitsp)

Parameters

*digitsp
a structure of the following type: 
typedef struct sm_play_digits_parms {
	tSMChannelId channel;					/* in */
	tSM_INT wait_for_completion;				/* in */
	struct sm_digits {
		enum kSMDigitType {
			kSMDTMFDigits,
		} type;						/* in */
		tSM_INT qualifier;				/* in */
		char digit_string[kSMMaxDigits_plus1];		/* in */
		tSM_INT inter_digit_delay;			/* in */
		tSM_INT digit_duration;				/* in */
	} digits;						/* in */
} SM_PLAY_DIGITS_PARMS;

Description

This call outputs a sequence of DTMF digits in-band on the output channel specified. The digits structure contains details of the digits to be dialled. The type parameter determines the way digits contained in the zero terminated string digit_string are output on the timeslot.

The qualifier parameter is not currently used and should be set to zero.

The inter_digit_delay and digit_duration parameters are specified in milliseconds. Set parameters to zero for default delay and duration.

The characters permitted in digit_string depend on the type parameter specified. For kSMDTMFDigits, only '0'..'9','*', '#' , and 'A'..'D' are permitted.

The wait_for_completion flag may be set by the application in which case the API call will not return until the digits have been completely output, however no other Prosody API function can be performed on the channel during this waiting period. See the document Prosody application note: waiting for completion for examples of how to wait without blocking other functions.

Alternatively the application can wait to be notified by an event indicating that the digits have been completely output. This requires the module tonegen to have been downloaded.

The channel is reserved for playing the digits until the API has reported completion. If the wait_for_completion flag is set, then the API considers that completion has been reported when this API function returns, otherwise completion is reported only by sm_play_digits_status() returning the status kSMPlayDigitsStatusComplete. In this case the application must call sm_play_digits_status() periodically and should use a write event on the channel to notify it when to check the status. No other output activity can take place on the channel until the completion of the digits has been reported, so Note that the event itself does not indicate completion of the digits. It is possible for the event to be signalled even if the digits have not yet completed, so it is essential that the application checks the status and continues waiting if the digits have not completed.

Fields

channel
The channel on which the digits are to be played.
wait_for_completion
An indicator of whether this function would return as soon as it has set up the generation of the tone (0), or wait until the end of the tone (non-zero). If this value is zero, the application must have an event associated with this channel and invoke sm_play_digits_status() whenever the event is set.
digits
The details of the digits to play.
type
The type of digits to play. One of these values:
kSMDTMFDigits
qualifier
Unused. Set to zero.
digit_string
The digits to play.
inter_digit_delay
The amount of silence (in mS) to leave between digits.
digit_duration
The duration (in mS) of each digit.

Returns

0 if call completed successfully, otherwise a standard error such as:

This function is part of the Prosody speech processing API.