(v13) seek_file seek to a specified point in a file on the device

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

TEXT

  int32 seek_file (
  DEVICELIST *dev,
  DEVICE_FILEDESCRIPTOR descriptor, Hq32x2 *destn;
  int32 flags );

Some devices will be able to support positionable files that is, there is a current file position associated with the open file and the next read or write will read from, or write to, bytes at that point, and this current file position can be set.

This routine should return TRUE if the current file position was successfully set, or FALSE

if it failed. If it fails, last_error should return DeviceIOError .

The flags parameter indicates how the destn parameter should be interpreted. If flags is SW_SET (the constants for flags are defined in the file swdevice.h ), the current file position should be set to destn bytes from the start of the file. If flags is SW_INCR , the current file position should be changed by destn bytes, and if flags is SW_XTND, the current file position should be set to the length of the file plus destn . If this results in the current file position being beyond the current end of the file, the file is open for writing, and the file permissions allow it to be extended, then file should be extended to the current file position. [RB3] does not specify the values in any bytes between the old and new lengths of the file.

Calls to seek_file with a value of zero passed in the destn argument have special meanings. The meaning of such a call depends on the value of the flags argument. Even if a device cannot support seeking, it is usually possible to implement support for some or all of these special calls. The meanings of calls to seek_file when destn is zero are defined below.

`SW_SET`	The RIP passes this `flags` value and a `destn` value of zero to ask a device if it supports arbitrary seeks. A device should return `true` if it does, or `false` otherwise.
`SW_INCR`	The RIP passes this `flags` value and a `destn` value of zero when it wants to know the current file position. It is often possible to support this feature even when other seeks are not supported. If supported, the file position value should be written back into `destn` .
`SW_XTND`	The RIP passes this `flags` value and a `destn` value of zero to ask a device to flush its file, discarding any remaining input. This may not always require reading the remaining input for example, a network connection could be shut down instead.