Information technology — SEDRIS —
Part 1:  Functional specification

8 Application program interface (API)

8.1 Introduction

8.1.1 Topics

Table 8.1 lists the topics in this clause.

Table 8.1 — Topics

8 Application program interface (API)

8.1 Introduction

8.1.1 Topics

8.1.2 Description

8.2 Document conventions and notations

8.3 API functions

8.3.1 Overview

8.3.2 AddAssociateRelationship

8.3.3 AddComponentRelationship

8.3.4 CloneObjectHandle

8.3.5 CloseTransmittal

8.3.6 CreateObject

8.3.7 CreateSearchFilter

8.3.8 CreateSpatialSearchBoundary

8.3.9 DetermineSpatialInclusion

8.3.10 FreeIterator

8.3.11 FreeObject

8.3.12 FreePackedHierarchy

8.3.13 FreeRemainingObjectsList

8.3.14 FreeRemainingPackedHierarchiesList

8.3.15 FreeSearchFilter

8.3.16 FreeSpatialSearchBoundary

8.3.17 FreeTransmittal

8.3.18 GetAggregate

8.3.19 GetAssociate

8.3.20 GetColourModel

8.3.21 GetComponent

8.3.22 GetContextTransformation

8.3.23 GetDataTableData

8.3.24 GetDRMClass

8.3.25 GetEncoding

8.3.26 GetFields

8.3.27 GetImageData

8.3.28 GetIterationLengthRemaining

8.3.29 GetLastFunctionStatus

8.3.30 GetMeshFaceTableData

8.3.31 GetNextObject

8.3.32 GetNthAssociate

8.3.33 GetNthComponent

8.3.34 GetNumberOfPathsToTransmittalRoot

8.3.35 GetObjectFromIDString

8.3.36 GetObjectIDString

8.3.37 GetObjectReferenceCount

8.3.38 GetPackedHierarchy

8.3.39 GetPublishedLabels

8.3.40 GetPublishedObjectList

8.3.41 GetReferencedTransmittalList

8.3.42 GetRelationCounts

8.3.43 GetRemainingObjectsList

8.3.44 GetRemainingPackedHierarchies

8.3.45 GetRootObject

8.3.46 GetSRFContextInfo

8.3.47 GetTransmittalFromObject

8.3.48 GetTransmittalLocation

8.3.49 GetTransmittalName

8.3.50 GetTransmittalVersionInformation

8.3.51 GetUniqueTransmittalID

8.3.52 GetUnresolvedObjectFromPublishedLabel

8.3.53 GetUserData

8.3.54 InitializeAggregateIterator

8.3.55 InitializeAssociateIterator

8.3.56 InitializeComponentIterator

8.3.57 InitializeInheritedComponentIterator

8.3.58 IsIteratorComplete

8.3.59 ObjectIsPublished

8.3.60 ObjectIsResolved

8.3.61 ObjectsAreSame

8.3.62 OpenTransmittalByLocation

8.3.63 OpenTransmittalByName

8.3.64 PublishObject

8.3.65 PutDataTableData

8.3.66 PutFields

8.3.67 PutImageData

8.3.68 PutMeshFaceTableData

8.3.69 RemoveAssociateRelationship

8.3.70 RemoveComponentRelationship

8.3.71 RemoveFromTransmittal

8.3.72 ResolveObject

8.3.73 ResolveTransmittalName

8.3.74 SetColourModel

8.3.75 SetFirstErrorMessage

8.3.76 SetGeneralCallback

8.3.77 SetGeneralCallbackForOneFunction

8.3.78 SetRootObject

8.3.79 SetSecondErrorMessage

8.3.80 SetSpecificCallback

8.3.81 SetSRFContextInfo

8.3.82 SetTransmittalName

8.3.83 SetUserData

8.3.84 TransmittalsAreSame

8.3.85 UnpublishObject

8.3.86 UseDefaultColourModel

8.3.87 UseDefaultSRFContextInfo

8.1.2 Description

This clause provides a detailed definition of the syntax and semantics of each API function. The API provides the means for creating, accessing, and modifying transmittals.

8.2 Document conventions and notations

The following convention is used to present information about the API. Table 8.2 itemizes the different properties of the API functions. All functions use only the DRM classes defined in 6.2 DRM class specificagtions and data types defined in 5 Fundamental data types.

Table 8.2 — API presentation format

Property Description

Semantics

A specification of the operation of the function.

Input parameters

Parameter name

Parameter data type

parameter_i

Data_Type_For_Parameter_i

Input/output parameters

Parameter name

Parameter data type

parameter_io

Data_Type_For_Parameter_io

Output parameters

Parameter name

Parameter data type

parameter_o

Data_Type_For_Parameter_o

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.

8.3 API functions

8.3.1 Overview

The functions declared in this clause are used to create, modify, and access transmittals. There are also functions that interface with the error handling mechanism specified by the API.

8.3.2 AddAssociateRelationship

Table 8.3 — AddAssociateRelationship

Property Description

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

Parameter name

Parameter data type

from_object

Object

to_object

Object

link_object

Object

make_two_way

Boolean

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

None

 

Success status codes

SUCCESS

Failure status codes

INVALID_ACCESS_MODE
UNPUBLISHED_OBJECT
UNRESOLVED_INPUT_OBJECT
DELETED_OBJECT
INACTIONABLE_FAILURE

 

8.3.3 AddComponentRelationship

Table 8.4 — AddComponentRelationship

Property Description

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

Parameter name

Parameter data type

component_object

Object

aggregate_object

Object

link_object

Object

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

None

 

Success status codes

SUCCESS

Failure status codes

UNPUBLISHED_OBJECT
UNRESOLVED_INPUT_OBJECT
INVALID_ACCESS_MODE
DELETED_OBJECT
INACTIONABLE_FAILURE

 

8.3.4 CloneObjectHandle

Table 8.5 — CloneObjectHandle

Property Description

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

Parameter name

Parameter data type

original_object

Object

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

duplicate_object

Object

Success status codes

SUCCESS

Failure status codes

DELETED_OBJECT
OUT_OF_MEMORY
INACTIONABLE_FAILURE

 

8.3.5 CloseTransmittal

Table 8.6 — CloseTransmittal

Property Description

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

Parameter name

Parameter data type

transmittal

Transmittal

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

None

 

Success status codes

SUCCESS

Failure status codes

INACTIONABLE_FAILURE

 

8.3.6 CreateObject

Table 8.7 — CreateObject

Property Description

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

Parameter name

Parameter data type

transmittal

Transmittal

new_object_class DRM_Class

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

new_object

Object

Success status codes

SUCCESS

Failure status codes

INVALID_ACCESS_MODE
OUT_OF_MEMORY
INACTIONABLE_FAILURE

 

8.3.7 CreateSearchFilter

Table 8.8 — CreateSearchFilter

Property Description

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

Parameter name

Parameter data type

rules

Search_Rule[*]

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

search_filter

Search_Filter

Success status codes

SUCCESS

Failure status codes

OUT_OF_MEMORY
INACTIONABLE_FAILURE

 

8.3.8 CreateSpatialSearchBoundary

Table 8.9 — CreateSpatialSearchBoundary

Property Description

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

Parameter name

Parameter data type

search_bounds

Search_Bounds

search_bounds_closure

Search_Bounds_Closure

search_quality

Search_Type

inclusion

Object_Inclusion

search_dimension

Search_Dimension

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

search_boundary

Search_Boundary

Success status codes

SUCCESS

Failure status codes

OUT_OF_MEMORY
INACTIONABLE_FAILURE

 

8.3.9 DetermineSpatialInclusion

Table 8.10 — DetermineSpatialInclusion

Property Description

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

Parameter name

Parameter data type

test_object

Object

search_bounds

Search_Bounds

search_bounds_closure

Search_Bounds_Closure

search_quality

Search_Type

search_dimension

Search_Dimension

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

object_fully_included

Boolean

object_partly_included

Boolean

object_includes_search_bounds

Boolean

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
DELETED_OBJECT
INACTIONABLE_FAILURE

 

8.3.10 FreeIterator

Table 8.11 — FreeIterator

Property Description

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

Parameter name

Parameter data type

to_free_iterator

Iterator

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

None

 

Success status codes

SUCCESS

Failure status codes

INACTIONABLE_FAILURE

 

8.3.11     FreeObject

Table 8.12 — FreeObject

Property Description

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

Parameter name

Parameter data type

to_free_object

Object

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

None

 

Success status codes

SUCCESS

Failure status codes

INVALID_OBJECT
INACTIONABLE_FAILURE

 

8.3.12 FreePackedHierarchy

Table 8.13 — FreePackedHierarchy

Property Description

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

Parameter name

Parameter data type

None

 

Input/output parameters

Parameter name

Parameter data type

to_free_hierarchy

Packed_Hierarchy

