Zen API

- Home
- Help Topics
- Types by Category
- All Types
- Files

All Classes Files Functions Variables Typedefs Macros Groups Pages
kStream.h
Go to the documentation of this file.
1 /**
2 * @file kStream.h
3 * @brief Declares the kStream class.
4 *
5 * @internal
6 * Copyright (C) 2005-2014 by LMI Technologies Inc.
7 * Licensed under the MIT License.
8 * Redistributed files must retain the above copyright notice.
9 */
10 #ifndef K_API_STREAM_H
11 #define K_API_STREAM_H
12
13 #include <kApi/kApiDef.h>
14
15 kBeginHeader()
16
17 /**
18 * @class kStream
19 * @extends kObject
20 * @ingroup kApi-Io
21 * @brief Represents an I/O stream.
22 */
23 //typedef kObject kStream; --forward-declared in kApiDef.x.h
24
25 /**
26 * Reads the specified number of bytes from the stream.
27 *
28 * @public @memberof kStream
29 * @param stream Stream object.
30 * @param buffer Destination for bytes that are read.
31 * @param size Count of bytes to read.
32 * @return Operation status.
33 */
34 kFx(kStatus) kStream_Read(kStream stream, void* buffer, kSize size);
35
36 /**
37 * Reads up to the specified number of bytes from the stream.
38 *
39 * @public @memberof kStream
40 * @param stream Stream object.
41 * @param buffer Destination for bytes that are read.
42 * @param minCount Minimum count of bytes to read.
43 * @param maxCount Maximum count of bytes to read.
44 * @param bytesRead Receives count of bytes read.
45 * @return Operation status.
46 */
47 kFx(kStatus) kStream_ReadSome(kStream stream, void* buffer, kSize minCount, kSize maxCount, kSize* bytesRead);
48
49 /**
50 * Writes the specified number of bytes to the stream.
51 *
52 * @public @memberof kStream
53 * @param stream Stream object.
54 * @param buffer Bytes to be written to the stream.
55 * @param size Count of bytes to be written.
56 * @return Operation status.
57 */
58 kFx(kStatus) kStream_Write(kStream stream, const void* buffer, kSize size);
59
60 /**
61 * Copies the specified number of bytes from one stream to another.
62 *
63 * @public @memberof kStream
64 * @param stream Destination stream.
65 * @param source Source stream.
66 * @param size Count of bytes to be copied.
67 * @return Operation status.
68 */
69 kFx(kStatus) kStream_Copy(kStream stream, kStream source, kSize size);
70
71 /**
72 * Copies the specified number of bytes from one stream to another, with progress feedback.
73 *
74 * The specified callback will be invoked to provide feedback on the progress of the operation. The callback 'args'
75 * parameter will receive a k32u value representing the percentage completed. The callback is guaranteed to be
76 * called at least once if the operation is successful, with a progress value of 100%.
77 *
78 * @public @memberof kStream
79 * @param stream Destination stream.
80 * @param source Source stream.
81 * @param size Count of bytes to be copied.
82 * @param progress Optional progress callback (can be kNULL).
83 * @param context Callback context.
84 * @return Operation status.
85 */
86 kFx(kStatus) kStream_CopyEx(kStream stream, kStream source, kSize size, kCallbackFx progress, kPointer context);
87
88 /**
89 * Moves the read/write pointer to the specified location.
90 *
91 * @public @memberof kStream
92 * @param stream Stream object.
93 * @param offset Offset by which to adjust the read/write pointer.
94 * @param origin Origin to which movement is relative (i.e. begin, current, end).
95 * @return Operation status.
96 */
97 kFx(kStatus) kStream_Seek(kStream stream, k64s offset, kSeekOrigin origin);
98
99 /**
100 * Flushes buffered writes to the underlying medium.
101 *
102 * @public @memberof kStream
103 * @param stream Stream object.
104 * @return Operation status.
105 */
106 kFx(kStatus) kStream_Flush(kStream stream);
107
108 /**
109 * Reports the number of bytes read from this stream.
110 *
111 * @public @memberof kStream
112 * @param stream Stream object.
113 * @return Count of bytes read.
114 */
115 kFx(k64u) kStream_BytesRead(kStream stream);
116
117 /**
118 * Reports the number of bytes written to this stream.
119 *
120 * @public @memberof kStream
121 * @param stream Stream object.
122 * @return Count of bytes written.
123 */
124 kFx(k64u) kStream_BytesWritten(kStream stream);
125
126 /**
127 * Clears stream statistics (e.g. BytesRead, BytesWritten).
128 *
129 * @public @memberof kStream
130 * @param stream Stream object.
131 * @return Operation Status
132 */
133 kFx(kStatus) kStream_ClearStats(kStream stream);
134
135 #define kStream_BytesRead_(STREAM) kxStream_BytesRead_(STREAM) ///< Macro version of kStream_BytesRead.
136 #define kStream_BytesWritten_(STREAM) kxStream_BytesWritten_(STREAM) ///< Macro version of kStream_BytesWritten.
137
138 kEndHeader()
139
140 #include <kApi/Io/kStream.x.h>
141
142 #endif
k64u
Represents a 64-bit unsigned integer.
kStream::kStream_CopyEx
kStatus kStream_CopyEx(kStream stream, kStream source, kSize size, kCallbackFx progress, kPointer context)
Copies the specified number of bytes from one stream to another, with progress feedback.
kCallbackFx
kStatus(kCall * kCallbackFx)(kPointer receiver, kPointer sender, void *args)
Callback signature for a generic event handler.
Definition: kApiDef.h:1030
kPointer
Represents a void pointer.
kSize
Represents an unsigned integer that can store a pointer address.
kStream::kStream_ReadSome
kStatus kStream_ReadSome(kStream stream, void *buffer, kSize minCount, kSize maxCount, kSize *bytesRead)
Reads up to the specified number of bytes from the stream.
kStream::kStream_Copy
kStatus kStream_Copy(kStream stream, kStream source, kSize size)
Copies the specified number of bytes from one stream to another.
kStream::kStream_Seek
kStatus kStream_Seek(kStream stream, k64s offset, kSeekOrigin origin)
Moves the read/write pointer to the specified location.
kSeekOrigin
Seek origin enumeration.
kStream::kStream_Read
kStatus kStream_Read(kStream stream, void *buffer, kSize size)
Reads the specified number of bytes from the stream.
kApiDef.h
Essential API declarations.
kStream
Represents an I/O stream.
kStream::kStream_Flush
kStatus kStream_Flush(kStream stream)
Flushes buffered writes to the underlying medium.
k64s
Represents a 64-bit signed integer.
kStream::kStream_BytesRead
k64u kStream_BytesRead(kStream stream)
Reports the number of bytes read from this stream.
kStream::kStream_ClearStats
kStatus kStream_ClearStats(kStream stream)
Clears stream statistics (e.g.
kStream::kStream_BytesWritten
k64u kStream_BytesWritten(kStream stream)
Reports the number of bytes written to this stream.
kStatus
Represents an enumeration of error codes.
kStream::kStream_Write
kStatus kStream_Write(kStream stream, const void *buffer, kSize size)
Writes the specified number of bytes to the stream.