7 Application program interface (API)

Semantics

Input parameters

Input/output parameters

Output parameters

Success status codes

Failure status codes

Semantics

Add an associate relationship from from_object to to_object provided that the following criteria are met.

1. Either from_object or to_object shall be a resolved object, or both shall be resolved objects. If both from_object and to_object are resolved, link_object (if provided) shall be a resolved object; otherwise, link_object may be unresolved.

2. from_object shall reside in a transmittal that has been explicitly opened with either access mode CREATE or access mode UPDATE.

3. to_object if not in the same transmittal as from_object, shall be a published object.

4. link_object, if not in the same transmittal as from_object, shall be a published object.

It should be noted that relationships between objects in different transmittals are not implicitly bi-directional, so the make_two_way parameter will have an effect in inter-transmittal referencing only if:

1. both the from_object and to_object are published,

2. both the from_object and to_object are resolved and,

3. both transmittals have been opened for writing or modification

If only the from_object is resolved, the association can only be one way.

If the DRM specifies that a link object is required for a relationship, the link_object parameter shall be used. If the DRM does not allow for the link object to exist in a relationship, the link_object parameter shall not be used.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and all actions succeeded.

When this function completes in error, one of the following actions occurs:

• Current status code is set to INVALID_ACCESS_MODE and no changes are made, if:
  1. from_object (and link_object if specified) is in a transmittal that is open in READ_ONLY mode;
  2. to_object is in a transmittal that has not been opened for writing or modification, so no association could be created from to_object.
• Current status code is set to UNPUBLISHED_OBJECT and no changes are made if:
  1. to_object is in another transmittal than from_object, but is not published by that transmittal; or
  2. link_object is in another transmittal than from_object, but is not published by that transmittal; or
  3. to_object is in another transmittal than from_object, and make_two_way is TRUE, but from_object is not published by its transmittal.
• Current status code is set to UNRESOLVED_INPUT_OBJECT and no changes are made if:
  1. from_object is an unresolved object,
  2. link_object is an unresolved object, or
  3. to_object is an unresolved object and make_two_way is TRUE.
• Current status code is set to DELETED_OBJECT and no changes are made if any of the DRM objects passed into this function have been removed from the transmittal in which they resided.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. from_object is not a valid handle to a DRM object;
  2. to_object is not a valid handle to a DRM object;
  3. if a link object is required for association relationship from to_object to from_object but is not provided or link_object is not a valid handle to a DRM object; or
  4. the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

INVALID_ACCESS_MODE
UNPUBLISHED_OBJECT
UNRESOLVED_INPUT_OBJECT
DELETED_OBJECT
INACTIONABLE_FAILURE

Semantics

Adds a composition relationship from aggregate_object to component_object, provided that the following criteria are met.

1. Either aggregate_object or component_object shall be a resolved object, or both shall be resolved objects. If both aggregate_object and component_object are resolved, link_object (if provided) shall be a resolved object; otherwise, link_object may be unresolved.
2. aggregate_object shall reside in a transmittal that has been explicitly opened with either access mode CREATE or access mode UPDATE.
3. component_object, if component_object is resolved and not in the same transmittal as aggregate_object, shall be a published object.
4. link_object, if not in the same transmittal as aggregate_object, shall be a published object.

If the DRM specifies that a link object is required for a relationship, the link_object parameter shall be used. If the DRM does not allow for the link object to exist in a relationship, the link_object parameter shall not be used.

NOTE Relationships between objects in different transmittals are not implicitly bi-directional, so if the component_object is unresolved, the relationship will be uni-directional from the aggregate to the component.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS the requested composition relationship is added if valid parameters were passed in and all operations succeeded.

When this function completes in error, one of the following actions occurs:

• Current status code is set to UNPUBLISHED_OBJECT and no changes are made if both component_object and aggregate_object are resolved, in different transmittals, and either is not published.
• Current status code is set to UNRESOLVED_INPUT_OBJECT and no changes are made if:
  1. aggregate_object and component_object are both unresolved, or
  2. both aggregate_object and component_object are resolved and link_object is not unresolved.
• Current status code is set to INVALID_ACCESS_MODE and no changes are made if:
  1. aggregate_object (or link_object if specified) is in a transmittal that is not open for creation or modification,.
  2. component_object is in a transmittal that is not open for creation or modification.
• Current status code is set to DELETED_OBJECT and no changes are made if any of the DRM objects passed into this function have been removed from the transmittal in which they resided.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. component_object is not a valid handle to a DRM object;
  2. aggregate_object is not a valid handle to a DRM object;
  3. a link object is required for the relationship from component_object to aggregate_object but is not provided or link_object is not a valid handle to a DRM object; or
  4. the relationship could not be created for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

UNPUBLISHED_OBJECT
UNRESOLVED_INPUT_OBJECT
INVALID_ACCESS_MODE
DELETED_OBJECT
INACTIONABLE_FAILURE

Semantics

This function creates a new handle to the same object referenced by object.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and the object referenced by object is made accessible through duplicate_object if valid parameters were passed in and all operations succeeded.

When this function completes in error, one of the following actions occurs:

• Current status code is set to DELETED_OBJECT and no changes are made if any of the DRM objects passed into this function have been removed from the transmittal in which they resided.
• Current status code is set to OUT_OF_MEMORY and no changes are made if memory cannot be allocated for the new object handle.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if object is not a valid handle to a DRM object or this function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

DELETED_OBJECT
OUT_OF_MEMORY
INACTIONABLE_FAILURE

Semantics

This function closes the transmittal specified by transmittal and frees any and all memory allocated to hold the representation of the transmittal.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and all actions succeeded.

When this function completes in error, one of the following actions occurs:

• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. transmittal is not a valid, active, and open transmittal;
  2. transmittal has no root object set; or
  3. the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

INACTIONABLE_FAILURE

Semantics

This function creates a new object of the DRM class specified by new_object_type and inserts it into the transmittal specified by transmittal. The fields are initialized to the default values for the specified class.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and the new object is created with its handle placed in new_object.

When this function completes in error, one of the following actions occurs:

• Current status code is set to INVALID_ACCESS_MODE and no changes are made if transmittal was opened in read-only mode.
• Current status code is set to OUT_OF_MEMORY and no changes are made if memory cannot be allocated for new_object.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. transmittal is not a valid handle to a transmittal;
  2. new_object_type does not correspond to a valid, concrete (i.e., not abstract) DRM class;
  3. new_object is not valid; or
  4. the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

INVALID_ACCESS_MODE
OUT_OF_MEMORY
INACTIONABLE_FAILURE

Semantics

Defines a set of rules that can be used to filter objects from a SEDRIS transmittal so that only the objects that pass the rules will be returned to the user. This function only defines a set of rules; to use a set of rules after they have been defined, pass the set of rules into an iterator when creating the iterator. By doing so, the iterator will be bound to use that set of rules (i.e., that search filter) to filter all objects that will be returned by that iterator.

The search filter referenced by search_filter can be freed at any time; a search filter does not need to stay in existence until the iterator(s) that depend on that filter are freed. (An iterator are expected to retain a copy of any search filter used to initialize that iterator).

The encoding parameter specifies with which encoding the search filter will be used.

See 5.3.3.239 Search_Rule for further details on how to construct a valid set of rules.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and all actions succeeded.

When this function completes in error, one of the following actions occurs:

• Current status code is set to OUT_OF_MEMORY and no changes are made if the API could not allocate memory for the new search filter.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. encoding is invalid;
  2. an illegal expression was specified by the rules parameter;
  3. search_filter is invalid;
  4. the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

OUT_OF_MEMORY
INACTIONABLE_FAILURE

Semantics

This function creates a spatial search boundary to limit the scope of a component iterator’s search. The spatial search boundary can be used in a later call to 7.3.56 InitializeComponentIterator to limit the spatial area that the iterator will search.

Spatial search boundaries can be freed at any time; a spatial search boundary does not need to stay in existence until the iterator(s) that depend on that boundary are freed. (An iterator is expected to retain a copy of any search boundary used to initialize that iterator).

If no spatial search boundary is supplied, the set of objects an iterator will iterate over will be determined solely by the search rules and the starting object of the search.

The encoding parameter specifies with which encoding the spatial search boundary will be used.

The search_bounds parameter specifies the spatial extents of the search boundary.

The search_bounds_closure parameter specifies the boundaries to be included in the spatial extents of the search boundary.

The search_quality parameter specifies whether the location data of a DRM object should be evaluated as one point, a box containing all points, or each individual point.

The inclusion parameter specifies whether to include DRM objects fully included or only partially included in the spatial extents of the search boundary.

The search_dimension parameter specifies the dimensionality of the location data to be used for evaluation.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and all actions succeeded.

When this function completes in error, one of the following actions occurs:

• Current status code is set to OUT_OF_MEMORY and no changes are made if the API could not allocate memory for the new search boundary.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. an invalid boundary was specified by the search_bounds parameter;
  2. an invalid search_bounds_closure, search_quality, inclusion, or search_dimension was specified, or
  3. if the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

OUT_OF_MEMORY
INACTIONABLE_FAILURE

Semantics

This function determines whether a DRM object is contained within the user-specified spatial area. DetermineSpatialInclusion supplements the normal method of filtering objects by spatial location (i.e. the use of search boundaries with component iterators as described under 7.3.8 CreateSpatialSearchBoundary).

While DetermineSpatialInclusion can be used with any SEDRIS object, its intended use is to find out more information about the relationship of an object returned by a component iterator to the search bounds used in that iterator. The canonical example is to have the component iterator created with a partial inclusion choice, then to check objects for full inclusion with DetermineSpatialInclusion.

In addition to determining whether a DRM object is partly or completely inside the user-defined search bounds, this function, unlike a search boundary, will also determine whether a two-dimensional or three-dimensional object completely includes the spatial search area.

The encoding parameter specifies with which encoding the spatial search boundary will be used.

The search_bounds parameter specifies the spatial extents of the search boundary.

The search_bounds_closure parameter specifies the boundaries to be included in the spatial extents of the search boundary.

The search_quality parameter specifies whether the location data of a DRM object should be evaluated as one point, a box containing all points, or each individual point.

The search_dimension parameter specifies the dimensionality of the location data to be used for evaluation.

Three output parameters provide the results of the evaluation. The parameter object_fully_included returns whether the DRM object was fully included in the search area. The parameter object_partly_included returns whether the DRM object was partially included in the search area. The parameter object_includes_search_bounds returns whether the DRM object fully includes the search area.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and the output parameters are set to the appropriate values if valid parameters were passed in, and the relationship between the object and the boundary was determined.

