Zen API

- Home
- Topics
- Types
- Files

All Classes Files Functions Variables Typedefs Friends Macros Modules Pages

kStatus kTcpClient_EnableSeek | ( | kTcpClient | client,
|  | kBool | enabled
| ) |  |

Enables limited support for forward/reverse seek operations.

kTcpClient supports seek operations with respect to the stream read pointer. The stream write pointer is unaffected. Seek operations can be relative to kSEEK_ORIGIN_BEGIN or kSEEK_ORIGIN_CURRENT. The value reported by the kStream_BytesRead method is affected by seek operations.

Seek support is most commonly required when client logic that was written for a random-access stream (e.g., kFile) will be reused with a kTcpClient object. Forward seek operations are relatively straightforward. Reverse seek operations are more complex and limited, but can still occasionally be useful (e.g., to read a file header for file-type detection, and then restart from the beginning).

Forward seek is supported by reading and discarding bytes from the underlying stream. There is no limit to forward seek distance.

Reverse seek is supported by "unreading" bytes from the client buffer. Accordingly, in order to support reverse seek, kTcpClient_SetReadBuffers must be invoked with a non-zero clientSize argument. Reverse seek distance is limited by the number of buffered bytes that have previously been read, but have not yet been overwritten by subsequent operations affecting the read buffer. In client code that uses reverse seek, it is recommended to call kStream_Flush just prior to reading bytes that will later be reversed. Doing so ensures that maximum buffer space will available for reverse seek.

Seek support can slightly reduce stream efficiency and is therefore disabled by default.

Parameters

  client | TCP client object.
  enabled | kTRUE to enable forward/reverse seek support.

Returns
  Operation status.