MOAB: Mesh Oriented datABase  (version 5.1.1)
iRel.h
Go to the documentation of this file.
00001 #ifndef _ITAPS_iRel
00002 #define _ITAPS_iRel
00003 
00004 /***************************************************************************//**
00005  * \ingroup VersionNumbers
00006  * \brief Compile time version number digits
00007  *
00008  * iRel maintains a major, minor and patch digit in its version number.
00009  * Technically speaking, there is not much practical value in patch digit
00010  * for an interface specification. A patch release is typically only used
00011  * for bug fix releases. Although it is rare, sometimes a bug fix
00012  * necessitates an API change. So, we define a patch digit for iRel.
00013  ******************************************************************************/
00014 #define IREL_VERSION_MAJOR 1
00015 #define IREL_VERSION_MINOR 1
00016 #define IREL_VERSION_PATCH 0
00017 
00018 /***************************************************************************//**
00019  * \ingroup VersionNumbers
00020  * \brief Maintain backward compatibility with old version symbol names
00021  ******************************************************************************/
00022 #define IREL_MAJOR_VERSION IREL_VERSION_MAJOR
00023 #define IREL_MINOR_VERSION IREL_VERSION_MINOR
00024 #define IREL_PATCH_VERSION IREL_VERSION_PATCH
00025 
00026 /***************************************************************************//**
00027  * \ingroup VersionNumbers
00028  * \brief Version Comparison
00029  *
00030  * Evaluates to true at CPP time if the version of iRel currently being
00031  * compiled is greater than or equal to the version specified.
00032  ******************************************************************************/
00033 #define IREL_VERSION_GE(Maj,Min,Pat) ITAPS_VERSION_GE(Maj,Min,Pat)
00034 
00035 /***************************************************************************//**
00036  * \ingroup VersionNumbers
00037  * \brief Compose string represention of the iRel version number
00038  ******************************************************************************/
00039 #define IREL_VERSION_STRING ITAPS_VERSION_STRING_(iRel)
00040 
00041 /***************************************************************************//**
00042  * \ingroup VersionNumbers
00043  * \brief Compose a symbol name derived from the current iRel version number.
00044  ******************************************************************************/
00045 #define IREL_VERSION_TAG ITAPS_VERSION_TAG_(iRel)
00046 
00047 /***************************************************************************//**
00048  * \ingroup VersionNumbers
00049  * \brief Define iRel_create symbol such that it depends on version number.
00050  *
00051  * Note: We ran into problems with this as it influences or is influenced by
00052  * fortran name mangling and so breaks fortran compilation. So, this is
00053  * currently disabled.
00054  ******************************************************************************/
00055 #define IREL_CREATE_NAME__(A,B,C) A##_##B##_##C
00056 #define IREL_CREATE_NAME_(A,B,C) IREL_CREATE_NAME__(A,B,C)
00057 #define IREL_CREATE_NAME(A) IREL_CREATE_NAME_(A,IREL_VERSION_MAJOR,IREL_VERSION_MINOR)
00058 /*
00059 #undef  iRel_create
00060 #define iRel_create IREL_CREATE_NAME(iRel_create)
00061 */
00062 
00063 #include "iBase.h"
00064 #include "iRel_protos.h"
00065 
00066 #ifdef __cplusplus
00067 extern "C" {
00068 #endif
00069 
00070 typedef void* iRel_Instance;
00071 typedef struct iRel_PairHandle_Private* iRel_PairHandle;
00072 
00073 /***************************************************************************//**
00074  * \brief  \enum IfaceType Enumerator specifying interface types
00075  *
00076  * Enumerator specifying interface types.  This enumeration is
00077  * necessary because functions to get entities of a given dimension
00078  * are part of the higher-level interfaces (e.g. iGeom, iMesh) instead
00079  * of iBase.
00080  ******************************************************************************/
00081 enum iRel_IfaceType {
00082     iRel_IfaceType_MIN = 0,
00083         /**< facilitates iteration over all values */
00084     iRel_IGEOM_IFACE = iRel_IfaceType_MIN, 
00085         /**< description unavailable */
00086     iRel_IMESH_IFACE, 
00087         /**< description unavailable */
00088     iRel_IFIELD_IFACE, 
00089         /**< description unavailable */
00090     iRel_IREL_IFACE,
00091         /**< description unavailable */
00092     iRel_FBIGEOM_IFACE,
00093         /**< description unavailable */
00094     iRel_IfaceType_MAX = iRel_FBIGEOM_IFACE
00095         /**< facilitates iteration over all values */
00096 };
00097 
00098 /***************************************************************************//**
00099  * \brief  \enum RelationType Enumerator specifying relation types
00100  *
00101  * Enumerator specifying relation types.  A relation has two types, one
00102  * for each side of the relation.
00103  ******************************************************************************/
00104 enum iRel_RelationType {
00105     iRel_RelationType_MIN = 0,
00106         /**< facilitates iteration over all values */
00107     iRel_ENTITY = iRel_RelationType_MIN, 
00108         /**< description unavailable */
00109     iRel_SET, 
00110         /**< description unavailable */
00111     iRel_BOTH,
00112         /**< description unavailable */
00113     iRel_RelationType_MAX = iRel_BOTH
00114         /**< facilitates iteration over all values */
00115 };
00116 
00117 /***************************************************************************//**
00118  * \brief  \enum RelationStatus Enumerator specifying relation status
00119  *
00120  * Enumerator specifying relation status.  A relation has two statuses, one
00121  * for each side of the relation.  Allowed values of this enumeration are:
00122  * It is an error to request relations from a side that does not have
00123  * iRel_ACTIVE status.
00124  ******************************************************************************/
00125 enum iRel_RelationStatus {
00126     iRel_RelationStatus_MIN = 0,
00127         /**< facilitates iteration over all values */
00128     iRel_ACTIVE = iRel_RelationType_MIN, 
00129         /**< the relation on this side is active and up to date */
00130     iRel_INACTIVE, 
00131         /**< the relation on this side is inactive, and may be out of date */
00132     iRel_NOTEXIST,
00133         /**< the relation on this side is not stored */
00134     iRel_RelationStatus_MAX = iRel_NOTEXIST
00135         /**< facilitates iteration over all values */
00136 };
00137 
00138 /***************************************************************************//**
00139  * \brief Get the error type returned from the last iRel function
00140  *
00141  * Get the error type returned from the last iRel function.  Value
00142  * returned is a member of the iBase_ErrorType enumeration.
00143  ******************************************************************************/
00144 void iRel_getErrorType(
00145     iRel_Instance instance,
00146         /**< [in] iRel instance handle */
00147     int* error_type
00148         /**< [out] Error type returned from last iRel function */
00149 );
00150 
00151 /***************************************************************************//**
00152  * \brief Get a description of the error returned from the last iRel function
00153  *
00154  * Get a description of the error returned from the last iRel function
00155  ******************************************************************************/
00156 void iRel_getDescription(
00157     iRel_Instance instance,
00158         /**< [in] iRel instance handle */
00159     char* descr,
00160         /**< [inout] Pointer to a character string to be filled with a
00161         description of the error from the last iRel function */
00162     int descr_len
00163         /**< [in] Length of the character string pointed to by descr */
00164 );
00165 
00166 /***************************************************************************//**
00167  * \brief Create a new iRel instance
00168  *
00169  * Create a new iRel instance.  Currently no options are implemented.
00170  ******************************************************************************/
00171 void iRel_create(
00172     const char* options,
00173         /**< const Options for the implementation */
00174     iRel_Instance* instance,
00175         /**< [in] iRel instance handle */
00176     int* err,
00177         /**< [out] Returned Error status (see iBase_ErrorType) */
00178     const int options_len
00179         /**< [in] Length of options string */
00180 );
00181 
00182 /***************************************************************************//**
00183  * \brief Destroy the interface object
00184  *
00185  * Calls destructor on interface object
00186  ******************************************************************************/
00187 void iRel_destroy(
00188     iRel_Instance instance,
00189         /**< [in] iRel instance handle */
00190     int* err
00191         /**< [out] Returned Error status (see iBase_ErrorType) */
00192 );
00193 
00194 /***************************************************************************//**
00195  * \brief Create a relation pair between two interfaces
00196  *
00197  * Creates a relation pair between two interfaces, passing
00198  * back a handle to the pair.  It is an error to create a relation pair
00199  * having both sides iRel_NOTEXIST.  If a relation pair has a side with status
00200  * iRel_NOTEXIST, the relation for that side is never stored, and the status
00201  * cannot change over the life of the relation pair.  
00202  ******************************************************************************/
00203 void iRel_createPair(
00204     iRel_Instance instance,
00205         /**< [in] iRel instance handle */
00206     iBase_Instance iface1,
00207         /**< [in] 1st interface object in the relation pair */
00208     const int ent_or_set1,
00209         /**< [in] This relation relates entities, sets, or both from 1st
00210         interface object */
00211     const int iface_type1,
00212         /**< [in] Type of 1st interface */
00213     const int irel_status1,
00214         /**< [in] The status of 1st side */
00215     iBase_Instance iface2,
00216         /**< [in] 2nd interface object in the relation pair */
00217     const int ent_or_set2,
00218         /**< [in] This relation relates entities, sets, or both from 2nd
00219         interface object */
00220     const int iface_type2,
00221         /**< [in] Type of 2nd interface */
00222     const int irel_status2,
00223         /**< [in] The status of 2nd side */
00224     iRel_PairHandle* pair,
00225         /**< [out] Pointer to relation pair handle, returned from function */
00226     int* err
00227         /**< [out] Returned Error status (see iBase_ErrorType) */
00228 );
00229 
00230 /***************************************************************************//**
00231  * \brief Get information for this relation handle
00232  *
00233  * Get information about the interfaces and relation type for this
00234  * relation.  Relation type for each side is passed back as integers,
00235  * but values will be from RelationType enumeration.
00236  ******************************************************************************/
00237 void iRel_getPairInfo(
00238     iRel_Instance instance,
00239         /**< [in] iRel instance handle */
00240     iRel_PairHandle pair,
00241         /**< [in] handle of relation pair being queried */
00242     iBase_Instance* iface1,
00243         /**< [out] Side 1 instance for this relation */
00244     int* ent_or_set1,
00245         /**< [out] relation type for side 1 of this relation */
00246     int* iface_type1,
00247         /**< [out] Interface type for side 1 of this relation */
00248     int* irel_status1,
00249         /**< [out] The status of the first side of this relation */
00250     iBase_Instance* iface2,
00251         /**< [out] Side 2 instance for this relation */
00252     int* ent_or_set2,
00253         /**< [out] Relation type for side 2 of this relation */
00254     int* iface_type2,
00255         /**< [out] Interface type for side 2 of this relation */
00256     int* irel_status2,
00257         /**< [out] Status of the 2nd side of this relation */
00258     int* err
00259         /**< [out] Returned Error status (see iBase_ErrorType) */
00260 );
00261 
00262 /***************************************************************************//**
00263  * \brief Change the relation type
00264  *
00265  * Change the type of one or both sides of a relation.  Only changes that
00266  * result in no lost information are allowed, e.g. changing a type from SET
00267  * to BOTH or vice versa.
00268  ******************************************************************************/
00269 void iRel_changePairType(
00270     iRel_Instance instance,
00271         /**< [in] iRel instance handle */
00272     iRel_PairHandle pair,
00273         /**< [in] Relation pair handle being changed */
00274     int ent_or_set1,
00275         /**< [in] The new type of side 1 of this relation pair */
00276     int ent_or_set2,
00277         /**< [in] The new type of side 2 of this relation pair */
00278     int* err
00279         /**< [out] Returned Error status (see iBase_ErrorType) */
00280 );
00281 
00282 /***************************************************************************//**
00283  * \brief Change the relation status
00284  *
00285  * Change the status of one or both sides of a relation.  It is an error to
00286  * change the status of both sides to iRel_NOTEXIST.  If a side is changed to
00287  * iRel_NOTEXIST, it will no longer be changeable back to iRel_ACTIVE or
00288  * iRel_INACTIVE. Changing a side from iRel_INACTIVE to iRel_ACTIVE implies a
00289  * traversal of all related entities on the other side, to recover the relations
00290  * on the side being changed. Changing both sides from iRel_ACTIVE to something
00291  * else is an error, since in that case neither will be able to be updated to
00292  * iRel_ACTIVE.
00293  ******************************************************************************/
00294 void iRel_changePairStatus(
00295     iRel_Instance instance,
00296         /**< [in] iRel instance handle */
00297     iRel_PairHandle pair,
00298         /**< [in] Relation pair handle being changed */
00299     int irel_status1,
00300         /**< [in] The new status of side 1 of this relation pair */
00301     int irel_status2,
00302         /**< [in] The new status of side 2 of this relation pair */
00303     int* err
00304         /**< [out] Returned Error status (see iBase_ErrorType) */
00305 );
00306 
00307 /***************************************************************************//**
00308  * \brief Destroy a relation pair
00309  *
00310  * Destroy the relation pair corresponding to the handle input
00311  ******************************************************************************/
00312 void iRel_destroyPair(
00313     iRel_Instance instance,
00314         /**< [in] iRel instance handle */
00315     iRel_PairHandle pair,
00316         /**< [in] Handle of relation pair to destroy */
00317     int* err
00318         /**< [out] Returned Error status (see iBase_ErrorType) */
00319 );
00320 
00321 /***************************************************************************//**
00322  * \brief Get relations containing specified interface
00323  *
00324  * Get relations containing the specified interface
00325  ******************************************************************************/
00326 void iRel_findPairs(
00327     iRel_Instance instance,
00328         /**< [in] iRel instance handle */
00329     iBase_Instance iface,
00330         /**< [in] Specified interface */
00331     iRel_PairHandle** pairs,
00332         /**< [inout] Pointer to array holding returned relation pairs
00333         containing specified interface */
00334     int* pairs_allocated,
00335         /**< [inout] Pointer to allocated size of relation pairs list */
00336     int* pairs_size,
00337         /**< [out] Pointer to occupied size of relation pairs list */
00338     int* err
00339         /**< [out] Returned Error status (see iBase_ErrorType) */
00340 );
00341 
00342 /***************************************************************************//**
00343  * \brief Set a relation between two entities
00344  *
00345  * Set a relation between an entity and several entities. It is an error
00346  * to set a relation on a pair with both sides not iRel_ACTIVE.
00347  ******************************************************************************/
00348 void iRel_setEntEntRelation(
00349     iRel_Instance instance,
00350         /**< [in] iRel instance handle */
00351     iRel_PairHandle pair,
00352         /**< [in] Relation pair handle being queried */
00353     iBase_EntityHandle ent1,
00354         /**< [in] 1st entity of relation being set */
00355     iBase_EntityHandle ent2,
00356         /**< [in] 2nd entity of relation being set */
00357     int* err
00358         /**< [out] Returned Error status (see iBase_ErrorType) */
00359 );
00360 
00361 /***************************************************************************//**
00362  * \brief Set a relation between an entity and an entity set
00363  *
00364  * Description unavailable.
00365  ******************************************************************************/
00366 void iRel_setEntSetRelation(
00367     iRel_Instance instance,
00368         /**< [in] iRel instance handle */
00369     iRel_PairHandle pair,
00370         /**< [in] Relation pair handle being queried */
00371     iBase_EntityHandle ent1,
00372         /**< [in] entity of relation being set */
00373     iBase_EntitySetHandle entset2,
00374         /**< [in] entity set of relation being set */
00375     int* err
00376         /**< [out] Returned Error status (see iBase_ErrorType) */
00377 );
00378 
00379 /***************************************************************************//**
00380  * \brief Set a relation between an entity set an an entity
00381  *
00382  * Description unavailable.
00383  ******************************************************************************/
00384 void iRel_setSetEntRelation(
00385     iRel_Instance instance,
00386         /**< [in] iRel instance handle */
00387     iRel_PairHandle pair,
00388         /**< [in] Relation pair handle being queried */
00389     iBase_EntitySetHandle entset1,
00390         /**< [in] entity set of relation being set */
00391     iBase_EntityHandle ent2,
00392         /**< [in] entity of relation being set */
00393     int* err
00394         /**< [out] Returned Error status (see iBase_ErrorType) */
00395 );
00396 
00397 /***************************************************************************//**
00398  * \brief Set a relation between two entity sets
00399  *
00400  * Description unavailable.
00401  * Set a relation between an entity and several entities.  It is an error to set
00402  * a relation on a pair with both sides not iRel_ACTIVE.
00403  ******************************************************************************/
00404 void iRel_setSetSetRelation(
00405     iRel_Instance instance,
00406         /**< [in] iRel instance handle */
00407     iRel_PairHandle pair,
00408         /**< [in] Relation pair handle being queried */
00409     iBase_EntitySetHandle entset1,
00410         /**< [in] 1st entity set of relation being set */
00411     iBase_EntitySetHandle entset2,
00412         /**< [in] 2nd entity set of relation being set */
00413     int* err
00414         /**< [out] Returned Error status (see iBase_ErrorType) */
00415 );
00416 
00417 /***************************************************************************//**
00418  * \brief Set relations between arrays of entities pairwise,
00419  * ent_array_1[i]<->ent_array_2[i]
00420  *
00421  * Set relations between arrays of entities pairwise, 
00422  * ent_array_1[i]<->ent_array_2[i].  If either array
00423  * contains sets and that side of the relation is 'both'-type, 
00424  * set relations for individual entities in those sets too.  It is an error to
00425  * set a relation on a pair with both sides not iRel_ACTIVE.
00426  ******************************************************************************/
00427 void iRel_setEntArrEntArrRelation(
00428     iRel_Instance instance,
00429         /**< [in] iRel instance handle */
00430     iRel_PairHandle pair,
00431         /**< [in] Relation pair handle being queried */
00432     iBase_EntityHandle* ent_array_1,
00433         /**< [in] 1st array of entities of relation being set */
00434     int num_ent1,
00435         /**< [in] Number of entities in 1st array */
00436     iBase_EntityHandle* ent_array_2,
00437         /**< [in] 2nd array of entities of relation being set */
00438     int num_ent2,
00439         /**< [in] Number of entities in 2nd array */
00440     int* err
00441         /**< [out] Returned Error status (see iBase_ErrorType) */
00442 );
00443 
00444 /***************************************************************************//**
00445  * \brief Set relations between arrays of entity sets and entities
00446  *
00447  * Description unavailable.
00448  ******************************************************************************/
00449 void iRel_setSetArrEntArrRelation(
00450     iRel_Instance instance,
00451         /**< [in] iRel instance handle */
00452     iRel_PairHandle pair,
00453         /**< [in] Relation pair handle being queried */
00454     iBase_EntitySetHandle* entset_array_1,
00455         /**< [in] 1st array of entities of relation being set */
00456     int num_set1,
00457         /**< [in] Number of entity sets in 1st array */
00458     iBase_EntityHandle* ent_array_2,
00459         /**< [in] 2nd array of entities of relation being set */
00460     int num_ent2,
00461         /**< [in] Number of entities in 2nd array */
00462     int* err
00463         /**< [out] Returned Error status (see iBase_ErrorType) */
00464 );
00465 
00466 /***************************************************************************//**
00467  * \brief Set relations between arrays of entities and entity sets
00468  *
00469  * Description unavailable.
00470  ******************************************************************************/
00471 void iRel_setEntArrSetArrRelation(
00472     iRel_Instance instance,
00473         /**< [in] iRel instance handle */
00474     iRel_PairHandle pair,
00475         /**< [in] Relation pair handle being queried */
00476     iBase_EntityHandle* ent_array_1,
00477         /**< [in] 1st array of entities of relation being set */
00478     int num_ent1,
00479         /**< [in] Number of entities in 1st array */
00480     iBase_EntitySetHandle* entset_array_2,
00481         /**< [in] 2nd array of entities of relation being set */
00482     int num_set2,
00483         /**< [in] Number of entity sets in 2nd array */
00484     int* err
00485         /**< [out] Returned Error status (see iBase_ErrorType) */
00486 );
00487 
00488 /***************************************************************************//**
00489  * \brief Set relations between arrays of entity sets pairwise,
00490  * ent_array_1[i]<->ent_array_2[i]
00491  *
00492  * Set relations between arrays of entities pairwise, 
00493  * ent_array_1[i]<->ent_array_2[i].  If either array
00494  * contains sets and that side of the relation is 'both'-type, 
00495  * set relations for individual entities in those sets too.  It is an error to
00496  * set a relation on a pair with both sides not iRel_ACTIVE.
00497  ******************************************************************************/
00498 void iRel_setSetArrSetArrRelation(
00499     iRel_Instance instance,
00500         /**< [in] iRel instance handle */
00501     iRel_PairHandle pair,
00502         /**< [in] Relation pair handle being queried */
00503     iBase_EntitySetHandle* entset_array_1,
00504         /**< [in] 1st array of entities of relation being set */
00505     int num_set1,
00506         /**< [in] Number of entities in 1st array */
00507     iBase_EntitySetHandle* entset_array_2,
00508         /**< [in] 2nd array of entities of relation being set */
00509     int num_set2,
00510         /**< [in] Number of entities in 2nd array */
00511     int* err
00512         /**< [out] Returned Error status (see iBase_ErrorType) */
00513 );
00514 
00515 /***************************************************************************//**
00516  * \brief Get entity related to specified entity and relation handle
00517  *
00518  * Get entity related to specified entity and relation handle.  Also
00519  * returns whether the related entity is an entity or a set.  It is an error to
00520  * get a relation for a side with status iRel_NOTEXIST.
00521  ******************************************************************************/
00522 void iRel_getEntEntRelation(
00523     iRel_Instance instance,
00524         /**< [in] iRel instance handle */
00525     iRel_PairHandle pair,
00526         /**< [in] Relation pair handle being queried */
00527     iBase_EntityHandle ent1,
00528         /**< [in] 1st entity of relation being queried */
00529     int switch_order,
00530         /**< [in] 1st entity is related to 1st interface (=0) or 2nd interface
00531         (=1) of relation pair */
00532     iBase_EntityHandle* ent2,
00533         /**< [out] Pointer to entity related to ent1 */
00534     int* err
00535         /**< [out] Returned Error status (see iBase_ErrorType) */
00536 );
00537 
00538 /***************************************************************************//**
00539  * \brief Get entity set related to specified entity and relation handle
00540  *
00541  * Description unavailable.
00542  ******************************************************************************/
00543 void iRel_getEntSetRelation(
00544     iRel_Instance instance,
00545         /**< [in] iRel instance handle */
00546     iRel_PairHandle pair,
00547         /**< [in] Relation pair handle being queried */
00548     iBase_EntityHandle ent1,
00549         /**< [in] entity of relation being queried */
00550     int switch_order,
00551         /**< [in] 1st entity is related to 1st interface (=0) or 2nd interface
00552         (=1) of relation pair */
00553     iBase_EntitySetHandle* entset2,
00554         /**< [out] Pointer to entity set related to ent1 */
00555     int* err
00556         /**< [out] Returned Error status (see iBase_ErrorType) */
00557 );
00558 
00559 /***************************************************************************//**
00560  * \brief Get entity related to specified entity set and relation handle
00561  *
00562  * Description unavailable.
00563  ******************************************************************************/
00564 void iRel_getSetEntRelation(
00565     iRel_Instance instance,
00566         /**< [in] iRel instance handle */
00567     iRel_PairHandle pair,
00568         /**< [in] Relation pair handle being queried */
00569     iBase_EntitySetHandle entset1,
00570         /**< [in] entity set of relation being queried */
00571     int switch_order,
00572         /**< [in] 1st entity is related to 1st interface (=0) or 2nd interface
00573         (=1) of relation pair */
00574     iBase_EntityHandle* ent2,
00575         /**< [out] Pointer to entity related to entset1 */
00576     int* err
00577         /**< [out] Returned Error status (see iBase_ErrorType) */
00578 );
00579 
00580 /***************************************************************************//**
00581  * \brief Get entity set related to specified entity set and relation handle
00582  *
00583  * Description unavailable.
00584  ******************************************************************************/
00585 void iRel_getSetSetRelation(
00586     iRel_Instance instance,
00587         /**< [in] iRel instance handle */
00588     iRel_PairHandle pair,
00589         /**< [in] Relation pair handle being queried */
00590     iBase_EntitySetHandle entset1,
00591         /**< [in] 1st entity set of relation being queried */
00592     int switch_order,
00593         /**< [in] 1st entity is related to 1st interface (=0) or 2nd interface
00594         (=1) of relation pair */
00595     iBase_EntitySetHandle* entset2,
00596         /**< [out] Pointer to entity set related to entset1 */
00597     int* err
00598         /**< [out] Returned Error status (see iBase_ErrorType) */
00599 );
00600 
00601 /***************************************************************************//**
00602  * \brief Get entity iterator related to specified entity set and relation
00603  * handle.
00604  *
00605  * Description unavailable.
00606  ******************************************************************************/
00607 void iRel_getEntSetIterRelation(
00608     iRel_Instance instance,
00609         /**< [in] iRel instance handle */
00610     iRel_PairHandle pair,
00611         /**< [in] Relation pair handle being queried */
00612     iBase_EntityHandle ent1,
00613         /**< [in] ent1 1st entity set of relation being queried */
00614     int switch_order,
00615         /**< [in] 1st entity is related to 1st interface (=0) or 2nd interface
00616         (=1) of relation pair */
00617     iBase_EntityIterator* entIter,
00618         /**< [out] Returned entity iterator */
00619     int* err
00620         /**< [out] Returned Error status (see iBase_ErrorType) */
00621 );
00622 
00623 /***************************************************************************//**
00624  * \brief Get entities related to those in specified array and relation,
00625  * pairwise
00626  *
00627  * Get entities related to those in specified array and relation, pairwise.
00628  * Returns sets or entities, depending on relation type and entities in 
00629  * ent_array_1.  It is an error to get a relation for a side with status
00630  * iRel_NOTEXIST.
00631  ******************************************************************************/
00632 void iRel_getEntArrEntArrRelation(
00633     iRel_Instance instance,
00634         /**< [in] iRel instance handle */
00635     iRel_PairHandle pair,
00636         /**< [in] Relation pair handle being queried */
00637     iBase_EntityHandle* ent_array_1,
00638         /**< [in] Array of entities whose relations are being queried */
00639     int ent_array_1_size,
00640         /**< [in] Number of entities in ent_array_1 */
00641     int switch_order,
00642         /**< [in] Entities in ent_array_1 are related with 1st (=0) or 2nd (=1)
00643         interface of this relation pair */
00644     iBase_EntityHandle** ent_array_2,
00645         /**< [inout] Pointer to array of entity handles returned from function */
00646     int* ent_array_2_allocated,
00647         /**< [inout] Pointer to allocated size of ent_array_2 */
00648     int* ent_array_2_size,
00649         /**< [out] Pointer to occupied size of ent_array_2 */
00650     int* err
00651         /**< [out] Returned Error status (see iBase_ErrorType) */
00652 );
00653 
00654 /***************************************************************************//**
00655  * \brief Get entity sets related to entities in specified array and relation,
00656  * pairwise
00657  *
00658  * Description unavailable.
00659  ******************************************************************************/
00660 void iRel_getEntArrSetArrRelation(
00661     iRel_Instance instance,
00662         /**< [in] iRel instance handle */
00663     iRel_PairHandle pair,
00664         /**< [in] Relation pair handle being queried */
00665     iBase_EntityHandle* ent_array_1,
00666         /**< [in] Array of entities whose relations are being queried */
00667     int ent_array_1_size,
00668         /**< [in] Number of entities in ent_array_1 */
00669     int switch_order,
00670         /**< [in] Entities in ent_array_1 are related with 1st (=0) or 2nd (=1)
00671         interface of this relation pair */
00672     iBase_EntitySetHandle** entset_array_2,
00673         /**< [inout] Pointer to array of entity set handles returned from function */
00674     int* entset_array_2_allocated,
00675         /**< [inout] Pointer to allocated size of entset_array_2 */
00676     int* entset_array_2_size,
00677         /**< [out] Pointer to occupied size of entset_array_2 */
00678     int* err
00679         /**< [out] Returned Error status (see iBase_ErrorType) */
00680 );
00681 
00682 /***************************************************************************//**
00683  * \brief Get entities related to entity sets in specified array and relation,
00684  * pairwise
00685  *
00686  * Description unavailable.
00687  ******************************************************************************/
00688 void iRel_getSetArrEntArrRelation(
00689     iRel_Instance instance,
00690         /**< [in] iRel instance handle */
00691     iRel_PairHandle pair,
00692         /**< [in] Relation pair handle being queried */
00693     iBase_EntitySetHandle* entset_array_1,
00694         /**< [in] Array of entity sets whose relations are being queried */
00695     int entset_array_1_size,
00696         /**< [in] Number of entity sets in entset_array_1 */
00697     int switch_order,
00698         /**< [in] Entities in ent_array_1 are related with 1st (=0) or 2nd (=1)
00699         interface of this relation pair */
00700     iBase_EntityHandle** ent_array_2,
00701         /**< [inout] Pointer to array of entity handles returned from function */
00702     int* ent_array_2_allocated,
00703         /**< [inout] Pointer to allocated size of ent_array_2 */
00704     int* ent_array_2_size,
00705         /**< [out] Pointer to occupied size of ent_array_2 */
00706     int* err
00707         /**< [out] Returned Error status (see iBase_ErrorType) */
00708 );
00709 
00710 /***************************************************************************//**
00711  * \brief Get entity sets related to entity sets in specified array and relation,
00712  * pairwise
00713  *
00714  * Description unavailable.
00715  ******************************************************************************/
00716 void iRel_getSetArrSetArrRelation(
00717     iRel_Instance instance,
00718         /**< [in] iRel instance handle */
00719     iRel_PairHandle pair,
00720         /**< [in] Relation pair handle being queried */
00721     iBase_EntitySetHandle* entset_array_1,
00722         /**< [in] Array of entity sets whose relations are being queried */
00723     int entset_array_1_size,
00724         /**< [in] Number of entity sets in entset_array_1 */
00725     int switch_order,
00726         /**< [in] Entities in ent_array_1 are related with 1st (=0) or 2nd (=1)
00727         interface of this relation pair */
00728     iBase_EntitySetHandle** entset_array_2,
00729         /**< [inout] Pointer to array of entity handles returned from function */
00730     int* entset_array_2_allocated,
00731         /**< [inout] Pointer to allocated size of entset_array_2 */
00732     int* entset_array_2_size,
00733         /**< [out] Pointer to occupied size of entset_array_2 */
00734     int* err
00735         /**< [out] Returned Error status (see iBase_ErrorType) */
00736 );
00737 
00738 /***************************************************************************//**
00739  * \brief Get entity iterators related to entity sets in specified array and
00740  * relation.
00741  *
00742  * Description unavailable.
00743  ******************************************************************************/
00744 void iRel_getEntArrSetIterArrRelation(
00745     iRel_Instance instance,
00746         /**< [in] iRel instance handle */
00747     iRel_PairHandle pair,
00748         /**< [in] Relation pair handle being queried */
00749     iBase_EntityHandle* ent_array_1,
00750         /**< [in] Array of entities whose relations are being queried */
00751     int ent_array_1_size,
00752         /**< [in] Number of entities in ent_array_1 */
00753     int switch_order,
00754         /**< [in] Entities in ent_array_1 are related with 1st (=0) or 2nd (=1)
00755         interface of this relation pair */
00756     iBase_EntityIterator** entiter,
00757         /**< [inout] Pointer to array of entity iterator handles returned from
00758         function */
00759     int* entiter_allocated,
00760         /**< [inout] Pointer to allocated size of entiter */
00761     int* entiter_size,
00762         /**< [out] Pointer to occupied size of entiter */
00763     int* err
00764         /**< [out] Returned Error status (see iBase_ErrorType) */
00765 );
00766 
00767 /***************************************************************************//**
00768  * \brief Remove a relation from an entity
00769  *
00770  * Remove a relation from an entity
00771  ******************************************************************************/
00772 void iRel_rmvEntRelation(
00773     iRel_Instance instance,
00774         /**< [in] iRel instance handle */
00775     iRel_PairHandle pair,
00776         /**< [in] Relation pair handle being queried */
00777     iBase_EntityHandle ent,
00778         /**< [in] entity of relation being removed */
00779     int switch_order,
00780         /**< [in] entity is related to 1st interface (=0) or 2nd interface
00781         (=1) of relation pair */
00782     int* err
00783         /**< [out] Returned Error status (see iBase_ErrorType) */
00784 );
00785 
00786 /***************************************************************************//**
00787  * \brief Remove a relation from an entity set
00788  *
00789  * Remove a relation from an entity set
00790  ******************************************************************************/
00791 void iRel_rmvSetRelation(
00792     iRel_Instance instance,
00793         /**< [in] iRel instance handle */
00794     iRel_PairHandle pair,
00795         /**< [in] Relation pair handle being queried */
00796     iBase_EntitySetHandle set,
00797         /**< [in] entity set of relation being removed */
00798     int switch_order,
00799         /**< [in] entity set is related to 1st interface (=0) or 2nd interface
00800         (=1) of relation pair */
00801     int* err
00802         /**< [out] Returned Error status (see iBase_ErrorType) */
00803 );
00804 
00805 /***************************************************************************//**
00806  * \brief Remove a relation from an array of entities
00807  *
00808  * Remove a relation from an array of entities
00809  ******************************************************************************/
00810 void iRel_rmvEntArrRelation(
00811     iRel_Instance instance,
00812         /**< [in] iRel instance handle */
00813     iRel_PairHandle pair,
00814         /**< [in] Relation pair handle being queried */
00815     iBase_EntityHandle* ent_array_1,
00816         /**< [in] Array of entities of relation being removed */
00817     int num_ent1,
00818         /**< [in] Number of entities in array */
00819     int switch_order,
00820         /**< [in] entities are related to 1st interface (=0) or 2nd interface
00821         (=1) of relation pair */
00822     int* err
00823         /**< [out] Returned Error status (see iBase_ErrorType) */
00824 );
00825 
00826 /***************************************************************************//**
00827  * \brief Remove a relation from an array of entity sets
00828  *
00829  * Remove a relation from an array of entity sets
00830  ******************************************************************************/
00831 void iRel_rmvSetArrRelation(
00832     iRel_Instance instance,
00833         /**< [in] iRel instance handle */
00834     iRel_PairHandle pair,
00835         /**< [in] Relation pair handle being queried */
00836     iBase_EntitySetHandle* entset_array_1,
00837         /**< [in] Array of entity sets of relation being removed */
00838     int num_entset1,
00839         /**< [in] Number of entity sets in array */
00840     int switch_order,
00841         /**< [in] entity sets are related to 1st interface (=0) or 2nd interface
00842         (=1) of relation pair */
00843     int* err
00844         /**< [out] Returned Error status (see iBase_ErrorType) */
00845 );
00846 
00847 /***************************************************************************//**
00848  * \brief Infer relations between entities in specified pair of interfaces
00849  *
00850  * Infer relations between entities in specified pair of interfaces.  The
00851  * criteria used to infer these relations depends on the interfaces in
00852  * the pair, the iRel implementation, and the source of the data in those
00853  * interfaces.
00854  ******************************************************************************/
00855 void iRel_inferAllRelations(
00856     iRel_Instance instance,
00857         /**< [in] iRel instance handle */
00858     iRel_PairHandle pair,
00859         /**< [in] Relation pair handle being queried */
00860     int* err
00861         /**< [out] Returned Error status (see iBase_ErrorType) */
00862 );
00863 
00864 /***************************************************************************//**
00865  * \brief Infer relations and relation type between entities in specified pair
00866  * of interfaces 
00867  *
00868  * Infer relations between entities in specified pair of interfaces, and the
00869  * relation type used by this iRel implementation.  The criteria used to
00870  * infer these relations depends on the interfaces in the pair, the iRel
00871  * implementation, and the source of the data in those interfaces.
00872  ******************************************************************************/
00873 void iRel_inferAllRelationsAndType(
00874     iRel_Instance instance,
00875         /**< [in] iRel instance handle */
00876     iRel_PairHandle* pair,
00877         /**< [in] Relation pair handle created by implementation */
00878     int* err
00879         /**< [out] Returned Error status (see iBase_ErrorType) */
00880 );
00881 
00882 /***************************************************************************//**
00883  * \brief Infer relations corresponding to specified entity and relation pair
00884  *
00885  * Infer relations corresponding to specified entity and relation pair.  The
00886  * criteria used to infer these relations depends on the interfaces in
00887  * the pair, the iRel implementation, and the source of the data in those
00888  * interfaces.
00889  ******************************************************************************/
00890 void iRel_inferEntRelations(
00891     iRel_Instance instance,
00892         /**< [in] iRel instance handle */
00893     iRel_PairHandle pair,
00894         /**< [in] Relation pair handle being queried */
00895     iBase_EntityHandle entity,
00896         /**< [in] Entity whose relations are being inferred */
00897     int iface_no,
00898         /**< [in] Entity corresponds to 1st (=0) or 2nd (=1) interface in
00899         relation pair */
00900     int* err
00901         /**< [out] Returned Error status (see iBase_ErrorType) */
00902 );
00903 
00904 /***************************************************************************//**
00905  * \brief Brief unavailable
00906  *
00907  * Description unavailable
00908  ******************************************************************************/
00909 void iRel_inferSetRelations(
00910     iRel_Instance instance,
00911         /**< [in] iRel instance handle */
00912     iRel_PairHandle pair,
00913         /**< [in] description unknown */
00914     iBase_EntitySetHandle entity_set,
00915         /**< [in] description unknown */
00916     int iface_no,
00917         /**< [in] description unknown */
00918     int* err
00919         /**< [out] Returned Error status (see iBase_ErrorType) */
00920 );
00921 
00922 /***************************************************************************//**
00923  * \brief Infer relations corresponding to specified entities and relation pair
00924  *
00925  * Infer relations corresponding to specified entities and relation pair.
00926  * The criteria used to infer these relations depends on the interfaces in
00927  * the pair, the iRel implementation, and the source of the data in those
00928  * interfaces.
00929  ******************************************************************************/
00930 void iRel_inferEntArrRelations(
00931     iRel_Instance instance,
00932         /**< [in] iRel instance handle */
00933     iRel_PairHandle pair,
00934         /**< [in] Relation pair handle being queried */
00935     iBase_EntityHandle* entities,
00936         /**< [in] Array of entities whose relation are being inferred */
00937     int entities_size,
00938         /**< [in] Number of entities in array */
00939     int iface_no,
00940         /**< [in] Entities correspond to 1st (=0) or 2nd (=1) interface in
00941         relation pair */
00942     int* err
00943         /**< [out] Returned Error status (see iBase_ErrorType) */
00944 );
00945 
00946 /***************************************************************************//**
00947  * \brief Brief unavailable
00948  *
00949  * Description unavailable
00950  ******************************************************************************/
00951 void iRel_inferSetArrRelations(
00952     iRel_Instance instance,
00953         /**< [in] iRel instance handle */
00954     iRel_PairHandle pair,
00955         /**< [in] description unknown */
00956     iBase_EntitySetHandle* entity_sets,
00957         /**< [in] description unknown */
00958     int entities_size,
00959         /**< [in] description unknown */
00960     int iface_no,
00961         /**< [in] description unknown */
00962     int* err
00963         /**< [out] Returned Error status (see iBase_ErrorType) */
00964 );
00965 
00966 
00967   /** \mainpage The ITAPS Relations Interface iRel
00968    *
00969    * Each ITAPS interface encapsulates functionality that "belongs"
00970    * together, for example mesh or geometric model functionality.  In
00971    * some cases, however, data in several of these interfaces need to
00972    * be related together.  For example, a collection of mesh faces
00973    * should be related to the geometric model face which they
00974    * discretize.  The ITAPS Relations interface accomplishes this in a
00975    * way which allows the lower-level interfaces to remain
00976    * independent.
00977    *
00978    * iRel defines relations as pairwise relations between entities
00979    * or entity sets.  Related entities can be in the same or different
00980    * interfaces.  A given relation is created for a given pair of
00981    * interfaces and returned in the form of a \em Relation \em Handle.
00982    * After a specific relation pair has been created, concrete
00983    * relations for that pair can be assigned and retrieved for
00984    * specific entities using set and get functions on the iRel
00985    * interface.  A given interface instance can appear in one or many
00986    * relation pairs, each identified by the relation pair handle.
00987    *
00988    * \section Types Relation Types
00989    *
00990    * Relations are also distinguished by a pair of relation types.
00991    * For each interface in a relation pair, a corresponding type
00992    * indicates whether the relation applies to entities, entity sets,
00993    * or both entities and sets in the corresponding interface in the
00994    * pair.  If only one of the interfaces in a given pair has a
00995    * 'both'-type, entities and entity sets in that
00996    * interface are each related to either entities or sets in the other
00997    * interface in the pair.  If both of the sides of a relation are of 
00998    * 'both'-type, entities and sets on one side of a relation point to 
00999    * sets on the other side.
01000    *
01001    * \section Status Relation Status
01002    *
01003    * Relations are also distinguished by a pair of relation statuses.
01004    * For each interface in a relation pair, a corresponding status indicates
01005    * whether the relation on that side is kept up to date, or stored at all.
01006    * Allowable values for status are iRel_ACTIVE, iRel_INACTIVE, and iRel_NOTEXIST,
01007    * defined in the iRel_RelationStatus enumeration.  Status for a given side
01008    * can be changed from iRel_ACTIVE to iRel_INACTIVE and vice versa, or from
01009    * either of those to iRel_NOTEXIST.  However, once changed to iRel_NOTEXIST
01010    * (or created that way), a side cannot be changed back to the other two.
01011    * Changing a side to be iRel_INACTIVE can be used when frequent changes to
01012    * the underlying entities are being made, e.g. during adaptive mesh refinement.
01013    * Changing from iRel_INACTIVE to iRel_ACTIVE implies a traversal of all entities
01014    * on the iRel_ACTIVE side to recover which entities on the iRel_INACTIVE side
01015    * must have their relations updated.
01016    *
01017    * \section ArgOrder Argument Order
01018    *
01019    * Many functions in the iRel interface take as input two entities,
01020    * or two lists of entities, along with a relation pair handle.  For
01021    * these functions, the entities or lists are assumed to be in the
01022    * same order as the interfaces used to create that relation pair.
01023    * For example, if a relation pair is created by calling:
01024    * \code 
01025    * iRel_createRelation(instance, iface1, ent_or_set1, type1, 
01026    *                     iface2, ent_or_set2, type2,
01027    *                     &relation_handle, &ierr)
01028    * \endcode
01029    * and relations set by calling
01030    * \code
01031    * iRel_setEntEntRelation(instance, relation_handle,
01032    *                        ent1, is_set1, ent2, is_set2, &ierr)
01033    * \endcode
01034    * it is assumed that ent1 is contained in iface1 and ent2 in
01035    * iface2.
01036    *
01037    * For functions taking only one entity or list as input, and
01038    * returning an entity or list, an additional argument indicates
01039    * whether the input entity or list belongs to the first or second
01040    * interface in that relation pair.
01041    * 
01042    */
01043 
01044 #ifdef __cplusplus
01045 } /* extern "C" */
01046 #endif
01047 
01048 #endif /* #ifndef _ITAPS_iRel */
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines