Zen API

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

All Classes Files Functions Variables Typedefs Macros Groups Pages
kMemory.h
Go to the documentation of this file.
1 /**
2 * @file kMemory.h
3 * @brief Declares the kMemory 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_MEMORY_H
11 #define K_API_MEMORY_H
12
13 #include <kApi/kApiDef.h>
14
15 kBeginHeader()
16
17 /**
18 * @class kMemory
19 * @extends kStream
20 * @ingroup kApi-Io
21 * @brief Represents an in-memory stream.
22 */
23 //typedef kStream kMemory; --forward-declared in kApiDef.x.h
24
25 /**
26 * Constructs a kMemory object.
27 *
28 * By default, an auto-sizing, internally-managed buffer is used.
29 *
30 * @public @memberof kMemory
31 * @param memory Destination for the constructed object handle.
32 * @param allocator Memory allocator (or kNULL for default).
33 * @return Operation status.
34 */
35 kFx(kStatus) kMemory_Construct(kMemory* memory, kAlloc allocator);
36
37 /**
38 * Attaches the memory stream to an external, fixed-capacity buffer.
39 *
40 * @public @memberof kMemory
41 * @param memory kMemory object.
42 * @param buffer Data buffer.
43 * @param position Current read/write position, relative to start of buffer.
44 * @param length Length of valid data contained in the buffer, in bytes.
45 * @param capacity Total size of the buffer, in bytes.
46 * @return Operation status.
47 */
48 kFx(kStatus) kMemory_Attach(kMemory memory, void* buffer, kSize position, kSize length, kSize capacity);
49
50 /**
51 * Allocates an auto-sizing, internally-managed buffer for the memory stream.
52 *
53 * @public @memberof kMemory
54 * @param memory kMemory object.
55 * @param initialCapacity Initial capacity of the buffer, in bytes.
56 * @return Operation status.
57 */
58 kFx(kStatus) kMemory_Allocate(kMemory memory, kSize initialCapacity);
59
60 /**
61 * Returns the current length of the memory buffer.
62 *
63 * @public @memberof kMemory
64 * @param memory kMemory object.
65 * @return Length of the memory buffer.
66 */
67 kFx(k64u) kMemory_Length(kMemory memory);
68
69 /**
70 * Returns the current position of the read/write pointer, relative to the beginning of the buffer.
71 *
72 * @public @memberof kMemory
73 * @param memory kMemory object.
74 * @return Position of the write/write pointer.
75 */
76 kFx(k64u) kMemory_Position(kMemory memory);
77
78 /**
79 * Returns the current capacity of the memory buffer.
80 *
81 * @public @memberof kMemory
82 * @param memory kMemory object.
83 * @return Capacity of the memory buffer.
84 */
85 kFx(kSize) kMemory_Capacity(kMemory memory);
86
87 /**
88 * Sets the reported length of the memory buffer.
89 *
90 * @public @memberof kMemory
91 * @param memory kMemory object.
92 * @param length Buffer length
93 * @return Operation status.
94 */
95 kFx(kStatus) kMemory_SetLength(kMemory memory, kSize length);
96
97 /**
98 * Returns a pointer to the memory buffer at the specified position.
99 *
100 * @public @memberof kMemory
101 * @param memory kMemory object.
102 * @param offset Position of interest, in bytes.
103 * @return Operation status.
104 */
105 kFx(void*) kMemory_At(kMemory memory, kSize offset);
106
107 kEndHeader()
108
109 #include <kApi/Io/kMemory.x.h>
110
111 #endif
kMemory
Represents an in-memory stream.
k64u
Represents a 64-bit unsigned integer.
kMemory::kMemory_Construct
kStatus kMemory_Construct(kMemory *memory, kAlloc allocator)
Constructs a kMemory object.
kMemory::kMemory_Capacity
kSize kMemory_Capacity(kMemory memory)
Returns the current capacity of the memory buffer.
kSize
Represents an unsigned integer that can store a pointer address.
kAlloc
Abstract base class for memory allocator types.
kMemory::kMemory_At
void * kMemory_At(kMemory memory, kSize offset)
Returns a pointer to the memory buffer at the specified position.
kApiDef.h
Essential API declarations.
kMemory::kMemory_Position
k64u kMemory_Position(kMemory memory)
Returns the current position of the read/write pointer, relative to the beginning of the buffer...
kMemory::kMemory_Allocate
kStatus kMemory_Allocate(kMemory memory, kSize initialCapacity)
Allocates an auto-sizing, internally-managed buffer for the memory stream.
kMemory::kMemory_SetLength
kStatus kMemory_SetLength(kMemory memory, kSize length)
Sets the reported length of the memory buffer.
kStatus
Represents an enumeration of error codes.
kMemory::kMemory_Attach
kStatus kMemory_Attach(kMemory memory, void *buffer, kSize position, kSize length, kSize capacity)
Attaches the memory stream to an external, fixed-capacity buffer.
kMemory::kMemory_Length
k64u kMemory_Length(kMemory memory)
Returns the current length of the memory buffer.