adiRecordMMAsync

Initiates multimedia recording in asynchronous buffer mode. In this mode, the ADI service generates a buffer full event when each buffer is full. The application asynchronously stores the data and submits empty buffers in response.

Parameters to control silence detection are provided and apply if silence detection is configured.

Prototype

DWORD adiRecordMMAsync ( CTAHD ctahd, unsigned encoding, void *buffer1, unsigned bufsize, DWORD *video_ephd, DWORD *audio_ephd, ADI_MM_RECORD_PARMS *parms)

Argument	Description
ctahd	Context handle returned by ctaCreateContext or ctaAttachContext.
encoding	Encoding type. See adidef.h for a complete list of ADI_ENCODING_xxx values. See Multimedia encoding types for the RTP compressed format encoding types.
buffer1	Pointer to the media data buffer.
bufsize	Number of bytes pointed to by buffer1.
video_ephd	Pointer to the CG board video filter endpoint handle obtained with mspGetFilterHandle. The application uses this endpoint handle to connect the ADI channel on the board to the RTP endpoint and to synchronize the beginning and ending of the audio and video record.
audio_ephd	Pointer to the CG board audio filter endpoint handle obtained with mspGetFilterHandle. The application uses this endpoint handle to connect the ADI channel on the board to the RTP endpoint and to synchronize the beginning and ending of the audio and video record.
parms	Pointer to the ADI_MM_RECORD_PARMS structure that contains record parameters.

Return values

Return value	Description
SUCCESS
ADIERR_INVALID_CALL_STATE	Function not valid in the current call state.
CTAERR_BAD_ARGUMENT	Either invalid encoding selected or NULL buffer1 pointer passed.
CTAERR_FUNCTION_ACTIVE	Function already started.
CTAERR_INVALID_CTAHD	Context handle is invalid.
CTAERR_INVALID_STATE	Function not valid in the current port state.
CTAERR_OUTPUT_ACTIVE	Record failed because there is another active output function.
CTAERR_RESOURCE_CONFLICT	Silence detector is in use by adiStartEnergyDetector.
CTAERR_SVR_COMM	Server communication error.

Events

Event	Description
ADIEVN_RECORD_DONE	Generated when the record operation completes. The event size field contains the total number of bytes recorded during the record instance lifetime. The value field contains a reason code or an error code. The reason codes are described in the Reason codes for ADIEVN_RECORD_DONE table.
ADIEVN_RECORD_BUFFER_FULL	Generated by the ADI service when a buffer is filled with recorded voice data. The event contains the following fields: buffer - Pointer to a previously submitted user buffer1. size - Number of bytes recorded into the buffer. value - Flags. If the ADI_RECORD_BUFFER_REQ bit is set, more buffers are needed and the application must submit another empty buffer. If the ADI_RECORD_UNDERRUN bit is set, an underrun occurred. There was no new buffer to record information when this one was completed.
ADIEVN_RECORD_STARTED	Generated by the ADI service after the function is started on the board. If the ADI_RECORD_BUFFER_REQ bit in the event value field is set, more buffers are needed and the application must submit another empty buffer.

Reason codes for ADIEVN_RECORD_DONE

Reason	Description
CTA_REASON_FINISHED	Buffer is filled.
CTA_REASON_MAXTIME_AUDIO	Maximum recording time reached. Applicable for pass-through audio encoding types only.
CTA_REASON_MAXTIME_VIDEO	Maximum recording time reached. Applicable for pass-through video encoding types only.
CTA_REASON_NATIVE_COMPANION_RECORD_STOPPED	Companion record channel stopped. For example, a pass-through audio channel and a pass-through video channel are companion channels because they have matching video_ephd and audio_ephd input parameters. If one of the two channels stops recording for any reason, the companion pass-through channel is also stopped with this reason code.
CTA_REASON_NO_VIDEO	No video detected.
CTA_REASON_NO_VOICE	No voice detected.
CTA_REASON_RELEASED	Call terminated.
CTA_REASON_STOPPED	Stopped by application request.
CTA_REASON_VIDEO_END	Video packets not detected for specified timeout period. Applicable only for pass-through video encoding types.
CTA_REASON_VOICE_END	User stopped speaking.
CTAERR_FUNCTION_NOT_AVAIL	Required DSP file not loaded on the board.
CTAERR_xxx or ADIERR_xxx	Record failed.

Details

Use adiRecordMMAsync to initiate a multimedia record operation. The data is supplied to the application in a sequence of buffers. The application submits empty buffers using adiSubmitRecordBuffer for the duration of the operation. These buffers are then filled with recorded voice data and ADIEVN_RECORD_BUFFER_FULL events are returned. The application is responsible for allocating, flushing, and submitting the buffers.

When the ADI service needs another buffer, it sets the ADI_RECORD_BUFFER_REQ bit in the event value field for ADIEVN_RECORD_STARTED and ADIEVN_RECORD_BUFFER_FULL. The application responds by submitting another empty buffer using adiSubmitRecordBuffer. The application submits buffers only when requested by the ADI service. The ADI service owns the buffer until either ADIEVN_RECORD_BUFFER_FULL or ADIEVEN_RECORD_DONE is delivered to the application.

The last buffer before the DONE event can be a partial buffer. The DONE event itself does not include a buffer of data. The record operation terminates when the application receives ADIEVN_RECORD_DONE.

Note: The final buffer that was submitted may not be returned to the application. If the application dynamically allocates buffers, it must keep track of submitted buffers to free any outstanding buffers when record is done.

The bufsize should be set to the board buffer size, which by default is 16,400 for CG boards.

For proper operation, each buffer must be submitted while the previous buffer is being filled.

For more information about adiSubmitRecordBuffer, see the ADI Service Developer's Reference Manual.

Example

if ((ret = SetRecordParms(VideoCtx[i].ctahd, &recParms)) != SUCCESS)
{
    printf("Failed to setup Record Parameters\n");
    exit(1);
}
ret = adiRecordMMAsync(VideoCtx[i].ctahd,
mmParm.ADIvidEncoder,      // Encoding
VideoCtx[i].data_buffer,   // Buffer to receive recorded video
16400,                     // Buffer size
videoEP_filterhd,          // Video EndPoint Filter Handle
audioEP_filterhd,          // Audio EndPoint Filter Handle
&recParms);                // Record parameters
if (ret != SUCCESS)
{
    printf("Failed to Record Async, %x\n", ret);
    exit(1);
}