Output parameters

Parameter name

Parameter data type

None

 

Success status codes

SUCCESS

Failure status codes

INACTIONABLE_FAILURE

 

8.3.13 FreeRemainingObjectsList

Table 8.14 — FreeRemainingObjectsList

Property Description

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

Parameter name

Parameter data type

None

 

Input/output parameters

Parameter name

Parameter data type

to_free_list

Remaining_Objects_List

Output parameters

Parameter name

Parameter data type

None

 

Success status codes

SUCCESS

Failure status codes

INACTIONABLE_FAILURE

 

8.3.14 FreeRemainingPackedHierarchiesList

Table 8.15 — FreeRemainingPackedHierarchiesList

Property Description

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

Parameter name

Parameter data type

None

 

Input/output parameters

Parameter name

Parameter data type

to_free_hierarchies_list

 Remaining_Packed_Hierarchies_List

Output parameters

Parameter name

Parameter data type

None

 

Success status codes

SUCCESS

Failure status codes

INACTIONABLE_FAILURE

 

8.3.15 FreeSearchFilter

Table 8.16 — FreeSearchFilter

Property Description

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

Parameter name

Parameter data type

to_free_filter

Search_Filter

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

None

 

Success status codes

SUCCESS

Failure status codes

INACTIONABLE_FAILURE

 

8.3.16 FreeSpatialSearchBoundary

Table 8.17 — FreeSpatialSearchBoundary

Property Description

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

Parameter name

Parameter data type

to_free_boundary

Search_Boundary

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

None

 

Success status codes

SUCCESS

Failure status codes

INACTIONABLE_FAILURE

 

8.3.17 FreeTransmittal

Table 8.18 — FreeTransmittal

Property Description

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

Parameter name

Parameter data type

to_free_transmittal

Transmittal

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

None

 

Success status codes

SUCCESS

Failure status codes

INACTIONABLE_FAILURE

 

8.3.18 GetAggregate

Table 8.19 — GetAggregate

Property Description

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

Parameter name

Parameter data type

component_object

Object

drm_class

DRM_Class

itr_traversal

ITR_Behaviour

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

aggregate_object

Object

link_object

Object

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

 

8.3.19 GetAssociate

Table 8.20 — GetAssociate

Property Description

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

Parameter name

Parameter data type

associating_object

Object

drm_class

DRM_Class

itr_traversal

ITR_Behaviour

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

associate_object

Object

link_object

Object

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

 

8.3.20 GetColourModel

Table 8.21 — GetColourModel

Property Description

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

Parameter name

Parameter data type

transmittal

Transmittal

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

colour_model

Colour_Model

Success status codes

SUCCESS

Failure status codes

INACTIONABLE_FAILURE

 

8.3.21 GetComponent

Table 8.22 — GetComponent

Property Description

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

Parameter name

Parameter data type

aggregate_object

Object

drm_class

DRM_Class

directly_attach_table_components

Boolean

process_inheritance

Boolean

itr_traversal

ITR_Behaviour

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

component_object

Object

link_object

Object

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

 

8.3.22 GetContextTransformation

Table 8.23 — GetContextTransformation

Property Description

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

Parameter name

Parameter data type

transformed_object

Object

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

matrix

Matrix_4x4

Success status codes

SUCCESS

Failure status codes

DELETED_OBJECT
UNRESOLVED_INPUT_OBJECT
INACTIONABLE_FAILURE

 

8.3.23 GetDataTableData

Table 8.24 — GetDataTableData

Property Description

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

Parameter name

Parameter data type

data_table_object

Object

extents

Data_Table_Sub_Extent

element_count

Integer_Positive

element_indices 

Integer_Positive[element_count]

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

results

Data_Table_Data[element_count]

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
DELETED_OBJECT
OUT_OF_MEMORY
INACTIONABLE_FAILURE

 

8.3.24 GetDRMClass

Table 8.25 — GetDRMClass

Property Description

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 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 a DRM 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_class is not valid; or
    3. the function fails for any other reason.

Input parameters

Parameter name

Parameter data type

object

Object

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

object_class

DRM_Class

Success status codes

SUCCESS

Failure status codes

DELETED_OBJECT
UNRESOLVED_INPUT_OBJECT
INACTIONABLE_FAILURE

 

8.3.25 GetEncoding

Table 8.26 — GetEncoding

Property Description

Semantics

Given a handle to a DRM object specified in object, this function returns in encoding the encoding of the transmittal in which that DRM object resides.

When this function completes successfully, the following action occurs:

  • Current status code is set to SUCCESS and the encoding 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 object is an unresolved DRM object.
  • Current status code is set to DELETED_OBJECT and no changes are made if 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 INACTIONABLE_FAILURE and no changes are made if:
    1. object is not a valid handle to a DRM object; or
    2. the function fails for any other reason.

Input parameters

Parameter name

Parameter data type

object

Object

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

encoding

Encoding

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
DELETED_OBJECT
INACTIONABLE_FAILURE

 

8.3.26 GetFields

Table 8.27 — GetFields

Property Description

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 DRM object is valid. When the DRM object is freed (by a call to 8.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 DRM object are returned in Fields.

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 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 SRF_OPERATION_UNSUPPORTED and no changes are made if object is a handle to a <DRM Location> instance and 8.3.81 SetSRFContextInfo has been invoked to set the current SRF to an SRF to which the DRM object cannot be converted.
  • 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

Parameter name

Parameter data type

object

Object

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

Fields

DRM_Class_Fields

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
DELETED_OBJECT
SRF_OPERATION_UNSUPPORTED
OUT_OF_MEMORY
INACTIONABLE_FAILURE

 

8.3.27 GetImageData

Table 8.28 — GetImageData

Property Description

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 2D or 3D texel data. The texel values are stored in order one after the other across octet boundaries. The Fields of image_object specify the form of the texel 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 Fields (see 5.2.6.8 Image_Scan_Direction and 5.2.6.9 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 image_data.

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 DRM object.
  • Current status code is set to DELETED_OBJECT and no changes are made if image_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 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> instance;
    2. no image data has yet been specified for the <DRM Image> instance 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

Parameter name

Parameter data type

image_object

Object

start_texel

Image_Texel_Location_3D

stop_texel

Image_Texel_Location_3D

mip_level

Short_Integer_Unsigned

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

image_data

Image_Data

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
DELETED_OBJECT
OUT_OF_MEMORY
INACTIONABLE_FAILURE

 

8.3.28 GetIterationLengthRemaining

Table 8.29 — GetIterationLengthRemaining

Property Description

Semantics

This function returns the number of DRM 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 DRM objects left to be returned by the iterator is returned in count.

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. iterator is invalid; or
    2. the function fails for any other reason.

Input parameters

Parameter name

Parameter data type

iterator

Iterator

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

count

Integer_Unsigned

Success status codes

SUCCESS

Failure status codes

INACTIONABLE_FAILURE

 

8.3.29 GetLastFunctionStatus

Table 8.30 — GetLastFunctionStatus

Property Description

Semantics

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

The last_function_status Field returns 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

Parameter name

Parameter data type

None

 

Input/output parameters

Parameter name

Parameter data type

None

Output parameters

Parameter name

Parameter data type

last_function_status

Status_Code

status_description

String

Success status codes

SUCCESS

Failure status codes

INACTIONABLE_FAILURE

 

8.3.30 GetMeshFaceTableData

Table 8.31 — GetMeshFaceTableData

Property Description

Semantics

Given the <DRM Mesh Face Table> instance specified by mesh_face_table_object, this function returns the face definition data for the selected faces in mesh_face_table_data. The selected faces are specified by the start_face and number_faces parameters.

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 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 mesh_face_table_object is a handle to an unresolved DRM 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.

Input parameters

Parameter name

Parameter data type

mesh_face_table_object

Object

get_adjacent_face_table_data

Boolean

start_face

Integer_Positive

number_faces

Integer_Positive

Input/output parameters

Parameter name

Parameter data type

None

Output parameters

Parameter name

Parameter data type

mesh_face_table_data

Integer_Unsigned[number_faces, maximum_vertices_per_face]

adjacent_face_table_data

Integer_Unsigned[number_faces, maximum_node_count]

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
DELETED_OBJECT
OUT_OF_MEMORY
INACTIONABLE_FAILURE

 

8.3.31 GetNextObject

Table 8.32 — GetNextObject

Property Description

Semantics

This function retrieves the next_object, and optionally the related link_object, from an iterator. The link_object shall be the link object on the relationship traversed by the iterator to arrive at next_object. If no link object existed on the relationship, link_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 handle of the next DRM object from the iterator if either no ITR references were encountered in searching for the next DRM object or the iterator is configured to ignore ITR references.
  • Current status code is set to DIFFERENT_TRANSMITTAL and next_object returns the next DRM object from the iterator if:
    1. the iterator is configured to automatically resolve ITR references;
    2. an ITR reference was encountered in searching for the next DRM object; and
    3. the iterator successfully resolved it and continued to search in the new, different transmittal until the next DRM 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 DRM object from the iterator, if an ITR reference was encountered in searching for the next DRM 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 DRM 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_object is invalid; or
    4. the function fails for any other reason.

Input parameters

Parameter name

Parameter data type

iterator

Iterator

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

next_object

Object

link_object

Object

Success status codes

SUCCESS
DIFFERENT_TRANSMITTAL
UNRESOLVED_OUTPUT_OBJECT

Failure status codes

UNRESOLVED_OUTPUT_OBJECT
NO_OBJECT
DELETED_OBJECT
OUT_OF_MEMORY
INACTIONABLE_FAILURE

 

8.3.32 GetNthAssociate

Table 8.33 — GetNthAssociate

Property Description

Semantics

Given a DRM object that has multiple, ordered associates of a certain DRM class (from_object), this function returns a DRM object for the nth 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_object output parameter returns the link object on the relationship traversed to arrive at the DRM object specified by associate_object. If no link object exists on the relationship, link_object shall be set to NULL.

When this function completes successfully, the following action occurs:

  • Current status code is set to SUCCESS and a handle to the desired associate DRM object is returned in associate_object and link_object is set appropriately.

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 DRM object has been removed from the transmittal in which it resided; or
    3. the link object for the associate DRM 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 DRM 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_object is invalid;
    4. the given class of associate DRM object is not ordered for the given from_object; or
    5. the function failed for any other reason.

Input parameters

Parameter name

Parameter data type

from_object

Object

desired_associate_class

DRM_Class

n

Integer_Positive

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

associate_object

Object

link_object

Object

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
UNRESOLVED_OUTPUT_OBJECT
DELETED_OBJECT
NO_OBJECT
OUT_OF_MEMORY
INACTIONABLE_FAILURE

 

8.3.33 GetNthComponent

Table 8.34 — GetNthComponent

Property Description

Semantics

Given a DRM object that has multiple, ordered components of a certain DRM class (aggregate_object), this function returns a DRM object for the nth 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_object output parameter returns the link object on the relationship traversed to arrive at the DRM object specified by component_object. If no link object exists on the relationship, link_object shall be set to NULL.

When this function completes successfully, the following action occurs:

  • Current status code is set to SUCCESS and the nth component DRM object is returned in component_object  and link_object is set appropriately.

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_object for the component DRM 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 DRM object did not contain n component DRM 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;
    3. the given class of component is not ordered for the given aggregate_object;
    4. either component_object or link_object is invalid; or
    5. the function failed for any other reason.

Input parameters

Parameter name

Parameter data type

aggregate_object

Object

desired_component_class

DRM_Class

n Integer_Positive

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

component_object

Object

link_object

Object

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
UNRESOLVED_OUTPUT_OBJECT
DELETED_OBJECT
NO_OBJECT
OUT_OF_MEMORY
INACTIONABLE_FAILURE

 

8.3.34 GetNumberOfPathsToTransmittalRoot

Table 8.35 — GetNumberOfPathsToTransmittalRoot

Property Description

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

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

Parameter name

Parameter data type

object

Object

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

number_of_paths

Integer_Unsigned

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
UNRESOLVED_OUTPUT_OBJECT
DELETED_OBJECT
INACTIONABLE_FAILURE

 

8.3.35 GetObjectFromIDString

Table 8.36 — GetObjectFromIDString

Property Description

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.

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 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 invalid;
    2. object is invalid; or
    3. the function failed for any other reason.

Input parameters

Parameter name

Parameter data type

transmittal

Transmittal

id

String

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

object

Object

Success status codes

SUCCESS

Failure status codes

DELETED_OBJECT
OUT_OF_MEMORY
INACTIONABLE_FAILURE

 

8.3.36 GetObjectIDString

Table 8.37 — GetObjectIDString

Property Description

Semantics

This function returns an identification string in id for the DRM object specified by object.

When this function completes successfully, the following action occurs:

  • Current status code is set to SUCCESS and a string corresponding to the given DRM object will be returned in id.

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 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. id is invalid; or
    3. the function failed for any other reason.

Input parameters

Parameter name

Parameter data type

object

Object

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

id

String

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
DELETED_OBJECT
OUT_OF_MEMORY
INACTIONABLE_FAILURE

 

8.3.37 GetObjectReferenceCount

Table 8.38 — GetObjectReferenceCount

Property Description

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 data type Object) to the same DRM object may exist by having the same DRM object returned from multiple iterators or from multiple calls to other functions that return the data type Object. A DRM object is termed active while at least one handle to the DRM object exists. That is, a DRM object is active until 8.3.11 FreeObject is called for as many handles as were returned  for that DRM object from other API functions.

This function can be used to determine if a handle to a DRM object has already been returned from any of the API calls that return DRM object handles (e.g., 8.3.31 GetNextObject and  8.3.33 GetNthComponent). This function can also assist with the 8.3.83 SetUserData and 8.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.

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 DRM 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; or
    2. the function failed for any other reason.

Input parameters

Parameter name

Parameter data type

object

Object

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

reference_count

Short_Integer_Unsigned

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
DELETED_OBJECT
INACTIONABLE_FAILURE

 

8.3.38 GetPackedHierarchy

Table 8.39 — GetPackedHierarchy

Property Description

Semantics

This function retrieves a subhierarchy rooted at a given DRM object into a set of data structures that can be directly traversed by the calling application. This subhierarchy 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> instance would otherwise be returned, the <DRM Property Set Index> instance shall be automatically replaced by the corresponding DRM objects referenced by the primary (that is,  the 1st) <DRM Property Set> instance of the referenced <DRM Property Set Table Group> instance.
  2. If a <DRM Colour Index> instance would otherwise be returned, the <DRM Colour Index> instance shall be replaced by a <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 provided in the packed hierarchy.

If the hierarchy_depth parameter is specified, the packed hierarchy will only contain DRM 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 subhierarchy 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 DRM objects they reference will be placed in the packed hierarchy. If REPORT is specified, the ITR references will not be resolved, but unresolved DRM objects will be placed in the packed hierarchy. If IGNORE is specified, the ITR references will not be resolved and the DRM 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.
  • Current status code is set to DIFFERENT_TRANSMITTAL and the packed hierarchy is returned in hierarchy if one or more DRM 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 one or more DRM 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 DRM 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 DRM 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 a DRM object that has been removed from the transmittal in which it resided; or
    2. any DRM object encountered in the packed hierarchy has been removed from the transmittal in which the DRM 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; or
    2. the function fails for any other reason.

Input parameters

Parameter name

Parameter data type

root_object

Object

directly_attach_table_components

Boolean

process_inheritance

Boolean

hierarchy_depth

Integer_Unsigned

itr_traversal

ITR_Behaviour

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

hierarchy

Packed_Hierarchy

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

 

8.3.39 GetPublishedLabels

Table 8.40 — GetPublishedLabels

Property Description

Semantics

Given the DRM object specified by object, this function returns in the output parameters the labels under which the DRM 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.

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 DRM object.
  • Current status code is set to UNPUBLISHED_OBJECT and no changes are made if object is not a published DRM object.
  • Current status code is set to DELETED_OBJECT and no changes are made if: 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:
    1. object is not a valid handle to a DRM object; or
    2. the function fails for any other reason.

Input parameters

Parameter name

Parameter data type

object

Object

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

label_count

Integer_Unsigned

label_list

String[label_count]

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_OUTPUT_OBJECT
UNPUBLISHED_OBJECT
DELETED_OBJECT
OUT_OF_MEMORY
INACTIONABLE_FAILURE

 

8.3.40 GetPublishedObjectList

Table 8.41 — GetPublishedObjectList

Property Description

Semantics

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

The number of published DRM 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.

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; or
    2. the function fails for any other reason.

Input parameters

Parameter name

Parameter data type

transmittal

Transmittal

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

published_object_count

Integer_Unsigned

published_object_list

Object[published_object_count]

Success status codes

SUCCESS

Failure status codes

OUT_OF_MEMORY
INACTIONABLE_FAILURE

 

8.3.41 GetReferencedTransmittalList

Table 8.42 — GetReferencedTransmittalList

Property Description

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. The names returned are formal 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.

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; or
    2. the function fails for any other reason.

Input parameters

Parameter name

Parameter data type

transmittal

Transmittal

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

transmittal_name_count 

Integer_Unsigned

transmittal_name_list

URN[transmittal_name_count]

Success status codes

SUCCESS

Failure status codes

OUT_OF_MEMORY
INACTIONABLE_FAILURE

 

8.3.42 GetRelationCounts

Table 8.43 — GetRelationCounts

Property Description

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 DRM 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 DRM object.
  • Current status code is set to DELETED_OBJECT and no changes are made if 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 INACTIONABLE_FAILURE if the function failed for any other reason.

Input parameters

Parameter name

Parameter data type

object

Object

itr_traversal

ITR_Behaviour

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

component_count

Integer_Unsigned

aggregate_count

Integer_Unsigned

association_count

Integer_Unsigned

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
DELETED_OBJECT
INACTIONABLE_FAILURE

 

8.3.43 GetRemainingObjectsList

Table 8.44 — GetRemainingObjectsList

Property Description

Semantics

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

The number_of_objects field of the output parameter is set to the number of DRM 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 nth entry in the remaining_objects_list and remaining_link_objects_list arrays correspond to the nth DRM object returned by the iterator and its related link DRM object, if one exists. The nth entry in object_status_list and link_object_status_list arrays correspond to the status codes indicating the results of the DRM object retrieval for the nth DRM object.

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

  • Current status code is set to SUCCESS and all remaining DRM objects are returned in remaining_objects.
  • Current status code is set to DIFFERENT_TRANSMITTAL and all remaining DRM objects are returned in remaining_objects if one or more DRM 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 DRM objects are returned in remaining_objects if one or more DRM 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 a DRM object has been removed from the transmittal in which it was stored.
  • Current status code is set to NO_OBJECT and no changes are made if the iterator has no more DRM 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; or
    2. this function fails for any other reason.

Input parameters

Parameter name

Parameter data type

iterator

Iterator

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

remaining_objects

Remaining_Objects_List

Success status codes

SUCCESS
DIFFERENT_TRANSMITTAL
UNRESOLVED_OUTPUT_OBJECT

Failure status codes

UNRESOLVED_OUTPUT_OBJECT
DELETED_OBJECT
NO_OBJECT
OUT_OF_MEMORY
INACTIONABLE_FAILURE

 

8.3.44 GetRemainingPackedHierarchies

Table 8.45 — GetRemainingPackedHierarchies

Property Description

Semantics

This function iterates over the remaining DRM 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.205 Remaining_Packed_Hierarchies_List.

The hierarchy_depth parameter specifies the depth to which the subhierarchy of each remaining DRM object is extracted below that DRM object. A value of one indicates that only the components of each remaining DRM object are to be returned. A value of zero indicates that the entire subhierarchy of each remaining DRM 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.
  • Current status code is set to DIFFERENT_TRANSMITTAL and remaining_hierarchies returns the remaining hierarchy list data if one or more DRM 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 DRM objects were left that have not yet been returned, and one or more DRM 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 DRM 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 a DRM 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 has no more DRM objects to return.
  • Current status code is set to INACTIONABLE_FAILURE and no changes are made if:
    1. iterator is invalid; or
    2. the function fails for any other reason.

Input parameters

Parameter name

Parameter data type

iterator

Iterator

hierarchy_depth

Integer_Unsigned

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

remaining_hierarchies 

Remaining_Packed_Hierarchies_List

Success status codes

SUCCESS
DIFFERENT_TRANSMITTAL
UNRESOLVED_OUTPUT_OBJECT

Failure status codes

UNRESOLVED_OUTPUT_OBJECT
DELETED_OBJECT
NO_OBJECT
INACTIONABLE_FAILURE

 

8.3.45 GetRootObject

Table 8.46 — GetRootObject

Property Description

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 DRM object hierarchy.

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, following action 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. the transmittal does not have a root DRM object; or
    3. the function fails for any other reason.

Input parameters

Parameter name

Parameter data type

transmittal

Transmittal

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

root_object

Object

Success status codes

SUCCESS

Failure status codes

INACTIONABLE_FAILURE

 

8.3.46 GetSRFContextInfo

Table 8.47 — GetSRFContextInfo

Property Description

Semantics

This function returns in srf_context_info the definition of the SRF currently being used when returning <DRM Location> instances in the same SRF scope as the DRM object specified by object.

More details are available under 8.3.81 SetSRFContextInfo.

The value of srf_context_info depends on the last call made to 8.3.81 SetSRFContextInfo and/or 8.3.87 UseDefaultSRFContextInfo and the manner in which the transmittal was produced.

Case 1: 8.3.81 SetSRFContextInfo was called more recently than 8.3.87 UseDefaultSRFContextInfo. The SRF defined by 8.3.81 SetSRFContextInfo is still the current retrieval SRF, and that SRF’s context information will be returned by this function. This indicates that the SRF used to originally produce the given transmittal was overridden by a call to the 8.3.81 SetSRFContextInfo function.

Case 2: 8.3.87 UseDefaultSRFContextInfo was called more recently than 8.3.81 SetSRFContextInfo, or 8.3.81 SetSRFContextInfo was never called. In this case, the retrieval SRF that will be used to define <DRM Location> instances 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.

When this function completes successfully, the following action occurs:

  • Current status code is set to SUCCESS and the scoping SRF definition is returned in srf_context_info.

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 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 DRM object has no scoping SRF; or
    3. the function fails for any other reason.

Input parameters

Parameter name

Parameter data type

object

Object

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

srf_context_info

SRF_Context_Info

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
DELETED_OBJECT
INACTIONABLE_FAILURE

 

8.3.47 GetTransmittalFromObject

Table 8.48 — GetTransmittalFromObject

Property Description

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 DRM object 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 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; or
    2. the function fails for any other reason.

Input parameters

Parameter name

Parameter data type

object

Object

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

transmittal

Transmittal

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
DELETED_OBJECT
OUT_OF_MEMORY
INACTIONABLE_FAILURE

 

8.3.48 GetTransmittalLocation

Table 8.49 — GetTransmittalLocation

Property Description

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.

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; or
    2. the function fails for any other reason.

Input parameters

Parameter name

Parameter data type

transmittal

Transmittal

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

location

URL

Success status codes

SUCCESS

Failure status codes

OUT_OF_MEMORY
INACTIONABLE_FAILURE

 

8.3.49 GetTransmittalName

Table 8.50 — GetTransmittalName

Property Description

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.

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; or
    2. the function fails for any other reason.

Input parameters

Parameter name

Parameter data type

transmittal

Transmittal

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

name

URN

Success status codes

SUCCESS

Failure status codes

OUT_OF_MEMORY
INACTIONABLE_FAILURE

 

8.3.50 GetTransmittalVersionInformation

Table 8.51 — GetTransmittalVersionInformation

Property Description

Semantics

This function returns the versions of the implementations of the DRM, EDCS, and SRM used to define the given transmittal.

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

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

Interim versions are specified using a lower case letter which is incremented whenever a new interim version of the implementation 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.

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 handle to an open transmittal; or
    2. the function fails for any other reason.

Input parameters

Parameter name

Parameter data type

transmittal

Transmittal

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

major_DRM_version

Short_Integer_Unsigned

minor_DRM_version

Byte_Unsigned

interim_DRM_version

Character

major_EDCS_version

Short_Integer_Unsigned

minor_EDCS_version

Byte_Unsigned

interim_EDCS_version

Character

major_SRM_version

Short_Integer_Unsigned

minor_SRM_version

Byte_Unsigned

interim_SRM_version

Character

Success status codes

SUCCESS

Failure status codes

INACTIONABLE_FAILURE

 

8.3.51 GetUniqueTransmittalID

Table 8.52 — GetUniqueTransmittalID

Property Description

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.

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; or
    2. the function fails for any other reason.

Input parameters

Parameter name

Parameter data type

transmittal

Transmittal

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

identifier

String

Success status codes

SUCCESS

Failure status codes

OUT_OF_MEMORY
INACTIONABLE_FAILURE

 

8.3.52 GetUnresolvedObjectFromPublishedLabel

Table 8.53 — GetUnresolvedObjectFromPublishedLabel

Property Description

Semantics

This function creates an unresolved reference to a DRM 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 DRM objects, without requiring the transmittal containing the DRM object to be accessible. The 8.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.

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.
  • 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 (see 8.3.64 PublishObject).
  • 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 fails for any other reason.

Input parameters

Parameter name

Parameter data type

transmittal_name

URN

object_label

String

encoding

String

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

object

Object

Success status codes

SUCCESS

Failure status codes

INVALID_TRANSMITTAL_NAME
INVALID_OBJECT_LABEL
OUT_OF_MEMORY
INACTIONABLE_FAILURE

 

8.3.53 GetUserData

Table 8.54 — GetUserData

Property Description

Semantics

This function returns in user_data, the handle to the user data associated with the DRM object specified by object. This is a user data handle previously set with a call to 8.3.83 SetUserData on an active handle to this DRM object. If 8.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.

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 DRM 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; or
    2. the function fails for any other reason.

Input parameters

Parameter name

Parameter data type

object

Object

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

user_data

User_Data

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
INACTIONABLE_FAILURE

 

8.3.54 InitializeAggregateIterator

Table 8.55 — InitializeAggregateIterator

Property Description

Semantics

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

  1. The aggregate DRM objects contain the start_object as an immediate component (a component that is exactly one link away) via a two-way aggregation relationship.
  2. If a search filter is defined for the iterator, the aggregate DRM objects satisfy the rules specified in filter. 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 8.3.31 GetNextObject function is provided to get the next DRM object from an iterator.

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

The 8.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 DRM 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.

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 search filter is provided, but is not a handle to a valid, active (i.e., unfreed) search filter; or
    3. the function fails for any other reason.

Input parameters

Parameter name

Parameter data type

start_object

Object

filter

Search_Filter

itr_traversal

ITR_Behaviour

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

iterator

Iterator

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
DELETED_OBJECT
OUT_OF_MEMORY
INACTIONABLE_FAILURE

 

8.3.55 InitializeAssociateIterator

Table 8.56 — InitializeAssociateIterator

Property Description

Semantics

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

  1. The DRM objects 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 DRM object. If a DRM object is associated to the start_object via a one-way association from the associated DRM object to the start_object, the associated DRM object will not be included in the list of DRM objects returned by this iterator.
  2. If a search filter is defined for the iterator, the associate DRM objects satisfy the rules specified in filter. 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 is created, but it has a length of zero and does not return any DRM objects.

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

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

The 8.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 DRM 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 is returned in iterator.

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 search filter is provided, but is not a handle to a valid, active (i.e., unfreed) search filter; or
    3. the function fails for any other reason.

Input parameters

Parameter name

Parameter data type

start_object

Object

filter

Search_Filter

itr_traversal

ITR_Behaviour

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

iterator

Iterator

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
DELETED_OBJECT
OUT_OF_MEMORY
INACTIONABLE_FAILURE

 

8.3.56 InitializeComponentIterator

Table 8.57 — InitializeComponentIterator

Property Description

Semantics

This function returns a handle in iterator for an iterator created to traverse over the list of component DRM objects returning handles to those DRM objects that meet the user-specified conditions. This iterator starts at the top of an component 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 DRM object in the component tree rooted by the start_object.

DRM objects returned by a component iterator shall meet the following conditions:

  1. The DRM objects are components, either directly or indirectly, of the start_object. That is, they are contained within the component tree that is rooted at the start_object.
  2. The DRM objects 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 subtree 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. The DRM objects 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 DRM objects or it contains component DRM objects, but none of the components within the specified search depth meet the search filter and/or spatial search boundary conditions, a component iterator is created, but it has a length of zero and does not return any DRM objects.

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

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

The 8.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 DRM objects have been returned).

