7 Application program interface (API)

Semantics:

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

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

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

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

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

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

1. both the from_object and to_object are published,

2. both the from_object and to_object are resolved and,

3. both transmittals have been opened for writing or modification

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

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

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_ACCESS_MODE and no changes are made, if:
1. from_object (and link_object if specified) is in a transmittal that is open in READ_ONLY mode;
2. to_object is in a transmittal that has not been opened for writing or modification, so no association could be created from to_object.
• Current status code is set to INVALID_OBJECT and no changes are made if:
1. from_object is NULL, has not yet been added to the transmittal, or does not belong to a valid SEDRIS class;
2. to_object is NULL, has not yet been added to the transmittal, or does not belong to a valid SEDRIS class;
3. link_object is non-NULL and either has not yet been added to the transmittal, or does not belong to a valid SEDRIS class; or
4. if a link object is required for the association relationship from to_object to from_object, but link_object is NULL, has not been added to a transmittal, or does not belong to a valid DRM class.
• Current status code is set to UNPUBLISHED_OBJECT and no changes are made if:
1. to_object is in another transmittal than from_object, but is not published by that transmittal; or
2. link_object is in another transmittal than from_object, but is not published by that transmittal; or
3. to_object is in another transmittal than from_object, and make_two_way is TRUE, but from_object is not published by its transmittal.
• Current status code is set to UNRESOLVED_START_OBJECT and no changes are made if:
1. from_object is an unresolved object, or
2. link_object is an unresolved object, or
3. to_object is an unresolved object and make_two_way is TRUE.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_ACCESS_MODE
INVALID_OBJECT
UNPUBLISHED_OBJECT
UNRESOLVED_START_OBJECT
FAILURE

Semantics:

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

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

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

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

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_OBJECT if:
1. aggregate_object is NULL, has not yet been added to the transmittal, or does not belong to a valid SEDRIS class;
2. component_object is NULL, has not yet been added to the transmittal, or does not belong to a valid SEDRIS class;
3. link_object is non-NULL and either has not yet been added to the transmittal, or does not belong to a valid SEDRIS class; or
4. the DRM requires a link object for the association relationship from to_object to from_object, but link_object was NULL, has not been added to a transmittal, or does not belong to a valid SEDRIS class.
• Current status code is set to UNPUBLISHED_OBJECT and no changes are made if both component_object and aggregate_object are resolved, in different transmittals, and either is not published.
• UNRESOLVED_START_OBJECT and no changes are made if:
1. aggregate_object and component_object are both unresolved, or
2. both aggregate_object and component_object are resolved and link_object is not unresolved.
• Current status code is set to INVALID_ACCESS_MODE and no changes are made if:
1. aggregate_object (or link_object if specified) is in a transmittal that is not open for creation or modification,.
2. component_object is in a transmittal that is not open for creation or modification.
• Current status code is set to FAILURE and no changes are made if the relationship could not be created for any other reason.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_OBJECT
UNPUBLISHED_OBJECT
UNRESOLVED_START_OBJECT
INVALID_ACCESS_MODE
FAILURE

Semantics:

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

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and no changes are made if duplicate_object is invalid.
• Current status code is set to INVALID_OBJECT and duplicate_object is set to DRM_NULL if the input parameter is invalid.
• Current status code is set to OUT_OF_MEMORY and duplicate_object is set to DRM_NULL if memory cannot be allocated for the new object handle.
• Current status code is set to FAILURE and object is set to DRM_NULL if this function fails for any other reason.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_REQUIRED_PARAMETER
INVALID_OBJECT
OUT_OF_MEMORY
FAILURE

Semantics:

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

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_TRANSMITTAL and no changes are made if transmittal is not a valid, active transmittal.
• Current status code is set to FAILURE and no changes are made, if transmittal is not an open transmittal.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_TRANSMITTAL
FAILURE

Semantics:

This function converts a CMYK colour value to a CMY colour value.

Incoming data values are expected to be between 0.0 and 1.0, inclusive. Furthermore, after adding the incoming black value to the incoming cyan, magenta, and yellow values, all results are expected to be between 0.0 and 1.0, inclusive. No checking of parameters or results are made by this function. This function does not clamp a result even if the result is greater than 1.0.

The algorithm that will be applied is:

Cyan = incoming Cyan + incoming Black
Magenta = incoming Magenta + incoming Black
Yellow = incoming Yellow + incoming Black

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_PARAMETER and no changes are made, if either parameter is invalid. The output parameter is not modified.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_PARAMETER

Semantics:

This function converts a CMY colour value to a CMYK colour value.

Incoming data values are expected to be between 0.0 and 1.0, inclusive.

The algorithm that will be applied is:

Black = Minimum of
  (incoming Cyan,
   incoming Magenta,
   incoming Yellow)
Cyan = incoming Cyan - Black
Magenta = incoming Magenta - Black
Yellow = incoming Yellow - Black

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_PARAMETER and no changes are made, if either parameter is invalid. The output parameter is not modified.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_PARAMETER

Semantics:

This function converts a colour data value in one colour model to the equivalent colour data value in another colour model.— The three colour models supported by this function are CMY (Cyan Magenta Yellow), HSV (Hue Saturation Value) and RGB (Red Green Blue).

All incoming data values are expected to be between 0.0 and 1.0, inclusive; the only exception is the value for Hue in the HSV colour model, which is expected to be between 0.0 and 360.0 inclusive (360.0 will be automatically converted to 0.0).

The value of POSITIVE_INFINITY will be returned for the Hue value of “undefined”. When converting from HSV to any other system, if the Saturation value is 0.0, the Hue value is ignored.

The conversion algorithms are defined in 2.[I9592].

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and no changes are made, if original_colour is not valid or new_colour is not an accessor for a <DRM Colour Data> instance.
• Current status code is set to INVALID_SOURCE_COLOUR and no changes are made, if original_colour is not a valid <DRM Colour Data> instance.
• Current status code is set to INVALID_NEW_COLOUR_MODEL and no changes are made, if new_colour_model is invalid.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_REQUIRED_PARAMETER
INVALID_SOURCE_COLOUR
INVALID_NEW_COLOUR_MODEL

Semantics:

This function creates a new object. The fields are initialized to the default values for the specified class.

The object is not actually stored in the transmittal until the  AddToTransmittal function is called. Until then, it remains in an  unsaved state, and becomes resolved when added to the transmittal.

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_PARAMETER and no change is made if new_object is invalid.
• Current status code is set to INVALID_TRANSMITTALand new_object is set to DRM_NULL if transmittal is not a handle to a valid, active (i.e., open) transmittal.
• Current status code is set to INVALID_ACCESS_MODE and and new_object is set to DRM_NULL if transmittal was opened in read-only mode.
• Current status code is set to OUT_OF_MEMORY and new_object is set to DRM_NULL if memory cannot be allocated for new_object.
• Current status code is set to FAILURE and new_object is set to DRM_NULL if new_object_type does not correspond to a valid, concrete (i.e., not abstract) DRM class.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_PARAMETER
INVALID_TRANSMITTAL
INVALID_ACCESS_MODE
OUT_OF_MEMORY
FAILURE

Semantics:

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

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

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

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and no changes are made, if either the search_filter or rules parameters are invalid.
• Current status code is set to OUT_OF_MEMORY and search_filter is set to NULL if the API could not allocate memory for the new search filter.
• Current status code is set to INVALID_REQUIRED_PARAMETER and no changes are made, if an illegal expression was specified by the rules parameter (for example, if an AND expression within the array only had one parameter).

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_REQUIRED_PARAMETER
OUT_OF_MEMORY
FAILURE

Semantics:

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

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

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

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and no changes are made, if either the search_bounds or search_boundary are invalid.
• Current status code is set to OUT_OF_MEMORY and search_boundary is set to NULL if the API could not allocate memory for the new search boundary.
• Current status code is set to FAILURE and no changes are made, if:
1. an invalid boundary was specified by the search_bounds parameter (e.g., the minimal and maximal points are not in the same SRF), or
2. an invalid search_bounds_closure, search_quality, inclusion, or search_dimension was specified.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_REQUIRED_PARAMETER
OUT_OF_MEMORY
FAILURE

Semantics:

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

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

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

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and none of the output parameters are modified if the search_bounds parameter is invalid or if all the output parameters are invalid.
• Current status code is set to UNRESOLVED_START_OBJECT and all provided output parameters are set to FALSE  if object is an unresolved SEDRIS object.
• Current status code is set to UNRESOLVED_OBJECT and all provided output parameters are set to FALSE if an unresolved object was encountered and could not be resolved.
• Current status code is set to FAILURE and all output parameters are set to FALSE if:
1. an invalid boundary was specified by the search_bounds parameter (e.g., the minimal and maximal points are not in the same SRF);
2. if an invalid search_bounds_closure, search_quality, or search_dimension was specified; or
3. the determination of the object/search area relationship could not be made.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_REQUIRED_PARAMETER
UNRESOLVED_START_OBJECT
UNRESOLVED_OBJECT
FAILURE

Semantics:

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

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to FAILURE and no changes are made, if to_free was not a valid iterator.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

FAILURE

Semantics:

This function frees the memory directly associated with the specified object handle allocated by this API during an earlier call to a function that retrieved an object handle (e.g., GetNthComponentOfDRMClass, GetNextObject, or CreateObject).

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

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_OBJECT and nothing is changed if to_free was not a valid object.
• Current status code is set to FAILURE and nothing is changed if any implementation-specific error occurs.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_OBJECT
FAILURE

Semantics:

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

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_ACCESS_MODE and to_free is left unaltered if the to_free parameter is invalid.
• Current status code is set to FAILURE no changes are made if any implementation-specific error occurs.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_REQUIRED_PARAMETER
FAILURE

Semantics:

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

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and to_free is left unaltered if to_free is invalid.
• Current status code is set to INVALID_OBJECT and to_free is left unaltered if to_free contains an entry that is not a handle to a valid, active (i.e., unfreed) object, or if to_free contains a non-NULL entry that is not a handle to a valid, active (i.e., unfreed) object.
• Current status code is set to FAILURE and no changes are made if any of the fields of the input parameter are unset.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_REQUIRED_PARAMETER
INVALID_OBJECT
FAILURE

Semantics:

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

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and to_free is left unaltered if to_free is invalid.
• Current status code is set to FAILURE and no changes are made if any implementation-specific error occurs.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_REQUIRED_PARAMETER
FAILURE

Semantics:

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

As this function completes successfully, the following action occurs:

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

As 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 to_free is not a valid search filter.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

FAILURE

Semantics:

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

As this function completes successfully, the following action occurs:

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

As 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 to_free is not a valid spatial search boundary.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

FAILURE

Semantics:

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

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_TRANSMITTAL and no changes are made if to_free is invalid or if to_free was allocated by 7.3.69 OpenTransmittalByLocation or 7.3.70 OpenTransmitalByName.
• Current status code is set to FAILURE, and no changes are made, if any implementation-specific error occurs.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_TRANSMITTAL
FAILURE

Semantics:

This function retrieves the given kind of aggregate object (an aggregate object of the specified DRM class) that directly contains the given object (object) as a component.— For example, if 7.3.21 GetAggregate is called with a <DRM Model> as the object object, the <DRM Model Library> would be returned in object, since the <DRM Model Library> is the aggregate object that contains the <DRM Model> as a component.

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

