8 Application program interface (API)

Semantics

A specification of the operation of the function.

Input parameters

Input/output parameters

Output parameters

Success status codes

A list of success status codes that may apply when this function terminates.

Failure status codes

A list of failure status codes that may apply when this function terminates.

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 DRM object, or both shall be resolved DRM objects. If both from_object and to_object are resolved, link_object (if provided) shall be a resolved DRM 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 DRM object.
4. link_object, if not in the same transmittal as from_object, shall be a published DRM object.

It should be noted that relationships between DRM 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 with either Access_Mode CREATE or Access_Mode UPDATE.

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.

If the requested relationship has already been established, another such relationship is established and SUCCESS is returned.

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 with either Access_Mode CREATE or Access_Mode UPDATE, 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 a different transmittal from from_object, but is not published by that transmittal; or
  2. link_object is in a different transmittal from from_object, but is not published by that transmittal; or
  3. to_object is in a different transmittal from 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 DRM object,
  2. link_object is an unresolved DRM object, or
  3. to_object is an unresolved DRM 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

This function 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 DRM object, or both shall be resolved DRM objects. If both aggregate_object and component_object are resolved, link_object (if provided) shall be a resolved DRM 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 DRM object.
4. link_object, if not in the same transmittal as aggregate_object, shall be a published DRM 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.

If the requested relationship has already been established, no action is taken and SUCCESS is returned.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and the requested composition relationship is added.

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 all involved DRM objects are resolved, in one or more different transmittals, and any are unpublished.
• 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 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, or
  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 DRM object referenced by original_object.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and the DRM object referenced by object is made accessible through duplicate_object.

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 DRM 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, the following action 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 DRM 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 DRM object of the DRM class specified by new_object_class and inserts it into the transmittal specified by transmittal. The Fields are initialized to the default values for the specified class (see Annex D Default Field values).

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and the new DRM 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

This function defines a set of rules that can be used to filter DRM objects from a transmittal so that only the DRM 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, the set of rules is passed to an iterator creation function. The iterator will then use that set of rules to filter all DRM 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 retains a copy of any search filter used to initialize that iterator).

See 5.3.3.220 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. an illegal expression was specified by the rules parameter;
  2. search_filter is invalid;
  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 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 8.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 DRM objects an iterator will iterate over will be determined solely by the search rules and the starting DRM object of the search.

The search_bounds parameter specifies the spatial extents of the search.

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

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.

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. 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 specified by test_object is contained within the user-specified spatial area. DetermineSpatialInclusion supplements the normal method of filtering DRM objects by spatial location (i.e., the use of search boundaries with component iterators as described under 8.3.8 CreateSpatialSearchBoundary).

While DetermineSpatialInclusion can be used with any DRM object, its intended use is to find out more information about the relationship of a DRM 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 DRM 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 DRM object completely includes the spatial extents.

The search_bounds parameter specifies the spatial extents of the search.

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

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 specified by test_object is fully included in the search area. The parameter object_partly_included returns whether test_object is partially included in the spatial extents. The parameter object_includes_search_bounds returns whether test_object fully includes the search extents.

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.

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 test_object is an unresolved DRM object.
• Current status code is set to DELETED_OBJECT and no changes are made if test_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 <DRM Location> instance is encountered.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. test_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 DRM 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
INACTIONABLE_FAILURE

Semantics

This function frees the memory directly associated with the iterator specified by to_free_iterator. 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, the following action occurs:

• Current status code is set to INACTIONABLE_FAILURE and no changes are made if to_free_iterator 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 DRM object handle specified by to_free_object.

If multiple DRM object handles corresponding to the same DRM object have been retrieved through this API, FreeObject shall not release the memory for that DRM object until the last handle to the DRM 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 DRM object is decremented. The actual DRM object is not freed until the reference count becomes zero, but  this DRM 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, the following action 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 8.3.38 GetPackedHierarchy specified by to_free_hierarchy, including decrementing the reference counts of all DRM object handles in records of the object_list Field. All memory allocated by GetPackedHierarchy is freed when this function completes successfully.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and the packed hierarchy data is freed.

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

• Current status code is set to INACTIONABLE_FAILURE and no changes are made if to_free_hierarchy is not a valid instance of Packed_Hierarchy 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 8.3.43 GetRemainingObjectsList and specified by to_free_list, including decrementing the reference counts of all DRM object handles in the remaining_objects_list and remaining_link_objects_list Fields. All memory allocated by 8.3.43 GetRemainingObjectsList is freed when this function completes successfully.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and the remaining DRM objects data is freed.

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

• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. to_free_list is not a valid instance of Remaining_Objects_List,
  2. to_free_list contains a non-NULL entry that is not a handle to a valid, active (i.e., unfreed) DRM 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 8.3.44 GetRemainingPackedHierarchies and specified by to_free_hierarchies_list including decrementing the reference counts of all DRM object handles in the records of the object_list Field contained within each Packed_Hierarchy record in the hierarchy_list Field. All memory allocated by GetRemainingPackedHierarchiesList is freed when this function completes successfully.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and the remaining packed hierarchy data is freed.

When this function completes in error, the following action 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_filter. The memory was allocated during an earlier call to 8.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.

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

• Current status code is set to INACTIONABLE_FAILURE and no changes are made if to_free_filter 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_boundary. The memory was allocated by this API during an earlier call to 8.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.

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

• Current status code is set to INACTIONABLE_FAILURE and no changes are made if to_free_boundary 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_transmittal. The memory was allocated by an earlier call to 8.3.47 GetTransmittalFromObject. The handle to the transmittal is invalid following a call to this function. Transmittal handles returned from 8.3.62 OpenTransmittalByLocation or 8.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 memory associated with the given handle to the transmittal is freed.

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

• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. to_free_transmittal is invalid;
  2.  to_free_transmittal is the only handle to an open transmittal; 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 DRM class of aggregate DRM object specified by drm_class that directly contains the DRM object specified by component_object as a component. If more than one valid aggregate of the specified class has component_object as a component, the first encountered aggregate is retrieved.

EXAMPLE  If GetAggregate is called with a <DRM Model> instance as the DRM object component_object, the <DRM Model Library> instance would be returned in component_object, since the <DRM Model Library> instance is the aggregate DRM 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 8.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.
• Current status code is set to DIFFERENT_TRANSMITTAL and aggregate_object is set to point to the aggregate, and link_object is set appropriately, unless a NULL for that value was provided, if the following conditions are met:
  1. automatic resolution of ITR references was requested,
  2. an ITR reference was encountered in searching for the aggregate, and
  3. the aggregate_object (and link_object, if appropriate) from a new, different transmittal was successfully resolved and retrieved.
• Current status code is set to UNRESOLVED_OUTPUT_OBJECT and aggregate_object or link_object are set to point to an unresolved DRM object handle if 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 component_object is unresolved.
• Current status code is set to NO_OBJECT and no changes are made if no aggregate DRM 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 in, 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. component_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_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. component_object is not a valid handle to a DRM object;
  2. drm_class specifies an invalid value;
  3. aggregate_object and/or link_object are 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_INPUT_OBJECT
UNRESOLVED_OUTPUT_OBJECT
NO_OBJECT
DELETED_OBJECT
OUT_OF_MEMORY
INACTIONABLE_FAILURE

Semantics

Given a DRM object (associating_object) and the DRM class of associate for which to search (drm_class), this function retrieves an immediately associated DRM object of the given drm_class. Only DRM objects at the “to” end of a one-way association, or at either end of a two-way association, is retrieved 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 8.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 a handle to the associate and link_object is set appropriately, if provided, if only one DRM 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. automatic resolution of ITR references was requested,
  2. an ITR reference was encountered in searching for the associate, and
  3. the associate_object (and link_object, if appropriate) from a new, different transmittal was successfully resolved and retrieved.
• Current status code is set to UNRESOLVED_OUTPUT_OBJECT and associate_object or link_object are set to point to an unresolved DRM object handle, if 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 associating_object is unresolved.
• 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, 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 associate DRM object of the specified DRM class could be found.
• Current status code is set to DELETED_OBJECT and no changes are made if:
  1. associating_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_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. associating_object is not a valid handle to a DRM object;
  2. drm_class specifies an invalid value;
  3. associate_object and/or link_object are 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_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> instances from the transmittal specified by transmittal. The value returned depends on the last call made to 8.3.74 SetColourModel and/or 8.3.86 UseDefaultColourModel functions and the manner in which the transmittal was produced.

Case 1: 8.3.74 SetColourModel was called more recently than 8.3.86 UseDefaultColourModel. The colour model selected by 8.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 8.3.74 SetColourModel function was used to override any default colour model choices and forces all <DRM Colour Data> instances to be of the colour model specified by the current colour model.

Case 2: 8.3.86 UseDefaultColourModel was called more recently than 8.3.74 SetColourModel or 8.3.74 SetColourModel was never called. In this case, the colour model that will be used to return <DRM Colour Data> instances 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.

When this function completes in error, the following action 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 DRM 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 DRM object specified by aggregate_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 are 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 DRM 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> component would otherwise be returned, the <DRM Colour Index> component shall be replaced by a <DRM Inline Colour> instance containing a <DRM Primitive Colour> instance with the same definition 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 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> instance without regard to whether the <DRM Inline Colour> component was an immediate or inherited component of the <DRM Polygon> instance.

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 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.

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

• Current status code is set to SUCCESS and component_object is set to a handle to the component, and link_object is set appropriately if provided, if a DRM 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. automatic resolution of ITR references was requested,
  2. an ITR reference was encountered in searching for the component DRM object, and
  3. the component_object (and link_object, if appropriate) from a new, different transmittal was successfully resolved and retrieved.
• Current status code is set to UNRESOLVED_OUTPUT_OBJECT and the output parameters are set as for the SUCCESS case if a component DRM object (and link_object, if appropriate) was found that satisfied the specified criteria, but the component DRM object and/or link DRM 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 aggregate_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. aggregate_object has been removed from the transmittal in which it resided;
  2. component_object has been removed from the transmittal in which it resided; and/or
  3. link_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 DRM 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. aggregate_object is not a valid handle to a DRM object;
  2. drm_class specifies an invalid 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
NO_OBJECT
OUT_OF_MEMORY
INACTIONABLE_FAILURE

Semantics

This function retrieves a copy of the currently effective composition of <DRM Transformation> instances that apply to transformed_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 Environment Root> instance down to transformed_object, including any transformation components directly aggregated by that DRM object. If transformed_object, or any of the DRM objects between it and its <DRM Transmittal Root> instance, are referenced as a component from another transmittal and that transmittal is open, the accumulation is from the other transmittal’s <DRM Transmittal Root> instance. Otherwise, the accumulation is from the <DRM Transmittal Root> instance within transformed_object’s own transmittal.

In the second case, the accumulated transformation is from the <DRM Model> instance down to transformed_object, including any <DRM Transformation> components directly aggregated by that DRM object.

If no matrices were accumulated by transformed_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 currently effective transformation of DRM object is returned in matrix.

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 transformed_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 transformed_object is unresolved.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
  1. transformed_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 the requested data is returned.

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 DRM object.
• Current status code is set to DELETED_OBJECT and no changes are made if data_table_object is a handle to a DRM 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 DRM object specified by the object parameter.

When this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and object_class is set appropriately.

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