If the directly_attach_table_components parameter has the value FALSE, the handles to the actual DRM objects are returned by the component iterators. However, if the value is TRUE, the component iterators shall automatically make the following adjustments to the DRM objects returned through the API in the following special cases:

  1. If a <DRM Property Set Index> instance would otherwise be returned by the component iterator, the <DRM Property Set Index> instance 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> instance would otherwise be returned by the component  iterator, the <DRM Colour Index> instance shall be replaced by a <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_inheritance parameter has value TRUE, inherited components shall be inherited, and they shall appear as components of the appropriate DRM 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> instances shall be transformed according to the <DRM 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 DRM 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> instance.

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 A <DRM Aggregate Feature> or <DRM Aggregate Geometry> instance.

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 DRM objects, so it is possible for no context (an empty context) to be returned with the returned DRM 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.

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. select_parameters are provided but are not valid;
    5. traversal_order_parameters are provided, but are not valid;
    6. general_traversal_pattern is not valid; or
    7. the function fails for any other reason.

Input parameters

Parameter name

Parameter data type

start_object

Object

boundary

Search_Boundary

filter

Search_Filter

directly_attach_table_components 

Boolean

process_inheritance

Boolean

transform_locations

Boolean

follow_model_instances

Boolean

evaluate_static_control_links

