Prosody speech processing: API: sm_record_status

Prototype Definition

int sm_record_status(struct sm_record_status_parms *statusp)

Parameters

*statusp
a structure of the following type: 
typedef struct sm_record_status_parms {
	tSMChannelId channel;					/* inout */
	enum kSMRecordStatus {
		kSMRecordStatusComplete,
		kSMRecordStatusCompleteData,
		kSMRecordStatusOverrun,
		kSMRecordStatusData,
		kSMRecordStatusNoData,
		kSMRecordStatusRecognition,
	} status;						/* out */
	enum kSMRecognition recog_type;				/* out */
	tSM_INT param0;						/* out */
	tSM_INT param1;						/* out */
	enum kSMRecordHowTerminated {
		kSMRecordHowTerminatedNotYet,
		kSMRecordHowTerminatedLength,
		kSMRecordHowTerminatedMaxTime,
		kSMRecordHowTerminatedSilence,
		kSMRecordHowTerminatedAborted,
		kSMRecordHowTerminatedError,
	} termination_reason;					/* out */
	tSM_UT32 termination_octets;				/* out */
	tSM_UT32 sample_rate;					/* out */
} SM_RECORD_STATUS_PARMS;

Description

This call, typically invoked in response to a read event being signalled, allows an application to determine the status of a specific on-going record job.

In order to determine the status of a specific record job, the application should set channel to specify the job concerned.

This function can also be used for 'any channel' operation. This mode of operation is a legacy feature and is not recommended for new applications. See Prosody TiNG: any channel operation for more details.

A channel ceases to be recording when this function returns a status of kSMRecordStatusComplete. Until this happens, the channel input is reserved for the record and no other recording activity can take place on the channel during this time. After this happens, the channel input returns to being idle and consequently if this function is used again it will return the error ERR_SM_NO_RECORD_IN_PROGRESS.

Fields

channel
The channel which is recording.
status
The channel's status. One of these values:
kSMRecordStatusComplete
The recording job has completed and all the recorded data has been passed to the application.
kSMRecordStatusCompleteData
The recording job has completed but there still remains recorded data for the application to collect.
kSMRecordStatusOverrun
Data has not been retrieved sufficiently frequently by the application and now some has been lost due to module buffer overrun.
kSMRecordStatusData
The record job is still ongoing and data is available for collection by the application.
kSMRecordStatusNoData
The record job is still ongoing however not enough data is buffered in the module to justify collection by the application.
kSMRecordStatusRecognition
A recognition event has occurred in the recording. The recog_type, param0 and param1 fields contain a report of what was detected. This status can occur when sm_record_start() specified an option such as tone elimination.
recog_type
The recognition event which has occurred. This field, with the param0 and param1 fields, has the same meaning as the type field returned by sm_get_recognised() with its corresponding param0 and param1 fields. This field is only valid when the status field is kSMRecordStatusRecognition. One of these values:
kSMRecognisedNothing
No digit, simple or call-progress tone has been recognised
kSMRecognisedTrainingDigit
kSMRecognisedDigit
A pulse dialled or DTMF dialled digit has been recognised and a character representation for it has been stored in param0. In param1 will be an indication of the digit type (kSMPulseDigits or kSMDTMFDigits) unless a tone detection mode of type kSMToneLen... was specified in which case it will contain the duration in milliseconds of the detected DTMF digit.
kSMRecognisedTone
A simple tone has been recognised from the active set of input tones for the channel. The parameter param0 and param1 are assigned values as described above.
kSMRecognisedCPTone
A call-progress tone has been recognised and the corresponding identifier has been stored in param0.
kSMRecognisedGruntStart
The beginning of a grunt has been detected. param0 is set to the duration of the preceding silence in milliseconds.
kSMRecognisedGruntEnd
The end of a grunt has been detected, param0 is set to grunt duration in milliseconds, and param1 to grunt average energy in negative dBm0 (average is calculated only over periods during which signal is present).
kSMRecognisedASRResult
Obsolete
kSMRecognisedASRUncertain
Obsolete
kSMRecognisedASRRejected
Obsolete
kSMRecognisedASRTimeout
Obsolete
kSMRecognisedCatSig
A signal has been categorised, the parameter param0 indicates the algorithm id (see sm_catsig_listen_for()) and param1 is a value indicating the signal category with respect to this algorithm (eg. live speaker or answer machine).
kSMRecognisedOverrun
The recognition FIFO has been overrun because it has not been polled frequently enough through calls to sm_get_recognised().
kSMRecognisedANS
An ANS or ANSam tone has been detected (see sm_ans_listen_for()). The parameter param0 will describe the tone detected: 0 for end of tone, 1 for an ordinary ANS tone, or 2 for the modulated ANSam tone. The parameter param1 will be non zero if the ANS or ANSam tone has phase reversals
kSMRecognisedBeep
A beep has been recognised The parameter param0 will be the beep frequency and param1 will be zero at the start of the beep and non-zero when the beep ends.
kSMRecognisedOnHook
An 'on-hook' state has been recognised
param0
A parameter giving details of what was detected. The interpretation of this depends on the recog_type field. This field is only valid when the status field is kSMRecordStatusRecognition.
param1
Another parameter giving details of what was detected. The interpretation of this also depends on the recog_type field. This field is only valid when the status field is kSMRecordStatusRecognition.
termination_reason
The reason why a recording has terminated. One of these values:
kSMRecordHowTerminatedNotYet
Recording not yet completed.
kSMRecordHowTerminatedLength
The max_octets criterion specified to sm_record_start() was satisfied.
kSMRecordHowTerminatedMaxTime
The max_elapsed_time criterion specified to sm_record_start() was satisfied.
kSMRecordHowTerminatedSilence
The max_silence criterion specified to sm_record_start() was satisfied. The termination_octets field will indicate approximately how many octets of recorded silence were present at the end of the recording.
kSMRecordHowTerminatedAborted
sm_record_abort() was invoked.
kSMRecordHowTerminatedError
An error occurred.
termination_octets
The amount of data representing silence at the end of the recording (only valid if the recording has completed and termination_reason was kSMRecordHowTerminatedSilence).
sample_rate
The sample rate of data. This is the rate for data not yet collected.

Returns

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

This function is part of the Prosody speech processing API.