When this function completes in error, one of the following actions occurs:

• Current status code is set to UNRESOLVED_INPUT_OBJECT and no changes are made if object is an unresolved DRM object.
• Current status code is set to DELETED_OBJECT and no changes are made if the DRM object passed into this function has been removed from the transmittal in which it resided.
• Current status code is set to UNRESOLVED_OUTPUT_OBJECT and no changes are made if an unresolved object was encountered and could not be resolved.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. object is not a valid handle to a DRM object;
  2. an invalid boundary was specified by the search_bounds parameter;
  3. an invalid search_bounds_closure, search_quality, or search_dimension was specified;
  4. the determination of the object/search area relationship could not be made; or
  5. the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
DELETED_OBJECT
UNRESOLVED_OUTPUT_OBJECT
INACTIONABLE_FAILURE

Semantics

This function frees the memory directly associated with the iterator specified by to_free_object. The handle to the iterator is invalid following a call to this function.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and all actions succeeded.

When this function completes in error, one of the following actions occurs:

• Current status code is set to INACTIONABLE_FAILURE and no changes are made if to_free_object is not a valid handle to an iterator or the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

INACTIONABLE_FAILURE

Semantics

This function frees the memory directly associated with the object handle specified by to_free_object.

If multiple object handles corresponding to the same object have been retrieved through this API, FreeObject shall not release the memory for that object until the last object handle to the object is passed in to FreeObject.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and the reference count for this object is decremented a valid parameter was passed in and all operations succeeded. The actual object is not freed until the reference count becomes zero, but  this object handle is no longer valid, since any contextual information associated with it (e.g., inheritance context) is released.

When this function completes in error, one of the following actions occurs:

• Current status code is set to INACTIONABLE_FAILURE and no changes are made if to_free_object is not a valid handle to a DRM object or the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

INVALID_OBJECT
INACTIONABLE_FAILURE

Semantics

This function frees the data associated with the fields of a Packed_Hierarchy instance returned by 7.3.38 GetPackedHierarchy specified by to_free, including decrementing the reference counts of all object handles in records of the object_list field.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and the packed hierarchy data is freed if a valid parameter was passed in and all operations succeeded. In this case, the fields of to_free are cleared.

When this function completes in error, one of the following actions occurs:

• Current status code is set to INACTIONABLE_FAILURE and no changes are made if to_free is not a valid handle to a DRM object or the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

INACTIONABLE_FAILURE

Semantics

This function frees the data associated with the fields of a Remaining_Objects_List value returned by 7.3.43 GetRemainingObjectsList and specified by to_free, including decrementing the reference counts of all object handles in the remaining_objects_list and remaining_link_objects_list fields.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and the remaining objects data is freed if valid parameters were passed in and all operations succeeded. In this case, the fields of to_free are cleared.

When this function completes in error, one of the following actions occurs:

• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. to_free is invalid,
  2. to_free contains a non-NULL entry that is not a handle to a valid, active (i.e., unfreed) object,
  3. the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

INACTIONABLE_FAILURE

Semantics

This function frees the data associated with the fields of a Remaining_Packed_Hierarchies_List returned from 7.3.44 GetRemainingPackedHierarchies and specified by to_free, including decrementing the reference counts of all object handles in the records of the object_list field contained within each Packed_Hierarchy record in the hierarchy_list field.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and the remaining packed hierarchy data is freed if valid parameters were passed in. In this case, the fields of to_free are cleared.

When this function completes in error, one of the following actions occurs:

• Current status code is set to INACTIONABLE_FAILURE and no changes are made if to_free is invalid or the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

INACTIONABLE_FAILURE

Semantics

This function frees the memory directly associated with the search filter handle specified by to_free. The memory was allocated during an earlier call to 7.3.7 CreateSearchFilter. The handle to the search filter is invalid following a call to this function.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and the search filter is freed if valid parameters were passed in and all operations succeeded.

When this function completes in error, one of the following actions occurs:

• Current status code is set to INACTIONABLE_FAILURE and no changes are made if to_free is not a valid search filter or the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

INACTIONABLE_FAILURE

Semantics

This function frees the memory directly associated with the spatial search boundary handle specified by to_free. The memory was allocated by this API during an earlier call to 7.3.8 CreateSpatialSearchBoundary. The handle to the spatial search boundary is invalid following a call to this function.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and the search boundary is freed if a valid parameter was passed in and all operations succeeded.

When this function completes in error, one of the following actions occurs:

• Current status code is set to INACTIONABLE_FAILURE and no changes are made if to_free is not a valid spatial search boundary or the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

INACTIONABLE_FAILURE

Semantics

This function frees the memory directly associated with the transmittal handle specified by to_free. The memory was allocated by an earlier call to 7.3.47 GetTransmittalFromObject. The handle to the transmittal is invalid following a call to this function. Transmittal handles returned from 7.3.62 OpenTransmittalByLocation or 7.3.63 OpenTransmitalByName shall not be provided to this function.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and the given handle to the transmittal is freed if a valid parameter was passed in.

When this function completes in error, one of the following actions occurs:

• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. to_free is invalid;
  2.  to_free was not allocated by 7.3.62 OpenTransmittalByLocation or 7.3.63 OpenTransmitalByName; or
  3. the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

INACTIONABLE_FAILURE

Semantics

This function retrieves the instance of the type of aggregate object specified by drm_class that directly contains the object specified by object as a component.

EXAMPLE  If GetAggregate is called with a <DRM Model> instance as the object object, the <DRM Model Library> instance would be returned in object, since the <DRM Model Library> instance is the aggregate object that contains the <DRM Model> instance as a component.

The itr_traversal parameter specifies how the function will behave when it encounters an ITR reference. The function could:

1. automatically resolve such references and continue the search within the new transmittal;
2. report all ITR references without resolving them; or
3. ignore such references completely and continue to search within the current transmittal.

This is a short form, single instance version of an aggregate iterator. It combines the creation of an iterator, making a call to 7.3.31 GetNextObject, and freeing the iterator, in the case where one and only one aggregate should be retrieved.

When this function completes successfully, one of the following actions occurs:

• Current status code is set to SUCCESS and the output parameters are set to the appropriate values if valid parameters were passed in and one valid aggregate of the specified class was found.
• Current status code is set to DIFFERENT_TRANSMITTAL and aggregate_object is set to point to the aggregate, and link_class_object is set appropriately, unless a NULL for that value was provided, if the following conditions are met:
  1. valid parameters were passed in,
  2. the user requested that the API automatically resolve inter-transmittal references (ITR),
  3. an ITR reference was encountered in searching for the aggregate, and
  4. the iterator successfully resolved it and retrieved the aggregate from the new, different transmittal.
• Current status code is set to UNRESOLVED_OUTPUT_OBJECT and aggregate_object and/or link_class_object are set to point to an unresolved object, if valid parameters were passed in and an ITR reference was encountered while itr_traversal is set to report ITR references.

When this function completes in error, one of the following actions occurs:

• Current status code is set to UNRESOLVED_INPUT_OBJECT and no changes are made if object is unresolved.
• Current status code is set to NO_OBJECT and no changes are if no aggregate object of the specified DRM class could be found.
• Current status code is set to UNRESOLVED_OUTPUT_OBJECT and no changes are made, if valid parameters were passed, an ITR reference was encountered, itr_traversal is set to resolve ITR references, and an ITR reference was not resolved.
• Current status code is set to DELETED_OBJECT and no changes are made if:
  1. object has been removed from the transmittal in which it resided;
  2. aggregate_object has been removed from the transmittal in which it resided; or
  3. link_class_object has been removed from the transmittal in which it resided.
• Current status code is set to OUT_OF_MEMORY and no changes are made if memory could not be allocated.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. object is not a valid handle to a DRM object;
  2. drm_class specifies an invalid value;
  3. itr_traversal is not valid;
  4. aggregate_object and/or link_class_object are invalid; or
  5. the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS
DIFFERENT_TRANSMITTAL
UNRESOLVED_OUTPUT_OBJECT

Failure status codes

UNRESOLVED_INPUT_OBJECT
UNRESOLVED_OUTPUT_OBJECT
NO_OBJECT
DELETED_OBJECT
OUT_OF_MEMORY
INACTIONABLE_FAILURE

Semantics

This function retrieves an instance of the type of associated object specified by drm_class from the object specified by object.

Given an object (object) and a type of associate for which to search (drm_class), this function will look for an immediately associated object of the given drm_class. Only objects at the “to” end of a one-way association, or at either end of a two-way association, will be returned by this function.

The itr_traversal parameter specifies how the function will behave when it encounters an ITR reference. The function could:

1. automatically resolve such references and continue the search within the new transmittal;
2. report all ITR references without resolving them; or
3. ignore such references completely and continue to search within the current transmittal.

This is a short form, single instance version of an associate iterator. It combines the creation of an iterator, making a call to 7.3.31 GetNextObject, and freeing the iterator, in the case when one and only one associate should be retrieved.

When this function completes successfully, one of the following actions occurs:

• Current status code is set to SUCCESS and associate_object is set to point to the associate, and link_class_object is set appropriately if provided, if valid parameters were passed in, only one object was found that satisfied the specified criteria, and no ITR references were involved.
• Current status code is set to DIFFERENT_TRANSMITTAL and the output parameters are set as for the SUCCESS case,  if the following conditions are met:
  1. valid parameters were passed in,
  2. the user requested that the API automatically resolve inter-transmittal references (ITR),
  3. an ITR reference was encountered in searching for the associate, and
  4. the iterator successfully resolved it and retrieved the associate from the new, different transmittal.
• Current status code is set to UNRESOLVED_OUTPUT_OBJECT and associate_object and/or link_class_object are set to point to an unresolved object, if valid parameters were passed in and an ITR reference was encountered while itr_traversal is set to report ITR references.

When this function completes in error, one of the following actions occurs:

• Current status code is set to UNRESOLVED_INPUT_OBJECT and no changes are made if object is unresolved.
• Current status code is set to UNRESOLVED_OUTPUT_OBJECT and no changes are made if valid parameters were passed, an ITR reference was encountered, itr_traversal is set to resolve ITR references, and an ITR reference was not resolved.
• Current status code is set to NO_OBJECT and no changes are made if no aggregate object of the specified DRM class could be found.
• Current status code is set to DELETED_OBJECT and no changes are made if:
  1. object has been removed from the transmittal in which it resided;
  2. associate_object has been removed from the transmittal in which it resided; and/or
  3. link_class_object has been removed from the transmittal in which it resided.