Boolean

select_parameters

Hierarchy_Select_Parameters

traversal_order_parameters

Hierarchy_Order_Parameters

general_traversal_pattern

Traversal_Order

itr_traversal

ITR_Behaviour

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

iterator

Iterator

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
DELETED_OBJECT
OUT_OF_MEMORY
INACTIONABLE_FAILURE

 

8.3.57 InitializeInheritedComponentIterator

Table 8.58 — InitializeInheritedComponentIterator

Property Description

Semantics

This function returns a handle in iterator for an iterator created to traverse over the list of component DRM 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 8.3.56 InitializeComponentIterator.

If only directly aggregated components of a DRM object are to be identified, the 8.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 a DRM object are to be identified and it is not necessary to distinguish between the two sets, the 8.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.

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; or
    3. the function fails for any other reason.

Input parameters

Parameter name

Parameter data type

start_object

Object

filter

Search_Filter

directly_attach_table_components

Boolean

itr_traversal

ITR_Behaviour

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

iterator

Iterator

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
DELETED_OBJECT
OUT_OF_MEMORY
INACTIONABLE_FAILURE

 

8.3.58 IsIteratorComplete

Table 8.59 — IsIteratorComplete

Property Description

Semantics

This function is used to determine whether the iterator specified by iterator has any more DRM objects to return. If the iterator has no DRM 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.

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

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

Input parameters

Parameter name

Parameter data type

iterator

Iterator

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

result

Boolean

Success status codes

SUCCESS

Failure status codes

INACTIONABLE_FAILURE

 

8.3.59 ObjectIsPublished

Table 8.60 — ObjectIsPublished

Property Description

Semantics

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

When this function completes successfully, the following action occurs:

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

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

Parameter name

Parameter data type

object

Object

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

result

Boolean

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
DELETED_OBJECT
INACTIONABLE_FAILURE

 

8.3.60 ObjectIsResolved

Table 8.61 — ObjectIsResolved

Property Description

Semantics

Given the DRM object specified by object, result returns the value TRUE if the DRM 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.

When this function completes in error, the following action 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

Parameter name

Parameter data type

object

Object

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

result

Boolean

Success status codes

SUCCESS

Failure status codes

INACTIONABLE_FAILURE

 

8.3.61 ObjectsAreSame

Table 8.62 — ObjectsAreSame

Property Description

Semantics

This function determines if two DRM object handles both refer to the same DRM 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.

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 DRM 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 DRM 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; or
    2. the function fails for any other reason.

Input parameters

Parameter name

Parameter data type

object_1

Object

object_2

Object

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

result

Boolean

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
DELETED_OBJECT
INACTIONABLE_FAILURE

 

8.3.62 OpenTransmittalByLocation

Table 8.63 — OpenTransmittalByLocation

Property Description

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

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:
    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. CREATE or UPDATE mode was requested and the API implementation does not support write capability.
  • 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

Parameter name

Parameter data type

location

URL

encoding

Encoding

access_mode

Access_Mode

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

transmittal

Transmittal

Success status codes

SUCCESS

Failure status codes

TRANSMITTAL_INACCESSIBLE
INVALID_ACCESS_MODE
UNSUPPORTED_ENCODING
OUT_OF_MEMORY
INACTIONABLE_FAILURE

 

8.3.63 OpenTransmittalByName

Table 8.64 — OpenTransmittalByName

Property Description

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

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 validly formed transmittal name.
  • Current status code is set to UNRESOLVED_TRANSMITTAL and no changes are made if transmittal_name could not be resolved.
  • 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. CREATE or UPDATE mode was requested and the API implementation does not support 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.
  • 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 fails for any other reason.

Input parameters

Parameter name

Parameter data type

transmittal_name

URN

encoding

Encoding

access_mode

Access_Mode

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

transmittal

Transmittal

Success status codes

SUCCESS

Failure status codes

INVALID_TRANSMITTAL_NAME
UNRESOLVED_TRANSMITTAL
TRANSMITTAL_INACCESSIBLE
INVALID_ACCESS_MODE
UNSUPPORTED_ENCODING
OUT_OF_MEMORY
INACTIONABLE_FAILURE

 

8.3.64 PublishObject

Table 8.65 — PublishObject

Property Description

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 DRM object has already been published with a different label, the new label is added to the list of labels for the DRM object. If the DRM object has already been published under the same label, the call shall return success and provide a string to be retrieved using 8.3.29 GetLastFunctionStatus.

A valid DRM object label shall obey the following label syntax rules:

  1. consist only of letters, numbers, and underscores from the character set, specified in ISO/IEC 646, and
  2. begin with a letter.

The transmittal whose DRM 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 label syntax rules.
  • 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

Parameter name

Parameter data type

object

Object

label

String

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

None

 

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
INVALID_OBJECT_LABEL
INVALID_ACCESS_MODE
INACTIONABLE_FAILURE

 

8.3.65 PutDataTableData

Table 8.66 — PutDataTableData

Property Description

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.

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

