Panda3D

interrogate_interface.h

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
 All Classes Functions Variables Enumerations