• Current status code is set to OUT_OF_MEMORY and no changes are made if memory could not be allocated.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. object is not a valid handle to a DRM object;
  2. drm_class specifies an invalid value;
  3. itr_traversal is not valid;
  4. associate_object and/or link_class_object are invalid; or
  5. the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS
DIFFERENT_TRANSMITTAL
UNRESOLVED_OUTPUT_OBJECT

Failure status codes

UNRESOLVED_INPUT_OBJECT
UNRESOLVED_OUTPUT_OBJECT
NO_OBJECT
DELETED_OBJECT
OUT_OF_MEMORY
INACTIONABLE_FAILURE

Semantics

This function returns the colour model currently being used in colour_model when returning <DRM Colour Data> objects from the transmittal specified by transmittal. The value returned depends on the last call made to 7.3.74 SetColourModel and/or 7.3.86 UseDefaultColourModel functions and the manner in which the transmittal was produced.

Case 1: 7.3.74 SetColourModel was called more recently than 7.3.86 UseDefaultColourModel. The colour model selected by 7.3.74 SetColourModel is still the current colour model, and that colour model data will be returned. It does not matter which colour model was originally used to produce the given transmittal, since the 7.3.74 SetColourModel function was used to override any default colour model choices and forces all <DRM Colour Data> objects to be of the type specified by the current colour model.

Case 2: 7.3.86 UseDefaultColourModel was called more recently than 7.3.74 SetColourModel or 7.3.74 SetColourModel was never called. In this case, the colour model that will be used to return <DRM Colour Data> objects from the given transmittal depends entirely on the transmittal. The colour model used to return data will be the colour model that was used when producing the transmittal. This is the default case.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and colour_model is set to the colour model currently being used by the API when returning <DRM Colour Data> instances from the specified transmittal, if valid parameters were passed in.

When this function completes in error, one of the following actions occurs:

• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. the default colour model is in effect but the given transmittal does not specify a colour model;
  2. colour_model is invalid;
  3. transmittal is not a handle to a valid, active (i.e., open and unfreed) transmittal; or
  4. the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

INACTIONABLE_FAILURE

Semantics

This function retrieves a component object of the DRM class specified by drm_class (or, if drm_class specifies an abstract class, a subclass of the class specified by drm_class) from the object specified by object.

If the directly_attach_table_components parameter has the value FALSE, the actual DRM objects will be retrieved. However, if the value is TRUE, the following adjustments will be made:

1. If a <DRM Property Set Index> component would otherwise be returned, the <DRM Property Set Index> component shall be automatically replaced by the corresponding objects referenced by the primary (1st) <DRM Property Set> of the referenced <DRM Property Set Table Group>.
2. If a <DRM Colour Index> component would otherwise be returned, the <DRM Colour Index> component shall be replaced by a <DRM Inline Colour> containing the same <DRM Primitive Colour> as the <DRM Primitive Colour> that would have been referenced by the <DRM Colour Index> (through the default <DRM Colour Table> of the associated <DRM Colour Table Group>).

If the value of process_inheritance is TRUE, inherited components will be considered as well as immediate components. If the value is FALSE, only immediate components will be considered.

EXAMPLE setting the process_inheritance parameter to TRUE allows asking for the <DRM Inline Colour> component of a <DRM Polygon> without regard to whether the <DRM Inline Colour> component was an “mmediate” or “nherited” component of the <DRM Polygon>.

An immediate component shall always take precedence over an inherited component.

The itr_traversal parameter specifies how the function will behave when it encounters an Inter-Transmittal Reference (ITR). The function could:

1. automatically resolve such references and continue the search within the new transmittal;
2. report all ITR references without resolving them; or
3. ignore such references completely and continue to search within the current transmittal.

When this function completes successfully, one of the following actions occurs:

• Current status code is set to SUCCESS and component_object is set to point to the component, and link_class_object is set appropriately if provided, if valid parameters were passed in, only one object was found that satisfied the specified criteria, and no ITR references were involved.
• Current status code is set to DIFFERENT_TRANSMITTAL and the output parameters are set as for the SUCCESS case,  if the following conditions are met:
  1. valid parameters were passed in,
  2. the user requested that the API automatically resolve inter-transmittal references (ITR),
  3. an ITR reference was encountered in searching for the associate, and
  4. the iterator successfully resolved it and retrieved the associate from the new, different transmittal.
• Current status code is set to UNRESOLVED_OUTPUT_OBJECT and the output parameters are set as for the SUCCESS case if valid parameters were passed in and only one object was found that satisfied the specified criteria, but the component object is unresolved.

When this function completes in error, one of the following actions occurs:

• Current status code is set to UNRESOLVED_INPUT_OBJECT and no changes are made if object is unresolved.
• Current status code is set to UNRESOLVED_OUTPUT_OBJECT and no changes are made if valid parameters were passed, an ITR reference was encountered, itr_traversal is set to resolve ITR references, and an ITR reference was not resolved.
• Current status code is set to DELETED_OBJECT and no changes are made if:
  1. object has been removed from the transmittal in which it resided;
  2. associate_object has been removed from the transmittal in which it resided; and/or
  3. link_class_object has been removed from the transmittal in which it resided.
• Current status code is set to NO_OBJECT and no changes are made if no component object of the specified DRM class could be found.
• Current status code is set to OUT_OF_MEMORY and no changes are made if memory could not be allocated.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. object is not a valid handle to a DRM object;
  2. drm_class specifies an invalid value; or
  3. itr_traversal is not valid;
  4. the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS
DIFFERENT_TRANSMITTAL
UNRESOLVED_OUTPUT_OBJECT

Failure status codes

UNRESOLVED_INPUT_OBJECT
UNRESOLVED_OUTPUT_OBJECT
DELETED_OBJECT
NO_OBJECT
OUT_OF_MEMORY
INACTIONABLE_FAILURE

Semantics

This function retrieves a copy of the current effective transformation of the given object. This is the accumulation of all transformations for one of two possible cases as described below.

In the first case, the accumulated transformation is from the <DRM Transmittal Root> down to the object, including any transformation components directly aggregated by that object. If object, or any of the objects between it and its <DRM Transmittal Root>, are referenced as a component from another transmittal and that transmittal is open, the accumulation is from the other transmittal’s <DRM Transmittal Root>. Otherwise, the accumulation is from the <DRM Transmittal Root> within object’s own transmittal.

In the second case, the accumulated transformation is from the <DRM Model> down to the object, including any transformation components directly aggregated by that object depending on whether the object was or was not part of a <DRM Model>.

If no matrices were accumulated by the object, the identity matrix shall be returned.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and the current effective transformation of object is returned in matrix, if valid parameters were passed in.

When this function completes in error, one of the following actions occurs:

• Current status code is set to DELETED_OBJECT and no changes are made if object has been removed from the transmittal in which it resided.
• Current status code is set to UNRESOLVED_INPUT_OBJECT and no changes are made if object is unresolved.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. object is not a valid handle to a DRM object;
  2. matrix is invalid; or
  3. the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

DELETED_OBJECT
UNRESOLVED_INPUT_OBJECT
INACTIONABLE_FAILURE

Semantics

Given a <DRM_Data_Table> instance specified by data_table_object, this function copies the selected cell elements from the selected area of interest into a space in memory to which the user has direct access.

The range of data cells to be retrieved is specified by extents. The number of data elements within each cell that are to be retrieved is specified by element_count. The component index of each of the data elements is specified by element_indices.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and and the requested data is returned, if valid parameters were passed in.

When this function completes in error, one of the following actions occurs:

• Current status code is set to UNRESOLVED_INPUT_OBJECT and no changes are made if data_table_object is a handle to an unresolved object.
• Current status code is set to DELETED_OBJECT and no changes are made if data_table_object is a handle to an object that had been removed from the transmittal in which it resided.
• Current status code is set to OUT_OF_MEMORY and no changes are made if the implementation was not able to allocate enough memory to return the data.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if the function failed for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
DELETED_OBJECT
OUT_OF_MEMORY
INACTIONABLE_FAILURE

Semantics

This function identifies the DRM class of the object specified by the object parameter.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and object_type is set appropriately if valid parameters were passed in.

When this function completes in error, one of the following actions occurs:

• Current status code is set to UNRESOLVED_INPUT_OBJECT and no changes are made if object is unresolved.
• Current status code is set to DELETED_OBJECT and no changes are made to the output parameter if object is a handle to an object that had been removed from the transmittal in which it resided.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. object is not a valid handle to a DRM object;
  2. object_type is not valid; or
  3. the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

DELETED_OBJECT
UNRESOLVED_INPUT_OBJECT
INACTIONABLE_FAILURE

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and the encoding is returned if valid parameters were passed in.

When this function completes in error, one of the following actions occurs:

• Current status code is set to UNRESOLVED_INPUT_OBJECT and no changes are made if object is an unresolved object.
• Current status code is set to DELETED_OBJECT and no changes are made if object is a handle to an object that has been removed from the transmittal in which it resided.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. object is not a valid handle to a DRM object;
  2. encoding is invalid; or
  3. the function fails for any other reason.

SUCCESS

Semantics

This function retrieves the field data of the DRM object specified by object. The DRM_Class_Fields data type is a variant record type that can represent any of the different collections of field data types from all of the different concrete DRM classes. The field values returned by the fields parameter are only valid as long as the object is valid. When the object is freed (by a call to 7.3.11 FreeObject), the information returned by the fields parameter is no longer valid.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and the fields of the specified object are returned in fields if valid parameters were passed in and all operations succeeded.

When this function completes in error, one of the following actions occurs:

• Current status code is set to UNRESOLVED_INPUT_OBJECT and no changes are made if object is an unresolved object.
• Current status code is set to DELETED_OBJECT and no changes are made if object is a handle to an object that had been removed from the transmittal in which it resided.
• Current status code is set to OUT_OF_MEMORY and no changes are made if the implementation is unable to allocate sufficient memory.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if object is not a valid handle to a DRM object or the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
DELETED_OBJECT
OUT_OF_MEMORY
INACTIONABLE_FAILURE

Semantics

This function accesses a subset of the data for a selected MIP level of the image data associated with the image specified by image_object and returns the texel data in image_data.

A <DRM Image> instance is a set of 2D or 3D collections of texel values. The number of MIP levels for the <DRM Image> instance defines the number of 2D or 3D collections in the <DRM Image> instance.