Parameter name

Parameter data type

data_table_object

Object

extents

Data_Table_Sub_Extent

element_count

Integer_Positive

element_indices

Integer_Positive[element_count]

data_table_data

Data_Table_Data[element_count]

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

None

 

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
DELETED_OBJECT
INVALID_ACCESS_MODE
INACTIONABLE_FAILURE

 

8.3.66 PutFields

Table 8.67 — PutFields

Property Description

Semantics

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

The transmittal whose DRM object is to be edited shall be explicitly opened in either CREATE or 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 DRM object are replaced with the given Fields.

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

Parameter name

Parameter data type

existing_object

Object

new_Fields

DRM_Class_Fields

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

None

 

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_OUTPUT_OBJECT
INVALID_ACCESS_MODE
DELETED_OBJECT
OUT_OF_MEMORY
INACTIONABLE_FAILURE

 

8.3.67 PutImageData

Table 8.68 — PutImageData

Property Description

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 form 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.8 Image_Scan_Direction and 5.2.6.9 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.

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 is greater than start for any of the extents;
    5. a partial image is specified;
    6. image_data is invalid; or
    7. the function fails for any other reason.

Input parameters

Parameter name

Parameter data type

image_object

Object

start_texel_horizontal

Integer_Unsigned

start_texel_vertical

Integer_Unsigned

start_texel_z

Integer_Unsigned

stop_texel_horizontal

Integer_Unsigned

stop_texel_vertical

Integer_Unsigned

stop_texel_z

Integer_Unsigned

mip_level

Short_Integer_Unsigned

image_data

Image_Data

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

None

 

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
DELETED_OBJECT
INVALID_ACCESS_MODE
INACTIONABLE_FAILURE

 

8.3.68 PutMeshFaceTableData

Table 8.69 — PutMeshFaceTableData

Property Description

Semantics

Given the <DRM Mesh Face Table> instance specified by mesh_face_table_object, this function places the face definition data for the selected faces as specified in mesh_face_table_data into that instance. The selected faces are specified by start_face and number_faces.

In addition, if put_adjacent_face_table_data has value TRUE, the adjacent face table data specified by adjacent_face_table_data is placed into the selected faces of mesh_face_table_object. If put_adjacent_face_table_data has value FALSE, the adjacent face table data of mesh_face_table_object is not modified.

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

The validity of adjacent_face_table_data shall only be verified if put_adjacenct_face_table_data has value TRUE.

When this function completes successfully, the following action occurs:

  • Current status code is set to SUCCESS and the cell data is placed in the mesh face table as specified.

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 DRM object.
  • Current status code is set to DELETED_OBJECT and no changes are made if mesh_face_table_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 mesh_face_table_object is not a valid handle to a DRM object or the function fails for any other reason.

Input parameters

Parameter name

Parameter data type

mesh_face_table_object

Object

put_adjacent_face_table_data

Boolean

start_face

Integer_Positive

number_faces

Integer_Positive

mesh_face_table_data

Integer_Unsigned[number_faces, maximum_vertices_per_face]

adjacent_face_table_data

Integer_Unsigned[number_faces, maximum_vertices_per_face]

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

None

 

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
DELETED_OBJECT
INACTIONABLE_FAILURE

 

8.3.69 RemoveAssociateRelationship

Table 8.70 — RemoveAssociateRelationship

Property Description

Semantics

This function breaks the relationship between from_object and to_object (and link_object, if given), but does not remove any of the DRM objects involved from the transmittal (for removal, see 8.3.71 RemoveFromTransmittal).

The relationship being removed may be one-way or two-way. If it is two-way, and remove_two_way is true, both connections are broken, unless the to_object is unresolved.

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

When this function completes successfully, the following action occurs:

  • Current status code is set to SUCCESS and the relationship is removed.

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 unresolved or link_object is provided but is unresolved.
  • Current status code is set to UNRESOLVED_OUTPUT_OBJECT and no changes are made if remove_two_way has value TRUE and the DRM defines the relationship as bidirectional, but to_object is unresolved, so the relationship from to_object to from_object cannot be removed.
  • Current status code is set to DELETED_OBJECT and no changes are made if any of the DRM objects have been removed from the transmittal in which they resided.
  • Current status code is set to INVALID_ACCESS_MODE and no changes are made if:
    1. to_object is in a transmittal that is open in READ_ONLY mode;
    2. link_object was provided but is in a transmittal that is open in READ_ONLY mode; and/or
    3. to_object is resolved, has a relationship back to from_object and remove_two_way has value TRUE but to_object is in a transmittal that is open in READ_ONLY mode.
  • 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 link_object is required and link_object is not a valid handle to a DRM object;
    4. from_object and to_object are not related by an association relationship;
    5. link_object is provided, but it is not the link object for the relationship; or
    6. the function fails for any other reason.

Input parameters

Parameter name

Parameter data type

from_object

Object

to_object

Object

link_object

Object

remove_two_way

Boolean

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

None

 

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
UNRESOLVED_OUTPUT_OBJECT
DELETED_OBJECT
INVALID_ACCESS_MODE
INACTIONABLE_FAILURE

 

8.3.70 RemoveComponentRelationship

Table 8.71 — RemoveComponentRelationship

Property Description

Semantics

This function breaks the relationship between aggregate_object and component_object (and link_object, if given). It does not remove any of the DRM objects involved from the transmittal (for this, see 8.3.71 RemoveFromTransmittal).

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

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

When this function completes successfully, the following action occurs:

  • Current status code is set to SUCCESS and the specified relationship is removed.

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 and/or link_object is provided but is unresolved.
  • Current status code is set to DELETED_OBJECT and no changes are made if any of the DRM objects have been removed from the transmittal in which they resided.
  • Current status code is set to INVALID_ACCESS_MODE and no changes are made if:
    1. aggregate_object or component_object is in a transmittal that is open in READ_ONLY mode; or
    2. link_object was provided but is in a transmittal that is open in READ_ONLY mode.
  • 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. component_object is not a valid handle to a DRM object;
    3. if link_object is required and link_object is not a valid handle to a DRM object;
    4. aggregate_object and component_object are not related by a component relationship;
    5. link_object is provided, and it is not the link object for the relationship; or
    6. the function fails for any other reason.

Input parameters

Parameter name

Parameter data type

aggregate_object

Object

component_object

Object

link_object

Object

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

None

 

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
DELETED_OBJECT
INVALID_ACCESS_MODE
INACTIONABLE_FAILURE

 

8.3.71 RemoveFromTransmittal

Table 8.72 — RemoveFromTransmittal

Property Description

Semantics

This function removes the DRM object specified by old_object from the transmittal specified by transmittal.

Prior to calling this function, any relationships that old_object has with other DRM objects shall have been removed. Otherwise, this function shall fail.

In addition, removing old_object does not automatically remove its component tree. This would not be valid for the general case, since part of the component tree of old_object might be shared with other DRM objects. Similarly, none of the associates of old_object will be removed when old_object is removed.

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

When this function completes successfully, the following action occurs:

  • Current status code is set to SUCCESS.

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

  • Current status code is set to DIFFERENT_TRANSMITTAL and no changes are made if old_object is in a different transmittal from the transmittal specified.
  • Current status code is set to DELETED_OBJECT and no changes are made if old_object has already been removed from the transmittal.
  • Current status code is set to UNRESOLVED_INPUT_OBJECT and no changes are made if old_object is unresolved.
  • 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 INACTIONABLE_FAILURE and no changes are made if:
    1. old_object is not a valid handle to a DRM object;
    2. old_object has relationships to any existing DRM objects;
    3. old_object is published;
    4. transmittal is invalid; or
    5. the function fails for any other reason.

Input parameters

Parameter name

Parameter data type

old_object

Object

transmittal

Transmittal

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

None

 

Success status codes

SUCCESS

Failure status codes

DIFFERENT_TRANSMITTAL
DELETED_OBJECT
UNRESOLVED_INPUT_OBJECT
INVALID_ACCESS_MODE
INACTIONABLE_FAILURE

 

8.3.72 ResolveObject

Table 8.73 — ResolveObject

Property Description

Semantics

Given a DRM object specified by object, this function attempts to resolve the reference. If object is already resolved, no action occurs.

If object is unresolved, the name of the transmittal containing the DRM object shall first be resolved to a specific transmittal that can be accessed by the API. The DRM object shall be resolved within the transmittal using the DRM object’s published label.

NOTE  A transmittal that has been accessed in this way cannot be modified. The transmittal shall be explicitly opened with either Access_Mode CREATE or Access_Mode UPDATE if the DRM object is to be modified.

When this function completes successfully, the following action occurs:

  • Current status code is set to SUCCESS and object becomes resolved.

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 object could not be resolved. This value indicates that the transmittal name was successfully resolved, but the transmittal did not contain the DRM object label as a published DRM object.
  • Current status code is set to UNRESOLVED_TRANSMITTAL and no changes are made if object could not be resolved. This value indicates that the transmittal name portion of the reference could not be resolved.
  • 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