Given an object (object) and a type of aggregate to search for (drm_class), this function looks for an immediate aggregate object of the given type. Only aggregates that include the object via a two-way aggregation will be returned by this function.

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

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

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and no changes are made, if object is invalid.
• Current status code is set to INVALID_OBJECT and no changes are made, if object is invalid or drm_class specifies an invalid value. In this case, the output parameters return NULL.
• Current status code is set to UNRESOLVED_START_OBJECT and the output parameters return NULL if object is unresolved.
• Current status code is set to NO_OBJECT and the output parameters return NULL if no aggregate object of the specified DRM class could be found.
• Current status code is set to OUT_OF_MEMORY and the output parameters return NULL if memory could not be allocated.
• Current status code is set to FAILURE and the output parameters return NULL if itr_traversal is not valid.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS
DIFFERENT_TRANSMITTAL
UNRESOLVED_OBJECT

Failure status codes:

INVALID_REQUIRED_PARAMETER
INVALID_OBJECT
UNRESOLVED_START_OBJECT
NO_OBJECT
OUT_OF_MEMORY
FAILURE

Semantics:

This function retrieves the given kind of associated object from the given object.

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

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

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

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

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and no changes are made, if object is invalid.
• Current status code is set to INVALID_OBJECT and no changes are made, if object is invalid or drm_class specifies an invalid value. In this case, the output parameters return NULL.
• Current status code is set to UNRESOLVED_START_OBJECT and the output parameters return NULL if object is unresolved.
• Current status code is set to NO_OBJECT and the output parameters return NULL if no aggregate object of the specified DRM class could be found.
• Current status code is set to OUT_OF_MEMORY and the output parameters return NULL if memory could not be allocated.
• Current status code is set to FAILURE and the output parameters return NULL if itr_traversal is not valid.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS
DIFFERENT_TRANSMITTAL
UNRESOLVED_OBJECT

Failure status codes:

INVALID_REQUIRED_PARAMETER
INVALID_OBJECT
UNRESOLVED_START_OBJECT
NO_OBJECT
OUT_OF_MEMORY
FAILURE

Semantics:

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

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

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

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and colour_model is not affected, if colour_model was invalid.
• Current status code is set to and colour_model is not affected, if transmittal is not a handle to a valid, active (i.e., open and unfreed) transmittal.
• Current status code is set to FAILURE and colour_model is not affected if the default colour model is in effect but transmittal does not specify a colour model.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_REQUIRED_PARAMETER
INVALID_TRANSMITTAL
FAILURE

Semantics:

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

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

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

An “immediate” component will always take precedence over an “inherited” component.

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

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

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

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

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and no changes are made, if object is invalid.
• Current status code is set to INVALID_OBJECT and no changes are made, if object is invalid or drm_class specifies an invalid value. In this case, the output parameters return NULL.
• Current status code is set to UNRESOLVED_START_OBJECT and the output parameters return NULL if object is unresolved.
• Current status code is set to NO_OBJECT and the output parameters return NULL if no aggregate object of the specified DRM class could be found.
• Current status code is set to OUT_OF_MEMORY and the output parameters return NULL if memory could not be allocated.
• Current status code is set to FAILURE and the output parameters return NULL if itr_traversal is not valid.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS
DIFFERENT_TRANSMITTAL
UNRESOLVED_OBJECT

Failure status codes:

INVALID_REQUIRED_PARAMETER
INVALID_OBJECT
UNRESOLVED_START_OBJECT
NO_OBJECT
OUT_OF_MEMORY
FAILURE

Semantics:

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

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

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

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

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and matrix is left unchanged, if matrix is invalid.
• Current status code is set to INVALID_OBJECT and the identity matrix is returned, if object is not valid.
• Current status code is set to UNRESOLVED_START_OBJECT and the identity matrix is returned, if object is unresolved.
• Current status code is set to FAILURE and the identity matrix is returned, if any implementation-specific error occurs.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_REQUIRED_PARAMETER
INVALID_OBJECT
UNRESOLVED_START_OBJECT
FAILURE

Semantics:

Given a <DRM_Data_Table> instance, 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.

As this function completes successfully, the following action occurs:

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

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

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

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

UNRESOLVED_START_OBJECT
DELETED_OBJECT
OUT_OF_MEMORY
INACTIONABLE_FAILURE

Semantics:

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

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and object_type is left unaltered if object_type is not valid.
• Current status code is set to INVALID_OBJECT and object_type returns NULL if object is not valid.
• Current status code is set to UNRESOLVED_OBJECT and object_type returns NULL if object is not valid.
• Current status code is set to FAILURE and object_type returns NULL if any implementation-specific error occurs.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_REQUIRED_PARAMETER
INVALID_OBJECT
UNRESOLVED_OBJECT
FAILURE

Semantics:

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

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_OBJECT and the NULL field value is returned if object is not a valid SEDRIS object.
• Current status code is set to UNRESOLVED_OBJECT and the NULL field value is returned if object is an unresolved object.
• Current status code is set to OUT_OF_MEMORY and the NULL field value is returned if the implementation was unable to allocate sufficient memory.
• Current status code is set to FAILURE and the NULL field value is returned if any implementation-specific error occurs.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_OBJECT
UNRESOLVED_OBJECT
OUT_OF_MEMORY
FAILURE

Semantics:

This function returns an ID text string for the specified object.

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and id is unaffected if id is NULL.
• Current status code is set to INVALID_OBJECT and id is set to to the empty string if object is not a valid SEDRIS object.
• Current status code is set to UNRESOLVED_OBJECT and id is set to the empty string if object is an unresolved object.
• Current status code is set to FAILURE and id is set to the empty string if the ID string cannot be retrieved for any other reason.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_REQUIRED_PARAMETER
INVALID_OBJECT
UNRESOLVED_OBJECT
FAILURE

