Table of Contents

Wwise SDK 2019.1.6

◆ Open() [1/2]

virtual AKRESULT AK::StreamMgr::IAkFileLocationResolver::Open ( const AkOSChar in_pszFileName,
AkOpenMode  in_eOpenMode,
AkFileSystemFlags in_pFlags,
bool &  io_bSyncOpen,
AkFileDesc io_fileDesc 
)
pure virtual

Returns a file descriptor for a given file name (string). Performs the operations needed to make the file descriptor usable by the other methods of the interface (for e.g. ask the OS for a valid file handle).

Returns
  • AK_Success: A valid file descriptor is returned
  • AK_FileNotFound: File was not found.
  • AK_Fail: File could not be open for any other reason.
  • A file descriptor, which contains
    • an unique identifier to be used with functions of the low-level IO interface.
    • the total stream size in bytes.
    • the offset from the beginning of the file (in blocks).
    • a device ID, that was obtained through AK::StreamMgr::CreateDevice().
  • The updated io_bSyncOpen flag depending on the File Resolver's deferred opening policy.
Remarks
  • The file descriptor is unique for each stream, and its address remains the same throughout its lifetime. In other words, the value of &in_fileDesc inside Read() or Close() is the same as &out_fileDesc in Open().
  • Open() is always called first in the client thread.
  • If io_bSyncOpen is true, file opening must be executed now. If it is false, the File Location Resolver may choose whether it wants open it now, or later from the streaming device's thread. If it wishes to open it now, then it must set io_bSyncOpen to true. Otherwise, it needs to do the following: leave io_bSyncOpen to false, clear out_fileDesc::iFileSize and out_fileDesc::uSector, and set out_fileDesc::deviceID to the streaming device's ID that will handle this file. By returning io_bSyncOpen as false, the Stream Manager will interpret this as a request for deferred file opening, and this function will called again from the streaming device's thread (this time, with this io_bSyncOpen set to true).
  • All members of out_fileDesc will be cleared upon first call to Open().
Warning
  • It is illegal to return io_bSyncOpen as false if Open() was called with io_bSyncOpen set to true.
  • Deferred file opening requires allocations in the Stream Manager's small object pool. The File Location Resolver should always choose to open files synchronously if it is fast to do so.
  • Whether opening is deferred or not, GetBlockSize() is always called right after the first call to Open(), in the client's thread, and is never called again.
See also
Parameters
in_pszFileName File name.
in_eOpenMode Open mode.
in_pFlags Special flags. Can pass NULL.
io_bSyncOpen If true, the file must be opened synchronously. Otherwise it is left at the File Location Resolver's discretion. Return false if Open needs to be deferred.
io_fileDesc Returned file descriptor.