Parameter name

Parameter data type

object

Object

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

None

 

Success status codes

SUCCESS

Failure status codes

UNPUBLISHED_OBJECT|
UNRESOLVED_TRANSMITTAL
INACTIONABLE_FAILURE

 

8.3.73 ResolveTransmittalName

Table 8.74 — ResolveTransmittalName

Property Description

Semantics

Given a character string specified by transmittal_name representing a formal transmittal name, this function returns in location the file location associated with this name.

The format of a valid transmittal name is as described for the URN data type.

When this function completes successfully, the following action occurs:

  • Current status code is set to SUCCESS and location returns the location associated with the transmittal.

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 URN namespace.
  • Current status code is set to UNRESOLVED_TRANSMITTAL and no changes are made if transmittal_name could not be resolved to a transmittal location.
  • 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_name is invalid; or
    2. this function fails for any other reason.

Input parameters

Parameter name

Parameter data type

transmittal_name

URN

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

location

URL

Success status codes

SUCCESS

Failure status codes

INVALID_TRANSMITTAL_NAME
UNRESOLVED_TRANSMITTAL
OUT_OF_MEMORY
INACTIONABLE_FAILURE

 

8.3.74 SetColourModel

Table 8.75 — SetColourModel

Property Description

Semantics

This function sets the colour model that will be used to represent all <DRM Colour Data> instances retrieved after this function is called. The colour model is specified by colour_model. This function has no effect on <DRM Colour Data> instances that were returned to the user before this function was called. By default, if this function is not called, colours are returned to the user in the format in which the colours were defined in the transmittal from which the colours were extracted.

EXAMPLE  If a transmittal contains HSV colours, by default these colours will be returned to the user as <DRM HSV Colour> instances. If the user calls SetColourModel and sets the colour model to RGB, all colours returned after this call are returned as <DRM RGB Colour> instances.

The colour model used for returning <DRM Colour Data> instances can be changed as often as desired. After changing colour models, the 8.3.86 UseDefaultColourModel function may be invoked to return to using the colour model that was used by the producer of each transmittal.

When this function completes successfully, the following action occurs:

  • Current status code is set to SUCCESS and the current colour model of this API is changed to the colour model specified by colour_model.

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

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

Input parameters

Parameter name

Parameter data type

colour_model

Colour_Model

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

None

 

Success status codes

SUCCESS

Failure status codes

INACTIONABLE_FAILURE

 

8.3.75 SetFirstErrorMessage

Table 8.76 — SetFirstErrorMessage

Property Description

Semantics

If an error occurs for a situation where the user has registered an error-handling callback function, that user-defined function is called, and is passed, among other items, two user-defined messages. The first of those messages is set by this function. The second message is set by the 8.3.79 SetSecondErrorMessage function. The intent of these messages is to give the user the ability to construct an intelligent error message that can give an indication as to what was occurring when the error occurred.

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 the function fails for any reason.

Input parameters

Parameter name

Parameter data type

message

String

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

None

 

Success status codes

SUCCESS

Failure status codes

INACTIONABLE_FAILURE

 

8.3.76 SetGeneralCallback

Table 8.77 — SetGeneralCallback

Property Description

Semantics

This function registers the function specified by user_defined_function as the general callback, to be called when any transmittal function is about to return any status code, unless that function has either a general function callback or a specific callback for that status code currently registered. This user-defined function shall be defined to be of function data type Status_Logger (see 5.5.3 Status_Logger).

The value NULL for user_defined_function indicates that a callback function is not being requested.

A general function single function callback has priority over this general function callback for all functions' callback. See the 8.3.77 SetGeneralCallbackForOneFunction function comments for more details about general function callbacks. A specific function/specific status code callback has priority over both general function callbacks and general callbacks. More details may be found under the 8.3.80 SetSpecificCallback 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 the function fails for any reason.

Input parameters

Parameter name

Parameter data type

user_defined_function

Status_Logger

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

None

 

Success status codes

SUCCESS

Failure status codes

INACTIONABLE_FAILURE

 

8.3.77 SetGeneralCallbackForOneFunction

Table 8.78 — SetGeneralCallbackForOneFunction

Property Description

Semantics

This function registers the function specified by user_defined_function as the callback  function to be called when any status code is about to be returned by the API function specified by function_to_catch. This user-defined function shall be defined to be of function data type Status_Logger (see 5.5.3 Status_Logger).

The value NULL for user_defined_function indicates that a callback function is not being requested.

This callback will not be called if a specific status code is about to be returned from the selected transmittal function and that particular function and status code currently has a specific function/specific status code callback set by the 8.3.80 SetSpecificCallback function.

When this function completes successfully, the following action occurs:

  • Current status code is set to SUCCESS and the specified callback is set.

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

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

Input parameters

Parameter name

Parameter data type

user_defined_function

Status_Logger

function_to_catch

API_Function

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

None

 

Success status codes

SUCCESS

Failure status codes

INACTIONABLE_FAILURE

 

8.3.78 SetRootObject

Table 8.79 — SetRootObject

Property Description

Semantics

Given the handle to a transmittal specified by transmittal that has explicitly been opened in CREATE or UPDATE mode, this function sets the DRM object specified by new_root_object as the root of the transmittal’s DRM object hierarchy. The handle to the previous root DRM object is returned in old_root_object. If no root DRM object has been set for the given transmittal, NULL is returned in old_root_object.

CAUTION  Calling this function will permanently change the root DRM object of the transmittal. In order to avoid orphaning DRM objects within the transmittal, the old_root_object parameter is required in order to return the root DRM object that was previously set.

When this function completes successfully, the following action occurs:

  • Current status code is set to SUCCESS and the previously set root DRM object is returned in old_root_object (if requested), and new_root_object is set to be the new root DRM object of transmittal.

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 new_root_object is not a resolved DRM object.
  • Current status code is set to DELETED_OBJECT and no changes are made if new_root_object has been removed from transmittal.
  • 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 DIFFERENT_TRANSMITTAL and no changes are made if new_root_object does not belong to the given transmittal.
  • 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 invalid;
    2. new_root_object is not a valid handle to a DRM object; or
    3. the function fails for any other reason.

Input parameters

Parameter name

Parameter data type

transmittal

Transmittal

new_root_object

Object

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

old_root_object

Object

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_OUTPUT_OBJECT
DELETED_OBJECT
INVALID_ACCESS_MODE
DIFFERENT_TRANSMITTAL
OUT_OF_MEMORY
INACTIONABLE_FAILURE

 

8.3.79 SetSecondErrorMessage

Table 8.80 — SetSecondErrorMessage

Property Description

Semantics

If an error occurs for a situation where the user has registered an error-handling callback function, that user-defined function is called, and is passed, among other items, two user-defined messages. The second of those messages is set by this function. The first message is set by 8.3.75 SetFirstErrorMessage. These messages allow construction of an intelligent error message that more accurately reflects the status when the error occurred.

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 the function fails for any reason.

Input parameters

Parameter name

Parameter data type

message

String

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

None

 

Success status codes

SUCCESS

Failure status codes

INACTIONABLE_FAILURE

 

8.3.80 SetSpecificCallback

Table 8.81 — SetSpecificCallback

Property Description

Semantics

This function registers the function specified by user_defined_function as the callback function to be called when the status code specified by status_code_to_catch is about to be returned by the API function specified by function_to_catch. This user-defined function shall be of type Status_Logger (see 5.5.3 Status_Logger).

The value NULL for user_defined_function indicates that a callback function is not being requested.

This is the most specific type of callback, a specific status code for a specific function. This callback has priority over a general function callback for the same function (if one is currently defined), and it also has priority over the general callback function (if one is currently defined). The term has priority over means that if a specific status code/specific function callback is defined, it is the only callback that will be called when that particular status code is about to be returned from that particular function.

When an API function returns, it will return the appropriate status code. If the user has defined a callback to be called when that particular status code is about to be returned by that particular function, that user-defined callback function will be called immediately before the function returns the status code. After the user-defined callback has been called, the API function will still return the status code it was about to return. The user-defined callback has no effect on the status code returned. Instead, the user-defined callback simply provides the user a method for tracking the return values of the API functions without explicitly checking each return value.

When this function completes successfully, the following action occurs:

  • Current status code is set to SUCCESS and the callback is set.

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. function_to_catch is invalid;
    2. status_code_to_catch is invalid; or
    3. the function fails for any other reason.

Input parameters

Parameter name

Parameter data type

user_defined_function

Status_Logger

function_to_catch

API_Function

status_code_to_catch

Status_Code

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

None

 

Success status codes

SUCCESS

Failure status codes