The fields of the <DRM Image> instance specify the extents for each MIP level and therefore also the number of texels in each MIP level. The image_signature field specifies the meaning and form of the texel components that constitute each texel. Also for each image signature there are fields that specify the number of bits, minimum value, and maximum value for each of the texel components defined to be part of that image signature.

The mip level to be accessed is specified by mip_level. The subset of texels to be retrieved is specified by start_texel and stop_texel.

The one-dimensional octet array field of the instance of the Image_Data specified by image_data will contain the retrieved two or three-dimensional texel data. The texel values are stored in order one after the other across octet boundaries by fields of the <DRM Image> specified by image_object that define the encoding of the texel component values. These fields are data_is_little_endian, component_data_type and the appropriate bits_of_ fields as specified by the image_signature field.

The ordering of the texels is specified by the scan_direction and scan_direction_z (see 5.2.6.10 Image_Scan_Direction and 5.2.6.11 Image_Scan_Direction_Z). The scan_direction field has a value that determines not only the direction of the individual horizontal and vertical values but also the ordering of the dimensions.

EXAMPLE  a scan_direction specifying a value of RIGHT_DOWN indicates that the horizontal values are stored first (that is, vertical values vary more rapidly) while a scan_direction specifying a value of DOWN_RIGHT indicates that the vertical values are stored first.

In all cases the z values are stored last so that z values will vary the most rapidly.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and the requested data is returned in data, if valid parameters were passed in and all operations succeeded.

When this function completes in error, one of the following actions occurs:

• Current status code is set to UNRESOLVED_INPUT_OBJECT and no changes are made if image_object is an unresolved object.
• Current status code is set to DELETED_OBJECT and no changes are made if image_object is a handle to an object that has been removed from the transmittal in which it resided.
• Current status code is set to OUT_OF_MEMORY and no changes are made if the implementation was unable to allocate sufficient memory.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. image_object is not a valid handle to a <DRM Image> object;
  2. no image data has yet been specified for the <DRM Image> object specified by image_object.
  3. any of the start or stop texels are invalid for the image;
  4. mip_level invalid for the image;
  5. level_count of image is zero or its mip_fields_array is empty;
  6. image_data is invalid; or
  7. the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
DELETED_OBJECT
OUT_OF_MEMORY
INACTIONABLE_FAILURE

Semantics

This function returns the number of objects remaining for the given iterator.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and the number of objects left to be returned by the iterator is returned in count if all parameters are valid.

When this function completes in error, one of the following actions occurs:

• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. iterator is invalid;
  2. count is invalid; or
  3. the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

INACTIONABLE_FAILURE

Semantics

This function returns the status and description of the result of the last function call.

The last_function_status field eturns the status of the last function call. The status_description parameter will contain information about the status code returned in last_function_status.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and last_function_status and status_description are set appropriately.

When this function completes in error, the following action occurs:

• Current status code is set to INACTIONABLE_FAILURE when any error occurs and no changes are made. The current error description shall be set to a value that reflects the reason why this function failed.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

INACTIONABLE_FAILURE

In addition, if get_adjacent_face_table_data has value TRUE, the adjacent_face_table_data parameter returns the adjacent face information from the adjacent face table for the selected faces. If get_adjacent_face_table_data has value FALSE, the adjacent_face_table_data parameter is not modified.

The array dimension specified by maximum_vertices_per_face is obtained from that field of mesh_face_table_object.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and and the requested data is returned, if valid parameters were provided.

When this function completes in error, one of the following actions occurs:

• Current status code is set to UNRESOLVED_INPUT_OBJECT and no changes are made if mesh_face_table_object is a handle to an unresolved object.
• Current status code is set to DELETED_OBJECT and no changes are made if mesh_face_table_object is a handle to a DRM object that has been removed from the transmittal in which it resided.
• Current status code is set to OUT_OF_MEMORY and no changes are made if sufficient memory could not be allocated.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if the function failed for any other reason.

SUCCESS

Semantics

This function retrieves the next_object, and optionally the related link_class_object, from an iterator. The link_class_object shall be the link class object on the relationship traversed by the iterator to arrive at next_object. If no link class object existed on the relationship, link_class_object shall be set to NULL.

When this function completes successfully, one of the following actions occurs:

• Current status code is set to SUCCESS and next_object is set to point to the next object from the iterator if valid parameters were passed in and either no ITR references were encountered in searching for the next object, or the iterator is configured to ignore ITR references.
• Current status code is set to DIFFERENT_TRANSMITTAL and next_object returns the next object from the iterator if:
  1. valid parameters were passed in;
  2. the iterator is configured to automatically resolve ITR references;
  3. an ITR reference was encountered in searching for the next object; and
  4. the iterator successfully resolved it and continued to search in the new, different transmittal until the next object from the iterator was found.
• Current status code is set to UNRESOLVED_OUTPUT_OBJECT and next_object is set to point to an unresolved object from the iterator, if valid parameters were passed in and an ITR reference was encountered in searching for the next object while the iterator is configured to report ITR references

When this function completes in error, one of the following actions occurs:

• Current status code is set to UNRESOLVED_OUTPUT_OBJECT and no changes are made if valid parameters were passed in, an ITR reference was encountered, the iterator is configured to resolve ITR references, and the ITR reference was not resolved.
• Current status code is set to NO_OBJECT and no changes are made if the iterator has completed.
• Current status code is set to DELETED_OBJECT and no changes are made if the next object or the next link object have been removed from the transmittal in which they were stored.
• Current status code is set to OUT_OF_MEMORY and no changes are made if the implementation was unable to allocate sufficient memory.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. iterator is not a handle to an iterator;
  2. next_object is invalid;
  3. link_class_object is invalid; or
  4. the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS
DIFFERENT_TRANSMITTAL
UNRESOLVED_OUTPUT_OBJECT

Failure status codes

UNRESOLVED_OUTPUT_OBJECT
NO_OBJECT
DELETED_OBJECT
OUT_OF_MEMORY
INACTIONABLE_FAILURE

Semantics

Given an object that has multiple, ordered associates of a certain DRM class (from_object), this function returns an object for the n^th associate of that class in associate_object. ITR associates will be automatically resolved and, if an ITR associate is encountered that cannot be resolved, the function will return UNRESOLVED_OUTPUT_OBJECT for the n value passed in and any higher n values.

The DRM class is specified in desired_associate_class. The one-based associate index is specified in n.

The link_class_object output parameter returns the link class object on the relationship traversed to arrive at the object specified by associate_object. If no link class object exists on the relationship, link_class_object shall be set to NULL.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and the desired associate object is returned in associate_object and link_class_object is set appropriately if valid parameters were passed in and all operations succeeded.

When this function completes in error, one of the following actions occurs:

• Current status code is set to UNRESOLVED_INPUT_OBJECT and no changes are made if from_object is an unresolved DRM object.
• Current status code is set to UNRESOLVED_OUTPUT_OBJECT and no changes are made if an ITR reference was encountered that could not be resolved.
• Current status code is set to DELETED_OBJECT and no changes are made if:
  1. from_object is a handle to a DRM object that has been removed from the transmittal in which it resided;
  2. the associate object has been removed from the transmittal in which it resided; or
  3. the link class object for the associate object has been removed from the transmittal in which it resided.
• Current status code is set to NO_OBJECT and no changes are made if the from_object did not contain n associate objects of the desired class.
• Current status code is set to OUT_OF_MEMORY and no changes are made if sufficient memory could not be allocated.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. from_object is not a valid handle to a DRM object;
  2. an invalid value was supplied for desired_associate_class;
  3. associate_object or link_class_object is invalid;
  4. the given class of associate is not ordered for the given from_object; or
  5. the function failed for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
UNRESOLVED_OUTPUT_OBJECT
DELETED_OBJECT
NO_OBJECT
OUT_OF_MEMORY
INACTIONABLE_FAILURE

Semantics

Given an object that has multiple, ordered components of a certain DRM class (aggregate_object), returns an object for the n^th component of that class in component_object. ITR components will be automatically resolved and if an ITR component is encountered that cannot be resolved, the function will return UNRESOLVED_OUTPUT_OBJECT for the n value passed in and any higher n values.

The DRM class is specified in desired_component_class. The one-based associate index is specified in n.

The link_class_object output parameter returns the link class object on the relationship traversed to arrive at the object specified by component_object. If no link class object exists on the relationship, link_class_object shall be set to NULL.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and the n^th component object is returned in component_object  and link_class_object is set appropriately if valid parameters were passed in and all operations succeeded.

When this function completes in error, one of the following actions occurs:

• Current status code is set to UNRESOLVED_INPUT_OBJECT and no changes are made if component_object is an unresolved DRM object.
• Current status code is set to UNRESOLVED_OUTPUT_OBJECT and no changes are made if an ITR reference was encountered that could not be resolved.
• Current status code is set to DELETED_OBJECT and no changes are made if:
  1. aggregate_object is a handle to a DRM object that has been removed from the transmittal in which it resided;
  2. component_object has been removed from the transmittal in which it resided; or
  3. link_class_object for the associate object has been removed from the transmittal in which it resided.
• Current status code is set to NO_OBJECT and no changes are made if the aggregate object did not contain n component objects of the desired class.
• Current status code is set to OUT_OF_MEMORY and no changes are made if sufficient memory could not be allocated.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. aggregate_object is not a valid handle to a DRM object;
  2. an invalid value was supplied for desired_component_class; or
  3. the given class of component is not ordered for the given aggregate_object;
  4. either component_object or link_class_object is invalid; or
  5. the function failed for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
UNRESOLVED_OUTPUT_OBJECT
DELETED_OBJECT
NO_OBJECT
OUT_OF_MEMORY
INACTIONABLE_FAILURE

Semantics

This function determines how many different paths can be traversed from the <DRM Transmittal Root> instance to the DRM object specified by object, where a path is defined as a bi-directional aggregate to component relationship. The result of this determination is returned in number_of_paths.

If object, or any of the objects between it and its <DRM Transmittal Root> instance, are referenced as a component from another transmittal and that transmittal is open, the paths counted are those to the other transmittal’s <DRM Transmittal Root> instance. Otherwise, the paths are to the <DRM Transmittal Root> instance within the transmittal containing object.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and number_of_paths is set appropriately if valid parameters were passed in.

When this function completes in error, one of the following actions occurs:

• Current status code is set to UNRESOLVED_INPUT_OBJECT and no changes are made if object is unresolved.
• Current status code is set to UNRESOLVED_OUTPUT_OBJECT and no changes are made if an ITR reference was encountered that could not be resolved.
• Current status code is set to DELETED_OBJECT and no changes are made if:
  1. object is a handle to a DRM object that has been removed from the transmittal in which it resided; or
  2. while calculating number_of_paths, a DRM object is encountered that has been deleted from the transmittal in which it resided.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if object is not a valid handle to a DRM object or the function failed for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
UNRESOLVED_OUTPUT_OBJECT
DELETED_OBJECT
INACTIONABLE_FAILURE

Semantics

This function returns the DRM object within the transmittal specified by transmittal that corresponds to the ID string specified by id.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and all actions succeeded if valid parameters were passed in and all operations succeeded.

When this function completes in error, one of the following actions occurs:

• Current status code is set to DELETED_OBJECT and no changes are made if the DRM object corresponding to id has been removed from transmittal.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. transmittal is invalid;
  2. object is invalid; or
  3. the function failed for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

DELETED_OBJECT
INACTIONABLE_FAILURE

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and a string corresponding to the given object will be returned in id, if valid parameters were passed in and all operations succeeded.

When this function completes in error, one of the following actions occurs:

• Current status code is set to UNRESOLVED_INPUT_OBJECT and no changes are made if object is an unresolved object.
• Current status code is set to DELETED_OBJECT and no changes are made if object has been removed from the transmittal in which it resided.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. object is not a valid handle to a DRM object;
  2. id is invalid; or
  3. the function failed for any other reason.

SUCCESS

Semantics

This function returns in reference_count the number of currently outstanding handles for the DRM object specified by object. Multiple handles (multiple variables of type Object) to the same object may exist by having the same object returned from multiple iterators or from multiple calls to other functions that return the type Object. An object is termed active while at least one handle to the object exists. That is, an object is active until 7.3.14 FreeObject is called for as many handles as were returned  for that object from other API functions.

This function can be used to determine if a handle to an object has already been returned from any of the API calls that return object handles (e.g., 7.3.31 GetNextObject and  7.3.33 GetNthComponent). This function can also assist with the 7.3.83 SetUserData and 7.3.53 GetUserData functions. See those function descriptions for details.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and reference_count is set appropriately if valid parameters were passed in.

When this function completes in error, one of the following actions occurs:

• Current status code is set to UNRESOLVED_INPUT_OBJECT and no changes are made if object is an unresolved object.
• Current status code is set to DELETED_OBJECT and no changes are made if object has been removed from the transmittal in which it resided.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. object is not a valid handle to a DRM object;
  2. reference_count is invalid; or
  3. the function failed for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
DELETED_OBJECT
INACTIONABLE_FAILURE

Semantics

This function retrieves a sub-hierarchy rooted at a given object into a set of data structures that can be directly traversed by the calling application. This sub-hierarchy is returned in hierarchy.

If the directly_attach_table_components parameter has the value FALSE, the actual DRM objects will be referenced in the packed hierarchy. However, if the value is TRUE, the following adjustments to the packed hierarchy will be made:

1. If a <DRM Property Set Index> object would otherwise be returned, the <DRM Property Set Index> object shall be automatically replaced by the corresponding objects referenced by the primary (that is,  the 1st) <DRM Property Set> object of the referenced <DRM Property Set Table Group> object.
2. If a <DRM Colour Index> object would otherwise be returned, the <DRM Colour Index> object shall be replaced by a <DRM Inline Colour> object containing the same <DRM Primitive Colour> object as the <DRM Primitive Colour> object that would have been referenced by the <DRM Colour Index> object (through the default <DRM Colour Table> object of the associated <DRM Colour Table Group> object).

If the process_inheritence parameter has value TRUE, inherited components shall be provided in the packed hierarchy.

If the hierarchy_depth parameter is specified, the packed hierarchy will only contain objects to the hierarchy_depth level. A value of 1 specifies only the components of the root_object are to be provided, while a value of 0 specifies that the entire sub-hierarchy is to be returned.

The itr_traversal parameter specifies how to handle ITR references. If RESOLVE is specified, the ITR references will be resolved and the objects they reference will be placed in the packed hierarchy. If REPORT is specified, the ITR references will not be resolved, but unresolved objects will be placed in the packed hierarchy. If IGNORE is specified, the ITR references will not be resolved and the objects they reference will not be placed in the packed hierarchy.

When this function completes successfully,  one of the following actions occurs:

• Current status code is set to SUCCESS and the packed hierarchy is returned in hierarchy if valid parameters were passed in.
• Current status code is set to DIFFERENT_TRANSMITTAL and the packed hierarchy is returned in hierarchy if valid parameters were passed in but one or more objects encountered were contained in a different transmittal from root_object and itr_traversal was specified as RESOLVE.
• Current status code is set to UNRESOLVED_OUTPUT_OBJECT and the packed hierarchy is returned in hierarchy if valid parameters were passed in but one or more objects encountered were contained in a different transmittal from root_object and itr_traversal was specified as REPORT. In this case, the object_is_resolved field is set to FALSE in the hierarchy data structure for those objects that are unresolved.

When this function completes in error, one of the following actions occurs:

• Current status code is set to UNRESOLVED_INPUT_OBJECT and no changes are made if root_object is unresolved.
• Current status code is set to UNRESOLVED_OUTPUT_OBJECT and no changes are made if one or more objects encountered were not resolved.
• Current status code is set to DELETED_OBJECT and no changes are made if:
  1. root_object is a handle to an object that has been removed from the transmittal in which it resided.
  2. any object encountered in the packed hierarchy has been removed from the transmittal in which the object resided.
• Current status code is set to OUT_OF_MEMORY and no changes are made if the implementation is unable to allocate sufficient memory.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. root_object is not a valid handle to a DRM object;
  2. itr_traversal does not contain a valid value; or
  3. the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS
DIFFERENT_TRANSMITTAL
UNRESOLVED_OUTPUT_OBJECT

Failure status codes

UNRESOLVED_INPUT_OBJECT
UNRESOLVED_OUTPUT_OBJECT
DELETED_OBJECT
OUT_OF_MEMORY
INACTIONABLE_FAILURE

Semantics

Given the DRM object specified by object, this function returns in the output parameters the labels under which the object was published.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and the output parameters are set appropriately if valid parameters were passed in and all operations succeeded.

When this function completes in error, one of the following actions occurs:

• Current status code is set to UNRESOLVED_INPUT_OBJECT and no changes are made if object is not a resolved object.
• Current status code is set to UNPUBLISHED_OBJECT and no changes are made if object is not a published object.
• Current status code is set to DELETED_OBJECT and no changes are made if: object is a handle to an object that has been removed from the transmittal in which it resided.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. object is not a valid handle to a DRM object;
  2. either label_list or number_labels is invalid; or
  3. the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_OUTPUT_OBJECT
UNPUBLISHED_OBJECT
DELETED_OBJECT
INACTIONABLE_FAILURE

Semantics

Given the transmittal specified by transmittal, this function returns in the output parameters a list of objects published by that transmittal for possible reference using ITR.

The number of published objects in published_object_list is returned in number_published_objects.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and all actions succeeded if valid parameters were passed in and published_object_list was successfully returned.

When this function completes in error, one of the following actions occurs:

• Current status code is set to OUT_OF_MEMORY and no changes are made if sufficient memory could not be allocated.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. transmittal is not a valid handle to a transmittal;
  2. number_published_objects or published_object_list is invalid; or
  3. the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

OUT_OF_MEMORY
INACTIONABLE_FAILURE

Semantics

Given the transmittal specified by transmittal, this function returns in the output parameters the list of other transmittals that are referenced by this transmittal using Inter-Transmittal Referencing (ITR). The names returned are formal SEDRIS transmittal names used to create the ITR references. If this transmittal contains no ITR references, an empty list is returned. The number of transmittal names being returned in transmittal_name_list is returned in transmittal_name_count.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and the output parameters are set appropriately, if valid parameters were passed in and all operations succeeded.

When this function completes in error, one of the following actions occurs:

• Current status code is set to OUT_OF_MEMORY and no changes are made if sufficient memory could not be allocated.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. transmittal is not a valid handle to a transmittal;
  2. transmittal_name_count or transmittal_name_list is invalid; or
  3. the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

OUT_OF_MEMORY
INACTIONABLE_FAILURE

Semantics

Given the DRM object specified by object, this function returns the counts of

1. the number of components (in component_count),

2. the number of aggregates (in aggregate_count), and

3. the number of associates (in associate_count)

that the specified object has.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and the output parameters are set to the values of the requested counts.

When this function completes in error, one of the following actions occurs:

• Current status code is set to UNRESOLVED_INPUT_OBJECT and no changes are made if object is a handle to an unresolved object.
• Current status code is set to DELETED_OBJECT and no changes are made if object is a handle to an object that has been removed from the transmittal in which it resided.
• Current status code is set to INACTIONABLE_FAILURE if the function failed for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
DELETED_OBJECT
INACTIONABLE_FAILURE

Semantics

This function iterates over the remaining objects available through the iterator specified by iterator, returning all of the remaining objects at one time. Following this call, the iterator is left such that no more objects will be returned by the iterator.

The number_of_objects field of the output parameter is set to the number of objects remaining on the iterator prior to the call, and is the number of items in each of the other array fields in the output record. The n^th entry in the remaining_objects_list and remaining_link_objects_list arrays correspond to the n^th object returned by the iterator and its related link class object, if one exists. The n^th entry in object_status_list and link_object_status_list arrays correspond to the status codes indicating the results of the object retrieval for the n^th object.

When this function completes successfully, one of the following actions occurs:

• Current status code is set to SUCCESS and all remaining objects are returned in remaining_objects if valid parameters were passed in.
• Current status code is set to DIFFERENT_TRANSMITTAL and all remaining objects are returned in remaining_objects if valid parameters were passed in but one or more objects encountered were contained in different transmittals from the iterator’s start_object.
• Current status code is set to UNRESOLVED_OUTPUT_OBJECT and all remaining objects are returned in remaining_objects if valid parameters were passed in but one or more objects encountered were not resolved.

When this function completes in error, one of the following actions occurs:

• Current status code is set to UNRESOLVED_OUTPUT_OBJECT and no changes are made if valid parameters were passed, an ITR reference was encountered, the iterator is configured to resolve ITR references, and the ITR reference was not resolved.
• Current status code is set to DELETED_OBJECT and no changes are made if an object have been removed from the transmittal in which they were stored.
• Current status code is set to NO_OBJECT and no changes are made if the iterator is out of objects to return.
• Current status code is set to OUT_OF_MEMORY and no changes are made if sufficient memory could not be allocated.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. iterator is invalid;
  2. remaining_objects is invalid; or
  3. this function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS
