StormLib API Reference

SFileFindFirstFile

Description

HANDLE WINAPI SFileFindFirstFile(
  HANDLE hMpq,                      // Archive handle
  const char * szMask,              // Search mask
  SFILE_FIND_DATA * lpFindFileData, // Pointer to the search result
  const char * szListFile           // Name of additional listfile
);

Function SFileFindFirstFile searches an MPQ archive and returns name of the first file that matches the given search mask and exists in the MPQ archive. When the caller finishes searching, the returned handle must be freed by calling SFileFindClose.

Parameters

hMpq

[in] Handle to an open archive.

szMask

[in] Name of the search mask. "*" will return all files.

lpFindFileData

[out] Pointer to SFILE_FIND_DATA structure that will receive information about the found file.

szListFile

[in] Name of an extra list file that will be used for searching. Note that SFileAddListFile is called internally. The internal listfile in the MPQ is always used (if exists). This parameter can be NULL.

SFILE_FIND_DATA Structure

struct SFILE_FIND_DATA
{
  char   cFileName[MAX_PATH];              // Name of the found file
  char * szPlainName;                      // Plain name of the found file
  DWORD  dwHashIndex;                      // Hash table index for the file
  DWORD  dwBlockIndex;                     // Block table index for the file
  DWORD  dwFileSize;                       // Uncompressed size of the file, in bytes
  DWORD  dwFileFlags;                      // MPQ file flags
  DWORD  dwCompSize;                       // Compressed file size
  DWORD  dwFileTimeLo;                     // Low 32-bits of the file time (0 if not present)
  DWORD  dwFileTimeHi;                     // High 32-bits of the file time (0 if not present)
  LCID   lcLocale;                         // Locale version
};

Return Value

When the function succeeds, it returns handle to the MPQ search object and the SFILE_FIND_DATA structure is filled with information about the file. On an error, the function returns NULL and GetLastError gives the error code.

Remarks

Note that even if names within MPQs contain "folder names", the searching functions don't support folders. The entire line in the list file is considered a file name.

Availability in Storm.dll

Copyright (c) Ladislav Zezula 2003 - 2010