Prosody speech processing: API: sm_add_input_cptone

Prototype Definition

int sm_add_input_cptone(struct sm_input_cptone_parms *cptonep)

Parameters

a structure of the following type:

typedef struct sm_input_cptone_parms {
	tSMModuleId module;					/* in */
	tSM_INT state_count;					/* in */
	struct sm_cptone_state {
		tSM_INT freq_id;				/* in */
		tSM_INT maximum_cadence;			/* in */
		tSM_INT minimum_cadence;			/* in */
	} states[kSMMaxCPToneStates];				/* in */
	tSM_INT id;						/* in */
} SM_INPUT_CPTONE_PARMS;

Description

Adds an additional call-progress tone to the repertoire of such tones recognised by the designated module.

The new call-progress tone is defined by a sequence of (up to kSMMaxCPToneStates) call-progress tone states. In order for a signal to be recognised as the new call-progress tone, each of the call-progress tone states must be satisfied in turn.

Each state is satisfied when, on the channel being processed, a signal is detected which has a duration of between minimum_cadence and maximum_cadence milliseconds and a frequency designated by freq_id. The actual frequency designated by freq_id is with respect to the tone set selected as the base set of frequencies for use by call-progress tone detection. By default this is tone set 1 (see Prosody speech processing: pre-loaded input tones), if another base set of frequencies is required then this may be specified by a tone set id specified when invoking sm_reset_input_cptones().

The parameter id is a value between 1 and 255 specified by the application, prior to calling the function. It is used to identify the recognised call-progress tone, and will be returned by sm_get_recognised() whenever the defined call-progress tone is being listened for and is recognised on an input channel. Distinct call-progress tones may be assigned the same id so that, for instance, two alternative call-progress tones could return the same id.

See Prosody speech processing: pre-loaded call-progress tones, for list of call-progress tones supported by default and their ids.

See Prosody speech processing: Notes on adding call-progress tones for further information on adding call-progress tones to be recognised.

This call can only be made when no channel is allocated on the given module.

The maximum duration of a tone for call-progress tone detection is over 50 days. It is not possible to detect tones longer than this. To match a continuous tone, specify ~0U (i.e. the maximum possible unsigned int value) as the maximum duration. This special value allows a tone to match before it finishes (normally detection must wait until the tone finishes so that it can check if the duration exceeded the permitted maximum).

Fields

module

The module whose call-progress tone set is to be modified.

state_count

The number of entries in the states field.

states

The sequence of component states representing this tone. The last to occur must be in states[0], and the first must be in states[state_count-1] - they are in the opposite order in this array to the order they occur in the incoming signal.

freq_id: The id of a component tone.
maximum_cadence: The minimum duration (in mS) of this component.
minimum_cadence: The maximum duration (in mS) of this component.

id

The identifier of this call-progress tone.

Returns

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

ERR_SM_DEVERR - device error
ERR_SM_NO_SUCH_MODULE - if no such module exists
ERR_SM_NO_RESOURCES - if no resources to store new call-progress tone
ERR_SM_BAD_PARAMETER - if bad call-progress tone definition
ERR_SM_CHANNEL_ALLOCATED - channel still allocated

This function is part of the Prosody speech processing API.