DIFFERENT_TRANSMITTAL
UNRESOLVED_OUTPUT_OBJECT

Failure status codes

UNRESOLVED_OUTPUT_OBJECT
DELETED_OBJECT
NO_OBJECT
OUT_OF_MEMORY
INACTIONABLE_FAILURE

Semantics

This function iterates over the remaining objects available through the iterator specified by iterator and returns packed hierarchies for all of them at one time. The number of remaining packed hierarchies and each packed hierarchy are returned in remaining_hierarchies, whose data type, Remaining_Packed_Hierarchies_List is defined in 5.3.3.225 Remaining_Packed_Hierarchies_List.

The hierarchy_depth parameter specifies the depth to which the sub-hierarchy of each remaining object is extracted below that object. A value of one indicates that only the components of each remaining object are to be returned. A value of zero indicates that the entire sub-hierarchy of each remaining object is to be returned.

When this function completes successfully, one of the following actions occurs:

• Current status code is set to SUCCESS and remaining_hierarchies returns the remaining hierarchy list data if valid parameters were passed in.
• Current status code is set to DIFFERENT_TRANSMITTAL and remaining_hierarchies returns the remaining hierarchy list data if valid parameters were passed in but one or more objects encountered were contained in different transmittals than the iterator’s start_object.
• Current status code is set to UNRESOLVED_OUTPUT_OBJECT and remaining_hierarchies returns the remaining hierarchy list data if valid parameters were passed in, objects were left that have not yet been returned, and one or more objects encountered were not resolved. In this case, the object_is_resolved field is set to FALSE in each of the Packed_Hierarchy data structures for those objects that are unresolved.

When this function completes in error, one of the following actions occurs:

• Current status code is set to UNRESOLVED_OUTPUT_OBJECT and no changes are made if valid parameters were passed, an ITR reference was encountered, the iterator is configured to resolve ITR references, and the ITR reference was not resolved.
• Current status code is set to DELETED_OBJECT and no changes are made if an object is encountered that has been removed from the transmittal in which it resided.
• Current status code is set to NO_OBJECT and no changes are made if the iterator is out of objects to return.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. iterator is invalid;
  2. remaining_hierarchies is invalid; or
  3. the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS
DIFFERENT_TRANSMITTAL
UNRESOLVED_OUTPUT_OBJECT

Failure status codes

UNRESOLVED_OUTPUT_OBJECT
DELETED_OBJECT
NO_OBJECT
INACTIONABLE_FAILURE

Semantics

Given the transmittal specified by transmittal, this function returns in root_object the DRM object that has been stored as the root of the transmittal object hierarchy.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and all actions succeeded if valid parameters were passed in and the root object was successfully returned.

When this function completes in error, one of the following actions occurs:

• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. transmittal is not a valid handle to a transmittal;
  2. root_object is invalid;
  3. the transmittal does not have a root object; or
  4. the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

INACTIONABLE_FAILURE

Semantics

This function returns in srf_info the spatial reference frame (SRF) parameters currently being used when returning <DRM Location> objects in the same SRF scope as the DRM object specified by object.

More details are available under 7.3.81 SetSRFInfo.

The answer depends on the last call made to 7.3.81 SetSRFInfo and/or 7.3.87 UseDefaultSRFInfo and the manner in which the transmittal was produced.

Case 1: 7.3.81 SetSRFInfo was called more recently than 7.3.87 UseDefaultSRFInfo. The SRF defined by 7.3.81 SetSRFInfo is still the current retrieval SRF, and that SRF’s information will be returned by this function. It does not matter what SRF was used to originally produce the given transmittal, since the 7.3.81 SetSRFInfo function was used to override any default SRF choices and force all <DRM Location> objects to be of the type specified by the current retrieval SRF.

Case 2: 7.3.87 UseDefaultSRFInfo was called more recently than 7.3.81 SetSRFInfo, or 7.3.81 SetSRFInfo was never called. In this case, the retrieval SRF that will be used to define <DRM Location> objects from the given transmittal depends entirely on the transmittal. The retrieval SRF used to return data will be the retrieval SRF that was used when producing the transmittal. This is the default case. If the supplied object does not fall within the scope of any SRF, the SRF info is undefined and GetSRFInfo will return INACTIONABLE_FAILURE.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and the scoping SRF parameters are returned in srf_info if valid parameters were passed in.

When this function completes in error, one of the following actions occurs:

• Current status code is set to UNRESOLVED_INPUT_OBJECT and no changes are made if object is an unresolved object.
• Current status code is set to DELETED_OBJECT and no changes are made if the object has been removed from the transmittal in which it resided.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. object is not a valid handle to a DRM object;
  2. the specified object has no scoping SRF;
  3. 7.3.98 UseDefaultSRFInfo was called more recently than 7.3.92 SetSRFInfo or 7.3.92 SetSRFInfo was never called; or
  4. the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
DELETED_OBJECT
INACTIONABLE_FAILURE

Semantics

Given the DRM object specified by object, this function returns in transmittal a handle to the transmittal containing the DRM object.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and a handle to the transmittal containing the object is returned if valid parameters were passed in and all operations succeeded.

When this function completes in error, one of the following actions occurs:

• Current status code is set to UNRESOLVED_INPUT_OBJECT and no changes are made if object is unresolved.
• Current status code is set to DELETED_OBJECT and no changes are made if object has been removed from the transmittal in which it resided.
• Current status code is set to OUT_OF_MEMORY and no changes are made if sufficient memory could not be allocated.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. object is not a valid handle to a DRM object;
  2. transmittal is invalid; or
  3. the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
DELETED_OBJECT
OUT_OF_MEMORY
INACTIONABLE_FAILURE

Semantics

Given the handle to the transmittal specified in transmittal, this function returns in location the URL specifying the location of the transmittal.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and the location from which the transmittal was opened is returned if valid parameters were passed in.

When this function completes in error, one of the following actions occurs:

• Current status code is set to OUT_OF_MEMORY and no changes are made if sufficient memory could not be allocated.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. transmittal is not a valid handle to an open transmittal;
  2. location is invalid; or
  3. the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

OUT_OF_MEMORY
INACTIONABLE_FAILURE

Semantics

Given the handle to a transmittal specified in transmittal, this function returns in name the formal transmittal name associated with the transmittal in the form of a URN.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and the transmittal name is returned in name if valid parameters were passed in.

When this function completes in error, one of the following actions occurs:

• Current status code is set to OUT_OF_MEMORY and no changes are made if sufficient memory could not be allocated.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. transmittal is not a valid to an open transmittal;
  2. name is invalid; or
  3. the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

OUT_OF_MEMORY
INACTIONABLE_FAILURE

Semantics

This function returns the version of the Data Representation Model, Environmental Data Coding Specification, and Spatial Reference Model used to define the given transmittal.

Major versions are specified by an integer that is incremented whenever large changes are made to the specification.

Minor version are specified by an integer that is incremented whenever any small changes are made to the specification.

Interim version are specified using a lower case letter which is incremented whenever a new interim version of the specification is released.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and the output parameters are set appropriately if valid parameters were passed in and all operations succeeded.

When this function completes in error, one of the following actions occurs:

• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. transmittal is not a valid handle to an open transmittal;
  2. any output parameter is invalid; or
  3. the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

INACTIONABLE_FAILURE

Semantics

Given the handle to a transmittal specified in transmittal, this function returns in identifier a string identifier for the associated transmittal that can then be compared with identifiers from other transmittals.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and identifier is set appropriately if valid parameters were passed in and all operations succeeded.

When this function completes in error, one of the following actions occurs:

• Current status code is set to OUT_OF_MEMORY and no changes are made if sufficient memory could not be allocated.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. transmittal is not a valid open transmittal;
  2. identifier is not valid; or
  3. the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

OUT_OF_MEMORY
INACTIONABLE_FAILURE

Semantics

This function creates an unresolved reference to an object based on the combination of transmittal_name and object_label as supported in the specified encoding.

This function does not validate the reference to ensure that it can be resolved. This behaviour is intentional in order to allow referencing well-known published objects, without requiring the transmittal containing the object to be accessible. The 7.3.72 ResolveObject function is available to do this, but requires that the referenced transmittal be accessible.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and produces the requested handle in object if valid parameters were passed in and all operations succeeded.

When this function completes in error, one of the following actions occurs:

• Current status code is set to INVALID_TRANSMITTAL_NAME and no changes are made if the transmittal URN is not valid according to the SEDRIS URN syntax rules (see 2.[RFCxxxx]).
• Current status code is set to INVALID_OBJECT_LABEL and no changes are made if object_label is not valid according to the label syntax rules.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

INVALID_TRANSMITTAL_NAME
INVALID_OBJECT_LABEL
INACTIONABLE_FAILURE

Semantics

This function returns in user_data, user data associated with the DRM object specified by object. This is data previously set with a call to 7.3.83 SetUserData on an active handle to this object. If 7.3.83 SetUserData has not been called, NULL shall be returned. Memory management of the user data is the responsibility of the application.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and user_data is set appropriately, if valid parameters were passed in and all operations succeeded.

When this function completes in error, one of the following actions occurs:

• Current status code is set to UNRESOLVED_INPUT_OBJECT and no changes are made if object is not a currently resolved object.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. object is not a valid handle to a DRM object;
  2. user_data is not valid; or
  3. the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
INACTIONABLE_FAILURE

Semantics

This function returns a handle in iterator for an iterator created to traverse over the list of aggregate objects returning handles to those that meet the following conditions:

1. The aggregate objects contain the start_object as an immediate component (a component that is exactly one link away) via a two-way aggregation relationship.

2. The aggregate objects satisfy the rules specified in the search filter specified by filter, if a search filter is defined for the iterator. If no search filter is specified (a search filter handle with value zero is provided), no filtering is applied, and only condition a need be satisfied.

The 7.3.31 GetNextObject function is provided to get the next object from an iterator.

The 7.3.28 GetIterationLengthRemaining may be invoked to find out the remaining length of an iterator (i.e., the number of objects remaining inside the iterator).

The 7.3.10 FreeIterator function should be invoked when finished with an iterator to free it. Iterators can be freed at any time (e.g., iterators can be freed before all of their objects have been returned).

