Creates a new voice file.

DWORD vceCreateFile ( CTAHD ctahd,
char *filename,
unsigned filetype,
unsigned encoding,
void *fileinfo,
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.

encoding The encoding used for all messages in the file.

fileinfo Pointer to a file-type-specific structure that contains parameters specific to the file type. For unformatted files, this argument should be NULL. For NMS VOX files, fileinfo can point to the VCE_CREATE_VOX structure (if fileinfo is NULL, default values will be used).

The VCE_CREATE_VOX structure is:

typedef struct
{
 DWORD size;       /* size of this structure        */
 DWORD maxindex;       /* number of index entries in        */
        /* header (default 250)        */
} VCE_CREATE_VOX;

For WAVE files, fileinfo can point to a VCE_WAVE_INFO structure. (Refer to vceSetWaveInfo for a description of this structure.) This enables WAVE files to be created with formats for which there is no predefined encoding value (for example, 22 kHz stereo). Set encoding to 0 in this case.

vh Pointer to a returned voice handle.

• SUCCESS
• CTAERR_BAD_ARGUMENT
  filetype is invalid.
• CTAERR_FILE_CREATE_FAILED
• CTAERR_FILE_EXISTS
• CTAERR_INVALID_CTAHD
• CTAERR_PATH_NOT_FOUND
  An invalid path is specified when creating a WAVE file.
• VCEERR_UNSUPPORTED_ENCODING
  The specified encoding is not supported either by the Voice Message service or by the associated play/record service, if any.

• None.

This function creates a new voice file. If the file already exists, an error is returned.

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.

The default number of index entries in a VOX file is 250. The minimum number of index entries is 48. If you specify to vceCreateFile less than 48, the number of index entries will be 48.

To create a WAVE file, vceCreateFile maps the encoding to the appropriate WAVE header values based on an internal table. vceSetWaveInfo lets you add entries for encodings not already in the table.

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.

Refer to Appendix E for details about the encoding information that is compiled into the Voice Message service.

vceAssignHandle, vceOpenFile, vceOpenMemory, vceSetWaveInfo

/* mycreatefile - create a new file for recording to */

void mycreatefile (CTAHD ctahd, char *filename, VCEHD *vh)
{
    unsigned        ret;

    ret = vceCreateFile (ctahd, filename, VCE_FILETYPE_VOX,
                                         VCE_ENCODE_NMS_24, NULL, vh);
    if (ret == CTAERR_FILE_EXISTS)
        printf("Create failed: File %s already exists\n", filename);
    else if (ret != SUCCESS)
    {
   char textbuf[80];
   ctaGetText (ctahd, ret, textbuf, sizeof textbuf);
   printf("Error creating %s: error %s from vceCreateFile\n", filename,
    textbuf);
    }
    else
        printf("File %s created\n", filename);
    return;
}