Seek method

Classes: TPJIStreamWrapper, TPJHandleIStreamWrapper, TPJFileIStream

Applies to: ~>3.0

function Seek(dlibMove: Largeint; dwOrigin: Longint;
  out libNewPosition: Largeint): HResult; virtual; stdcall;

Description

Changes the seek pointer of the wrapped stream to a new location. The new location can be relative to the beginning of the stream, the end of the stream, or the current seek pointer position.

Parameters:

dlibMove – Number of bytes to offset seek pointer from origin specified by dwOrigin.
dwOrigin – Origin of the move. Possible values are:
- STREAM_SEEK_SET: Offset from start of stream. dlibMove should be positive.
- STREAM_SEEK_CUR: Offset from current stream position. Positive values of dlibMove move forward in stream and negative values move backward.
- STREAM_SEEK_END: Offset from end of stream. dlibMove should be negative.
libNewPosition – Set to the new position in the wrapped stream after the move. See Remarks.

Returns:

S_OK on success.
STG_E_INVALIDPOINTER if the seek fails.
STG_E_INVALIDFUNCTION if an invalid origin was specified.

Remarks

Large Streams (=> MaxInit Bytes)

[~>3.0.0] This method cannot be used reliably on streams greater than MaxInt bytes in size. This is because the new stream position, passed out via the libNewPosition parameter is truncated to 32 bits, even though this is a 64 bit parameter. If the wrapped stream supports 64 bit offsets its new position will be set correctly, but the reported value in libNewPosition will be wrong.

[~>3.1] This method is reliable. The libNewPosition parameter is set correctly when the new stream position is greater than MaxInt.

Wrapped Stream Move Offset Limitations

It is possible that wrapped streams may support only 32 bit move offsets or be limited in size to MaxInt bytes. In such cases passing a value of more than MaxInt to the dlibMove parameter, or attempting to seek beyond MaxInt, can have unexpected results.

[~>3.0.0] The method will succeed, returning S_OK, even though the stream’s position will not be as expected.

[~>3.1] You can detect the 32 bit move offset or 32 bit stream size problems mentioned above because the value of libNewPosition will differ from dlibMove when the method returns.

Note that before Delphi 6 no TStream descendants supported 64 bit moves and all were limited to MaxInt bytes.

Seek Bug in TStringStream

For non-Unicode versions of Delphi, TStringStream does not behave as expected for some seek operations.

This problem does not occur in any other stream class, or in Unicode versions of TStringStream.

[~>3.0.0] Setting dwOrigin to STREAM_SEEK_END when dlibMove will cause offsets to work the opposite way to that expected, i.e. a positive offset will move back in the stream.