# vceCreateFile

Creates a new voice file.

#### Prototype

DWORD vceCreateFile ( CTAHD ctahd, char *filename, unsigned filetype, unsigned encoding, void *fileinfo, VCEHD *vh)

Argument | Description
ctahd | Handle returned by ctaCreateContext or ctaAttachContext.
filename | Pointer to the name of the file to create. If the name does not include a complete path, 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 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.
encoding | Encoding used for all messages in the file.
fileinfo | Pointer to a structure that contains parameters specific to the file type. For unformatted files, this argument must be NULL. For NMS VOX files, fileinfo can point to the VCE_CREATE_VOX structure (if fileinfo is NULL, default values are 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 argument 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.

#### Return values

Return value | Description
SUCCESS |
CTAERR_BAD_ARGUMENT | filetype is invalid.
CTAERR_FILE_CREATE_FAILED | File system error.
CTAERR_FILE_EXISTS | You attempted to create a file that already exists.
CTAERR_INVALID_CTAHD | Context handle is invalid.
CTAERR_PATH_NOT_FOUND | An invalid path is specified when creating a WAVE file.
CTAERR_SVR_COMM | Server communication error.
VCEERR_UNSUPPORTED_ENCODING | Neither the Voice Message service nor the associated play or record service, if any, support the specified encoding.

#### Details

vceCreateFile 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 infer the file type from the filename, set filetype to VCE_FILETYPE_AUTO.

If the file type is VCE_FILETYPE_AUTO and the file ends in... | The file type is...
.VOX | VCE_FILETYPE_VOX
.WAV or .WAVE | VCE_FILETYPE_WAVE
Any other | VCE_FILETYPE_FLAT

Note: The file extensions can also be lowercase.

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

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

When using the localhost default server, the Natural Access Server (ctdaemon) creates the file. To ensure the proper location of the file, specify a fully qualified path for the filename argument.

Refer to Encoding descriptions and Encoding and WAVE information for details about the encoding information that is compiled into the Voice Message service.

#### See also

vceAssignHandle, vceOpenFile, vceOpenMemory

#### Example

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