Opens a voice file and returns a voice handle.

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

ctahd Handle returned by ctaCreateContext.

filename Pointer to the name of the file to create. If the name does not contain a prepended path, then the file is created in the current working directory of either the application or the Natural Access Server (ctdaemon), depending on whether the application is running in Library or Server mode.

filetype Acceptable values are:
VCE_FILETYPE_VOX VCE_FILETYPE_WAVE VCE_FILETYPE_FLAT VCE_FILETYPE_AUTO

Refer to Details 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.

• 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 may have the file open for recording.
• CTAERR_FILE_NOT_FOUND
• CTAERR_FILE_OPEN_FAILED
• CTAERR_INVALID_CTAHD
• VCEERR_UNSUPPORTED_ENCODING
  The specified encoding is not supported either by the Voice Message service or the associated play/record service, if any.
• VCEERR_WRONG_ENCODING
  A non-zero encoding was specified, but was not the same as the encoding in the file.
• VCEERR_WRONG_FILE_TYPE
  The file is not of the specified or implied type.

• None.

This function 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, whereas 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	VCE_FILETYPE_FLAT

Note: The file extensions can also be lower case.

If the filename has no extension and the file type is specified, then a .vox, .wav, or .vce extension is automatically implied.

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

WAVE files are expected to conform to the Microsoft Multimedia Format and 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.

In Server mode, the file is created by the Natural Access Server (ctdaemon). It is recommended that you specify a fully qualified path for the filename argument to ensure the proper location of the file.

vceAssignHandle, vceCreateFile

/* 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] );
    }
}