extern XXX_ERROR XXX_API GetPrivateFileName (char *file_title, const char *filter, unsigned int mode, const char *boxtext,const char *inifile, const char *section, const char *entry);
file_title
filter
mode
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
inifile
section
entry
RE_SUCCESS or XXX error type.
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 ✘✘✘ Signature only (console applications incl.).