Functions | |
void | Begin_Segment_Search (const char *segspec) |
void | Show_Segment_Count (int *count) |
HC_BOOLEAN | Find_Segment (char *segment) |
void | End_Segment_Search (void) |
void Begin_Segment_Search | ( | const char * | segspec | ) |
Finds all segments matching a search specification.
segspec | - A specification, often including wildcards, of the segment(s) to be searched for. Passed by reference always |
Begin_Segment_Search() initiates the search by specifying where to start looking for segments.
Show_Segment_Count() lets a program anticipate how many segments names will be returned from a sequence of calls to Find_Segment() in order that sufficient space may be allocated to receive them. Count is the total number of matching segments.
Find_Segment() is the routine that returns, one at a time, the segments which matched the specification given in Begin_Segment_Search(). When all segments have been returned, its function value becomes false.
End_Segment_Search() terminates the search sequence and reactivates any previously active segment search.
The segspec parameter can take a number of valid segment name specifications including aliases, wildcards, and paths, as explained in the HOOPS/3dGS programming guide section 1.2.6 "Segment-Name Syntax". Wildcards in the segment specification will typically match more than one segment in the database. The following examples are valid usages:
level = 0 print_children (segment) { Open_Segment (segment) Begin_Segment_Search ("*") while (Find_Segment (child)) { Parse_String (child, "/", -1, pathname) print (level, pathname) level = level + 1 print_children (pathname) level = level - 1 } End_Segment_Search () Close_Segment () }
This example could also have been written using the "contents search" routines, replacing "Begin_Segment_Search ("*")" with "Begin_Contents_Search (".", "segments")", and so on.
If a search is in progress and a segment satisfying the target specification is deleted, it will not be returned by subsequent calls to Find_Segment() . If a segment is renamed, the new name will be returned. If a segment is created, it will not be returned in the current sequence of Find_Segment() calls.
Show_Segment_Count() must be called between Begin_Segment_Search() and End_Segment_Search() . It will always return the total number of segments, not the remaining number of segments.
void Show_Segment_Count | ( | int * | count | ) |
Finds out how many segments will be returned. This is useful for determining the size of a data structure needed to store incoming items.
count | - Number of segments that satisfy the search specification. Returned to user. Passed by reference always. |
HC_BOOLEAN Find_Segment | ( | char * | segment | ) |
Retrieves the segment names, one at a time. The function returns false when all segments have been returned.
segment | - The full pathname of a segment that satisfies the search specification (segspec). Returned to user. Passed by reference always. |
void End_Segment_Search | ( | void | ) |
Terminates the segment search sequence and frees any involved memory.