# vceConvertMessage

Copies a message and translates its encoding.

#### Prototype

DWORD vceConvertMessage ( VCEHD srcvh, unsigned srcmsg, VCEHD destvh, unsigned destmsg, int gain)

Argument | Description
srcvh | Voice handle of source file or memory block.
srcmsg | Source message number.
destvh | Voice handle of destination file or memory block.
destmsg | Destination message number.
gain | Amplification if positive or attenuation if negative.

#### Return values

Return value | Description
SUCCESS |
CTAERR_BAD_ARGUMENT | gain is less than -24 or greater than 24.
CTAERR_DISK_FULL | There is not enough room on the disk to complete the write operation. No data was written.
CTAERR_FILE_READ_FAILED | File system error.
CTAERR_FILE_WRITE_FAILED | File system error.
CTAERR_FUNCTION_ACTIVE | Playing or recording is active on the context.
CTAERR_INVALID_HANDLE | A voice handle is invalid, or the source and destination message numbers belong to different contexts.
CTAERR_SVR_COMM | Server communication error.
VCEERR_CONVERSION_FAILED | An internal error occurred in the conversion library.
VCEERR_INVALID_MESSAGE | Source message number or destination message number is invalid for the file type.
VCEERR_NO_SPACE | Insufficient room in the destination message.
VCEERR_OUT_OF_INDICES | No free header entries in the destination VOX file.
VCEERR_PLAY_ONLY | Destination voice file is not open for record.
VCEERR_UNSUPPORTED_ENCODING | Source or destination encoding format is not supported by the conversion function.

#### Details

vceConvertMessage copies a message from one voice object to another, or to another message in the same voice object. The encoding of the message is translated as needed from the source to the destination. If the gain argument is not zero (0), attenuation or amplification is applied, depending on whether gain is negative or positive.

Source and destination must belong to the same context. The destination message becomes the current message in the context.

EDTX encoding types are not supported.

To copy and translate all messages from the source to the destination, set the source message number (srcmsg) and the destination message number (destmsg) to VCE_ALL_MESSAGES. This setting replaces all messages in the destination, not just messages that exist in the source.

The gain must be in the range of -24 to +24. Otherwise, CTAERR_BAD_ARGUMENT is returned.

Depending on the type of conversion required, a long message can take many seconds to convert. During this time, the context and the queue associated with the message is locked. You can open a separate queue for performing conversions when other Natural Access functions are used in the same process.

Converting from one mu-law, A-law, or 8 kss PCM format to another is relatively fast. Converting between PCM and ADPCM, or converting from one sample rate to another, takes more time.

The following example shows the possible conversions and indicates the relative amount of processing required:

| a | b | c | d | e | f | g | h | i | j | k | l
--- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---
a) NMS 16/24/32 | 2 |  |  |  |  |  |  |  |  |  |  |
b) NMS 64 | 1 | 0 |  |  |  |  |  |  |  |  |  |
c) mu/A-law | 1 | 0 | 0 |  |  |  |  |  |  |  |  |
d) PCM 8 kss | 1 | 0 | 0 | 0 |  |  |  |  |  |  |  |
e) PCM 11 kss | 2 | 1 | 1 | 1 | 0 |  |  |  |  |  |  |
f) PCM 22 kss | 2 | 1 | 1 | 1 | 1 | 0 |  |  |  |  |  |
g) PCM 44 kss | 2 | 1 | 1 | 1 | 1 | 1 | 0 |  |  |  |  |
h) OKI 24 | x | x | x | x | x | x | x | x |  |  |  |
i) OKI 32 | 2 | 1 | 1 | 1 | 2 | 2 | 2 | x | 0 |  |  |
j) G.726 | 2 | 1 | 1 | 1 | 2 | 2 | 2 | x | 2 | 0 |  |
k) IMA 24 | x | x | x | x | x | x | x | x | x | x | x |
l) IMA 32 | 2 | 1 | 1 | 1 | 2 | 2 | 2 | x | 2 | 2 | x | 0

Note: kss = kilo-samples per second (mono or stereo, 8-bit or 16-bit).

Key:

Value | Description
0 | No conversion, or conversion between A-law, mu-law, and 8 kHz PCM.
1 | Either ADPCM <--> PCM conversion or sample rate conversion.
2 | Either two ADPCM <--> PCM conversions, or ADPCM <--> PCM plus sample rate conversion.
x | Not supported.

#### See also

vceCopyMessage

#### Example

/* Convert a Wave file of any encoding to a VCE file with NMS encoding */
void myWaveToVce (CTAHD ctahd, char *wavefile, char *vcefile)
{
VCEHD srcvh, destvh;
vceOpenFile (ctahd, wavefile, VCE_FILETYPE_WAVE, VCE_PLAY_ONLY, 0, &srcvh);
vceCreateFile (ctahd, vcefile, VCE_FILETYPE_FLAT,
VCE_ENCODE_NMS_24, NULL, &destvh);
vceConvertMessage (srcvh, 0, destvh, 0, 0);
vceClose (srcvh);
vceClose (destvh);
}