INACTIONABLE_FAILURE

 

8.3.81 SetSRFContextInfo

Table 8.82 — SetSRFContextInfo

Property Description

Semantics

This function sets the SRF that will be used to represent all <DRM Location> instances returned after this function is called. This SRF is specified by new_srf_context_info. This function has no effect on <DRM Location> instances that have already been returned to the user before this function was called. Details on the various SRFs supported by this part of ISO/IEC 18023 may be found in ISO/IEC 18026.

The SRF used for returning <DRM Location> instances can be changed as often as desired. After changing to any particular SRF, it is possible to return to the default state where coordinates are returned in the SRF in which they were originally stored in the transmittal by using the 8.3.87 UseDefaultSRFContextInfo function.

SPECIAL EXCEPTION:

Local Space Rectangular 3D (LSR_3D) or Local Space Rectangular 2D (LSR_2D) coordinates will always be returned as LSR_3D/LSR_2D coordinates, regardless of the values passed to SetSRFContextInfo. LSR_3D/LSR_2D coordinates are only converted into another SRF if they are instanced into the scope of another SRF via a model instance with a <DRM World Transformation> instance. If a <DRM Model> instance has been so instanced, and if that instance was traversed to reach the current <DRM Location> instance, and if this API was instructed to transform coordinates when going through transformations, then and only then will LSR_3D/LSR_2D coordinates be transformed into the current scoping SRF.  The various initialize iterator functions specify details on how to instruct this API to transform coordinates when going through transformations.

When this function completes successfully, the following action occurs:

  • Current status code is set to SUCCESS and the current retrieval SRF is set to the SRF specified by new_srf_context_info.

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 memory could not be allocated.
  • Current status code is set to INACTIONABLE_FAILURE and no changes are made if
    1. new_srf_info failed to specify a legal SRF as specified in this part of ISO/IEC 18023; or
    2. the function fails for any other reason.

Input parameters

Parameter name

Parameter data type

new_srf_context_info

SRF_Context_Info

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

None

 

Success status codes

SUCCESS

Failure status codes

OUT_OF_MEMORY
INACTIONABLE_FAILURE

 

8.3.82 SetTransmittalName

Table 8.83 — SetTransmittalName

Property Description

Semantics

Given the transmittal specified by transmittal, this function replaces the formal transmittal name associated with the transmittal to that specified by new_transmittal_name. This function can be used to supply the first name for a transmittal opened using 8.3.62 OpenTransmittalByLocation or to modify the name of a transmittal that was previously named or opened using 8.3.63 OpenTransmittalByName.

Details on the format of the transmittal name may be found under 8.3.73 ResolveTransmittalName.

CAUTION: While setting the transmittal name is desirable in many cases, care should be taken when invoking this function. The API is not responsible for managing configuration and changing control for the transmittal being modified. Calling this function will permanently change the transmittal name associated with the file containing 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 INVALID_TRANSMITTAL_NAME and no changes are made if new_transmittal_name did not specify a name that was valid according to the formal SEDRIS namespace.
  • 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 INACTIONABLE_FAILURE and no changes are made if:
    1. transmittal is not a valid handle to a transmittal; or
    2. the function fails for any other reason.

Input parameters

Parameter name

Parameter data type

transmittal

Transmittal

new_transmittal_name

URN

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

None

 

Success status codes

SUCCESS

Failure status codes

INVALID_TRANSMITTAL_NAME
INVALID_ACCESS_MODE
INACTIONABLE_FAILURE

 

8.3.83 SetUserData

Table 8.84 — SetUserData

Property Description

Semantics

This function associates the handle for user-defined data specified by user_data with the DRM object specified by object. This user data will remain associated with the DRM object until all handles to the DRM object are freed or until SetUserData is again called on any handle to the DRM object. Memory management of the user data is the responsibility of the application.

If user_data is NULL, the presence of user data is reset.

When this function completes successfully, the following action occurs:

  • Current status code is set to SUCCESS and user_data is stored with the DRM object identified by object.

When this function completes in error, the following action 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

Parameter name

Parameter data type

user_data

User_Data

Input/output parameters

Parameter name

Parameter data type

object

Object

Output parameters

Parameter name

Parameter data type

None

 

Success status codes

SUCCESS

Failure status codes

INACTIONABLE_FAILURE

 

8.3.84 TransmittalsAreSame

Table 8.85 — TransmittalsAreSame

Property Description

Semantics

Given the two transmittal handles specified by transmittal_a and transmittal_b, this function determines if the two handles reference the same transmittal. If they reference the same transmittal, result returns the value TRUE. Otherwise, result returns value FALSE.

When this function completes successfully, the following action occurs:

  • Current status code is set to SUCCESS and result returns the result of the evaluation.

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_a and/or transmittal_b is not a handle to a valid, open transmittal; or
    2. the function fails for any other reason.

Input parameters

Parameter name

Parameter data type

transmittal_a

Transmittal

transmittal_b

Transmittal

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

result

Boolean

Success status codes

SUCCESS

Failure status codes

INACTIONABLE_FAILURE

 

8.3.85 UnpublishObject

Table 8.86 — UnpublishObject

Property Description

Semantics

Given the resolved DRM object specified by object, this function removes the DRM object from being published under the label specified by label. The DRM object shall have already been published under the label for this function to complete successfully.

Unpublishing DRM objects may result in a need to change the transmittal name portion of the URN assigned to a transmittal. Using the same transmittal name guarantees that all labels ever published will remain available in future versions of the transmittal. Removing a label using this function will require a transmittal name change if another DRM object is not published under the same label before the transmittal is made publicly available or released.

The transmittal whose DRM object is to be edited shall be explicitly opened in either CREATE or UPDATE 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 unpublished.

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 UNPUBLISHED_OBJECT and no changes are made if object was not published under the specified label.
  • 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:
    1. object is not a valid handle to a DRM object;
    2. label is invalid; or
    3. the function fails for any other reason.

Input parameters

Parameter name

Parameter data type

object

Object

label

String

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

None

 

Success status codes

SUCCESS

Failure status codes

UNRESOLVED_INPUT_OBJECT
UNPUBLISHED_OBJECT
INVALID_ACCESS_MODE
INACTIONABLE_FAILURE

 

8.3.86 UseDefaultColourModel

Table 8.87 — UseDefaultColourModel

Property Description

Semantics

This function places the API into the default colour model state, in which <DRM Colour Data> instances are returned based entirely on the colour model specified in the <DRM Transmittal Summary> component of the <DRM Transmittal Root> instance in the transmittal from which the <DRM Colour Data> instances are extracted. The API will remain in this state until the 8.3.74 SetColourModel function is invoked that takes the API out of the current colour model state and places it into whatever colour model was specified in the 8.3.74 SetColourModel call.

EXAMPLE  If the transmittal was defined with RGB colours, <DRM RGB Colour> instances will be returned as <DRM Colour Data> instances once UseDefaultColourModel is called.

The 8.3.20 GetColourModel function may be invoked to find out what the default colour model is, either immediately after an invocation of UseDefaultColourModel, or at any time before an invocation of 8.3.74 SetColourModel.

This function changes the internal state of the API, determining the colour model used to define <DRM Colour Data> instances returned by this API.

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 the function fails for any reason.

Input parameters

Parameter name

Parameter data type

None

 

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

None

 

Success status codes

SUCCESS

Failure status codes

INACTIONABLE_FAILURE

 

8.3.87 UseDefaultSRFContextInfo

Table 8.88 — UseDefaultSRFContextInfo

Property Description

Semantics

This function places the API into the default SRF state, in which <DRM Location> instances are returned based entirely on the SRF in which they were originally encoded in the transmittal. The API will remain in this state until the user calls 8.3.81 SetSRFContextInfo that takes the API out of the current SRF state and forces the use of whatever SRF was specified by 8.3.81 SetSRFContextInfo.

EXAMPLE  If positions in a transmittal are represented with Augmented Transverse Mercator SRF locations, <DRM TM Augmented 3D Location> instances will be returned as the type of <DRM Location 3D> instances from that transmittal once UseDefaultSRFContextInfo is called.

The 8.3.46 GetSRFContextInfo can be used to find out what the current SRF is, either immediately after a call to UseDefaultSRFInfo, or at any time before a call to 8.3.81 SetSRFContextInfo is made.

Instead of returning a value, this function changes the internal state of the API, determining the SRF used to define <DRM Location> instances returned by this API.

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 the function fails for any reason.

Input parameters

Parameter name

Parameter data type

None

 

Input/output parameters

Parameter name

Parameter data type

None

 

Output parameters

Parameter name

Parameter data type

None

 

Success status codes

SUCCESS

Failure status codes

INACTIONABLE_FAILURE

http://standards.iso.org/ittf/PubliclyAvailableStandards/ISO_IEC_18023-1_Ed1.html