XPLMGetDirectoryContents

From X-Plane SDK
Jump to: navigation, search

XPLMGetDirectoryContents

XPLM_API int                  XPLMGetDirectoryContents(
                                   const char *         inDirectoryPath,    
                                   int                  inFirstReturn,    
                                   char *               outFileNames,    
                                   int                  inFileNameBufSize,    
                                   char **              outIndices,    /* Can be NULL */
                                   int                  inIndexCount,    
                                   int *                outTotalFiles,    /* Can be NULL */
                                   int *                outReturnedFiles);    /* Can be NULL */

This routine returns a list of files in a directory (specified by a full path, no trailing : or \). The output is returned as a list of NULL terminated strings. An index array (if specified) is filled with pointers into the strings. This routine The last file is indicated by a zero-length string (and NULL in the indices). This routine will return 1 if you had capacity for all files or 0 if you did not. You can also skip a given number of files.

inDirectoryPath - a null terminated C string containing the full path to the directory with no trailing directory char.

inFirstReturn - the zero-based index of the first file in the directory to return. (Usually zero to fetch all in one pass.)

outFileNames - a buffer to receive a series of sequential null terminated C-string file names. A zero-length C string will be appended to the very end.

inFileNameBufSize - the size of the file name buffer in bytes.

outIndices - a pointer to an array of character pointers that will become an index into the directory. The last file will be followed by a NULL value. Pass NULL if you do not want indexing information.

inIndexCount - the max size of the index in entries.

outTotalFiles - if not NULL, this is filled in with the number of files in the directory.

outReturnedFiles - if not NULL, the number of files returned by this iteration.

Return value - 1 if all info could be returned, 0 if there was a buffer overrun.

WARNING: Before X-Plane 7 this routine did not properly iterate through directories. If X-Plane 6 compatibility is needed, use your own code to iterate directories.

This routine can crash. This bug and the workaround are documented on the KnownBugs page.