jp2_input_box::open

Opens the box to read from the src object. If src was opened using a seekable file, seekable compressed data source, or a dynamic cache ( kdu_cache) object, multiple boxes may be simultaneously opened using the same jp2_family_src object. Moreover, they may be read in any order, or in interleaved fashion. The internal machinery maintains information about the current read state and manages all required context switching, but for multi-threaded applications you should consider supplying implementing the synchronization funcions, jp2_family_src::acquire_lock and jp2_family_src::release_lock in a class derived from jp2_family_src.

Every open box has a unique locator value. If you have visited a box before (e.g., during an initial pass through the file), you may open the box again using the locator you found at that time by invoking jp2_input_box::get_locator. Using a locator, you may open any box using this function, not just top level boxes. You may think of the locator as the address of the box within its file, even though the information source might be a kdu_cache object which has no linear file structure. Even in this case, a mechanism is provided (behind the scenes) for maintaining the association between each JP2 box and a location in an original file. These locations are managed by the jp2_locator::get_file_pos and jp2_locator::set_file_pos functions.

An error may be generated through kdu_error if a fundamental problem is detected. If the jp2_family_src object is using a cache as its data source, however, it is possible that the cache may not yet have sufficient information to open the box. In this case, the function returns false, leaving the box closed ( exists remains false). Any of the following conditions may cause this to happen:

• All or part of the box's header might not yet have been loaded into the cache.
• The cache might not contain sufficient information to determine the cache data-bin to which the box belongs. This may happen if the supplied locator object identifies only an original file location (set using jp2_locator::set_file_pos), in which case it may be necessary to walk through multiple data-bins to determine where the dynamic representation of that box will be; and some of the intermediate bins might not yet be available.
• The box might be represented by a placeholder box, whose contents are not yet fully available — the placeholder box's contents must be read before the actual location of the box's contents can be determined.

If any of the above occurs, the function returns false with the box still closed. Trying again later, however, once the cache contents have been augmented, may result in success ( exists becomes true).

True if a new box was opened, else false.

src [jp2_family_src *]

locator [jp2_locator]