Usermode/AxWin4 - Added text rendering (very hacky using VGA font)
[tpg/acess2.git] / KernelLand / Modules / Interfaces / EDI / edi / edi_objects.h
1 #ifndef EDI_OBJECTS_H
2
3 /* Copyright (c)  2006  Eli Gottlieb.
4  * Permission is granted to copy, distribute and/or modify this document
5  * under the terms of the GNU Free Documentation License, Version 1.2
6  * or any later version published by the Free Software Foundation;
7  * with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
8  * Texts.  A copy of the license is included in the file entitled "COPYING". */
9
10 #define EDI_OBJECTS_H
11
12 /*! \file edi_objects.h
13  * \brief The header file for basic EDI types and the object system.
14  *
15  * This file contains declarations of EDI's primitive data types, as well as structures and functions for with the object system.
16  * It represents these data structures and algorithms:
17  * 
18  *      DATA STRUCTURE: THE CLASS LIST - EDI implementing runtime's must keep an internal list of classes implemented by the runtime
19  *      and separate lists of classes implemented by each driver.  Whoever implements a class is said to "own" that class.  The
20  *      internal format of this list is up to the runtime coders, but it must be possible to recreate the original list of
21  *      edi_class_declaration structures the driver declared to the runtime from it.  This list is declared to the runtime in an
22  *      initialization function in the header edi.h.  The object_class member of an edi_object_metadata structure must point to that
23  *      object's class's entry in this list.
24  *      
25  *      ALGORITHM AND DATA STRUCTURE: CLASSES AND INHERITANCE - Classes are described using edi_class_declaration_t structures and
26  *      follow very simple rules.  All data is private and EDI provides no way to access instance data, so there are no member
27  *      variable declarations.  However, if the data isn't memory-protected (for example, driver data on the driver heap) EDI allows
28  *      the possibility of pointer access to data, since runtime and driver coders could make use of that behavior.  Classes may have
29  *      one ancestor by declaring so in their class declaration structure, and if child methods are different then parent methods
30  *      the children always override their parents.  An EDI runtime must also be able to check the existence and ownership of a given
31  *      class given its name in an edi_string_t.
32  *      
33  *      ALGORITHM: OBJECT CREATION AND DESTRUCTION - An EDI runtime should be able to call the constructor of a named class, put the
34  *      resulting object_pointer into an edi_object_metadata_t and return that structure.  The runtime should also be able to call an
35  *      object's class's destructor when given a pointer to a valid edi_metadata_t for an already-existing object.  Data equivalent
36  *      to an edi_object_metadata_t should also be tracked by the runtime for every object in existence in case of sudden EDI shutdown
37  *      (see edi.h).
38  *
39  *      ALGORITHM: RUNTIME TYPE INFORMATION - When passed the data_pointer member of an edi_object_metadata_t to a valid object, an
40  *      EDI runtime must be able to return an edi_string_t containing the name of that object's class and to return function_pointers
41  *      to methods when the required information to find the correct method is given by calling a class's method getting function.*/
42
43 /* If the EDI headers are linked with the standard C library, they use its type definitions.  Otherwise, equivalent definitions are
44  * made.*/
45 #if __STDC_VERSION__ == 199901L
46 # include <stdbool.h>
47 # include <stdint.h>
48 #else
49 # ifndef NULL
50 #  define       NULL    ((void*)0)
51 # endif
52 typedef unsigned char bool;
53 # define true 1
54 # define false 0
55 typedef char int8_t;
56 typedef short int16_t;
57 typedef long int32_t;
58 typedef long long int64_t;
59 typedef unsigned char   uint8_t;
60 typedef unsigned short  uint16_t;
61 typedef unsigned long   uint32_t;
62 typedef unsigned long long      uint64_t;
63 #endif
64
65 /*! \brief Define a variable in the header
66  */
67 #ifdef EDI_MAIN_FILE
68 # define EDI_DEFVAR
69 #else
70 # define EDI_DEFVAR     extern
71 #endif
72
73 /*! \brief A pointer to the in-memory instance of an object.
74  *
75  * This type is sized just like a general C pointer type (whatever*) for the target architecture.  It's passed as a first parameter
76  * to all methods, thus allowing EDI classes to be implemented as C++ classes and providing some protection from confusing objects
77  * with normal pointers.  Equivalent to a C++ this pointer or an Object Pascal Self argument. */
78 typedef void *object_pointer;
79 /*! \brief A basic pointer type pointing to arbitrary data in an arbitrary location. */
80 typedef void *data_pointer;
81 /*! \brief A basic function pointer type.
82  *
83  * A pointer to a piece of code which can be called and return to its caller, used to distinguish between pointers to code and
84  * pointers to data.  Its size is hardware-dependent. */
85 typedef void (*function_pointer)(void);
86 /*! \brief The length of an EDI string without its null character. */
87 #define EDI_STRING_LENGTH 31
88 /*! \brief A type representing a 31-character long string with a terminating NULL character at the end.  All of EDI uses this type
89  * for strings.
90  *
91  * A null-terminated string type which stores characters in int8s.  It allows for 31 characters in each string, with the final
92  * character being the NULL terminator.  Functions which use this type must check that its final character is NULL, a string which
93  * doesn't not have this property is invalid and insecure.  I (the author of EDI) know and understand that this form of a string
94  * suffers from C programmer's disease, but I can't use anything else without either making string use far buggier or dragging
95  * everyone onto a better language than C.  */
96 typedef int8_t edi_string_t[0x20];
97 /*! \brief A type representing a pointer form of #edi_string_t suitable for function returns
98  */
99 typedef int8_t *edi_string_ptr_t;
100
101 /*! \var EDI_BASE_TYPES
102  * \brief A constant array of edi_string_t's holding every available EDI primitive type. */
103 /*! \var EDI_TYPE_MODIFIERS
104  * \brief A constant array of edi_string_t's holding available modifiers for EDI primitive types. */
105 #ifdef IMPLEMENTING_EDI
106  const edi_string_t EDI_BASE_TYPES[9] = {"void","bool","int8_t","int16_t","int32_t","int64_t","function_pointer","intreg","edi_string_t"};
107  const edi_string_t EDI_TYPE_MODIFIERS[2] = {"pointer","unsigned"};
108 #else
109  //extern const edi_string_t EDI_BASE_TYPES[9] = {"void","bool","int8_t","int16_t","int32_t","int64_t","function_pointer","intreg", "edi_string_t"};
110  //extern const edi_string_t EDI_TYPE_MODIFIERS[2] = {"pointer","unsigned"};
111  extern const edi_string_t EDI_BASE_TYPES[9];
112  extern const edi_string_t EDI_TYPE_MODIFIERS[2];
113 #endif
114
115 /*! \struct edi_object_metadata_t
116  * \brief A packed structure holding all data to identify an object to the EDI object system. */
117 typedef struct {
118         /*! \brief Points to the instance data of the object represented by this structure.
119          *
120          * An object_pointer to the object this structure refers to.  The this pointer, so to speak. */
121         object_pointer object;
122         /*! \brief Points the internal record kept by the runtime describing the object's class.
123          *
124          * Points to wherever the runtime has stored the class data this object was built from.  The class data doesn't need to be
125          * readable to the driver, and so this pointer can point to an arbitrary runtime-reachable location. */
126         data_pointer object_class;
127 } edi_object_metadata_t;
128
129 /*! \struct edi_variable_declaration_t
130  * \brief The data structure used to describe a variable declaration to the EDI object system.
131  *
132  * The data structure used to describe a variable declaration to the EDI object system.  The context of the declaration depends on
133  * where the data structure appears, ie: alone, in a class declaration, in a parameter list, etc. */
134 typedef struct {
135         /*! \brief The type of the declared variable. 
136          *
137          * The type of the variable, which must be a valid EDI primitive type as specified in the constant EDI_BASE_TYPES and
138          * possibly modified by a modifier specified in the constant EDI_TYPE_MODIFIERS. */
139         edi_string_t type;
140         /*! \brief The name of the declared variable. */
141         edi_string_t name;
142         /*! \brief Number of array entries if this variable is an array declaration. 
143          *
144          * An int32_t specifying the number of variables of 'type' in the array 'name'.  For a single variable this value should
145          * simply be set to 1, for values greater than 1 a packed array of contiguous variables is being declared, and a value of 0
146          * is invalid. */
147         int32_t array_length;
148 } edi_variable_declaration_t;
149
150 /*! \struct edi_function_declaration_t
151  * \brief The data structure used to declare a function to the EDI object system. */
152 typedef struct {
153         /*! \brief The return type of the function.  The same type rules which govern variable definitions apply here. */
154         edi_string_t return_type;
155         /*! \brief The name of the declared function. */
156         edi_string_t name;
157         /*! \brief The version number of the function, used to tell different implementations of the same function apart. */
158         uint32_t version;
159         /*! \brief The number of arguments passed to the function.
160          *
161          * The number of entries in the member arguments that the object system should care about.  Caring about less misses
162          * parameters to functions, caring about more results in buffer overflows. */
163         uint32_t num_arguments;
164         /*! \brief An array of the declared function's arguments.
165          *
166          * A pointer to an array num_arguments long containing edi_variable_declaration_t's for each argument to the declared
167          * function.*/
168         edi_variable_declaration_t *arguments;
169         /*!\brief A pointer to the declared function's code in memory. */
170         function_pointer code;
171 } edi_function_declaration_t;
172
173 /*! \brief A pointer to a function for constructing instances of a class.
174  *
175  * A pointer to a function which takes no parameters and returns an object_pointer pointing to the newly made instance of a class.
176  * It is the constructor's responsibility to allocate memory for the new object.  Each EDI class needs one of these. */
177 typedef object_pointer (*edi_constructor_t)(void);
178 /*! \brief A pointer to a function for destroying instances of a class.
179  *
180  * A pointer to a function which takes an object_pointer as a parameter and returns void.  This is the destructor counterpart to a
181  * class's edi_constructor_t, it destroys the object pointed to by its parameter and frees the object's memory.  Every class must
182  * have one */
183 typedef void (*edi_destructor_t)(object_pointer);
184
185 /*! \brief Information the driver must give the runtime about its classes so EDI can construct them and call their methods.
186  *
187  * A structure used to declare a class to an EDI runtime so instances of it can be constructed by the EDI object system. */
188 typedef struct {
189         /*! \brief The name of the class declared by the structure. */
190         edi_string_t name;
191         /*! \brief The version of the class.  This number is used to tell identically named but differently
192          * implemented classes apart.*/
193         uint32_t version;
194         /*! \brief The number of methods in the 'methods' function declaration array. */
195         uint32_t num_methods;
196         /*! \brief An array of edi_function_declaration_t declaring the methods of this class. */
197         edi_function_declaration_t *methods;
198         /*! \brief Allocates the memory for a new object of the declared class and constructs the object.  Absolutely required.*/
199         edi_constructor_t constructor;
200         /*! \brief Destroys the given object of the declared class and frees its memory. Absolutely required. */
201         edi_destructor_t destructor;
202         /*! \brief A pointer to another EDI class declaration structure specifying the declared class's parent class. 
203          *
204          * Points to a parent class declared in another class declaration.  It can be NULL to mean this class has no parent. */
205         struct edi_class_declaration_t *parent;
206 } edi_class_declaration_t;
207
208 /*! \brief Checks the existence of the named class.
209  *
210  * This checks for the existence on THE CLASS LIST of the class named by its edi_string_t parameter and returns a signed int32_t.  If
211  * the class isn't found (ie: it doesn't exist as far as EDI is concerned) -1 is returned, if the class is owned by the driver
212  * (implemented by the driver and declared to the runtime by the driver) 0, and if the class is owned by the runtime (implemented by
213  * the runtime) 1. */
214 int32_t check_class_existence(edi_string_t class_name);
215 /*! \brief Constructs an object of the named class and returns its object_pointer and a data_pointer to its class data.
216  *
217  * Given a valid class name in an edi_string_t this function constructs the specified class and returns an edi_metadata_t describing
218  * the new object as detailed in OBJECT CREATION AND DESTRUCTION.  If the construction fails it returns a structure full of NULL
219  * pointers. */
220 edi_object_metadata_t construct_object(edi_string_t class_name);
221 /*! \brief Destroys the given object using its class data.
222  *
223  * As specified in OBJECT CREATION AND DESTRUCTION this function should destroy an object when given its valid edi_metadata_t.  The
224  * destruction is accomplished by calling the class's destructor. */
225 void destroy_object(edi_object_metadata_t object);
226 /*! \brief Obtains a function pointer to a named method of a given class. 
227  *
228  * When given a valid data_pointer object_class from an edi_object_metadata_t and an edi_string_t representing the name of the
229  * desired method retrieves a function_pointer to the method's machine code in memory.  If the desired method isn't found, NULL is
230  * returned. */
231 function_pointer get_method_by_name(data_pointer object_class,edi_string_t method_name);
232 /*! \brief Obtains a function pointer to a method given by a declaration of the given class if the class's method matches the
233  * declaration. 
234  *
235  * Works just like get_method_by_name(), but by giving an edi_function_declaration_t for the desired method instead of just its name.
236  * Performs detailed checking against THE CLASS LIST to make sure that the method returned exactly matches the declaration passed
237  * in. */
238 function_pointer get_method_by_declaration(data_pointer object_class,edi_function_declaration_t declaration);
239
240 /* Runtime typing information. */
241 /*! \brief Returns the name of the class specified by a pointer to class data. 
242  *
243  * Given the data_pointer to an object's class data as stored in an edi_object_metadata_t retrieves the name of the object's class
244  * and returns it in an edi_string_t. */
245 edi_string_ptr_t get_object_class(data_pointer object_class);
246 /*! \brief Returns the name of a class's parent class.
247  *
248  * When given an edi_string_t with a class name in it, returns another edi_string_t containing the name of the class's parent, or an
249  * empty string. */
250 edi_string_ptr_t get_class_parent(edi_string_t some_class);
251 /*! \brief Returns the internal class data of a named class (if it exists) or NULL.
252  *
253  * When given an edi_string_t with a valid class name in it, returns a pointer to the runtime's internal class data for that class.
254  * Otherwise, it returns NULL. */
255 data_pointer get_internal_class(edi_string_t some_class);
256
257 #endif 

UCC git Repository :: git.ucc.asn.au