Panda3D
 All Classes Functions Variables Enumerations
interrogate_interface.h
1 // Filename: interrogate_interface.h
2 // Created by: frang (09Nov99)
3 //
4 ////////////////////////////////////////////////////////////////////
5 //
6 // PANDA 3D SOFTWARE
7 // Copyright (c) Carnegie Mellon University. All rights reserved.
8 //
9 // All use of this software is subject to the terms of the revised BSD
10 // license. You should have received a copy of this license along
11 // with this source code in a file named "LICENSE."
12 //
13 ////////////////////////////////////////////////////////////////////
14 
15 #ifndef INTERROGATE_INTERFACE_H
16 #define INTERROGATE_INTERFACE_H
17 
18 #include "dtoolbase.h"
19 
20 #ifdef __cplusplus
21 extern "C" {
22 #endif
23 
24 // This file defines the interface to the interrogate database. This
25 // database is generated by running interrogate on a package's source
26 // code; interrogate parses the C++ syntax, determines the public
27 // interface, generates C-style wrapper functions where necessary, and
28 // builds up a table of functions and classes and their relationships.
29 
30 // Some of this data (in particular, the wrapper functions, and the
31 // table of unique names for these functions) is linked in along with
32 // the codebase, permanently a part of the library file, and is always
33 // available; the rest of it is stored in external files (named *.in)
34 // and read in when needed. For this reason, most of the interface
35 // functions defined here will force a load of the complete
36 // interrogate database the first time any of them are called. The
37 // three exceptions are noted below; they are
38 // interrogate_wrapper_has_pointer(), interrogate_wrapper_pointer(),
39 // and interrogate_get_wrapper_by_unique_name().
40 
41 
42 // The interface here is intentionally made to be as simple as
43 // possible, to maximize portability. All that is required of a
44 // scripting language is a foreign function interface capable of
45 // calling C functions.
46 
47 
48 // In general, the interrogate database consists of a number of query
49 // functions that allow the caller to walk through the list of
50 // available types, functions, manifests, etc. For each of these, a
51 // unique index number is returned; this index number may then be used
52 // to query details about the type, function, etc. The index numbers
53 // are only guaranteed to remain unchanged during a particular
54 // session; from one session to another they may differ.
55 
56 // All index numbers are ordinary integers. Each has a unique typedef
57 // here for clarity of meaning, but they may be treated as ordinary
58 // integers by the caller.
59 typedef int ManifestIndex;
60 typedef int ElementIndex;
61 typedef int TypeIndex;
62 typedef int FunctionIndex;
63 typedef int FunctionWrapperIndex;
64 typedef int MakeSeqIndex;
65 
66 // Atomic types are those that are built in to C. This enumerated
67 // value is returned by interrogate_type_atomic_token() when a type is
68 // known to be one of the atomic types.
69 enum AtomicToken {
70  AT_not_atomic = 0,
71  AT_int = 1,
72  AT_float = 2,
73  AT_double = 3,
74  AT_bool = 4,
75  AT_char = 5,
76  AT_void = 6,
77 
78  // There isn't an atomic string type in C, but there is one in
79  // almost all other languages. If -string is supplied to the
80  // interrogate command line, functions may be reported as returning
81  // and accepting objects of type atomic string. For the C calling
82  // convention wrappers, atomic string means (const char *); for
83  // other calling convention wrappers, atomic string means whatever
84  // the native string representation is.
85  AT_string = 7,
86 
87  AT_longlong = 8
88 };
89 
90 EXPCL_DTOOLCONFIG void interrogate_add_search_directory(const char *dirname);
91 EXPCL_DTOOLCONFIG void interrogate_add_search_path(const char *pathstring);
92 EXPCL_DTOOLCONFIG bool interrogate_error_flag();
93 
94 //////////////////////////////////////////////////////////////////////////
95 //
96 // Manifest Symbols
97 //
98 //////////////////////////////////////////////////////////////////////////
99 
100 // These correspond to #define constants that appear in the C code.
101 // (These are only the manifest constants--those #define's that take
102 // no parameters. Manifest functions, #define's that take one or more
103 // parameters, are not exported.) They cannot be set, of course, but
104 // they often have a meaningful value that may be get. The scripting
105 // language may choose to get the value as a literal string via
106 // interrogate_manifest_definition(), or as a value of a particular type
107 // (whatever type interrogate thinks it is), as returned by the getter
108 // function given by interrogate_manifest_getter().
109 
110 EXPCL_DTOOLCONFIG int interrogate_number_of_manifests();
111 EXPCL_DTOOLCONFIG ManifestIndex interrogate_get_manifest(int n);
112 EXPCL_DTOOLCONFIG ManifestIndex interrogate_get_manifest_by_name(const char *manifest_name);
113 EXPCL_DTOOLCONFIG const char *interrogate_manifest_name(ManifestIndex manifest);
114 EXPCL_DTOOLCONFIG const char *interrogate_manifest_definition(ManifestIndex manifest);
115 EXPCL_DTOOLCONFIG bool interrogate_manifest_has_type(ManifestIndex manifest);
116 EXPCL_DTOOLCONFIG TypeIndex interrogate_manifest_get_type(ManifestIndex manifest);
117 EXPCL_DTOOLCONFIG bool interrogate_manifest_has_getter(ManifestIndex manifest);
118 EXPCL_DTOOLCONFIG FunctionIndex interrogate_manifest_getter(ManifestIndex manifest);
119 
120 // An exception is made for manifest constants that have an integer
121 // type value, since these are so common. The scripting language can
122 // query these values directly, which saves having to generate a
123 // wrapper function for each stupid little manifest. In this case,
124 // there will be no getter function available.
125 EXPCL_DTOOLCONFIG bool interrogate_manifest_has_int_value(ManifestIndex manifest);
126 EXPCL_DTOOLCONFIG int interrogate_manifest_get_int_value(ManifestIndex manifest);
127 
128 
129 //////////////////////////////////////////////////////////////////////////
130 //
131 // Data Elements
132 //
133 //////////////////////////////////////////////////////////////////////////
134 
135 // These correspond to data members of a class, or global data
136 // elements. Interrogate automatically generates a getter function
137 // and, if possible, a setter function.
138 
139 EXPCL_DTOOLCONFIG const char *interrogate_element_name(ElementIndex element);
140 EXPCL_DTOOLCONFIG const char *interrogate_element_scoped_name(ElementIndex element);
141 EXPCL_DTOOLCONFIG bool interrogate_element_has_comment(ElementIndex element);
142 EXPCL_DTOOLCONFIG const char *interrogate_element_comment(ElementIndex element);
143 EXPCL_DTOOLCONFIG ElementIndex interrogate_get_element_by_name(const char *element_name);
144 EXPCL_DTOOLCONFIG ElementIndex interrogate_get_element_by_scoped_name(const char *element_name);
145 
146 // Be careful with this function. The element's bare type is not
147 // likely to be directly useful to the scripting language. This is a
148 // different answer than the return value of the getter.
149 
150 // The element type might well be something concrete that the
151 // scripting language can't handle directly, e.g. a Node, while the
152 // getter will return (and the setter accept) a pointer to a Node,
153 // which is what the scripting language actually works with.
154 EXPCL_DTOOLCONFIG TypeIndex interrogate_element_type(ElementIndex element);
155 
156 EXPCL_DTOOLCONFIG bool interrogate_element_has_getter(ElementIndex element);
157 EXPCL_DTOOLCONFIG FunctionIndex interrogate_element_getter(ElementIndex element);
158 EXPCL_DTOOLCONFIG bool interrogate_element_has_setter(ElementIndex element);
159 EXPCL_DTOOLCONFIG FunctionIndex interrogate_element_setter(ElementIndex element);
160 
161 //////////////////////////////////////////////////////////////////////////
162 //
163 // Global Data
164 //
165 //////////////////////////////////////////////////////////////////////////
166 
167 // This is the list of global data elements.
168 
169 EXPCL_DTOOLCONFIG int interrogate_number_of_globals();
170 EXPCL_DTOOLCONFIG ElementIndex interrogate_get_global(int n);
171 
172 //////////////////////////////////////////////////////////////////////////
173 //
174 // Functions
175 //
176 //////////////////////////////////////////////////////////////////////////
177 
178 // There is a unique FunctionIndex associated with each of the
179 // functions that interrogate knows about. This includes member
180 // functions, nonmember functions, synthesized getters and setters,
181 // and upcast/downcast functions.
182 
183 
184 // These are the global (nonmember) functions that appear outside of
185 // any class definition.
186 EXPCL_DTOOLCONFIG int interrogate_number_of_global_functions();
187 EXPCL_DTOOLCONFIG FunctionIndex interrogate_get_global_function(int n);
188 
189 // This can be used to traverse through *all* the functions known to
190 // interrogate. It's usually not what you want, since this includes
191 // global functions, class methods, and synthesized functions like
192 // upcasts and downcasts. You probably want to use instead
193 // interrogate_number_of_global_functions(), above.
194 EXPCL_DTOOLCONFIG int interrogate_number_of_functions();
195 EXPCL_DTOOLCONFIG FunctionIndex interrogate_get_function(int n);
196 
197 // This is the function's name. It is not unique; it may be shared
198 // between multiple different functions that have the same name but
199 // different parameter types (this is C++'s function overloading).
200 // Two different classes might also have member functions that have
201 // the same name, or the same name as a global function (but also see
202 // the scoped_name, below).
203 EXPCL_DTOOLCONFIG const char *interrogate_function_name(FunctionIndex function);
204 
205 // The scoped name is the function name prefixed with the name of the
206 // class that includes the function, if the function is a class
207 // method. If it is a global function, the scoped name is the same as
208 // the name returned above. In the absence of C++ function
209 // overloading, this name will be unique to each function.
210 EXPCL_DTOOLCONFIG const char *interrogate_function_scoped_name(FunctionIndex function);
211 
212 // This returns the C++ comment written for the function, either in
213 // the header file or in the .C file, or both.
214 EXPCL_DTOOLCONFIG bool interrogate_function_has_comment(FunctionIndex function);
215 EXPCL_DTOOLCONFIG const char *interrogate_function_comment(FunctionIndex function);
216 
217 // This defines the function prototype as it appears in the C++
218 // source, useful primarily for documentation purposes.
219 EXPCL_DTOOLCONFIG const char *interrogate_function_prototype(FunctionIndex function);
220 
221 // This can be used to determine the class that the function is a
222 // method for, if the function is a class method.
223 EXPCL_DTOOLCONFIG bool interrogate_function_is_method(FunctionIndex function);
224 EXPCL_DTOOLCONFIG TypeIndex interrogate_function_class(FunctionIndex function);
225 
226 // This returns the module name reported for the function, if
227 // available.
228 EXPCL_DTOOLCONFIG bool interrogate_function_has_module_name(FunctionIndex function);
229 EXPCL_DTOOLCONFIG const char *interrogate_function_module_name(FunctionIndex function);
230 
231 // This returns the library name reported for the function, if
232 // available.
233 EXPCL_DTOOLCONFIG bool interrogate_function_has_library_name(FunctionIndex function);
234 EXPCL_DTOOLCONFIG const char *interrogate_function_library_name(FunctionIndex function);
235 
236 // This is true for virtual member functions. It's not likely that
237 // this will be important to the scripting language.
238 EXPCL_DTOOLCONFIG bool interrogate_function_is_virtual(FunctionIndex function);
239 
240 
241 // The actual callable function interface is defined via one or more
242 // wrappers for each function. (There might be multiple wrappers for
243 // the same function to allow for default parameter values.)
244 
245 // At present, interrogate can generate wrappers that use the C
246 // calling convention or the Python calling convention. The set of
247 // wrappers that will actually be available depends on the parameters
248 // passed to the interrogate command line.
249 EXPCL_DTOOLCONFIG int interrogate_function_number_of_c_wrappers(FunctionIndex function);
250 EXPCL_DTOOLCONFIG FunctionWrapperIndex interrogate_function_c_wrapper(FunctionIndex function, int n);
251 
252 EXPCL_DTOOLCONFIG int interrogate_function_number_of_python_wrappers(FunctionIndex function);
253 EXPCL_DTOOLCONFIG FunctionWrapperIndex interrogate_function_python_wrapper(FunctionIndex function, int n);
254 
255 //////////////////////////////////////////////////////////////////////////
256 //
257 // Function wrappers
258 //
259 //////////////////////////////////////////////////////////////////////////
260 
261 // These define the way to call a given function. Depending on the
262 // parameters supplied to interrogate, a function wrapper may be able
263 // to supply either a void * pointer to the function, or the name of
264 // the function in the library, or both.
265 
266 
267 // This returns the actual name of the wrapper function, as opposed to
268 // the name of the function it wraps. It's probably not terribly
269 // useful to the scripting language, unless the -fnames option was
270 // given to interrogate, in which case this name may be used to call
271 // the wrapper function (see is_callable_by_name, below). It will
272 // usually be an ugly hashed name, not intended for human consumption.
273 
274 // Don't confuse this with the unique_name, below. The two are
275 // related, but not identical.
276 EXPCL_DTOOLCONFIG const char *interrogate_wrapper_name(FunctionWrapperIndex wrapper);
277 
278 // This returns true if -fnames was given to interrogate, making the
279 // wrapper function callable directly by its name.
280 EXPCL_DTOOLCONFIG bool interrogate_wrapper_is_callable_by_name(FunctionWrapperIndex wrapper);
281 
282 // This returns the C++ comment written for the function wrapper,
283 // usually from the .cpp file. There may be a different comment for
284 // each overload of a given function.
285 EXPCL_DTOOLCONFIG bool interrogate_wrapper_has_comment(FunctionWrapperIndex wrapper);
286 EXPCL_DTOOLCONFIG const char *interrogate_wrapper_comment(FunctionWrapperIndex wrapper);
287 
288 // Every function wrapper has zero or more parameters and may or may
289 // not have a return value. Each parameter has a type and may or may
290 // not have a name. For member functions, the first parameter may be
291 // a 'this' parameter, which should receive a pointer to the class
292 // object. (If a member function does not have a 'this' parameter as
293 // its first parameter, it is a static member function, also called a
294 // class method.)
295 
296 EXPCL_DTOOLCONFIG bool interrogate_wrapper_has_return_value(FunctionWrapperIndex wrapper);
297 EXPCL_DTOOLCONFIG TypeIndex interrogate_wrapper_return_type(FunctionWrapperIndex wrapper);
298 
299 // Sometimes interrogate must synthesize a wrapper that allocates its
300 // return value from the free store. Other times (especially if
301 // -refcount is supplied to interrogate), interrogate will
302 // automatically increment the count of a reference-counted object
303 // that it returns. In cases like these,
304 // interrogate_wrapper_caller_manages_return_value() will return true,
305 // and it is the responsibility of the scripting language to
306 // eventually call the destructor supplied by
307 // interrogate_wrapper_return_value_destructor() on this value when it
308 // is no longer needed (which will generally be the same destructor as
309 // that for the class). Otherwise, this function will return false,
310 // and the scripting language should *not* call any destructor on this
311 // value.
312 EXPCL_DTOOLCONFIG bool interrogate_wrapper_caller_manages_return_value(FunctionWrapperIndex wrapper);
313 EXPCL_DTOOLCONFIG FunctionIndex interrogate_wrapper_return_value_destructor(FunctionWrapperIndex wrapper);
314 
315 // These define the parameters of the function.
316 EXPCL_DTOOLCONFIG int interrogate_wrapper_number_of_parameters(FunctionWrapperIndex wrapper);
317 EXPCL_DTOOLCONFIG TypeIndex interrogate_wrapper_parameter_type(FunctionWrapperIndex wrapper, int n);
318 EXPCL_DTOOLCONFIG bool interrogate_wrapper_parameter_has_name(FunctionWrapperIndex wrapper, int n);
319 EXPCL_DTOOLCONFIG const char *interrogate_wrapper_parameter_name(FunctionWrapperIndex wrapper, int n);
320 EXPCL_DTOOLCONFIG bool interrogate_wrapper_parameter_is_this(FunctionWrapperIndex wrapper, int n);
321 
322 // This returns a pointer to a function that may be called to invoke
323 // the function, if the -fptrs option to return function pointers was
324 // specified to interrogate. Be sure to push the required parameters
325 // on the stack, according to the calling convention, before calling
326 // the function.
327 
328 // These two functions may be called without forcing a load of the
329 // complete interrogate database.
330 EXPCL_DTOOLCONFIG bool interrogate_wrapper_has_pointer(FunctionWrapperIndex wrapper);
331 EXPCL_DTOOLCONFIG void *interrogate_wrapper_pointer(FunctionWrapperIndex wrapper);
332 
333 // This function will return a name that is guaranteed to be unique to
334 // this particular function wrapper, and that will (usually) be
335 // consistent across multiple runtime sessions. (It will only change
336 // between sessions if the database was regenerated in the interim
337 // with some new function that happened to introduce a hash conflict.)
338 
339 // The unique name is an ugly hashed name, not safe for human
340 // consumption. Its sole purpose is to provide some consistent way to
341 // identify function wrappers between sessions.
342 EXPCL_DTOOLCONFIG const char *interrogate_wrapper_unique_name(FunctionWrapperIndex wrapper);
343 
344 // This function provides a reverse-lookup on the above unique name,
345 // returning the wrapper index corresponding to the given name. It
346 // depends on data having been compiled directly into the library, and
347 // thus is only available if the option -unique-names was given to
348 // interrogate.
349 
350 // This function may be called without forcing a load of the complete
351 // interrogate database.
352 EXPCL_DTOOLCONFIG FunctionWrapperIndex interrogate_get_wrapper_by_unique_name(const char *unique_name);
353 
354 //////////////////////////////////////////////////////////////////////////
355 //
356 // MakeSeqs
357 //
358 //////////////////////////////////////////////////////////////////////////
359 
360 // These are special synthesized methods that iterate through a list.
361 // They are generated in C++ code via the MAKE_SEQ macro. The normal
362 // pattern is that a pair of actual C++ methods like get_num_things()
363 // and get_thing(n) are used to synthesize a new method called
364 // get_things().
365 
366 // The class of which the make_seq is a method.
367 EXPCL_DTOOLCONFIG TypeIndex interrogate_make_seq_class(MakeSeqIndex make_seq);
368 
369 // The name of the syntheized method, e.g. "get_things"
370 EXPCL_DTOOLCONFIG const char *interrogate_make_seq_seq_name(MakeSeqIndex make_seq);
371 // The name of the real method that returns the length, e.g. "get_num_things"
372 EXPCL_DTOOLCONFIG const char *interrogate_make_seq_num_name(MakeSeqIndex make_seq);
373 // The name of the real method that returns the nth element, e.g. "get_thing"
374 EXPCL_DTOOLCONFIG const char *interrogate_make_seq_element_name(MakeSeqIndex make_seq);
375 
376 
377 //////////////////////////////////////////////////////////////////////////
378 //
379 // Types
380 //
381 //////////////////////////////////////////////////////////////////////////
382 
383 // These are all the types that interrogate knows about. This
384 // includes atomic types like ints and floats, type wrappers like
385 // pointers and const pointers, enumerated types, and classes.
386 
387 // Two lists of types are maintained: the list of global types, which
388 // includes only those types intended to be wrapped in the API (for
389 // instance, all of the classes). The second list is the complete
390 // list of all types, which probably does not need to be
391 // traversed--this includes *all* types known to the interrogate
392 // database, including simple types and pointers and const pointers to
393 // classes. These types are necessary to fully define all of the
394 // function parameters, but need not themselves be wrapped.
395 
396 EXPCL_DTOOLCONFIG int interrogate_number_of_global_types();
397 EXPCL_DTOOLCONFIG TypeIndex interrogate_get_global_type(int n);
398 EXPCL_DTOOLCONFIG int interrogate_number_of_types();
399 EXPCL_DTOOLCONFIG TypeIndex interrogate_get_type(int n);
400 EXPCL_DTOOLCONFIG TypeIndex interrogate_get_type_by_name(const char *type_name);
401 EXPCL_DTOOLCONFIG TypeIndex interrogate_get_type_by_scoped_name(const char *type_name);
402 EXPCL_DTOOLCONFIG TypeIndex interrogate_get_type_by_true_name(const char *type_name);
403 EXPCL_DTOOLCONFIG const char *interrogate_type_name(TypeIndex type);
404 EXPCL_DTOOLCONFIG const char *interrogate_type_scoped_name(TypeIndex type);
405 EXPCL_DTOOLCONFIG const char *interrogate_type_true_name(TypeIndex type);
406 
407 // A given type might be a nested type, meaning it is entirely defined
408 // within (and scoped within) some different C++ class. In this case,
409 // the type_name() will return the local name of the type as seen
410 // within the class, while the scoped_name() will return the
411 // fully-qualified name of the type, and is_nested() and outer_class()
412 // can be used to determine the class it is nested within.
413 EXPCL_DTOOLCONFIG bool interrogate_type_is_nested(TypeIndex type);
414 EXPCL_DTOOLCONFIG TypeIndex interrogate_type_outer_class(TypeIndex type);
415 
416 EXPCL_DTOOLCONFIG bool interrogate_type_has_comment(TypeIndex type);
417 EXPCL_DTOOLCONFIG const char *interrogate_type_comment(TypeIndex type);
418 
419 // This returns the module name reported for the type, if available.
420 EXPCL_DTOOLCONFIG bool interrogate_type_has_module_name(TypeIndex type);
421 EXPCL_DTOOLCONFIG const char *interrogate_type_module_name(TypeIndex type);
422 
423 // This returns the library name reported for the type, if available.
424 EXPCL_DTOOLCONFIG bool interrogate_type_has_library_name(TypeIndex type);
425 EXPCL_DTOOLCONFIG const char *interrogate_type_library_name(TypeIndex type);
426 
427 
428 // If interrogate_type_is_atomic() returns true, the type is one of
429 // the basic C types enumerated in AtomicToken, above. The type may
430 // then be further modified by one or more of unsigned, signed, long,
431 // longlong, or short. However, it will not be a pointer.
432 EXPCL_DTOOLCONFIG bool interrogate_type_is_atomic(TypeIndex type);
433 EXPCL_DTOOLCONFIG AtomicToken interrogate_type_atomic_token(TypeIndex type);
434 EXPCL_DTOOLCONFIG bool interrogate_type_is_unsigned(TypeIndex type);
435 EXPCL_DTOOLCONFIG bool interrogate_type_is_signed(TypeIndex type);
436 EXPCL_DTOOLCONFIG bool interrogate_type_is_long(TypeIndex type);
437 EXPCL_DTOOLCONFIG bool interrogate_type_is_longlong(TypeIndex type);
438 EXPCL_DTOOLCONFIG bool interrogate_type_is_short(TypeIndex type);
439 
440 // If interrogate_type_is_wrapped() returns true, this is a composite
441 // type "wrapped" around some simpler type, for instance a pointer to
442 // a class. The type will be either a pointer or a const wrapper--it
443 // cannot be a combination of these. (When combinations are required,
444 // they use multiple wrappers. A const char pointer, for example, is
445 // represented as a pointer wrapper around a const wrapper around an
446 // atomic char.)
447 EXPCL_DTOOLCONFIG bool interrogate_type_is_wrapped(TypeIndex type);
448 EXPCL_DTOOLCONFIG bool interrogate_type_is_pointer(TypeIndex type);
449 EXPCL_DTOOLCONFIG bool interrogate_type_is_const(TypeIndex type);
450 EXPCL_DTOOLCONFIG bool interrogate_type_is_typedef(TypeIndex type);
451 EXPCL_DTOOLCONFIG TypeIndex interrogate_type_wrapped_type(TypeIndex type);
452 
453 // If interrogate_type_is_enum() returns true, this is an enumerated
454 // type, which means it may take any one of a number of named integer
455 // values.
456 EXPCL_DTOOLCONFIG bool interrogate_type_is_enum(TypeIndex type);
457 EXPCL_DTOOLCONFIG int interrogate_type_number_of_enum_values(TypeIndex type);
458 EXPCL_DTOOLCONFIG const char *interrogate_type_enum_value_name(TypeIndex type, int n);
459 EXPCL_DTOOLCONFIG const char *interrogate_type_enum_value_scoped_name(TypeIndex type, int n);
460 EXPCL_DTOOLCONFIG const char *interrogate_type_enum_value_comment(TypeIndex type, int n);
461 EXPCL_DTOOLCONFIG int interrogate_type_enum_value(TypeIndex type, int n);
462 
463 // If none of the above is true, the type is some extension type. It
464 // may be a struct, class, or union (and the distinction between these
465 // three is not likely to be important to the scripting language). In
466 // any case, it may contain zero or more constructors, zero or one
467 // destructor, zero or more member functions, and zero or more data
468 // members; all of the remaining type functions may apply.
469 EXPCL_DTOOLCONFIG bool interrogate_type_is_struct(TypeIndex type);
470 EXPCL_DTOOLCONFIG bool interrogate_type_is_class(TypeIndex type);
471 EXPCL_DTOOLCONFIG bool interrogate_type_is_union(TypeIndex type);
472 
473 // If is_fully_defined() returns false, this class/struct was a
474 // forward reference, and we really don't know anything about it. (In
475 // this case, it will appear to have no methods or members.)
476 EXPCL_DTOOLCONFIG bool interrogate_type_is_fully_defined(TypeIndex type);
477 
478 // If is_unpublished() returns false, the class/struct is unknown
479 // because it was not marked to be published (or, in promiscuous mode,
480 // it is a protected or private nested class).
481 EXPCL_DTOOLCONFIG bool interrogate_type_is_unpublished(TypeIndex type);
482 
483 // Otherwise, especially if the type is a struct or class, we may have
484 // a number of member functions, including zero or more constructors
485 // and zero or one destructor. A constructor function may be called
486 // to allocate a new instance of the type; its return value will be a
487 // pointer to the new instance. The destructor may be called to
488 // destroy the instance; however, it usually should not be explicitly
489 // called by the user, since the proper support of the
490 // interrogate_caller_manages_return_value() interface, above, will
491 // ensure that the appropriate destructors are called when they should
492 // be.
493 
494 // In certain circumstances, the destructor might be inherited from a
495 // parent or ancestor class. This happens when the destructor wrapper
496 // from the ancestor class is an acceptable substitute for this
497 // destructor; this is only possible in the case of a virtual C++
498 // destructor. In this case, the destructor returned here will be the
499 // same function index as the one returned by the ancestor class, and
500 // interrogate_type_destructor_is_inherited() will return true for
501 // this class.
502 EXPCL_DTOOLCONFIG int interrogate_type_number_of_constructors(TypeIndex type);
503 EXPCL_DTOOLCONFIG FunctionIndex interrogate_type_get_constructor(TypeIndex type, int n);
504 EXPCL_DTOOLCONFIG bool interrogate_type_has_destructor(TypeIndex type);
505 EXPCL_DTOOLCONFIG bool interrogate_type_destructor_is_inherited(TypeIndex type);
506 EXPCL_DTOOLCONFIG FunctionIndex interrogate_type_get_destructor(TypeIndex type);
507 
508 // This is the set of exposed data elements in the struct or class.
509 EXPCL_DTOOLCONFIG int interrogate_type_number_of_elements(TypeIndex type);
510 EXPCL_DTOOLCONFIG ElementIndex interrogate_type_get_element(TypeIndex type, int n);
511 
512 // This is the set of exposed member functions in the struct or class.
513 EXPCL_DTOOLCONFIG int interrogate_type_number_of_methods(TypeIndex type);
514 EXPCL_DTOOLCONFIG FunctionIndex interrogate_type_get_method(TypeIndex type, int n);
515 
516 // This is the set of MAKE_SEQ wrappers in the struct or class.
517 EXPCL_DTOOLCONFIG int interrogate_type_number_of_make_seqs(TypeIndex type);
518 EXPCL_DTOOLCONFIG MakeSeqIndex interrogate_type_get_make_seq(TypeIndex type, int n);
519 
520 // A C++ class may also define a number of explicit cast operators,
521 // which define how to convert an object of this type to an object of
522 // some other type (the type can be inferred by the return type of the
523 // cast function). This is not related to upcast and downcast,
524 // defined below.
525 EXPCL_DTOOLCONFIG int interrogate_type_number_of_casts(TypeIndex type);
526 EXPCL_DTOOLCONFIG FunctionIndex interrogate_type_get_cast(TypeIndex type, int n);
527 
528 // A C++ class may inherit from zero or more base classes. This
529 // defines the list of base classes for this particular type.
530 EXPCL_DTOOLCONFIG int interrogate_type_number_of_derivations(TypeIndex type);
531 EXPCL_DTOOLCONFIG TypeIndex interrogate_type_get_derivation(TypeIndex type, int n);
532 
533 // For each base class, we might need to define an explicit upcast or
534 // downcast operation to convert the pointer to the derived class to
535 // an appropriate pointer to its base class (upcast) or vice-versa
536 // (downcast). This is particularly true in the presence of multiple
537 // inheritance or virtual inheritance, in which case you cannot simply
538 // use the same pointer as either type.
539 
540 // If interrogate_type_derivation_has_upcast() returns true for a
541 // particular type/derivation combination, you must use the indicated
542 // upcast function to convert pointers of this type to pointers of the
543 // base type before calling any of the inherited methods from the base
544 // class. If this returns false, you may simply use the same pointer
545 // as either a derived class pointer or a base class pointer without
546 // any extra step.
547 EXPCL_DTOOLCONFIG bool interrogate_type_derivation_has_upcast(TypeIndex type, int n);
548 EXPCL_DTOOLCONFIG FunctionIndex interrogate_type_get_upcast(TypeIndex type, int n);
549 
550 // Although it is always possible to upcast a pointer to a base class,
551 // it is not always possible to downcast from a base class to the
552 // derived class (particularly in the presence of virtual
553 // inheritance). If interrogate_type_derivation_downcast_is_impossible()
554 // returns true, forget it. Otherwise, downcasting works the same
555 // way as upcasting. (Of course, it is the caller's responsibility to
556 // guarantee that the pointer actually represents an object of the
557 // type being downcast to.)
558 EXPCL_DTOOLCONFIG bool interrogate_type_derivation_downcast_is_impossible(TypeIndex type, int n);
559 EXPCL_DTOOLCONFIG bool interrogate_type_derivation_has_downcast(TypeIndex type, int n);
560 EXPCL_DTOOLCONFIG FunctionIndex interrogate_type_get_downcast(TypeIndex type, int n);
561 
562 // A C++ class may also define any number of nested types--classes or
563 // enums defined within the scope of this class.
564 EXPCL_DTOOLCONFIG int interrogate_type_number_of_nested_types(TypeIndex type);
565 EXPCL_DTOOLCONFIG TypeIndex interrogate_type_get_nested_type(TypeIndex type, int n);
566 
567 #ifdef __cplusplus
568 }
569 #endif
570 
571 #endif