| synopsis || functions || variables |
[Declared in "../apps/kdu_server/kdu_serve.h"]
This object plays a critical role in the implementation of any JPIP server which is able to support intelligent delivery of meta-data together with imagery to its clients. It is used to build a tree-structured manifest of the meta-data which is available, together with pre-digested information concerning the relevance of that meta-data to particular image code-streams, or specific regions components or resolutions of those code-streams.
The meta-data tree need not contain an entry for every single meta-data box from the original JP2-family file. Instead, the granularity of the representation may be selected by the kdu_serve_target object which creates and owns the tree.
The elements of each meta data-bin are represented by a list of kds_metagroup objects, connected via their next members. Each element in this list represents one or more boxes (all JP2-family files are built from boxes) at the top level of the contents of that data-bin. The tree starts at meta data-bin 0, whose top-level boxes are the top-level boxes of the original JP2-family file.
Amongst the list of kds_metagroup objects which represent the contents of a meta data-bin, there may be one or more placeholder boxes. Placeholders have a rich and powerful structure, as described in the JPIP standard (to become IS 15444-9). In this case, the phld member of the kds_metagroup structure will point to another list of kds_metagroup objects, representing the data-bin to which the placeholder refers. The phld_bin_id member provides the corresponding meta data-bin identifier.
~kds_metagroup [virtual]
True if the group consists of a placeholder. Where a meta group contains a placeholder box , it must contain nothing other than that placeholder, and phld_bin_id holds the identifier of the meta data-bin to which the placeholder refers. Also, in this case the box_types array and last_box_type member hold the type of the box which has been replaced by the placeholder (the type of the box whose header is embedded within the placeholder).
If the placeholder represents an incremental code-stream (one which is to be served via code-stream header, precinct, tile and meta data-bins, the phld member will be NULL, phld_bin_id will be 0, and the box_types and last_box_type members hold the type of an appropriate code-stream box such as "jp2c".
True if this meta-data group contains the final JP2 box in its data-bin.
True if the length of this meta data-group extends to the end of the file, but is not otherwise known. In this case, length will be set to KDU_INT32_MAX.
Indicates the total number of bytes from the relevant meta data-bin, which belong to this group. This value will be equal to KDU_INT32_MAX if is_rubber_length is true.
Identifies the number of entries in the box_types array.
Array of num_box_types box type codes, providing the types of all boxes which are represented by this object, including sub-boxes. There need not be one entry here for each box, but only one entry for each different type of box, regardless of whether it appears at the top level or elsewhere. The reason for providing this information is to allow kdu_serve to determine whether or not the present group of boxes contains any box types in which the client may be interested, where the client explicitly provides a metareq query field to identify box types which are of interest.
If phld is non-NULL, this list should include the type of the box whose header appears within the placeholder box, but it need not include the types of the boxes which appear within the placeholder's data-bin (see phld_bin_id).
It can happen that this list is empty. This happens only if the group contains no visible boxes, but still does represent data. As an example, the group may hold the contents of a meta data-bin which represents the contents of another box, whose header appears within a placeholder the referencing data-bin.
If the group represents only one box, this is the number of bytes in the header of that box and num_box_types must be 1. However, if the group contains multiple boxes, this is the number of bytes from the start of the group up until the end of the header of the last box in the group. The type of this last box is given by the last_box_type member. By "last box" we do not just mean the last top level box, but rather the last box of any type listed in the box_types array, whether a sub-box or not. If the client asks only for headers of boxes in this group, the server will only be able to avoid sending the body of the last box in the group.
If the box contains a placeholder, last_box_header_prefix must be identical to length, since the placeholder box itself represents the original box header.
If the box contains no box headers at all ( last_box_type=0 and num_box_types=0), the value of last_box_header_prefix should be 0.
Holds the box type code for the last box in the group, whether it is a sub-box or not. See last_box_header_prefix for more on the significance of final boxes. If the last box is a placeholder, this member contains the type code of the box header which is embedded within the placeholder (the type of the original box which was replaced by the placeholder). The "phld" box type itself never appears within the box_types array or the last_box_type member. If the box_types list is empty, meaning that this object represents only the raw contents of a box whose header is in the placeholder of another meta data-bin, then last_box_type will also be 0.
Points to the next entry in the list of meta-data groups which are at the top level of a given meta data-bin.
NULL unless this group consists of a placeholder box which references another meta data-bin. Note that incremental code-stream placeholders stand for a code-stream which is to be replaced by header and precinct data-bins, synthesized by kdu_serve. In this case, the phld member should be NULL, although is_placeholder will be true. This condition uniquely identifies the presence of an incremental code-stream placeholder.
This member is valid if and only if phld is non-NULL. It provides the data-bin identifier of the new meta data-bin whose contents are represented by the meta group list referenced by phld.
Points to a list of kds_metascope objects which are used by kdu_serve to determine whether or not the metadata group is relevant to a client's interests and, if so, how the metadata should be sequenced relative to other metadata and compressed image data.
Placeholder boxes as well as ordinary boxes may have scope. In fact, incremental code-stream placeholders must have at least one scope which identifies the code-stream to which they belong.
If the object represents the contents of another box whose header appears in a placeholder somewhere, this object will have a NULL scope list, since the scope of the placeholder provides scope for the present contents object.
Otherwise, if an object has a NULL scope list, it is considered to represent "global" metadata, which is not attached to any particular code-stream or image region. Global metadata may, alternatively, be identified by a scope entry whose global member is true.