OpenAdvanced


The OpenAdvanced method opens or creates file with specified type of access, sharing and attributes. Currently attached file is detached, flushing its buffer and closing it if necessary.
C++
long OpenAdvanced(
  LPSTR FileName,                         // file name
  long Access,                            // access mode
  long Sharing,                           // sharing mode
  long Creation,                          // creation disposition
  long Attributes = IXF_FILE_NORMAL,      // flags and attributes
  long Timeout = 5                        // timeout
);
long OpenAdvanced(
  LPWSTR FileName,                        // file name
  long Access,                            // access mode
  long Sharing,                           // sharing mode
  long Creation,                          // creation disposition
  long Attributes = IXF_FILE_NORMAL,      // flags and attributes
  long Timeout = 5                        // timeout
);
BASIC
OpenAdvanced(
  FileName As Variant,                    // file name
  Access As FileAccessMode,               // access mode
  Sharing As FileShareMode,               // sharing mode
  Creation As FileCreationDisposition,    // creation disposition
  Attributes As FileAttributes = 
    IXF_FILE_NORMAL,                      // flags and attributes
  Timeout As Long = 5                     // timeout
) As Long

Parameters

FileName
C++
Pointer to buffer containing name of the file (must be NULL terminated).
BASIC
Variant containing name of the file.
Variant must be of String data type; it must not be an array.
Access
Mode of access, specified as a combination of the following values:

IXF_FILE_READ read access to the file,
IXF_FILE_WRITE write access to the file.

Commonly used access mode is predefined for convenience:

IXF_FILE_RDWR read and write access to the file.
Sharing
Sharing mode, specified as a combination of the following values:

IXF_FILE_SHARE_READ share file for reading,
IXF_FILE_SHARE_WRITE share file for writing.

Commonly used sharing mode is predefined for convenience:

IXF_FILE_SHARE_RDWR share file for reading and writing.
Creation
Creation disposition, must be one of the following values:

IXF_FILE_CREATE create new file (file must not exist),
IXF_FILE_OVERWRITE create new file or overwrite existing,
IXF_FILE_OPEN open existing file,
IXF_FILE_OPEN_CREATE open file or create if does no exist,
IXF_FILE_TRUNCATE open file and truncate to zero size (file must exist),
IXF_FILE_CREATE_TRUNCATE open file and truncate to zero size or create if file does not exist.
Attributes
Attributes and flags, specified as a combination of the following values:

IXF_FILE_READONLY create file for reading only,
IXF_FILE_HIDDEN create hidden file (not included in ordinary directory listing),
IXF_FILE_SYSTEM create system file (used exclusively by the operating system),
IXF_FILE_ARCHIVE create file marked to be archived,
IXF_FILE_NORMAL create file with no special attributes;
cannot be combined with other flags,
IXF_FILE_TEMPORARY create file for temporary usage (kept in memory),
IXF_FILE_NOCACHE open file with write-through access (without caching),
IXF_FILE_RANDOM optimize caching for random access,
IXF_FILE_SEQUENTIAL optimize caching for sequential access,
IXF_FILE_DELETE delete file when last handle is closed,
IXF_FILE_BACKUP file is to be used in backup or restore operations,
IXF_FILE_NOREPARSE inhibit NTFS reparse points.
Timeout
Time to wait for opening if file is used exclusively by another application or thread, in seconds.
If this parameter is 0 and opening is not possible method returns immediately with error.

Return Values

If the method succeeds, the return value is 0.
If the method fails, the return value is failure code and error code is set. Call GetError to get error code.

Remarks

FileName specifies name of the file given as relative or absolute path; if relative path is specified GetName method can be called to obtain fully qualified path.

Access specifies type of file access which should be, in general, compatible with mode of operation of the object as specified during initialization. This means that it is not possible to write data to file if mode of operation of the object does not have IXF_MODE_WRITE flag set, even if file is opened with IXF_FILE_WRITE access. In other words file should not be opened in access mode that is lower then type of access to be performed.

Sharing specifies type of shared access to the file. If IXF_FILE_SHARE_READ flag is set, other applications or threads can open the same file (opened by the object) with read access; similarily if IXF_FILE_SHARE_WRITE flag is set, other applications can open the file for write access. If neither flag is set file is opened for exclusive access by the object.

Creation specifies which action to take on files that exist, and which action to take when files do not exist. It also specifies if file should be truncated to zero size after opening.

Attributes specifies the file attributes and flags for the file. IXF_FILE_READONLY, IXF_FILE_HIDDEN, IXF_FILE_SYSTEM, IXF_FILE_ARCHIVE, IXF_FILE_NORMAL and IXF_FILE_TEMPORARY attributes are meaningful only during file creation; they are ignored when file to be opened already exists. IXF_FILE_NORMAL attribute is always overwritten by other attributes (if present). Remaining flags are valid when opening or creating file.

If specified file is opened exclusively by another application or thread, method waits up to Timeout seconds before returning error; if Timeout is 0, it returns immediately. File is opened for exclusive access whenever requested type of access is not compatible with sharing mode of the file. In other words application cannot open the same file for writing (IXF_FILE_WRITE) when file is opened by someone else without shared write access (IXF_FILE_SHARE_WRITE).

Method is used whenever file must be opened in specific access or share mode that cannot be achieved with Open method. Open method always opens file in access and share mode that is solely determined by mode of operation of the object, which may not be, in some situations, appropriate. For example, method should be used when file must be opened for shared access with manual locking only; in such case Open method opens file for exclusive access.

On completion internal object settings are set to default values. Active buffer is set to its maximum size, read and write counters are reset to zero, data buffers are cleared. File position is set at the beginning of the file (0).

Unicode version of the method should not be confused with Unicode system calls or Unicode text data. All versions of the method can be used on Unicode and non-Unicode systems depending on your needs. On Unicode systems, however, file is opened by Unicode version of system function (unless Unicode is disabled with EnableUnicode method). Conversion between ANSI and Unicode is performed internally according to current codepage which can be changed with SetCodePage method. See Unicode Support for more information on Unicode system calls, Unicode methods and Unicode text data.

See Also

Open, Attach, Close, GetName, GetFile, Opening and Attaching File