The itr_traversal parameter specifies how aggregates referenced through ITR are to be treated.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and a handle for the newly created aggregate iterator is returned in iterator, if valid parameters were passed in and all operations succeeded.

When this function completes in error, one of the following actions occurs:

• Current status code is set to UNRESOLVED_INPUT_OBJECT and no changes are made if start_object is unresolved.
• Current status code is set to DELETED_OBJECT and no changes are made if start_object has been removed from the transmittal it in which it resided.
• Current status code is set to OUT_OF_MEMORY and no changes are made if sufficient memory could not be allocated.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. start_object is not a valid handle to a DRM object;
  2. a search filter is provided, but is not a handle to a valid, active (i.e., unfreed) search filter;
  3. itr_traversal is not valid;
  4. iterator is not valid; or
  5. the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
DELETED_OBJECT
OUT_OF_MEMORY
INACTIONABLE_FAILURE

Semantics

This function returns a handle in iterator for an iterator created to traverse over the list of associate objects returning handles to those that meet the following conditions:

1. They are associated to the start_object as an immediate associate (an associate that is exactly one link away) via either a two-way association, or via a one-way association from the start_object to the associated object. If an object is associated to the start_object via a one-way association from the associated object to the start_object, the associated object will not be included in the list of objects returned by this iterator since, if it is a one-way association into the start_object, the start_object, by definition, does not know which objects are at the other end of the one-way associations.
2. They satisfy the rules specified in the search filter specified by filter, if a search filter is defined for the iterator. If no search filter is specified (a search filter handle with value zero is provided), no filtering is applied, and only condition a) need be satisfied.

If start_object is associated solely by one-way incoming associations, or if start_object does not participate in any associations, an associate iterator for that start_object shall not return any objects. An associate iterator is created, but it has a length of zero and does not return any objects.

The 7.3.31 GetNextObject function is used to get the next object from an iterator.

The 7.3.28 GetIterationLengthRemaining function is used to determine the remaining length of an iterator (i.e., the number of objects remaining inside the iterator).

The 7.3.10 FreeIterator function should be invoked when interaction with an iterator has been completed to free it. Iterators can be freed at any time (e.g., before all of their objects have been returned).

The itr_traversal parameter specifies how aggregates referenced through ITR are to be treated.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and a handle for the newly created associate iterator returned in iterator if valid parameters were passed in.

When this function completes in error, one of the following actions occurs:

• Current status code is set to UNRESOLVED_INPUT_OBJECT and no chnages are made if start_object is unresolved.
• Current status code is set to DELETED_OBJECT and no changes are made if start_object has been removed from the transmittal it in which it resided.
• Current status code is set to OUT_OF_MEMORY and no changes are made if sufficient memory could not be allocated.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. start_object is not a valid handle to a DRM object;
  2. a search filter is provided, but is not a handle to a valid, active (i.e., unfreed) search filter;
  3. itr_traversal is not valid;
  4. iterator is not valid; or
  5. the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
DELETED_OBJECT
OUT_OF_MEMORY
INACTIONABLE_FAILURE

Semantics

This function returns a handle in iterator for an iterator created to traverse over the list of component objects returning handles to those that meet the user-specified conditions. This iterator starts at the top of an aggregation tree. The start_object is considered the root of the tree. All of the components below the start_object will be searched, and the components of those components will be searched, and their components will be searched as  many levels down as the search filter specifies. If the search filter does not limit the depth of the search with a maximum search depth rule, the iterator shall search until it has tested every object in the aggregation tree rooted by the start_object.

Objects returned by a component iterator shall meet the following conditions:

1. They are components, either directly or transitively, of the start_object. That is, they are contained within the aggregation tree that is rooted at the start_object.

2. They satisfy the rules specified in the search filter, if a search filter is defined for the iterator. If no search filter is provided, no filtering is applied, and only conditions a) and c) need be satisfied. A search filter can include a maximum search depth restriction. If such a restriction is applied, the sub-tree rooted at the start_object shall only be searched until that maximum search depth has been reached. Components beyond that depth shall not be searched.

3. They fall within the bounds of the spatial search boundary as dictated by the inclusion rules specified for that spatial search boundary.If no spatial search boundary is specified, no location-based filtering shall be applied, and only conditions a) and b) need be satisfied.

If start_object does not contain any component objects (or it contains component objects, but none of the components within the specified search depth meet the search filter and/or spatial search boundary conditions), a component iterator for that start_object, search filter, and spatial search boundary will not return any objects. A component iterator is created, but it has a length of zero and does not return any objects.

The 7.3.31 GetNextObject function is used to get the next object from an iterator.

The 7.3.28 GetIterationLengthRemaining function can be used to determine the remaining length of an iterator (i.e., the number of objects remaining inside the iterator).

The 7.3.10 FreeIterator function shall be used when interaction with an iterator has been completed to free it. Iterators can be freed at any time (e.g., before all of their objects have been returned).

If the directly_attach_table_components parameter has the value FALSE, the actual SEDRIS objects can be examined by the consumer through the component iterators. However, if the value is TRUE, the component iterators shall automatically make the following adjustments to the object types returned through the API in the following special cases:

1. If a <DRM Property Set Index> object would otherwise be returned by the component iterator, the <DRM Property Set Index> object shall be automatically replaced by the corresponding objects referenced by the primary (1st) <DRM Property Set> instance of the referenced <DRM Property Set Table Group> instance.
2. If a <DRM Colour Index> object would otherwise be returned by the component  iterator, the <DRM Colour Index> object shall be replaced by an <DRM Inline Colour> instance containing the same <DRM Primitive Colour> instance as the <DRM Primitive Colour> instance that would have been referenced by the <DRM Colour Index> instance (through the default <DRM Colour Table> instance of the associated <DRM Colour Table Group> instance).

If the process_inheritence parameter has value TRUE, inherited components shall be inherited, and they shall appear as components of the appropriate objects. These inherited components are as valid as direct components, and they shall satisfy all matching criteria.

If the transform_locations parameter has value TRUE, all <DRM Location> objects shall be transformed according to the transformations (<DRM LSR Transformation> instances and/or <DRM World Transformation> instances) encountered by the iterator.

If the follow_model_instances parameter has value TRUE, the iterator shall search through the <DRM Geometry Model Instance> to <DRM Geometry Model> association as if it were an aggregation (that is, it will instance the model). The same logic applies to the <DRM Feature Model Instance> to <DRM Feature Model> association.

If the evaluate_static_control_links parameter has value TRUE, all expressions composed entirely of literals and functions that use only literals shall be evaluated, and their results shall replace the appropriate field values of their targeted controlled objects.

The select_parameters parameter is optional. If provided, it specifies the parameters that will be used to determine components to traverse when encountering a <DRM Aggregate Feature> or <DRM Aggregate Geometry> object.

The traversal_order_parameters parameter is optional. If provided, it specifies the parameters that will be used to determine what order to traverse the components when encountering an <DRM Aggregate Feature> or <DRM Aggregate Geometry> object.

The general_traversal_pattern parameter indicates whether the iterator should traverse the search space in a depth-first, breadth-first, or optimized order. The depth-first and breadth-first approaches allow for full transformation and inherited component information to be maintained at all times. The optimized approach can be faster, but there is no guarantee that any particular path was taken from the start_object to the returned objects, so it is possible for no context (an empty context) to be returned with the returned objects.

The itr_traversal parameter specifies how aggregates referenced through ITR are to be treated.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and iterator returns a handle for the newly created component iterator if valid parameters were passed in and all operations succeeded.

When this function completes in error, one of the following actions occurs:

• Current status code is set to UNRESOLVED_INPUT_OBJECT and no changes are made if start_object is unresolved.
• Current status code is set to DELETED_OBJECT and no changes are made if start_object has been removed from the transmittal in which it resided.
• Current status code is set to OUT_OF_MEMORY and no changes are made if sufficient memory could not be allocated.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. start_object is not a valid handle to a DRM object;
  2. a spatial search boundary is provided, but is not a legal, valid spatial search boundary for the scope of start_object;
  3. a search filter is provided, but is not a valid, active (i.e., unfreed) search filter;
  4. the start object, search filter, and/or spatial search boundary come from different transmittals;
  5. select_parameters are provided but are not valid;
  6. traversal order parameters are provided, but are not valid;
  7. general_traversal_pattern is not valid;
  8. itr_traversal is not valid;

  9. iterator is  not valid; or

  10. the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
DELETED_OBJECT
OUT_OF_MEMORY
INACTIONABLE_FAILURE

Semantics

This function returns a handle in iterator for an iterator created to traverse over the list of component objects returning handles to those that are inherited. This function should be used if only inherited components are to be identified.

The semantics of the input parameters are described in 7.3.56 InitializeComponentIterator.

If only directly aggregated components of an object are to be identified, the 7.3.56 InitializeComponentIterator function with the process_inheritance parameter set to FALSE should be used.

If both the inherited components and the directly aggregated components of an object are to be identified and it is not necessary to distinguish between the two sets), the 7.3.56 InitializeComponentIterator function with the process_inheritance parameter set to TRUE should be used.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and iterator returns a newly created inherited component iterator if valid parameters were passed in and all operations succeeded.

When this function completes in error, one of the following actions occurs:

• Current status code is set to UNRESOLVED_INPUT_OBJECT and no changes are made if start_object is unresolved.
• Current status code is set to DELETED_OBJECT and no changes are made if start_object has been removed from the transmittal it in which it resided.
• Current status code is set to OUT_OF_MEMORY and no changes are made if sufficient memory could not be allocated.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. start_object is not a valid handle to a DRM object;
  2. a search filter is provided, but is not a valid, active (i.e., unfreed) search filter;
  3. the start object and/or search filter come from different transmittals;
  4. itr_traversal is not valid;
  5. iterator is not valid; or
  6. the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
DELETED_OBJECT
OUT_OF_MEMORY
INACTIONABLE_FAILURE

Semantics

This function is used to determine whether the iterator specified by iterator has any more objects to return. If the iterator has no objects to return, result returns the value TRUE; otherwise, it returns the value FALSE.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and no error description is provided. If the function was able to determine that specified iterator is empty, the value TRUE is returned; otherwise the value FALSE is returned.

When this function completes in error, one of the following actions occurs:

• Current status code is set to INACTIONABLE_FAILURE and no changes are made if the function failed for any reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

INACTIONABLE_FAILURE

Semantics

Given a the DRM object specified by object, result returns the value TRUE if the DRM object has been published; otherwise, result returns FALSE;

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and result is set appropriately if valid parameters were passed in.

