Panda3D
|
00001 // Filename: interrogate_interface.h 00002 // Created by: frang (09Nov99) 00003 // 00004 //////////////////////////////////////////////////////////////////// 00005 // 00006 // PANDA 3D SOFTWARE 00007 // Copyright (c) Carnegie Mellon University. All rights reserved. 00008 // 00009 // All use of this software is subject to the terms of the revised BSD 00010 // license. You should have received a copy of this license along 00011 // with this source code in a file named "LICENSE." 00012 // 00013 //////////////////////////////////////////////////////////////////// 00014 00015 #ifndef INTERROGATE_INTERFACE_H 00016 #define INTERROGATE_INTERFACE_H 00017 00018 #include "dtoolbase.h" 00019 00020 #ifdef __cplusplus 00021 extern "C" { 00022 #endif 00023 00024 // This file defines the interface to the interrogate database. This 00025 // database is generated by running interrogate on a package's source 00026 // code; interrogate parses the C++ syntax, determines the public 00027 // interface, generates C-style wrapper functions where necessary, and 00028 // builds up a table of functions and classes and their relationships. 00029 00030 // Some of this data (in particular, the wrapper functions, and the 00031 // table of unique names for these functions) is linked in along with 00032 // the codebase, permanently a part of the library file, and is always 00033 // available; the rest of it is stored in external files (named *.in) 00034 // and read in when needed. For this reason, most of the interface 00035 // functions defined here will force a load of the complete 00036 // interrogate database the first time any of them are called. The 00037 // three exceptions are noted below; they are 00038 // interrogate_wrapper_has_pointer(), interrogate_wrapper_pointer(), 00039 // and interrogate_get_wrapper_by_unique_name(). 00040 00041 00042 // The interface here is intentionally made to be as simple as 00043 // possible, to maximize portability. All that is required of a 00044 // scripting language is a foreign function interface capable of 00045 // calling C functions. 00046 00047 00048 // In general, the interrogate database consists of a number of query 00049 // functions that allow the caller to walk through the list of 00050 // available types, functions, manifests, etc. For each of these, a 00051 // unique index number is returned; this index number may then be used 00052 // to query details about the type, function, etc. The index numbers 00053 // are only guaranteed to remain unchanged during a particular 00054 // session; from one session to another they may differ. 00055 00056 // All index numbers are ordinary integers. Each has a unique typedef 00057 // here for clarity of meaning, but they may be treated as ordinary 00058 // integers by the caller. 00059 typedef int ManifestIndex; 00060 typedef int ElementIndex; 00061 typedef int TypeIndex; 00062 typedef int FunctionIndex; 00063 typedef int FunctionWrapperIndex; 00064 typedef int MakeSeqIndex; 00065 00066 // Atomic types are those that are built in to C. This enumerated 00067 // value is returned by interrogate_type_atomic_token() when a type is 00068 // known to be one of the atomic types. 00069 enum AtomicToken { 00070 AT_not_atomic = 0, 00071 AT_int = 1, 00072 AT_float = 2, 00073 AT_double = 3, 00074 AT_bool = 4, 00075 AT_char = 5, 00076 AT_void = 6, 00077 00078 // There isn't an atomic string type in C, but there is one in 00079 // almost all other languages. If -string is supplied to the 00080 // interrogate command line, functions may be reported as returning 00081 // and accepting objects of type atomic string. For the C calling 00082 // convention wrappers, atomic string means (const char *); for 00083 // other calling convention wrappers, atomic string means whatever 00084 // the native string representation is. 00085 AT_string = 7, 00086 00087 AT_longlong = 8 00088 }; 00089 00090 EXPCL_DTOOLCONFIG void interrogate_add_search_directory(const char *dirname); 00091 EXPCL_DTOOLCONFIG void interrogate_add_search_path(const char *pathstring); 00092 EXPCL_DTOOLCONFIG bool interrogate_error_flag(); 00093 00094 ////////////////////////////////////////////////////////////////////////// 00095 // 00096 // Manifest Symbols 00097 // 00098 ////////////////////////////////////////////////////////////////////////// 00099 00100 // These correspond to #define constants that appear in the C code. 00101 // (These are only the manifest constants--those #define's that take 00102 // no parameters. Manifest functions, #define's that take one or more 00103 // parameters, are not exported.) They cannot be set, of course, but 00104 // they often have a meaningful value that may be get. The scripting 00105 // language may choose to get the value as a literal string via 00106 // interrogate_manifest_definition(), or as a value of a particular type 00107 // (whatever type interrogate thinks it is), as returned by the getter 00108 // function given by interrogate_manifest_getter(). 00109 00110 EXPCL_DTOOLCONFIG int interrogate_number_of_manifests(); 00111 EXPCL_DTOOLCONFIG ManifestIndex interrogate_get_manifest(int n); 00112 EXPCL_DTOOLCONFIG ManifestIndex interrogate_get_manifest_by_name(const char *manifest_name); 00113 EXPCL_DTOOLCONFIG const char *interrogate_manifest_name(ManifestIndex manifest); 00114 EXPCL_DTOOLCONFIG const char *interrogate_manifest_definition(ManifestIndex manifest); 00115 EXPCL_DTOOLCONFIG bool interrogate_manifest_has_type(ManifestIndex manifest); 00116 EXPCL_DTOOLCONFIG TypeIndex interrogate_manifest_get_type(ManifestIndex manifest); 00117 EXPCL_DTOOLCONFIG bool interrogate_manifest_has_getter(ManifestIndex manifest); 00118 EXPCL_DTOOLCONFIG FunctionIndex interrogate_manifest_getter(ManifestIndex manifest); 00119 00120 // An exception is made for manifest constants that have an integer 00121 // type value, since these are so common. The scripting language can 00122 // query these values directly, which saves having to generate a 00123 // wrapper function for each stupid little manifest. In this case, 00124 // there will be no getter function available. 00125 EXPCL_DTOOLCONFIG bool interrogate_manifest_has_int_value(ManifestIndex manifest); 00126 EXPCL_DTOOLCONFIG int interrogate_manifest_get_int_value(ManifestIndex manifest); 00127 00128 00129 ////////////////////////////////////////////////////////////////////////// 00130 // 00131 // Data Elements 00132 // 00133 ////////////////////////////////////////////////////////////////////////// 00134 00135 // These correspond to data members of a class, or global data 00136 // elements. Interrogate automatically generates a getter function 00137 // and, if possible, a setter function. 00138 00139 EXPCL_DTOOLCONFIG const char *interrogate_element_name(ElementIndex element); 00140 EXPCL_DTOOLCONFIG const char *interrogate_element_scoped_name(ElementIndex element); 00141 EXPCL_DTOOLCONFIG ElementIndex interrogate_get_element_by_name(const char *element_name); 00142 EXPCL_DTOOLCONFIG ElementIndex interrogate_get_element_by_scoped_name(const char *element_name); 00143 00144 // Be careful with this function. The element's bare type is not 00145 // likely to be directly useful to the scripting language. This is a 00146 // different answer than the return value of the getter. 00147 00148 // The element type might well be something concrete that the 00149 // scripting language can't handle directly, e.g. a Node, while the 00150 // getter will return (and the setter accept) a pointer to a Node, 00151 // which is what the scripting language actually works with. 00152 EXPCL_DTOOLCONFIG TypeIndex interrogate_element_type(ElementIndex element); 00153 00154 EXPCL_DTOOLCONFIG bool interrogate_element_has_getter(ElementIndex element); 00155 EXPCL_DTOOLCONFIG FunctionIndex interrogate_element_getter(ElementIndex element); 00156 EXPCL_DTOOLCONFIG bool interrogate_element_has_setter(ElementIndex element); 00157 EXPCL_DTOOLCONFIG FunctionIndex interrogate_element_setter(ElementIndex element); 00158 00159 ////////////////////////////////////////////////////////////////////////// 00160 // 00161 // Global Data 00162 // 00163 ////////////////////////////////////////////////////////////////////////// 00164 00165 // This is the list of global data elements. 00166 00167 EXPCL_DTOOLCONFIG int interrogate_number_of_globals(); 00168 EXPCL_DTOOLCONFIG ElementIndex interrogate_get_global(int n); 00169 00170 ////////////////////////////////////////////////////////////////////////// 00171 // 00172 // Functions 00173 // 00174 ////////////////////////////////////////////////////////////////////////// 00175 00176 // There is a unique FunctionIndex associated with each of the 00177 // functions that interrogate knows about. This includes member 00178 // functions, nonmember functions, synthesized getters and setters, 00179 // and upcast/downcast functions. 00180 00181 00182 // These are the global (nonmember) functions that appear outside of 00183 // any class definition. 00184 EXPCL_DTOOLCONFIG int interrogate_number_of_global_functions(); 00185 EXPCL_DTOOLCONFIG FunctionIndex interrogate_get_global_function(int n); 00186 00187 // This can be used to traverse through *all* the functions known to 00188 // interrogate. It's usually not what you want, since this includes 00189 // global functions, class methods, and synthesized functions like 00190 // upcasts and downcasts. You probably want to use instead 00191 // interrogate_number_of_global_functions(), above. 00192 EXPCL_DTOOLCONFIG int interrogate_number_of_functions(); 00193 EXPCL_DTOOLCONFIG FunctionIndex interrogate_get_function(int n); 00194 00195 // This is the function's name. It is not unique; it may be shared 00196 // between multiple different functions that have the same name but 00197 // different parameter types (this is C++'s function overloading). 00198 // Two different classes might also have member functions that have 00199 // the same name, or the same name as a global function (but also see 00200 // the scoped_name, below). 00201 EXPCL_DTOOLCONFIG const char *interrogate_function_name(FunctionIndex function); 00202 00203 // The scoped name is the function name prefixed with the name of the 00204 // class that includes the function, if the function is a class 00205 // method. If it is a global function, the scoped name is the same as 00206 // the name returned above. In the absence of C++ function 00207 // overloading, this name will be unique to each function. 00208 EXPCL_DTOOLCONFIG const char *interrogate_function_scoped_name(FunctionIndex function); 00209 00210 // This returns the C++ comment written for the function, either in 00211 // the header file or in the .C file, or both. 00212 EXPCL_DTOOLCONFIG bool interrogate_function_has_comment(FunctionIndex function); 00213 EXPCL_DTOOLCONFIG const char *interrogate_function_comment(FunctionIndex function); 00214 00215 // This defines the function prototype as it appears in the C++ 00216 // source, useful primarily for documentation purposes. 00217 EXPCL_DTOOLCONFIG const char *interrogate_function_prototype(FunctionIndex function); 00218 00219 // This can be used to determine the class that the function is a 00220 // method for, if the function is a class method. 00221 EXPCL_DTOOLCONFIG bool interrogate_function_is_method(FunctionIndex function); 00222 EXPCL_DTOOLCONFIG TypeIndex interrogate_function_class(FunctionIndex function); 00223 00224 // This returns the module name reported for the function, if 00225 // available. 00226 EXPCL_DTOOLCONFIG bool interrogate_function_has_module_name(FunctionIndex function); 00227 EXPCL_DTOOLCONFIG const char *interrogate_function_module_name(FunctionIndex function); 00228 00229 // This returns the library name reported for the function, if 00230 // available. 00231 EXPCL_DTOOLCONFIG bool interrogate_function_has_library_name(FunctionIndex function); 00232 EXPCL_DTOOLCONFIG const char *interrogate_function_library_name(FunctionIndex function); 00233 00234 // This is true for virtual member functions. It's not likely that 00235 // this will be important to the scripting language. 00236 EXPCL_DTOOLCONFIG bool interrogate_function_is_virtual(FunctionIndex function); 00237 00238 00239 // The actual callable function interface is defined via one or more 00240 // wrappers for each function. (There might be multiple wrappers for 00241 // the same function to allow for default parameter values.) 00242 00243 // At present, interrogate can generate wrappers that use the C 00244 // calling convention or the Python calling convention. The set of 00245 // wrappers that will actually be available depends on the parameters 00246 // passed to the interrogate command line. 00247 EXPCL_DTOOLCONFIG int interrogate_function_number_of_c_wrappers(FunctionIndex function); 00248 EXPCL_DTOOLCONFIG FunctionWrapperIndex interrogate_function_c_wrapper(FunctionIndex function, int n); 00249 00250 EXPCL_DTOOLCONFIG int interrogate_function_number_of_python_wrappers(FunctionIndex function); 00251 EXPCL_DTOOLCONFIG FunctionWrapperIndex interrogate_function_python_wrapper(FunctionIndex function, int n); 00252 00253 ////////////////////////////////////////////////////////////////////////// 00254 // 00255 // Function wrappers 00256 // 00257 ////////////////////////////////////////////////////////////////////////// 00258 00259 // These define the way to call a given function. Depending on the 00260 // parameters supplied to interrogate, a function wrapper may be able 00261 // to supply either a void * pointer to the function, or the name of 00262 // the function in the library, or both. 00263 00264 00265 // This returns the actual name of the wrapper function, as opposed to 00266 // the name of the function it wraps. It's probably not terribly 00267 // useful to the scripting language, unless the -fnames option was 00268 // given to interrogate, in which case this name may be used to call 00269 // the wrapper function (see is_callable_by_name, below). It will 00270 // usually be an ugly hashed name, not intended for human consumption. 00271 00272 // Don't confuse this with the unique_name, below. The two are 00273 // related, but not identical. 00274 EXPCL_DTOOLCONFIG const char *interrogate_wrapper_name(FunctionWrapperIndex wrapper); 00275 00276 // This returns true if -fnames was given to interrogate, making the 00277 // wrapper function callable directly by its name. 00278 EXPCL_DTOOLCONFIG bool interrogate_wrapper_is_callable_by_name(FunctionWrapperIndex wrapper); 00279 00280 // This returns the C++ comment written for the function wrapper, 00281 // usually from the .cpp file. There may be a different comment for 00282 // each overload of a given function. 00283 EXPCL_DTOOLCONFIG bool interrogate_wrapper_has_comment(FunctionWrapperIndex wrapper); 00284 EXPCL_DTOOLCONFIG const char *interrogate_wrapper_comment(FunctionWrapperIndex wrapper); 00285 00286 // Every function wrapper has zero or more parameters and may or may 00287 // not have a return value. Each parameter has a type and may or may 00288 // not have a name. For member functions, the first parameter may be 00289 // a 'this' parameter, which should receive a pointer to the class 00290 // object. (If a member function does not have a 'this' parameter as 00291 // its first parameter, it is a static member function, also called a 00292 // class method.) 00293 00294 EXPCL_DTOOLCONFIG bool interrogate_wrapper_has_return_value(FunctionWrapperIndex wrapper); 00295 EXPCL_DTOOLCONFIG TypeIndex interrogate_wrapper_return_type(FunctionWrapperIndex wrapper); 00296 00297 // Sometimes interrogate must synthesize a wrapper that allocates its 00298 // return value from the free store. Other times (especially if 00299 // -refcount is supplied to interrogate), interrogate will 00300 // automatically increment the count of a reference-counted object 00301 // that it returns. In cases like these, 00302 // interrogate_wrapper_caller_manages_return_value() will return true, 00303 // and it is the responsibility of the scripting language to 00304 // eventually call the destructor supplied by 00305 // interrogate_wrapper_return_value_destructor() on this value when it 00306 // is no longer needed (which will generally be the same destructor as 00307 // that for the class). Otherwise, this function will return false, 00308 // and the scripting language should *not* call any destructor on this 00309 // value. 00310 EXPCL_DTOOLCONFIG bool interrogate_wrapper_caller_manages_return_value(FunctionWrapperIndex wrapper); 00311 EXPCL_DTOOLCONFIG FunctionIndex interrogate_wrapper_return_value_destructor(FunctionWrapperIndex wrapper); 00312 00313 // These define the parameters of the function. 00314 EXPCL_DTOOLCONFIG int interrogate_wrapper_number_of_parameters(FunctionWrapperIndex wrapper); 00315 EXPCL_DTOOLCONFIG TypeIndex interrogate_wrapper_parameter_type(FunctionWrapperIndex wrapper, int n); 00316 EXPCL_DTOOLCONFIG bool interrogate_wrapper_parameter_has_name(FunctionWrapperIndex wrapper, int n); 00317 EXPCL_DTOOLCONFIG const char *interrogate_wrapper_parameter_name(FunctionWrapperIndex wrapper, int n); 00318 EXPCL_DTOOLCONFIG bool interrogate_wrapper_parameter_is_this(FunctionWrapperIndex wrapper, int n); 00319 00320 // This returns a pointer to a function that may be called to invoke 00321 // the function, if the -fptrs option to return function pointers was 00322 // specified to interrogate. Be sure to push the required parameters 00323 // on the stack, according to the calling convention, before calling 00324 // the function. 00325 00326 // These two functions may be called without forcing a load of the 00327 // complete interrogate database. 00328 EXPCL_DTOOLCONFIG bool interrogate_wrapper_has_pointer(FunctionWrapperIndex wrapper); 00329 EXPCL_DTOOLCONFIG void *interrogate_wrapper_pointer(FunctionWrapperIndex wrapper); 00330 00331 // This function will return a name that is guaranteed to be unique to 00332 // this particular function wrapper, and that will (usually) be 00333 // consistent across multiple runtime sessions. (It will only change 00334 // between sessions if the database was regenerated in the interim 00335 // with some new function that happened to introduce a hash conflict.) 00336 00337 // The unique name is an ugly hashed name, not safe for human 00338 // consumption. Its sole purpose is to provide some consistent way to 00339 // identify function wrappers between sessions. 00340 EXPCL_DTOOLCONFIG const char *interrogate_wrapper_unique_name(FunctionWrapperIndex wrapper); 00341 00342 // This function provides a reverse-lookup on the above unique name, 00343 // returning the wrapper index corresponding to the given name. It 00344 // depends on data having been compiled directly into the library, and 00345 // thus is only available if the option -unique-names was given to 00346 // interrogate. 00347 00348 // This function may be called without forcing a load of the complete 00349 // interrogate database. 00350 EXPCL_DTOOLCONFIG FunctionWrapperIndex interrogate_get_wrapper_by_unique_name(const char *unique_name); 00351 00352 ////////////////////////////////////////////////////////////////////////// 00353 // 00354 // MakeSeqs 00355 // 00356 ////////////////////////////////////////////////////////////////////////// 00357 00358 // These are special synthesized methods that iterate through a list. 00359 // They are generated in C++ code via the MAKE_SEQ macro. The normal 00360 // pattern is that a pair of actual C++ methods like get_num_things() 00361 // and get_thing(n) are used to synthesize a new method called 00362 // get_things(). 00363 00364 // The class of which the make_seq is a method. 00365 EXPCL_DTOOLCONFIG TypeIndex interrogate_make_seq_class(MakeSeqIndex make_seq); 00366 00367 // The name of the syntheized method, e.g. "get_things" 00368 EXPCL_DTOOLCONFIG const char *interrogate_make_seq_seq_name(MakeSeqIndex make_seq); 00369 // The name of the real method that returns the length, e.g. "get_num_things" 00370 EXPCL_DTOOLCONFIG const char *interrogate_make_seq_num_name(MakeSeqIndex make_seq); 00371 // The name of the real method that returns the nth element, e.g. "get_thing" 00372 EXPCL_DTOOLCONFIG const char *interrogate_make_seq_element_name(MakeSeqIndex make_seq); 00373 00374 00375 ////////////////////////////////////////////////////////////////////////// 00376 // 00377 // Types 00378 // 00379 ////////////////////////////////////////////////////////////////////////// 00380 00381 // These are all the types that interrogate knows about. This 00382 // includes atomic types like ints and floats, type wrappers like 00383 // pointers and const pointers, enumerated types, and classes. 00384 00385 // Two lists of types are maintained: the list of global types, which 00386 // includes only those types intended to be wrapped in the API (for 00387 // instance, all of the classes). The second list is the complete 00388 // list of all types, which probably does not need to be 00389 // traversed--this includes *all* types known to the interrogate 00390 // database, including simple types and pointers and const pointers to 00391 // classes. These types are necessary to fully define all of the 00392 // function parameters, but need not themselves be wrapped. 00393 00394 EXPCL_DTOOLCONFIG int interrogate_number_of_global_types(); 00395 EXPCL_DTOOLCONFIG TypeIndex interrogate_get_global_type(int n); 00396 EXPCL_DTOOLCONFIG int interrogate_number_of_types(); 00397 EXPCL_DTOOLCONFIG TypeIndex interrogate_get_type(int n); 00398 EXPCL_DTOOLCONFIG TypeIndex interrogate_get_type_by_name(const char *type_name); 00399 EXPCL_DTOOLCONFIG TypeIndex interrogate_get_type_by_scoped_name(const char *type_name); 00400 EXPCL_DTOOLCONFIG TypeIndex interrogate_get_type_by_true_name(const char *type_name); 00401 EXPCL_DTOOLCONFIG const char *interrogate_type_name(TypeIndex type); 00402 EXPCL_DTOOLCONFIG const char *interrogate_type_scoped_name(TypeIndex type); 00403 EXPCL_DTOOLCONFIG const char *interrogate_type_true_name(TypeIndex type); 00404 00405 // A given type might be a nested type, meaning it is entirely defined 00406 // within (and scoped within) some different C++ class. In this case, 00407 // the type_name() will return the local name of the type as seen 00408 // within the class, while the scoped_name() will return the 00409 // fully-qualified name of the type, and is_nested() and outer_class() 00410 // can be used to determine the class it is nested within. 00411 EXPCL_DTOOLCONFIG bool interrogate_type_is_nested(TypeIndex type); 00412 EXPCL_DTOOLCONFIG TypeIndex interrogate_type_outer_class(TypeIndex type); 00413 00414 EXPCL_DTOOLCONFIG bool interrogate_type_has_comment(TypeIndex type); 00415 EXPCL_DTOOLCONFIG const char *interrogate_type_comment(TypeIndex type); 00416 00417 // This returns the module name reported for the type, if available. 00418 EXPCL_DTOOLCONFIG bool interrogate_type_has_module_name(TypeIndex type); 00419 EXPCL_DTOOLCONFIG const char *interrogate_type_module_name(TypeIndex type); 00420 00421 // This returns the library name reported for the type, if available. 00422 EXPCL_DTOOLCONFIG bool interrogate_type_has_library_name(TypeIndex type); 00423 EXPCL_DTOOLCONFIG const char *interrogate_type_library_name(TypeIndex type); 00424 00425 00426 // If interrogate_type_is_atomic() returns true, the type is one of 00427 // the basic C types enumerated in AtomicToken, above. The type may 00428 // then be further modified by one or more of unsigned, signed, long, 00429 // longlong, or short. However, it will not be a pointer. 00430 EXPCL_DTOOLCONFIG bool interrogate_type_is_atomic(TypeIndex type); 00431 EXPCL_DTOOLCONFIG AtomicToken interrogate_type_atomic_token(TypeIndex type); 00432 EXPCL_DTOOLCONFIG bool interrogate_type_is_unsigned(TypeIndex type); 00433 EXPCL_DTOOLCONFIG bool interrogate_type_is_signed(TypeIndex type); 00434 EXPCL_DTOOLCONFIG bool interrogate_type_is_long(TypeIndex type); 00435 EXPCL_DTOOLCONFIG bool interrogate_type_is_longlong(TypeIndex type); 00436 EXPCL_DTOOLCONFIG bool interrogate_type_is_short(TypeIndex type); 00437 00438 // If interrogate_type_is_wrapped() returns true, this is a composite 00439 // type "wrapped" around some simpler type, for instance a pointer to 00440 // a class. The type will be either a pointer or a const wrapper--it 00441 // cannot be a combination of these. (When combinations are required, 00442 // they use multiple wrappers. A const char pointer, for example, is 00443 // represented as a pointer wrapper around a const wrapper around an 00444 // atomic char.) 00445 EXPCL_DTOOLCONFIG bool interrogate_type_is_wrapped(TypeIndex type); 00446 EXPCL_DTOOLCONFIG bool interrogate_type_is_pointer(TypeIndex type); 00447 EXPCL_DTOOLCONFIG bool interrogate_type_is_const(TypeIndex type); 00448 EXPCL_DTOOLCONFIG TypeIndex interrogate_type_wrapped_type(TypeIndex type); 00449 00450 // If interrogate_type_is_enum() returns true, this is an enumerated 00451 // type, which means it may take any one of a number of named integer 00452 // values. 00453 EXPCL_DTOOLCONFIG bool interrogate_type_is_enum(TypeIndex type); 00454 EXPCL_DTOOLCONFIG int interrogate_type_number_of_enum_values(TypeIndex type); 00455 EXPCL_DTOOLCONFIG const char *interrogate_type_enum_value_name(TypeIndex type, int n); 00456 EXPCL_DTOOLCONFIG const char *interrogate_type_enum_value_scoped_name(TypeIndex type, int n); 00457 EXPCL_DTOOLCONFIG int interrogate_type_enum_value(TypeIndex type, int n); 00458 00459 // If none of the above is true, the type is some extension type. It 00460 // may be a struct, class, or union (and the distinction between these 00461 // three is not likely to be important to the scripting language). In 00462 // any case, it may contain zero or more constructors, zero or one 00463 // destructor, zero or more member functions, and zero or more data 00464 // members; all of the remaining type functions may apply. 00465 EXPCL_DTOOLCONFIG bool interrogate_type_is_struct(TypeIndex type); 00466 EXPCL_DTOOLCONFIG bool interrogate_type_is_class(TypeIndex type); 00467 EXPCL_DTOOLCONFIG bool interrogate_type_is_union(TypeIndex type); 00468 00469 // If is_fully_defined() returns false, this class/struct was a 00470 // forward reference, and we really don't know anything about it. (In 00471 // this case, it will appear to have no methods or members.) 00472 EXPCL_DTOOLCONFIG bool interrogate_type_is_fully_defined(TypeIndex type); 00473 00474 // If is_unpublished() returns false, the class/struct is unknown 00475 // because it was not marked to be published (or, in promiscuous mode, 00476 // it is a protected or private nested class). 00477 EXPCL_DTOOLCONFIG bool interrogate_type_is_unpublished(TypeIndex type); 00478 00479 // Otherwise, especially if the type is a struct or class, we may have 00480 // a number of member functions, including zero or more constructors 00481 // and zero or one destructor. A constructor function may be called 00482 // to allocate a new instance of the type; its return value will be a 00483 // pointer to the new instance. The destructor may be called to 00484 // destroy the instance; however, it usually should not be explicitly 00485 // called by the user, since the proper support of the 00486 // interrogate_caller_manages_return_value() interface, above, will 00487 // ensure that the appropriate destructors are called when they should 00488 // be. 00489 00490 // In certain circumstances, the destructor might be inherited from a 00491 // parent or ancestor class. This happens when the destructor wrapper 00492 // from the ancestor class is an acceptable substitute for this 00493 // destructor; this is only possible in the case of a virtual C++ 00494 // destructor. In this case, the destructor returned here will be the 00495 // same function index as the one returned by the ancestor class, and 00496 // interrogate_type_destructor_is_inherited() will return true for 00497 // this class. 00498 EXPCL_DTOOLCONFIG int interrogate_type_number_of_constructors(TypeIndex type); 00499 EXPCL_DTOOLCONFIG FunctionIndex interrogate_type_get_constructor(TypeIndex type, int n); 00500 EXPCL_DTOOLCONFIG bool interrogate_type_has_destructor(TypeIndex type); 00501 EXPCL_DTOOLCONFIG bool interrogate_type_destructor_is_inherited(TypeIndex type); 00502 EXPCL_DTOOLCONFIG FunctionIndex interrogate_type_get_destructor(TypeIndex type); 00503 00504 // This is the set of exposed data elements in the struct or class. 00505 EXPCL_DTOOLCONFIG int interrogate_type_number_of_elements(TypeIndex type); 00506 EXPCL_DTOOLCONFIG ElementIndex interrogate_type_get_element(TypeIndex type, int n); 00507 00508 // This is the set of exposed member functions in the struct or class. 00509 EXPCL_DTOOLCONFIG int interrogate_type_number_of_methods(TypeIndex type); 00510 EXPCL_DTOOLCONFIG FunctionIndex interrogate_type_get_method(TypeIndex type, int n); 00511 00512 // This is the set of MAKE_SEQ wrappers in the struct or class. 00513 EXPCL_DTOOLCONFIG int interrogate_type_number_of_make_seqs(TypeIndex type); 00514 EXPCL_DTOOLCONFIG MakeSeqIndex interrogate_type_get_make_seq(TypeIndex type, int n); 00515 00516 // A C++ class may also define a number of explicit cast operators, 00517 // which define how to convert an object of this type to an object of 00518 // some other type (the type can be inferred by the return type of the 00519 // cast function). This is not related to upcast and downcast, 00520 // defined below. 00521 EXPCL_DTOOLCONFIG int interrogate_type_number_of_casts(TypeIndex type); 00522 EXPCL_DTOOLCONFIG FunctionIndex interrogate_type_get_cast(TypeIndex type, int n); 00523 00524 // A C++ class may inherit from zero or more base classes. This 00525 // defines the list of base classes for this particular type. 00526 EXPCL_DTOOLCONFIG int interrogate_type_number_of_derivations(TypeIndex type); 00527 EXPCL_DTOOLCONFIG TypeIndex interrogate_type_get_derivation(TypeIndex type, int n); 00528 00529 // For each base class, we might need to define an explicit upcast or 00530 // downcast operation to convert the pointer to the derived class to 00531 // an appropriate pointer to its base class (upcast) or vice-versa 00532 // (downcast). This is particularly true in the presence of multiple 00533 // inheritance or virtual inheritance, in which case you cannot simply 00534 // use the same pointer as either type. 00535 00536 // If interrogate_type_derivation_has_upcast() returns true for a 00537 // particular type/derivation combination, you must use the indicated 00538 // upcast function to convert pointers of this type to pointers of the 00539 // base type before calling any of the inherited methods from the base 00540 // class. If this returns false, you may simply use the same pointer 00541 // as either a derived class pointer or a base class pointer without 00542 // any extra step. 00543 EXPCL_DTOOLCONFIG bool interrogate_type_derivation_has_upcast(TypeIndex type, int n); 00544 EXPCL_DTOOLCONFIG FunctionIndex interrogate_type_get_upcast(TypeIndex type, int n); 00545 00546 // Although it is always possible to upcast a pointer to a base class, 00547 // it is not always possible to downcast from a base class to the 00548 // derived class (particularly in the presence of virtual 00549 // inheritance). If interrogate_type_derivation_downcast_is_impossible() 00550 // returns true, forget it. Otherwise, downcasting works the same 00551 // way as upcasting. (Of course, it is the caller's responsibility to 00552 // guarantee that the pointer actually represents an object of the 00553 // type being downcast to.) 00554 EXPCL_DTOOLCONFIG bool interrogate_type_derivation_downcast_is_impossible(TypeIndex type, int n); 00555 EXPCL_DTOOLCONFIG bool interrogate_type_derivation_has_downcast(TypeIndex type, int n); 00556 EXPCL_DTOOLCONFIG FunctionIndex interrogate_type_get_downcast(TypeIndex type, int n); 00557 00558 // A C++ class may also define any number of nested types--classes or 00559 // enums defined within the scope of this class. 00560 EXPCL_DTOOLCONFIG int interrogate_type_number_of_nested_types(TypeIndex type); 00561 EXPCL_DTOOLCONFIG TypeIndex interrogate_type_get_nested_type(TypeIndex type, int n); 00562 00563 #ifdef __cplusplus 00564 } 00565 #endif 00566 00567 #endif