Zen API

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

All Classes Files Functions Variables Typedefs Macros Groups Pages
kAssembly.h
Go to the documentation of this file.
1 /**
2 * @file kAssembly.h
3 * @brief Declares the kAssembly 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 #include <kApi/kApiDef.h> //--inclusion order controlled by kApiDef
11
12 #ifndef K_API_ASSEMBLY_H
13 #define K_API_ASSEMBLY_H
14
15 kBeginHeader()
16
17 /**
18 * @class kAssembly
19 * @extends kObject
20 * @ingroup kApi
21 * @brief Represents a library of types.
22 *
23 * An assembly represents a collection of types. Typically, one assembly is defined per library or application.
24 *
25 * The kAssembly_Enumerate method can be used to get a list of all loaded assemblies. The kAssemblyOf macro can be
26 * used to obtain a handle to a specific type assembly using the compile-time assembly symbol.
27 *
28 * @code
29 *
30 * //prints a list of supplemental assemblies that have been constructed (i.e., assemblies other than kApiLib)
31 * kStatus PrintOtherAssemblies()
32 * {
33 * kAssembly coreAssembly = kAssemblyOf(kApiLib);
34 * kArrayList assemblyList = kNULL;
35 * kSize i;
36 *
37 * kTry
38 * {
39 * //get a list of the loaded assemblies
40 * kTest(kArrayList_Construct(&assemblyList, kTypeOf(kAssembly), 0, kNULL));
41 * kTest(kAssembly_Enumerate(assemblyList));
42 *
43 * //print information for all assemblies except kApiLib
44 * for (i = 0; i < kArrayList_Count(assemblyList); ++i)
45 * {
46 * kAssembly assembly = kArrayList_As_(assemblyList, i, kAssembly);
47 *
48 * if (assembly != coreAssembly)
49 * {
50 * printf("%s (%u types)\n", kAssembly_Name(assembly), (k32u)kAssembly_TypeCount(assembly));
51 * }
52 * }
53 * }
54 * kFinally
55 * {
56 * //dispose the list of assemblies; each assembly handle returned by kAssembly_Enumerate
57 * //is a reference-counted instance that must be destroyed
58 * kObject_Dispose(assemblyList);
59 *
60 * kEndFinally();
61 * }
62 *
63 * return kOK;
64 * }
65 *
66 * @endcode
67 *
68 */
69 //typedef kObject kAssembly; --forward-declared in kApiDef.x.h
70
71 /**
72 * Gets a list of the currently-loaded assemblies.
73 *
74 * Each assembly returned by this function is a reference-counted instance that should be destroyed
75 * when no longer needed.
76 *
77 * @public @memberof kAssembly
78 * @param assemblies Receives references to loaded assemblies.
79 * @return Operation status.
80 */
81 kFx(kStatus) kAssembly_Enumerate(kArrayList assemblies);
82
83 /**
84 * Adds a callback to be notified when a new assembly is loaded.
85 *
86 * The callback will be notified immediately after the assembly is loaded. The callback 'sender'
87 * argument will be the handle of the loaded assembly.
88 *
89 * The static assembly lock (an internal, recursive, mutual exclusion structure) is held for the duration
90 * of callback invocation. Callback functions should be structured accordingly to avoid the potential
91 * for deadlock.
92 *
93 * @public @memberof kAssembly
94 * @param function Callback function.
95 * @param receiver Context pointer for callback function.
96 * @return Operation status.
97 */
98 kFx(kStatus) kAssembly_AddLoadHandler(kCallbackFx function, kPointer receiver);
99
100 /**
101 * Removes a callback that was registered with the kAssembly_AddLoadHandler function.
102 *
103 * @public @memberof kAssembly
104 * @param function Callback function.
105 * @param receiver Context pointer for callback function.
106 * @return Operation status.
107 */
108 kFx(kStatus) kAssembly_RemoveLoadHandler(kCallbackFx function, kPointer receiver);
109
110 /**
111 * Adds a callback to be notified just prior to unloading an assembly.
112 *
113 * The callback will be notified just prior to unloading the assembly. The callback 'sender'
114 * argument will be the handle of the assembly that is being unloaded.
115 *
116 * The static assembly lock (an internal, recursive, mutual exclusion structure) is held for the duration
117 * of callback invocation. Callback functions should be structured accordingly to avoid the potential
118 * for deadlock.
119 *
120 * @public @memberof kAssembly
121 * @param function Callback function.
122 * @param receiver Context pointer for callback function.
123 * @return Operation status.
124 */
125 kFx(kStatus) kAssembly_AddUnloadHandler(kCallbackFx function, kPointer receiver);
126
127 /**
128 * Removes a callback that was registered with the kAssembly_AddUnloadHandler function.
129 *
130 * @public @memberof kAssembly
131 * @param function Callback function.
132 * @param receiver Context pointer for callback function.
133 * @return Operation status.
134 */
135 kFx(kStatus) kAssembly_RemoveUnloadHandler(kCallbackFx function, kPointer receiver);
136
137 /**
138 * Adds a callback to be notified after unloading an assmebly.
139 *
140 * The callback will be notified just after the release of the assembly's static types, and just
141 * prior to destroying the assembly handle. The callback 'sender' argument will be the handle of
142 * the assembly that is being unloaded.
143 *
144 * The static assembly lock (an internal, recursive, mutual exclusion structure) is held for the duration
145 * of callback invocation. Callback functions should be structured accordingly to avoid the potential
146 * for deadlock.
147 *
148 * @public @memberof kAssembly
149 * @param function Callback function.
150 * @param receiver Context pointer for callback function.
151 * @return Operation status.
152 */
153 kFx(kStatus) kAssembly_AddUnloadedHandler(kCallbackFx function, kPointer receiver);
154
155 /**
156 * Removes a callback that was registered with the kAssembly_AddUnloadedHandler function.
157 *
158 * @public @memberof kAssembly
159 * @param function Callback function.
160 * @param receiver Context pointer for callback function.
161 * @return Operation status.
162 */
163 kFx(kStatus) kAssembly_RemoveUnloadedHandler(kCallbackFx function, kPointer receiver);
164
165 /**
166 * Gets the assembly version.
167 *
168 * @public @memberof kAssembly
169 * @param assembly Assembly.
170 * @return Version number.
171 */
172 kFx(kVersion) kAssembly_Version(kAssembly assembly);
173
174 /**
175 * Gets the assembly name.
176 *
177 * @public @memberof kAssembly
178 * @param assembly Assembly.
179 * @return Assembly name.
180 */
181 kFx(const kChar*) kAssembly_Name(kAssembly assembly);
182
183 /**
184 * Gets the number of types in an assembly.
185 *
186 * @public @memberof kAssembly
187 * @param assembly Assembly.
188 * @return Operation status.
189 */
190 kFx(kSize) kAssembly_TypeCount(kAssembly assembly);
191
192 /**
193 * Gets the type at a particular index within an assembly.
194 *
195 * @public @memberof kAssembly
196 * @param assembly Assembly.
197 * @param index Type index.
198 * @return Type.
199 */
200 kFx(kType) kAssembly_TypeAt(kAssembly assembly, kSize index);
201
202 /**
203 * Finds a type by name.
204 *
205 * @public @memberof kAssembly
206 * @param assembly Assembly to search.
207 * @param name Type name.
208 * @param type Receives the type.
209 * @return Operation status (kERROR_NOT_FOUND on lookup failure).
210 */
211 kFx(kStatus) kAssembly_FindType(kAssembly assembly, const kChar* name, kType* type);
212
213 kEndHeader()
214
215 #include <kApi/kAssembly.x.h>
216
217 #endif
kAssembly::kAssembly_AddUnloadedHandler
kStatus kAssembly_AddUnloadedHandler(kCallbackFx function, kPointer receiver)
Adds a callback to be notified after unloading an assmebly.
kAssembly::kAssembly_FindType
kStatus kAssembly_FindType(kAssembly assembly, const kChar *name, kType *type)
Finds a type by name.
kAssembly::kAssembly_AddLoadHandler
kStatus kAssembly_AddLoadHandler(kCallbackFx function, kPointer receiver)
Adds a callback to be notified when a new assembly is loaded.
kCallbackFx
kStatus(kCall * kCallbackFx)(kPointer receiver, kPointer sender, void *args)
Callback signature for a generic event handler.
Definition: kApiDef.h:1030
kAssembly
Represents a library of types.
kPointer
Represents a void pointer.
kAssembly::kAssembly_AddUnloadHandler
kStatus kAssembly_AddUnloadHandler(kCallbackFx function, kPointer receiver)
Adds a callback to be notified just prior to unloading an assembly.
kAssembly::kAssembly_Version
kVersion kAssembly_Version(kAssembly assembly)
Gets the assembly version.
kSize
Represents an unsigned integer that can store a pointer address.
kAssembly::kAssembly_TypeAt
kType kAssembly_TypeAt(kAssembly assembly, kSize index)
Gets the type at a particular index within an assembly.
kAssembly::kAssembly_RemoveLoadHandler
kStatus kAssembly_RemoveLoadHandler(kCallbackFx function, kPointer receiver)
Removes a callback that was registered with the kAssembly_AddLoadHandler function.
kChar
Represents a single unit (byte) in a UTF-8 character.
kAssembly::kAssembly_RemoveUnloadedHandler
kStatus kAssembly_RemoveUnloadedHandler(kCallbackFx function, kPointer receiver)
Removes a callback that was registered with the kAssembly_AddUnloadedHandler function.
kApiDef.h
Essential API declarations.
kAssembly::kAssembly_RemoveUnloadHandler
kStatus kAssembly_RemoveUnloadHandler(kCallbackFx function, kPointer receiver)
Removes a callback that was registered with the kAssembly_AddUnloadHandler function.
kType
Represents metadata about a type (class, interface, or value).
kAssembly::kAssembly_Enumerate
kStatus kAssembly_Enumerate(kArrayList assemblies)
Gets a list of the currently-loaded assemblies.
kArrayList
Represents a list implemented with a dynamic array.
kAssembly::kAssembly_Name
const kChar * kAssembly_Name(kAssembly assembly)
Gets the assembly name.
kVersion
Represents a version number.
kStatus
Represents an enumeration of error codes.
kAssembly::kAssembly_TypeCount
kSize kAssembly_TypeCount(kAssembly assembly)
Gets the number of types in an assembly.