# vceOpenFile

Opens a voice file and returns a voice handle.

#### Prototype

DWORD vceOpenFile ( CTAHD ctahd, char *filename, unsigned filetype, unsigned openmode, unsigned encoding, VCEHD *vh)

Argument | Description
ctahd | Handle returned by ctaCreateContext or ctaAttachContext.
filename | Pointer to a file name. If the file name does not include a full pathname, first the current directory is searched for the file, then the path in the CTA_DPATH environment variable. The current directory is either that of the application or of the Natural Access Server (ctdaemon), depending on whether the application is using the inproc default server or the localhost default server.
filetype | Acceptable values are: VCE_FILETYPE_VOX VCE_FILETYPE_WAVE VCE_FILETYPE_FLAT VCE_FILETYPE_AUTO Refer to the Details section for more information.
openmode | Either VCE_PLAY_ONLY or VCE_PLAY_RECORD.
encoding | For unformatted files, the encoding of the data in the file. Set this to zero (0) for other files.
vh | Pointer to a returned voice handle.

#### Return values

Return value | Description
SUCCESS |
CTAERR_BAD_ARGUMENT | An undefined value was passed for openmode or filetype, or an encoding of zero (0) was specified for a flat file.
CTAERR_FILE_ACCESS_DENIED | Another application process or thread in the system has the file open for recording.
CTAERR_FILE_NOT_FOUND | Specified file does not exist.
CTAERR_FILE_OPEN_FAILED | File open failed due to a system error.
CTAERR_INVALID_CTAHD | Context handle is invalid.
CTAERR_SVR_COMM | Server communication error.
VCEERR_UNSUPPORTED_ENCODING | Neither the Voice Message service nor the associated play or record service, if any, supports the specified encoding.
VCEERR_WRONG_ENCODING | A non-zero encoding that was specified is not the same as the encoding in the file.
VCEERR_WRONG_FILE_TYPE | The file is not of the specified or implied type.

#### Details

vceOpenFile opens an existing voice file. The file can be opened for play only or for both play and record. A file opened for record can have one writer but many readers. Only one application process or thread in the system can open the file for recording, but simultaneous play access is always allowed.

The following file types are supported:

- NMS VOX

- WAVE

- Flat (unformatted)

To have the file type inferred from the filename, set filetype to VCE_FILETYPE_AUTO.

If the filetype is VCE_FILETYPE_AUTO and the file ends in... | Then the file type will be...
.VOX | VCE_FILETYPE_VOX
.WAV or .WAVE | VCE_FILETYPE_WAVE
Any other extension | VCE_FILETYPE_FLAT

Note: The file extensions can also be lowercase.

If the file name has no extension and the file type is specified, then a .vox, .wav, or .vce extension is automatically implied. In UNIX, if no file with the implied name is found, vceOpenFile also looks for a file with the name as specified.

The NMS VOX file format stores multiple messages in one file and enables an application to delete, add, and edit messages.

WAVE files must conform to the Microsoft Multimedia Format and must contain a WAVE chunk as the first or only RIFF form in the file. For additional information, refer to the Microsoft Windows Multimedia Programmer's Reference.

Flat files contain no header information, only data.

The encoding argument is necessary for flat files. It is not necessary to specify the encoding for other file types because the encoding is contained in the file header. If a non-zero encoding is specified, it must match the encoding in the header, or an error is returned.

#### See also

vceAssignHandle, vceCreateFile

#### Example

/* Open ten files containing spoken digits and store the handles in an array. */
VCEHD prompt_hd[10] = {0};
void openprompts (CTAHD ctahd)
{
unsigned index;
for (index=0; index<10; index++)
{
char filename[20];
sprintf (filename, "PROMPT%d.VCE", index);
vceOpenFile (ctahd, filename,
VCE_FILETYPE_FLAT, VCE_PLAY_ONLY,
VCE_ENCODE_NMS_24, &prompt_hd [index] );
}
}