When this function completes in error, one of the following actions occurs:

• Current status code is set to UNRESOLVED_INPUT_OBJECT and no changes are made if object is not a resolved object.
• Current status code is set to DELETED_OBJECT and no changes are made if object has been removed from the transmittal in which it resided.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if object is not a valid handle to a DRM object or the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
DELETED_OBJECT
INACTIONABLE_FAILURE

Semantics

Given the DRM object specified by object, result returns the value TRUE if the object is resolved. Otherwise result returns FALSE.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and result is set to the result of the check if valid parameters were passed in and all operations succeeded.

When this function completes in error, one of the following actions occurs:

• Current status code is set to INACTIONABLE_FAILURE and no changes are made if object is not a valid handle to a DRM object or the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

INACTIONABLE_FAILURE

Semantics

This function determines if two object handles both refer to the same object. Given DRM object handles specified by object_1 and object_2, result returns TRUE if both handles refer to the same DRM object. Otherwise, result returns FALSE.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and result returns the result of the check if valid parameters were passed in and all operations succeeded.

When this function completes in error, one of the following actions occurs:

• Current status code is set to UNRESOLVED_INPUT_OBJECT and no changes are made if object_1 or object_2 is not a currently resolved object.
• Current status code is set to DELETED_OBJECT and no changes are made if object_1 and/or object_2 has been removed from the transmittal in which the removed object(s) resided.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. object_1 and/or object_2 is not a valid handle to a DRM object;
  2. result is not valid; or
  3. any implementation-specific error occurs.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
DELETED_OBJECT
INACTIONABLE_FAILURE

Semantics

This function opens a transmittal for access, based on the mode specified by access_mode. This function specifies the transmittal to be opened using the location of the file containing the transmittal and its objects. If this function is successful, transmittal returns a handle to the newly opened transmittal.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and transmittal returns the transmittal handle if valid parameters were passed in and the name was the name of a valid file that was able to be opened as a SEDRIS transmittal.

When this function completes in error, one of the following actions occurs:

• Current status code is set to TRANSMITTAL_INACCESSIBLE and no changes are made if the location was not accessible.
• Current status code is set to INVALID_ACCESS_MODE and no changes are made if the location was found but the security permissions of the underlying file system prohibit access to the file in the mode specified. This can occur if:
  1. the file was opened for read-only or update and the file did not exist, or
  2. the file location specified a non-local file and the API had no transport mechanism for accessing the remote file.
• Current status code is set to UNSUPPORTED_ENCODING and no changes are made if encoding or the default file extension specified a format that is not supported by the implementation.
• Current status code is set to OUT_OF_MEMORY and no changes are made if sufficient memory could not be allocated.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if transmittal is invalid or the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

TRANSMITTAL_INACCESSIBLE
INVALID_ACCESS_MODE
UNSUPPORTED_ENCODING
OUT_OF_MEMORY
INACTIONABLE_FAILURE

Semantics

This function opens a transmittal for access, based on the mode specified by access_mode. This function specifies the transmittal to be opened using the formal transmittal name of the transmittal. The formal name of the transmittal is resolved automatically based on the process described for the function 7.3.73 ResolveTransmittalName. If this function is successful, transmittal returns a handle to the newly opened transmittal.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and transmittal returns a handle to the newly opened transmittal if valid parameters were passed in and transmittal_name was a valid transmittal name that could be resolved and accessed.

When this function completes in error, one of the following actions occurs:

• Current status code is set to INVALID_TRANSMITTAL_NAME and no changes are made if transmittal_name did not specify a name that was valid according to the format of the SEDRIS namespace.
• Current status code is set to UNRESOLVED_TRANSMITTAL and no changes are made if transmittal_name could not be resolved to a file location.
• Current status code is set to TRANSMITTAL_INACCESSIBLE and no changes are made if the transmittal location was not accessible.
• Current status code is set to INVALID_ACCESS_MODE and no changes are made if:
  1. the resolved file location was found, but the security permissions of the underlying file system prohibited access to the file in the mode specified. This could occur if the access mode specified was create or update and the file was marked read-only, or if no access was permitted for the account running the application.
  2. if create or update mode was requested and the API implementation does not support the write capability.
• Current status code is set to UNSUPPORTED_ENCODING and no changes are made if the resolved transmittal_name referenced an encoding that is not supported by the implementation(s) of the linked to the application.
• Current status code is set to OUT_OF_MEMORY and no changes are made if sufficient memory could not be allocated.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if transmittal is invalid or the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

INVALID_TRANSMITTAL_NAME
UNRESOLVED_TRANSMITTAL
TRANSMITTAL_INACCESSIBLE
INVALID_ACCESS_MODE
UNSUPPORTED_ENCODING
OUT_OF_MEMORY
INACTIONABLE_FAILURE

Semantics

Given the resolved DRM object specified by object, this function makes the DRM object available for ITR referencing by listing it as published within the transmittal under the label specified by label. If the object has already been published with a different label, the new label is added to the list of labels for the object. If the object has already been published under the same label, the call shall return success and provide a string to be retrieved using 7.3.28 GetLastFunctionStatus.

The transmittal whose object is to be edited shall be explicitly opened in UPDATE or CREATE mode for this operation to succeed.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and object is successfully published.

When this function completes in error, one of the following actions occurs:

• Current status code is set to UNRESOLVED_INPUT_OBJECT and no changes are made if object is unresolved.
• Current status code is set to INVALID_OBJECT_LABEL and no changes are made if label does not adhere to the required conventions
• Current status code is set to INVALID_ACCESS_MODE and no changes are made if object belongs to a transmittal opened in read-only mode.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if object is not a valid handle to a DRM object or the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
INVALID_OBJECT_LABEL
INVALID_ACCESS_MODE
INACTIONABLE_FAILURE

Semantics

Given the <DRM_Data_Table> instance specified by data_table_object, this function inserts the elements specified by element_indices for the cells specified by extents into the transmittal. The number of cells to be modified is specified by element_indices. The actual cell data is specified by data_table_data.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS, the specified data is inserted into the transmittal and no error description is produced.

When this function completes in error, one of the following actions occurs:

• Current status code is set to UNRESOLVED_INPUT_OBJECT and no changes are made, if data_table_object is a handle to an unresolved object.
• Current status code is set to DELETED_OBJECT and no changes are made if data_table_object is a handle to an object that has been removed from its transmittal.
• Current status code is set to INVALID_ACCESS_MODE and no changes are made if the transmittal to which data_table_object belongs was opened in read-only mode.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
DELETED_OBJECT
INVALID_ACCESS_MODE
INACTIONABLE_FAILURE

Semantics

This function modifies the fields of the DRM object specified by  existing_object.

The transmittal whose object is to be edited shall be explicitly opened in UPDATE mode for this operation to succeed.

The function shall verify that new_fields contain valid data values compatible with the DRM class of existing_object.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and the fields of the given object are replaced with the given fields if valid parameters were passed in and all operations succeeded.

When this function completes in error, one of the following actions occurs:

• Current status code is set to UNRESOLVED_INPUT_OBJECT and no changes are made if existing_object is unresolved.
• Current status code is set to DELETED_OBJECT and no changes are made if existing_object has been removed from the transmittal in which it resided.
• Current status code is set to INVALID_ACCESS_MODE and no changes are made if existing_object belongs to a transmittal opened in read-only mode.
• Current status code is set to OUT_OF_MEMORY and no changes are made if sufficient memory for the new fields could not be allocated.
• Current status code is set to INACTIONABLE_FAILURE no changes are made if:
  1. existing_object is not a valid handle to a DRM object;
  2. the class of new_fields does not match the class of existing_object;
  3. new_fields contained invalid field values for the DRM class of existing_object; or
  4. the function fails for any other reason.

Input parameters

Input/output parameters

Output parameters

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_OUTPUT_OBJECT
INVALID_ACCESS_MODE
DELETED_OBJECT
OUT_OF_MEMORY
INACTIONABLE_FAILURE

Semantics

This function sets values for a subset of the data for a selected MIP level of the image data associated with the image specified by image_object.

A <DRM Image> instance is a set of 2D or 3D collections of texel values. The number of MIP levels for the <DRM Image> instance defines the number of 2D or 3D collections in the <DRM Image> instance.

The fields of the <DRM Image> instance specify the extents for each MIP level and therefore also the number of texels in each MIP level. The image_signature field specifies the meaning and form of the texel components that constitute each texel. Also for each image signature there are fields that specify the number of bits, minimum value, and maximum value for each of the texel components defined to be part of that image signature.

The mip level to be accessed is specified by mip_level. The subset of texels to be set is specified by start_texel and stop_texel.

The one-dimensional octet array field of the instance of the Image_Data specified by image_data shall contain the two or three-dimensional texel data to be set. The texel values shall be stored in order one after the other across octet boundaries by fields of the <DRM Image> specified by image_object that define the encoding of the texel component values. These fields are data_is_little_endian, component_data_type and the appropriate bits_of_ fields as specified by the image_signature field.

The ordering of the texels is specified by the scan_direction and scan_direction_z (see 5.2.6.10 Image_Scan_Direction and 5.2.6.11 Image_Scan_Direction_Z). The scan_direction field has a value that determines not only the direction of the individual horizontal and vertical values but also the ordering of the dimensions.

EXAMPLE  a scan_direction specifying a value of RIGHT_DOWN indicates that the horizontal values are stored first (that is, vertical values vary more rapidly) while a scan_direction specifying a value of DOWN_RIGHT indicates that the vertical values are stored first.

In all cases the z values are stored last so that z values will vary the most rapidly.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and the texels of image are created as specified if valid parameters were passed in and all operations succeeded.

When this function completes in error, one of the following actions occurs:

• Current status code is set to UNRESOLVED_INPUT_OBJECT and no changes are made if image_object is unresolved.
• Current status code is set to DELETED_OBJECT and no changes are made if image_object has been removed from the transmittal in which it resided.
• Current status code is set to INVALID_ACCESS_MODE and no changes are made if image_object belongs to a transmittal that was opened in read-only mode.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. image_object does not belong to an open transmittal;
  2. mip_level is out of range for the image’s level_count;
  3. the image’s mip_extents_array is invalid;
  4. the start and stop extents are out of range for the specified mip_level, or stop greater than start for any of the extents; or
  5. a partial image is specified;
  6. image_data is invalid; or
  7. the function fails for any other reason.

Input parameters

Input/output parameters