Semantics:

This function copies the selected texels from the selected area of interest of the given <DRM Image> instance into a space in memory that the user has already allocated to hold this data.

A <DRM Image> is a set of 2D or 3D collections of texel values. The number of MIP levels for the <DRM Image> defines the number of 2D or 3D collections in the <DRM Image>. The definition of the <DRM Image> will define the number of texels in each MIP level and the number of bits (not just bytes, but bits) for each texel.

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and data is unaffected if data is invalid.
• Current status code is set to INVALID_OBJECT and data is returned NULL if image is not a valid <DRM Image> object.
• Current status code is set to UNRESOLVED_OBJECT and data is returned NULL if image is an unresolved object.
• 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 FAILURE and data is returned NULL , if:
1. no image data has yet been specified for image;
2. mip_level s invalid for image;
3. level_count of image is zero or its mip_fields_array is empty; or
4. any of the start or stop texels were invalid for image.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_REQUIRED_PARAMETER
INVALID_OBJECT
UNRESOLVED_OBJECT
OUT_OF_MEMORY
FAILURE

Semantics:

Given a handle to an object, this function returns the implementation identifier associated with the API implementation in which that object resides.

As this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and the implementation identifier associated with the object’s API implementation is returned if valid parameters were passed in.

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and implementation_identifier is left unaltered if implementation_identifier is invalid.
• Current status code is set to INVALID_OBJECT and implementation_identifier is left unaltered if image is not a valid SEDRIS object.
• Current status code is set to FAILURE and and implementation_identifier is left unaltered if: any implementation-specific error occurs.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_REQUIRED_PARAMETER
INVALID_OBJECT
FAILURE

Semantics:

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

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and count is left unaltered if count is invalid.
• Current status code is set to FAILURE and count is left unaltered if count is invalid.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_REQUIRED_PARAMETER
FAILURE

Semantics:

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

The last_function_status returns the status of the last function call. The error_description parameter will contain information about the status code returned in last_function_status. The value of error_description shall be NULL if the last function completed successfully.

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INACTIONABLE_FAILURE when any error occurs and last_function_status nor error_description are left unaltered. The current error description shall be set to a value that reflects the reason why this function failed.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INACTIONABLE_FAILURE

Semantics:

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

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

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

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and the output parameter values are left unaltered if next_object is NULL.
• Current status code is set to UNRESOLVED_OBJECT and the output parameter values are left unaltered if next_object is NULL.
• Current status code is set to NO_OBJECT and the output parameter values are left unaltered if next_object is NULL.
• Current status code is set to OUT_OF_MEMORY and the output parameter values are left unaltered if next_object is NULL.
• Current status code is set to FAILURE and the output parameter values are left unaltered if next_object is NULL.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS
DIFFERENT_TRANSMITTAL

Failure status codes:

INVALID_REQUIRED_PARAMETER
UNRESOLVED_OBJECT
NO_OBJECT
OUT_OF_MEMORY
FAILURE

Semantics:

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

As this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and the desired associate object is returned in associate_object and link_class_object is set appropriately if valid parameters were passed in and all operations succeeded.
• Current status code is set to UNRESOLVED_OBJECT and the output parameters are set as for the SUCCESS case if valid parameters were passed in and valid objects are returned, but the object returned in associate_object is unresolved.

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and the output parameter values are left unaltered if associate_object is NULL.
• Current status code is set to INVALID_OBJECT and the output parameter values are left unaltered if associate_object is NULL.
• Current status code is set to UNRESOLVED_START_OBJECT and the output parameters are returned NULL if from_object is an unresolved SEDRIS object.
• Current status code is set to NO_OBJECT and the output parameters are returned NULL if the from_object did not contain n associate objects of the desired class.
• Current status code is set to OUT_OF_MEMORY and the output parameters are returned NULL if sufficient memory could not be allocated.
• Current status code is set to FAILURE and the output parameters are returned NULL if:
1. n was zero (since this is a one-based index),
2. an invalid value was supplied for desired_associate_class, or
3. the given class of associate is not ordered for the given from_object.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS
UNRESOLVED_OBJECT

Failure status codes:

INVALID_REQUIRED_PARAMETER
INVALID_OBJECT
UNRESOLVED_START_OBJECT
NO_OBJECT
OUT_OF_MEMORY
FAILURE

Semantics:

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

As this function completes successfully, the following action occurs:

• Current status code is set to SUCCESS and the n^th component object is returned in component_object  and link_class_object is set appropriately if valid parameters were passed in and all operations succeeded.
• Current status code is set to UNRESOLVED_OBJECT and the output parameters are set as for the SUCCESS case if valid parameters were passed in and valid objects are returned, but the object returned in component_object is unresolved.

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and the output parameter values are left unaltered if component_object is NULL.
• Current status code is set to INVALID_OBJECT and the output parameters are set to NULL if aggregate_object is not a valid object.
• Current status code is set to UNRESOLVED_START_OBJECT and the output parameters are returned NULL if aggregate_object is an unresolved SEDRIS object.
• Current status code is set to NO_OBJECT and the output parameters are returned NULL if the aggregate_object did not contain n associate objects of the desired class.
• Current status code is set to OUT_OF_MEMORY and the output parameters are returned NULL if sufficient memory could not be allocated.
• Current status code is set to FAILURE and the output parameters are returned NULL if:
1. n was zero (since this is a one-based index),
2. an invalid value was supplied for desired_component_class, or
3. the given class of component is not ordered for the given aggregate_object .

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS
UNRESOLVED_OBJECT

Failure status codes:

INVALID_REQUIRED_PARAMETER
INVALID_OBJECT
UNRESOLVED_START_OBJECT
NO_OBJECT
OUT_OF_MEMORY
FAILURE

Semantics:

This function returns the SEDRIS object corresponding to the specified ID.

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and no changes are made, if object is NULL.
• Current status code is set to INVALID_OBJECT and object is set to NULL if id is not a valid object identifier.
• Current status code is set to FAILURE and object is set to NULL if any implementation-specific error occurs.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_REQUIRED_PARAMETER
INVALID_OBJECT
FAILURE

Semantics:

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

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

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and reference_count is left unaltered if reference_count was NULL.
• Current status code is set to INVALID_OBJECT and reference_count is set to zero (0) if object is not a valid SEDRIS object.
• Current status code is set to FAILURE and reference_count t is set to zero (0) if the function cannot execute successfully due to an implementation dependent problem.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_REQUIRED_PARAMETER
INVALID_OBJECT
FAILURE
OUT_OF_MEMORY

Semantics:

Given a SEDRIS object, this function returns the labels under which the object was published.

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and the output parameter values are left unaltered, if either label_list is NULL or number_labels is invalid.
• Current status code is set to INVALID_OBJECT and label_list is returned empty if object is not a valid object.
• Current status code is set to UNRESOLVED_OBJECT and label_list is returned empty if object is not a resolved object.
• Current status code is set to UNPUBLISHED_OBJECT and label_list is returned empty if object is not a published object.
• Current status code is set to FAILURE and label_list is returned empty if the function fails for any other reason.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_REQUIRED_PARAMETER
INVALID_OBJECT
UNRESOLVED_OBJECT
UNPUBLISHED_OBJECT
FAILURE

Semantics:

Given a transmittal, this function returns a list of objects published by that transmittal for possible reference using ITR.

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and the output parameters are left unchanged if either of the two output parameters are invalid.
• Current status code is set to INVALID_TRANSMITTAL and published_object_list is returned empty if transmittal is not a valid transmittal.
• Current status code is set to OUT_OF_MEMORY and published_object_list is returned empty if memory could not be allocated.
• Current status code is set to FAILURE and published_object_list is returned empty if any implementation-specific error occurs.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_REQUIRED_PARAMETER
INVALID_TRANSMITTAL
OUT_OF_MEMORY
FAILURE

Semantics:

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

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and the output parameters are left unaltered if either of the two output parameters are invalid.
• Current status code is set to INVALID_TRANSMITTAL and an empty list is returned if transmittal is not a valid transmittal.
• Current status code is set to OUT_OF_MEMORY and an empty list is returned if memory could not be allocated.
• Current status code is set to FAILURE and an empty list is returned if any implementation-specific error occurs.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_REQUIRED_PARAMETER
INVALID_TRANSMITTAL
OUT_OF_MEMORY
FAILURE

Semantics:

Given an object, this function returns the counts of

1. the number of components,

2. the number of aggregates, and

3. the number of associates

that the specified object has.

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to UNRESOLVED_START_OBJECT and no changes are made, if object is a handle to an unresolved object.
• Current status code is set to DELETED_OBJECT and no changes are made, if object is a handle to an object that had been removed from its transmittal.
• Current status code is set to INACTIONABLE_FAILURE if the function failed for any other reason.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

UNRESOLVED_START_OBJECT
DELETED_OBJECT
INACTIONABLE_FAILURE

Semantics:

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

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

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

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

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and remaining_objects is left unaltered if remaining_objects is invalid.
• Current status code is set to NO_OBJECT and remaining_objects is returned with a zero (0) count and empty lists if the iterator is out of objects to return.
• Current status code is set to OUT_OF_MEMORY and remaining_objects is returned with a zero (0) count and empty lists if memory could not be allocated.
• Current status code is set to FAILURE and remaining_objects is returned with a zero (0) count and empty lists if this function fails for any other reason.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS
DIFFERENT_TRANSMITTAL
UNRESOLVED_OBJECT

Failure status codes:

INVALID_REQUIRED_PARAMETER
NO_OBJECT
OUT_OF_MEMORY
FAILURE

Semantics:

This function iterates over the remaining objects available through an iterator and returns packed hierarchies for all of them at one time.

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

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

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

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and remaining_hierarchies is left unaltered if remaining_hierarchies is invalid.
• Current status code is set to NO_OBJECT and remaining_hierarchies is returned empty if the iterator is out of objects to return.
• Current status code is set to FAILURE and remaining_hierarchies is returned empty if the iterator is invalid.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS
DIFFERENT_TRANSMITTAL
UNRESOLVED_OBJECT

Failure status codes:

INVALID_REQUIRED_PARAMETER
NO_OBJECT
FAILURE

Semantics:

Given a transmittal, this function returns the SEDRIS object that has been stored as root of the transmittal object hierarchy.

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and root_object is left unaltered if root_object is invalid.
• Current status code is set to INVALID_TRANSMITTAL and root_object is set to NULL if transmittal is not a valid transmittal.
• Current status code is set to FAILURE and root_object is set to NULL if the transmittal does not have a root object.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_REQUIRED_PARAMETER
INVALID_TRANSMITTAL
FAILURE

Semantics:

This function returns a value that can be used as a sort key for the object. The value of sort_key is valid only as long as the object is referenced by at least one object handle.

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and sort_key is left unaltered if sort_key is invalid.
• Current status code is set to INVALID_OBJECT and sort_key returns a zero if the object is not a valid SEDRIS object.
• Current status code is set to FAILURE and sort_key returns a zero if any implementation-specific error occurs.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_REQUIRED_PARAMETER
INVALID_OBJECT
FAILURE

Semantics:

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

More details are available under 7.3.92 SetSRFParameters.

The answer depends on the last call made to 7.3.92 SetSRFParameters and/or 7.3.98 UseDefaultSRFParameters and the manner in which the transmittal was produced.

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

Case 2: 7.3.98 UseDefaultSRFParameters was called more recently than 7.3.92 SetSRFParameters, or 7.3.92 SetSRFParameters was never called. In this case, the retrieval SRF that will be used to define <DRM Location> objects from the given transmittal depends entirely on the transmittal. The retrieval SRF used to return data will be the retrieval SRF that was used when producing the transmittal. This is the default case. If the supplied object does not fall within the scope of any SRF, the SRF parameters are undefined and 7.3.51 GetSRFParameters will return FAILURE.

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and srf_parameters is left unaltered if srf_parameters is invalid.
• Current status code is set to INVALID_OBJECT and srf_parameters is left unaltered if the object is not valid.
• Current status code is set to FAILURE and srf_parameters is left unaltered if the specified object has no scoping SRF and either 7.3.98 UseDefaultSRFParameters was called more recently than 7.3.92 SetSRFParameters or 7.3.92 SetSRFParameters was never called.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_REQUIRED_PARAMETER
INVALID_OBJECT
FAILURE

Semantics:

Given a SEDRIS object, this function retrieves the transmittal in which the object is contained.

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and transmittal is unaffected if transmittal is invalid.
• Current status code is set to INVALID_OBJECT and transmittal is set to NULL if object is not a valid object from an open transmittal.
• Current status code is set to UNRESOLVED_START_OBJECT and transmittal is set to NULL if object is unresolved.
• Current status code is set to OUT_OF_MEMORY and transmittal is set to NULL if memory could not be allocated.
• Current status code is set to FAILURE and transmittal is set to NULL if any implementation-specific error occurs.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_REQUIRED_PARAMETER
INVALID_OBJECT
UNRESOLVED_START_OBJECT
OUT_OF_MEMORY
FAILURE

Semantics:

Given a handle to a transmittal, this function retrieves the location associated with the transmittal and transmittal referenced a valid, open transmittal.

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and location is left unaltered if location is invalid.
• Current status code is set to INVALID_TRANSMITTAL and location is set to an empty string if transmittal is not a valid open transmittal.
• Current status code is set to OUT_OF_MEMORY and location is set to an empty string if memory could not be allocated.
• Current status code is set to FAILURE and location is set to an empty string if the function fails for any other reason.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_REQUIRED_PARAMETER
INVALID_TRANSMITTAL
OUT_OF_MEMORY
FAILURE

Semantics:

Given a handle to a transmittal, this function returns the formal transmittal name associated with the transmittal.

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and name is left unaltered if name is invalid.
• Current status code is set to INVALID_TRANSMITTAL and name is returned as an empty URN if transmittal is not a valid, open SEDRIS transmittal.
• Current status code is set to OUT_OF_MEMORY and name is returned as an empty URN if memory could not be allocated.
• Current status code is set to FAILURE and name is returned as an empty URN if this function fails for any other reason.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_REQUIRED_PARAMETER
INVALID_TRANSMITTAL
OUT_OF_MEMORY
FAILURE

Semantics:

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

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and none of the output parameters are affected if any output parameter is invalid.
• Current status code is set to INVALID_TRANSMITTAL and none of the output parameters are affected if any output parameter is invalid.
• Current status code is set to FAILURE and none of the output parameters are affected if any output parameter is invalid.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_REQUIRED_PARAMETER
INVALID_TRANSMITTAL
FAILURE

Semantics:

Given a transmittal, this function retrieves a string identifier for the associated transmittal that can then be compared with identifiers from other transmittals.

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and identifier is left unchanged if identifier is invalid.
• Current status code is set to INVALID_TRANSMITTAL and identifier is returned empty if transmittal is not a valid open transmittal.
• Current status code is set to OUT_OF_MEMORY and identifier is returned empty if sufficient memory could not be allocated.
• Current status code is set to FAILURE and identifier is returned empty if any implementation-specific error occurs.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_REQUIRED_PARAMETER
INVALID_TRANSMITTAL
OUT_OF_MEMORY
FAILURE

Semantics:

This function creates an unresolved reference to an object based on the combination of transmittal name and object label.

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

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and object remains unaltered if transmittal_name, object_label, or object is invalid.
• Current status code is set to INVALID_TRANSMITTAL_NAME and object returns NULL if the transmittal URN is not valid according to the SEDRIS URN syntax rules.
• Current status code is set to INVALID_OBJECT_LABEL and object returns NULL if object_label is not valid according to the label syntax rules.
• Current status code is set to FAILURE and object returns NULL if any implementation-specific error occurs.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_REQUIRED_PARAMETER
INVALID_TRANSMITTAL_NAME
INVALID_OBJECT_LABEL
FAILURE

Semantics:

This function returns the current value of the user data for the given object.

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and user_data is left unaltered if user_data is invalid.
• Current status code is set to INVALID_OBJECT and user_data is set to NULL if object is not a valid SEDRIS object.
• Current status code is set to UNRESOLVED_OBJECT and user_data is set to NULL if object is not a currently resolved object.
• Current status code is set to FAILURE and user_data is set to NULL if any implementation-specific error occurs.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_REQUIRED_PARAMETER
INVALID_OBJECT
UNRESOLVED_OBJECT
FAILURE

Semantics:

This function creates an iterator that traverses over the list of aggregate objects returning handles to those that meet the following conditions:

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

2. They satisfy the rules specified in the search filter, if a search filter is defined for the iterator. If NULL is passed in for the search filter, no filtering is applied, and only condition a) need be satisfied.

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

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

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

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and iterator is left unaltered if iterator is invalid.
• Current status code is set to INVALID_OBJECT and iterator returns NULL if start_object is not a valid, active (i.e., unfreed) SEDRIS object.
• Current status code is set to UNRESOLVED_START_OBJECT and iterator returns NULL if start_object is unresolved.
• Current status code is set to OUT_OF_MEMORY and iterator returns NULL if sufficient memory could not be allocated.
• Current status code is set to FAILURE and iterator returns NULL if:
1. itr_traversal is not valid; or
2. a search filter is provided, but is not a handle to a valid, active (i.e., unfreed) search filter.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_REQUIRED_PARAMETER
INVALID_OBJECT
UNRESOLVED_START_OBJECT
OUT_OF_MEMORY
FAILURE

Semantics:

This function creates an iterator that traverses over the list of associate objects returning handles to those that meet the following conditions:

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

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

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

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

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

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and iterator is left unaltered if iterator is invalid.
• Current status code is set to INVALID_OBJECT and iterator returns NULL if start_object is not a valid, active (i.e., unfreed) SEDRIS object.
• Current status code is set to UNRESOLVED_START_OBJECT and iterator returns NULL if start_object is unresolved.
• Current status code is set to OUT_OF_MEMORY and iterator returns NULL if sufficient memory could not be allocated.
• Current status code is set to FAILURE and iterator returns NULL if:
1. itr_traversal is not valid; or
2. a search filter is provided, but is not a handle to a valid, active (i.e., unfreed) search filter.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_REQUIRED_PARAMETER
INVALID_OBJECT
UNRESOLVED_START_OBJECT
OUT_OF_MEMORY

Semantics:

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

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

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

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

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

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

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

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

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

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

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

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

If the transform_locations parameter has value TRUE, all <DRM Location> objects shall be transformed according to the transformations (<DRM LSR Transformation>s and/or <DRM World Transformation>) 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 (it will “instance” the model). The same logic applies to the <DRM Feature Model Instance> to <DRM Feature Model> association.

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

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

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

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

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and iterator is left unaltered if iterator is invalid.
• Current status code is set to INVALID_OBJECT and iterator returns NULL if start_object is not a valid, active (i.e., unfreed) SEDRIS object.
• Current status code is set to UNRESOLVED_START_OBJECT and iterator returns NULL if start_object is unresolved.
• Current status code is set to OUT_OF_MEMORY and iterator returns NULL if sufficient memory could not be allocated.
• Current status code is set to FAILURE and iterator returns NULL if:
1. itr_traversal is not valid;

2. general_traversal_pattern is not valid;

3. selection_parameters are provided but are not valid;

4. traversal order parameters are provided, but are not valid;

5. a search filter is provided, but is not a valid, active (i.e., unfreed) search filter;

6. a spatial search boundary is provided, but is not a legal, valid spatial search boundary for the scope of start_object; or

7. the start_object, search filter, and/or spatial search boundary came from different transmittals.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_REQUIRED_PARAMETER
INVALID_OBJECT
UNRESOLVED_START_OBJECT
OUT_OF_MEMORY
FAILURE

Semantics:

This function creates an iterator that traverses over the list of component objects returning handles to those that are inherited. This function should be used if only inherited components are to be identified.

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

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

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and iterator is left unaltered if iterator is invalid.
• Current status code is set to INVALID_OBJECT and iterator returns NULL if start_object is not a valid, active (i.e., unfreed) SEDRIS object.
• Current status code is set to UNRESOLVED_START_OBJECT and iterator returns NULL if start_object is unresolved.
• Current status code is set to OUT_OF_MEMORY and iterator returns NULL if sufficient memory could not be allocated.
• Current status code is set to FAILURE and iterator returns NULL if:
1. itr_traversal is not valid;

2. a search filter is provided, but is not a valid, active (i.e., unfreed) search filter;

3. the start_object and/or search filter came from different transmittals.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_REQUIRED_PARAMETER
INVALID_OBJECT
UNRESOLVED_START_OBJECT
OUT_OF_MEMORY
FAILURE

Semantics:

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

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INACTIONABLE_FAILURE and result is set to FALSE, if the function failed for any reason.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INACTIONABLE_FAILURE

Semantics:

Given a SEDRIS object, this function determines whether the specified object has been published or not.

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and result is left unaltered if result is invalid.
• Current status code is set to INVALID_OBJECT and result is set to FALSE if object is not a valid, active (i.e., unfreed) SEDRIS object.
• Current status code is set to UNRESOLVED_OBJECT and result is set to FALSE if object is not a resolved object.
• Current status code is set to FAILURE and result is set to FALSE if any implementation-specific error occurs.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_REQUIRED_PARAMETER
INVALID_OBJECT
UNRESOLVED_OBJECT
FAILURE

Semantics:

Given a SEDRIS object, this function determines if the specified object is resolved.

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and result is left unaltered if result is invalid.
• Current status code is set to INVALID_OBJECT and result returns FALSE if object is not a valid, active (i.e., unfreed) SEDRIS object.
• Current status code is set to FAILURE and result is set to FALSE if the function fails for any other reason.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_REQUIRED_PARAMETER
INVALID_OBJECT
FAILURE

Semantics:

This function determines if two object handles both refer to the same object.

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and result is left unaltered if result is invalid.
• Current status code is set to INVALID_OBJECT and result returns FALSE if either object1 or object2 is not a valid SEDRIS object.
• Current status code is set to UNRESOLVED_OBJECT and result returns FALSE if object1 or object2 is not a currently resolved object.
• Current status code is set to FAILURE and result returns FALSE if any implementation-specific error occurs.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_REQUIRED_PARAMETER
INVALID_OBJECT
UNRESOLVED_OBJECT
FAILURE

Semantics:

This function opens a SEDRIS transmittal for access, based on the mode specified. This function specifies the SEDRIS transmittal to be opened using the location of the file containing the SEDRIS transmittal and its objects.

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and transmittal is left unaltered if transmittal is invalid.
• Current status code is set to TRANSMITTAL_INACCESSIBLE and transmittal returns NULL if the location was not accessible.
• Current status code is set to INVALID_ACCESS_MODE and transmittal returns NULL if the location was found but the security permissions of the underlying file system prohibit access to the file in the mode specified. This can occur if:
1. the file was opened for read-only or update and the file did not exist, or
2. the file location specified a non-local file and the API had no transport mechanism for accessing the remote file.
• Current status code is set to UNSUPPORTED_FORMAT and transmittal returns NULL if the implementation_identifier parameter or the default file extension specified a format that is not supported by the SEDRIS implementation.
• Current status code is set to OUT_OF_MEMORY and transmittal returns NULL if sufficient memory could not be allocated.
• Current status code is set to FAILURE and transmittal returns NULL if any implementation-specific error occurs.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_REQUIRED_PARAMETER
TRANSMITTAL_INACCESSIBLE
INVALID_ACCESS_MODE
UNSUPPORTED_FORMAT
OUT_OF_MEMORY
FAILURE

Semantics:

This function opens a SEDRIS transmittal for access, based on the mode specified. This function specifies the SEDRIS transmittal to be opened using the formal transmittal name of the SEDRIS transmittal. The formal name of the SEDRIS transmittal is resolved automatically based on the process described for the function 7.3.84 ResolveTransmittalName.

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and transmittal is left unaltered if transmittal is invalid.
• Current status code is set to INVALID_TRANSMITTAL_NAME and transmittal returns NULL if transmittal_name did not specify a name that was valid according to the format of the SEDRIS namespace.
• Current status code is set to UNRESOLVED_TRANSMITTAL and transmittal returns NULL if transmittal_name could not be resolved to a file location.
• Current status code is set to TRANSMITTAL_INACCESSIBLE and transmittal out returns NULL if the transmittal location was not accessible.
• Current status code is set to INVALID_ACCESS_MODE and transmittal returns NULL if:
  1. the resolved file location was found, but the security permissions of the underlying file system prohibited access to the file in the mode specified. This could occur if the access mode specified was create or update and the file was marked read-only, or if no access was permitted for the account running the application.
  2. if create or update mode was requested and the API implementation does not support the write capability.
• Current status code is set to UNSUPPORTED_FORMAT and transmittal returns NULL if the resolved transmittal_name referenced a format that is not supported by the implementation(s) of the SEDRIS API linked to the application.
• Current status code is set to OUT_OF_MEMORY and transmittal returns NULL if sufficient memory could not be allocated.
• Current status code is set to FAILURE and transmittal returns NULL if any implementation-specific error occurs.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_REQUIRED_PARAMETER
INVALID_TRANSMITTAL_NAME
UNRESOLVED_TRANSMITTAL
TRANSMITTAL_INACCESSIBLE
INVALID_ACCESS_MODE
UNSUPPORTED_FORMAT
OUT_OF_MEMORY
FAILURE

Semantics:

Given a resolved SEDRIS object, this function makes the object available for ITR referencing by listing it as “published” within the transmittal. If the object has already been published, the new label is added to the list of labels for the object.

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

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_REQUIRED_PARAMETER and object is not published if label is an empty string.
• Current status code is set to INVALID_OBJECT and object is not published if object is not a valid, active (i.e., unfreed) SEDRIS object.
• Current status code is set to UNRESOLVED_OBJECT and object is not published if object is unresolved.
• Current status code is set to INVALID_OBJECT_LABEL and object is not published if label does not adhere to the required conventions or is already in use.
• Current status code is set to INVALID_ACCESS_MODE and object is not published if object belongs to a transmittal opened in read-only mode.
• Current status code is set to FAILURE and object is not published if any implementation-specific error occurs.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

INVALID_REQUIRED_PARAMETER
INVALID_OBJECT
UNRESOLVED_OBJECT
INVALID_OBJECT_LABEL
INVALID_ACCESS_MODE
FAILURE

Semantics:

Given a <DRM_Data_Table> instance, this function inserts the selected cell elements from the selected area of interest into the transmittal.

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to UNRESOLVED_START_OBJECT and no changes are made,  if data_table was a handle to an unresolved object.
• Current status code is set to DELETED_OBJECT and no changes are made, if data_table was a handle to an object that had 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 belongs was opened in read only mode.
• Current status code is set to INACTIONABLE_FAILURE and no changes are made, if the function failed for any other reason.

Input parameters:

Input/output parameters:

Output parameters:

Success status codes:

SUCCESS

Failure status codes:

UNRESOLVED_START_OBJECT
DELETED_OBJECT
INVALID_ACCESS_MODE
INACTIONABLE_FAILURE

Semantics:

This function modifies the fields of  existing_object which is an object returned from the API.

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

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

As this function completes successfully, the following action occurs:

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

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

• Current status code is set to INVALID_ACCESS_MODE and existing_object is left unaltered if existing_object is not a valid, active (i.e., unfreed) SEDRIS object.
• Current status code is set to UNRESOLVED_OBJECT and existing_object is left unaltered if existing_object is unresolved.
• Current status code is set to INVALID_ACCESS_MODE and existing_object is left unaltered if existing_object belongs to a transmittal opened in read-only mode.
• Current status code is set to OUT_OF_MEMORY and existing_object is left unaltered if sufficient memory for the new fields could not be allocated.
• Current status code is set to FAILURE and existing_object is left unaltered if:
1. the class of new_fields does not match the class of existing_object; or
2. new_fields contained invalid field values for the DRM class of existing_object.