GetPrivateFileName()

extern KADMOS_ERROR KADMOS_API GetPrivateFileName
  (char *file_title, const char *filter, unsigned int mode,
  const char *boxtext,const char *inifile, const char *section,
  const char *entry);

Parameter:

file_title

Pointer to a returned file name.

filter

Same as with GetFileName under Windows.

mode

Same as with GetFileName under Windows.

`OF_READ`	Open for read only.
`OF_CREATE`	Create and open for writing.
`OF_PROMPT`	Prompt for file name.
`OF_EXIST`	File must exist.

boxtext

Same as with GetFileName under Windows.

inifile

Name of an INI file.

section

Name of the section in the INI file with the registrations.

entry

Name of the registration or entry of the file name under section.

Return value:

RE_SUCCESS or KADMOS error type.

Comment:

The function is designed similar to the Windows functions GetPrivateProfileString() and WritePrivateProfileString(). file_title is returned if a file name that matches the requirements of Mode (OF_EXIST, OF_CREATE) can be found in IniFile under section and entry. Users must ensure that there is enough memory provided for the file_title (_MAX_PATH). If no entry is found in the section and entry of the IniFile, but there is a string specified under file_title, then this string will be checked if it matches the requirements under Mode. For OF_EXIST, it is checked if the file exists. For OF_CREATE, it is checked if such a file can be created. If there is no file_title specified or the file_title does not match the requirements given by mode, a user dialog is invoked to allow input of a valid file_title. boxtext specifies the title to be displayed in the user dialog. If the dialog procedure is cancelled without a valid file_title, the function returns a value of the error type, otherwise a valid file_title is provided and the function returns the value RE_SUCCESS. If under Mode the additional value OF_PROMPT has been set, then a user dialog will always be invoked. The default setting for the dialog procedure is the file name given in file_title under section and entry or the file_title provided by the program call. After validation of the default or user provided file name it will be stored in Inifile under section and entry and the function returns with RE_SUCCESS. Presently the function GetPrivateFileName() is implemented for the Windows versions of KADMOS only (console applications incl.).