jp2_input_box::open_next

This function may be used to open the next box in sequence, after the one which was last closed. If the box was last opened as a sub-box of another jp2_input_box object, the function attempts to open a new sibling sub-box, failing (leaving the box in the closed state and returning false) if the containing super-box is exhausted.

If the box was last opened directly, using a locator to navigate inside the jp2_family_src object, this function opens the next box in sequence, failing (leaving the box in the closed state and returning false) only if the source is exhausted. Note that the behaviour could be misleading in this case, if the locator supplied to the first form of the open function did not correspond to a top level box, since we might then walk right over the containing super-box boundary without noticing. It is your responsibility to use this function in a meaningful way.

If the function fails to open a new box, the exists member will return false. While this usually means that the JP2 source, or the containing super-box is exhausted, it could also occur if the unerlying jp2_family_src object uses a dynamic cache ( kdu_cache or a suitably derived object). In that case, the present function may be called repeatedly, with the possibility of succeeding at a later point when the cache contents have been augmented.