int sm_play_cptone(struct sm_play_cptone_parms *cptonep)
typedef struct sm_play_cptone_parms {
tSMChannelId channel; /* in */
tSM_UT32 duration; /* in */
tSM_INT wait_for_completion; /* in */
enum kSMPlayCPToneType {
kSMPlayCPToneTypeOneShot,
kSMPlayCPToneTypeRepeat,
kSMPlayCPToneTypeContinuous,
} type; /* in */
tSM_INT tone_count; /* in */
struct sm_cadence {
tSM_INT tone_id; /* in */
tSM_INT on_cadence; /* in */
tSM_INT off_cadence; /* in */
} cadences[kSMMaxPlayCPToneCadences]; /* in */
} SM_PLAY_CPTONE_PARMS;
This call allows an application to generate a call-progress tone on specified output channel channel.
If the call-progress tone is to be output continuously (or until interrupted by sm_play_cptone_abort()), the parameter duration should be set to zero. Otherwise duration should be set to the required call-progress tone duration in milliseconds (the duration parameter is ignored if type is kSMPlayCPToneTypeOneShot).
Each element of cadences specifies an on-period on_cadence and an off-period off_cadence both specified in milliseconds, and also tone_id referencing to one of the module's currently defined simple output tones (see Prosody speech processing: pre-loaded output tones, for list of ids for output tones downloaded with module firmware and see description of sm_add_output_tone() for how an application may define its own simple output tones). Here are some examples of call-progress tones which use kSMPlayCPToneTypeRepeat:
| Name | tone_count | cadences | |||
|---|---|---|---|---|---|
| pos | tone_id | on_cadence | off_cadence | ||
| U.K. ring tone | 2 | 0 | 17 | 400 | 208 |
| 1 | 17 | 400 | 2000 | ||
| U.K. busy | 1 | 0 | 16 | 384 | 384 |
| E.C. busy | 1 | 0 | 18 | 512 | 512 |
| S.I.T. | 3 | 0 | 19 | 336 | 32 |
| 1 | 20 | 336 | 32 | ||
| 2 | 21 | 336 | 1008 | ||
The wait_for_completion flag may be set by the application in which case the API call will not complete until the tone has been completely output, however no other Prosody API function can be performed on the channel during this waiting period. Obviously setting this flag is not useful when the tone has been specified as being a continuous tone with no fixed duration, since there would then be no way to stop the tone. 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 that tone generation of a given duration has completed. When a write event has been associated with channel (see sm_channel_set_event), then the driver will notify the application with that event whenever it needs to invoke sm_play_cptone_status().
This requires the module tonegen to have been downloaded.
The channel is reserved for playing the tone 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_cptone_status() returning the status kSMPlayCPToneStatusComplete. In this case the application must call sm_play_cptone_status() periodically and should use an 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 tone has been reported. Note that the event itself does not indicate completion of the tone. It is possible for the event to be signalled even if the tone has not yet completed, so it is essential that the application checks the status and continues waiting if the tone has not completed.
Note that the only way to stop a continuous tone is by calling sm_play_cptone_abort().
0 if call completed successfully, otherwise a standard error such as:
This function is part of the Prosody speech processing API.