(v13) start_file_list begin listing files

This page applies to Harlequin v13.1r0 and later; and to Harlequin Core but not Harlequin MultiRIP

void *start_file_list ( DEVICELIST *dev, uint8 *pattern);

This routine is called as part of the implementation of filenameforall . pattern is the template string as passed to filenameforall . This routine should do any initializing necessary such that successive calls to next_file (described in (v13) next_file return next matching file will return filenames matching that template.

The pointer returned by this function will be passed to the first call to next_file . The implementation of next_file should use this pointer to identify where in the enumeration of files matching this pattern it has reached. This is necessary because it is possible to have recursive calls to filenameforall , so nested filename enumerations must be supported.

If for some reason the enumeration cannot be started, the routine should return NULL . One reason for this could be that the nesting level of filename enumerations is too deep, and in this case last_error should return DeviceLimitCheck . Other errors should return DeviceIOError .

If it is known that the enumeration will never return a matching file name, the routine can return NULL and set last_error to DeviceNoError . In this case the RIP will not then call next_file and end_file_list .