Visit Functions
In a application, you often want to perform an operation on all the objects that belong to another object, such as all the features in a part, or all the surfaces in a feature. For each case, provides an appropriate “visit function.” A visit function is an alternative to passing back an array of data.
You write a function that you want to be called for each item (referred to as the “visit action” function) and pass its pointer to the visit function. The visit function then calls your visit action function once for each visited item.
Most visit functions also provide for a second callback function, the filter function, which is called for each visited item before the action function. The return value of the filter function controls whether the action function is called. You can use the filter function as a way of visiting only a particular subset of the items in the list.
For example, the visit function for visiting the features in a solid is declared as follows:
ProError ProSolidFeatVisit (
ProSolid solid,
ProFeatureVisitAction visit_action,
ProFeatureFilterAction filter_action,
ProAppData app_data);
The first argument is the handle to the solid (the part or assembly) whose features you want to visit.
The second and third arguments are the visit action function and filter function, respectively.
The type of the final argument, ProAppData, is a typedef to a void*. This argument is used to pass any type of user-defined application data down to the visit_action and filter_action functions through the intervening layer. You might want to use this as an alternative to allowing global access to the necessary data.
Although you write the visit action and filter functions, they are called from within the visit function, so their arguments are defined by . To enable the C compiler to check the arguments, provides a typedef for each of these functions.
For example, the type for the action function for
ProSolidFeatVisit() is as follows:
typedef ProError (*ProFeatureVisitAction)(
ProFeature *feature,
ProError status,
ProAppData app_data);
It takes three arguments:
• The handle to the feature being visited
• The status returned by the preceding call to the filter function
• The application data passed as input to the visit function itself
The type for the filter function is as follows:
typedef ProError (*ProFeatureFilterAction)(
ProFeature *feature,
ProAppData app_data);
Its two arguments are the handle to the feature being visited and the application data.
The filter action function should return one of the following values:
• PRO_TK_CONTINUE—Do not call the visit action for this object, but continue to visit the subsequent objects.
• Any other value—Call the visit action function for this object and pass the return value as the status input argument.
The visit action function should return one of the following values:
• PRO_TK_NO_ERROR—Continue visiting the other objects in the list.
• PRO_TK_E_NOT_FOUND—For visit functions, this value indicates that no items of the desired type were found and no functions could be visited.
• Any other value (including PRO_TK_CONTINUE)—Terminate the visits. Typically this status is returned from the visit function upon termination, so that the calling function knows the reason that visiting terminated abnormally.