Zen API

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

All Classes Files Functions Variables Typedefs Macros Groups Pages
kFile.h
Go to the documentation of this file.
1 /**
2 * @file kFile.h
3 * @brief Declares the kFile class.
4 *
5 * @internal
6 * Copyright (C) 2004-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_FILE_H
11 #define K_API_FILE_H
12
13 #include <kApi/kApiDef.h>
14
15 kBeginHeader()
16
17 /**
18 * @class kFile
19 * @extends kStream
20 * @ingroup kApi-Io
21 * @brief Represents a file stream.
22 */
23 //typedef kStream kFile; --forward-declared in kApiDef.x.h
24
25 /**
26 * Reads the specified file and provides the file contents in an array.
27 *
28 * @public @memberof kFile
29 * @param path Path to file.
30 * @param data Receives a pointer to the file contents.
31 * @param size Receives the size of the file contents.
32 * @param allocator Memory allocator (or kNULL for default).
33 * @return Operation status.
34 */
35 kFx(kStatus) kFile_Load(const kChar* path, void* data, kSize* size, kAlloc allocator);
36
37 /**
38 * Reads the specified file into the provided array.
39 *
40 * @public @memberof kFile
41 * @param path Path to file.
42 * @param data Receives file contents.
43 * @param capacity Amount of file to read, in bytes.
44 * @return Operation status (kERROR_INCOMPLETE if file is smaller than capacity).
45 */
46 kFx(kStatus) kFile_LoadTo(const kChar* path, void* data, kSize capacity);
47
48 /**
49 * Saves the specified data to the specified file.
50 *
51 * @public @memberof kFile
52 * @param path Path to file.
53 * @param data Pointer to the file contents.
54 * @param size Size of the file contents.
55 * @return Operation status.
56 */
57 kFx(kStatus) kFile_Save(const kChar* path, const kByte* data, kSize size);
58
59 /**
60 * Constructs a kFile object.
61 *
62 * @public @memberof kFile
63 * @param file Destination for the constructed object handle.
64 * @param path Path to the file.
65 * @param mode Specifies how to open the file.
66 * @param allocator Memory allocator (or kNULL for default).
67 * @return Operation status.
68 */
69 kFx(kStatus) kFile_Construct(kFile* file, const kChar* path, kFileMode mode, kAlloc allocator);
70
71 /**
72 * Performs any outstanding I/O operations and closes the underlying file.
73 *
74 * The purpose of the Close method is to provide an opportunity to finalize I/O and
75 * report any errors before destroying a file object. If the Destroy method is called without
76 * having closed the file, the Destroy method will close the file and ignore any errors.
77 *
78 * The Close method should only be called once per file object. After calling the Close method,
79 * any operations other than Destroy will produce an undefined result.
80 *
81 *
82 * @public @memberof kFile
83 * @param file File object.
84 * @return Operation status.
85 */
86 kFx(kStatus) kFile_Close(kFile file);
87
88 /**
89 * Sets the size of the buffer used for writing.
90 *
91 * Buffering can improve efficiency when performing several small write operations.
92 * The default buffer size is 0.
93 *
94 * @public @memberof kFile
95 * @param file File object.
96 * @param size Size of the buffer.
97 * @return Operation status.
98 */
99 kFx(kStatus) kFile_SetWriteBuffer(kFile file, kSize size);
100
101 /**
102 * Sets the size of the buffer used for reading.
103 *
104 * Buffering can improve efficiency when performing several small read operations.
105 * The default buffer size is 0.
106 *
107 * @public @memberof kFile
108 * @param file File object.
109 * @param size Size of the buffer.
110 * @return Operation status.
111 */
112 kFx(kStatus) kFile_SetReadBuffer(kFile file, kSize size);
113
114 /**
115 * Returns the current length of the file.
116 *
117 * @public @memberof kFile
118 * @param file File object.
119 * @return Length of the file, in bytes.
120 */
121 kFx(k64u) kFile_Length(kFile file);
122
123 /**
124 * Returns the current position of the read/write pointer, relative to the beginning of the file.
125 *
126 * @public @memberof kFile
127 * @param file File object.
128 * @return Offset of read/write pointer from beginning of file.
129 */
130 kFx(k64u) kFile_Position(kFile file);
131
132 /**
133 * Reports whether the specified file exists.
134 *
135 * @public @memberof kFile
136 * @param fileName Path to the file.
137 * @return kTRUE if the file exists; kFALSE otherwise.
138 */
139 kFx(kBool) kFile_Exists(const kChar* fileName);
140
141 /**
142 * Reports the size the specified file, in bytes.
143 *
144 * @public @memberof kFile
145 * @param fileName Path to the file.
146 * @return Size of the file, in bytes.
147 */
148 kFx(k64u) kFile_Size(const kChar* fileName);
149
150 /**
151 * Copies a file to the specified destination.
152 *
153 * @public @memberof kFile
154 * @param source Source file path.
155 * @param destination Destination file path.
156 * @return Operation status.
157 */
158 kFx(kStatus) kFile_Copy(const kChar* source, const kChar* destination);
159
160 /**
161 * Copies a file to the specified destination with progress feedback.
162 *
163 * The specified callback will be invoked to provide feedback on the progress of the operation. The callback 'args'
164 * parameter will receive a k32u value representing the percentage completed. The callback is guaranteed to be
165 * called at least once if the operation is successful, with a progress value of 100%.
166 *
167 * @public @memberof kFile
168 * @param source Source file path.
169 * @param destination Destination file path.
170 * @param progress Optional progress callback (can be kNULL).
171 * @param context Callback context.
172 * @return Operation status.
173 */
174 kFx(kStatus) kFile_CopyEx(const kChar* source, const kChar* destination, kCallbackFx progress, kPointer context);
175
176 /**
177 * Moves a file to the specified destination.
178 *
179 * @public @memberof kFile
180 * @param source Source file path.
181 * @param destination Destination file path.
182 * @return Operation status.
183 */
184 kFx(kStatus) kFile_Move(const kChar* source, const kChar* destination);
185
186 /**
187 * Moves a file to the specified destination with progress feedback.
188 *
189 * The specified callback will be invoked to provide feedback on the progress of the operation. The callback 'args'
190 * parameter will receive a k32u value representing the percentage completed. The callback is guaranteed to be
191 * called at least once if the operation is successful, with a progress value of 100%.
192 *
193 * @public @memberof kFile
194 * @param source Source file path.
195 * @param destination Destination file path.
196 * @param progress Optional progress callback (can be kNULL).
197 * @param context Callback context.
198 * @return Operation status.
199 */
200 kFx(kStatus) kFile_MoveEx(const kChar* source, const kChar* destination, kCallbackFx progress, kPointer context);
201
202 /**
203 * Deletes the specified file.
204 *
205 * @public @memberof kFile
206 * @param path File path.
207 * @return Operation status.
208 */
209 kFx(kStatus) kFile_Delete(const kChar* path);
210
211 /**
212 * Gets a temporary file name.
213 *
214 * @public @memberof kFile
215 * @param name Receives temporary file name.
216 * @param capacity Maximum number of characters (including null terminator).
217 * @return Operation status.
218 */
219 kFx(kStatus) kFile_TempName(kChar* name, kSize capacity);
220
221 kEndHeader()
222
223 #include <kApi/Io/kFile.x.h>
224
225 #endif
kFile::kFile_Save
kStatus kFile_Save(const kChar *path, const kByte *data, kSize size)
Saves the specified data to the specified file.
k64u
Represents a 64-bit unsigned integer.
kFile::kFile_SetWriteBuffer
kStatus kFile_SetWriteBuffer(kFile file, kSize size)
Sets the size of the buffer used for writing.
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.
kFile::kFile_Length
k64u kFile_Length(kFile file)
Returns the current length of the file.
kFile::kFile_Close
kStatus kFile_Close(kFile file)
Performs any outstanding I/O operations and closes the underlying file.
kFile::kFile_Exists
kBool kFile_Exists(const kChar *fileName)
Reports whether the specified file exists.
kFile::kFile_Delete
kStatus kFile_Delete(const kChar *path)
Deletes the specified file.
kFile::kFile_TempName
kStatus kFile_TempName(kChar *name, kSize capacity)
Gets a temporary file name.
kSize
Represents an unsigned integer that can store a pointer address.
kAlloc
Abstract base class for memory allocator types.
kFile::kFile_Size
k64u kFile_Size(const kChar *fileName)
Reports the size the specified file, in bytes.
kChar
Represents a single unit (byte) in a UTF-8 character.
kByte
Represents a byte on the current platform.
kFile
Represents a file stream.
kFile::kFile_Move
kStatus kFile_Move(const kChar *source, const kChar *destination)
Moves a file to the specified destination.
kFile::kFile_CopyEx
kStatus kFile_CopyEx(const kChar *source, const kChar *destination, kCallbackFx progress, kPointer context)
Copies a file to the specified destination with progress feedback.
kFile::kFile_Construct
kStatus kFile_Construct(kFile *file, const kChar *path, kFileMode mode, kAlloc allocator)
Constructs a kFile object.
kApiDef.h
Essential API declarations.
kFile::kFile_Position
k64u kFile_Position(kFile file)
Returns the current position of the read/write pointer, relative to the beginning of the file...
kFile::kFile_LoadTo
kStatus kFile_LoadTo(const kChar *path, void *data, kSize capacity)
Reads the specified file into the provided array.
kFile::kFile_Load
kStatus kFile_Load(const kChar *path, void *data, kSize *size, kAlloc allocator)
Reads the specified file and provides the file contents in an array.
kFileMode
Flags that control how a file is opened.
kFile::kFile_Copy
kStatus kFile_Copy(const kChar *source, const kChar *destination)
Copies a file to the specified destination.
kStatus
Represents an enumeration of error codes.
kFile::kFile_SetReadBuffer
kStatus kFile_SetReadBuffer(kFile file, kSize size)
Sets the size of the buffer used for reading.
kFile::kFile_MoveEx
kStatus kFile_MoveEx(const kChar *source, const kChar *destination, kCallbackFx progress, kPointer context)
Moves a file to the specified destination with progress feedback.
kBool
Represents a boolean value.