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