ISO/IEC WD6 18023-1:200x(E) -- 7 Application programmer interface (API)

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

7.2 Document conventions and notations

The following convention is used to present information about the SEDRIS API. Table 7.2 itemizes the different properties of the API funcitons. All functions use only the DRM classes defined in 6 DRM class definitions and data types defined in 5 Fundamental data types. Only the properties which apply to the particular function are listed. Parameters that are optional are enclosed in braces.

Table 7.2 — SEDRIS API presentation format

Property

Description

Purpose:

Input parameters:

parameter_name	Parameter_Data_Type
parameter_i	Data_Type_For_Parameter_i

Output parameters:

parameter_name	Parameter_Data_Type
parameter_o	Data_Type_For_Parameter_o

Valid return codes:

7.3 API functions

7.3.1 Overview

The functions declared in this file are used to create, modify, and access SEDRIS transmittals.

7.3.2 AddAssociateRelationship

Table 7.3 — AddAssociateRelationship

Property

Description

Purpose:

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

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

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

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

d) 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:

e) both the from_object and to_object are published,

f) both the from_object and to_object are resolved and,

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

Input parameters:

parameter_name	Parameter_Data_Type
from_object	Object
to_object	Object
link_object	Object
make_two_way	Boolean

Output parameters:

parameter_name	Parameter_Data_Type
none

Valid return codes:

SUCCESS if valid parameters were passed in and all operations succeeded.

INVALID_OBJECT if:

a) from_object is NULL, has not yet been added to the transmittal, or does not belong to a valid SEDRIS class;

b) to_object is NULL, has not yet been added to the transmittal, or does not belong to a valid SEDRIS class;

c) link_object is non-NULL and either has not yet been added to the transmittal, or does not belong to a valid SEDRIS class.

UNPUBLISHED_OBJECT no changes are made, if:

d) to_object is in another transmittal than from_object, but is not published by that transmittal; or

e) link_object is in another transmittal than from_object, but is not published by that transmittal; or

f) to_object is in another transmittal than from_object, and make_two_way is TRUE, but from_object is not published by its transmittal.

UNRESOLVED_START_OBJECT no changes are made, if

g) from_object is an unresolved object, or

h) link_object is an unresolved object, or

i) to_object is an unresolved object and make_two_way is TRUE.

INVALID_ACCESS_MODE no changes are made, if

j) from_object (and link_object if specified) is in a transmittal that is open in READ_ONLY mode;

k) to_object is in a transmittal that has not been opened for writing or modification, so no association could be created from to_object.

FAILURE and no changes are made, if the relationship cannot be added for any other reason.

7.3.3 AddComponentRelationship

Table 7.4 — AddComponentRelationship

Property

Description

Purpose:

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

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

b) aggregate_object shall reside in a transmittal that has been explicitly opened with either access mode CREATE or access mode UPDATE.

c) component_object, if component_object is resolved and not in the same transmittal as aggregate_object, shall be a published object.

d) link_object, if not in the same transmittal as aggregate_object, shall be a published object.

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.

Input parameters:

parameter_name	Parameter_Data_Type
component_object	Object
aggregate_object	Object
link_object	Object

Input parameters:

parameter_name	Parameter_Data_Type
none

Valid return codes:

SUCCESS and the requested composition relationship is added if valid parameters were passed in and all operations succeeded.

INVALID_OBJECT if:

a) aggregate_object is NULL, has not yet been added to the transmittal, or does not belong to a valid SEDRIS class;

b) component_object is NULL, has not yet been added to the transmittal, or does not belong to a valid SEDRIS class;

c) link_object is non-NULL and either has not yet been added to the transmittal, or does not belong to a valid SEDRIS class.

UNPUBLISHED_OBJECT and no changes are made if 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:

d) aggregate_object and component_object are both unresolved, or

e) both aggregate_object and component_object are resolved and link_object is not unresolved.

INVALID_ACCESS_MODE and no changes are made if:

f) aggregate_object (or link_object if specified) is in a transmittal that is not open for creation or modification,.

g) component_object is in a transmittal that is not open for creation or modification.

FAILURE and no changes are made if the relationship could not be created for any other reason.

7.3.4 CloneObject

Table 7.5 — CloneObject

Property

Description

Purpose:

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

Input parameters:

parameter_name	Parameter_Data_Type
object	Object

Output parameters:

parameter_name	Parameter_Data_Type
duplicate_object	Object

Valid return codes:

SUCCESS and the object referenced by object is made accessible through duplicate_object if valid parameters were passed in and all operations succeeded.

INVALID_REQUIRED_PARAMETER and no changes are made if duplicate_object is invalid.

INVALID_OBJECT and duplicate_object is set to DRM_NULL if the input parameter is invalid.

OUT_OF_MEMORY and duplicate_object is set to DRM_NULL if memory cannot be allocated for the new object handle.

FAILURE and object is set to DRM_NULL if this function fails for any other reason.

7.3.5 CloseTransmittal

Table 7.6 — CloseTransmittal

Property

Description

Purpose:

Closes the specified transmittal and frees any and all memory allocated to hold the representation.of the transmittal.

Input parameters:

parameter_name	Parameter_Data_Type
transmittal	Transmittal

Input parameters:

parameter_name	Parameter_Data_Type
none

Valid return codes:

SUCCESS if valid parameters were passed in and all operations succeeded.

INVALID_TRANSMITTAL and no changes are made if transmittal is not a valid, active transmittal.

FAILURE and no changes are made, if

a) transmittal is not an open transmittal, or

b) the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.6 CMYKToCMY

Table 7.7 — CMYKToCMY

Property

Description

Purpose:

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

Input parameters:

parameter_name	Parameter_Data_Type
cmyk_colour	CMYK_Data

Output parameters:

parameter_name	Parameter_Data_Type
cmy_colour	CMY_Data

Valid return codes:

SUCCESS if valid parameters were passed in. In this case, cmy_colour is set to the appropriate values.

INVALID_PARAMETER if either parameter is invalid. The output parameter is not modified.

7.3.7 CMYToCMYK

Table 7.8 — CMYToCMYK

Property

Description

Purpose:

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

Input parameters:

parameter_name	Parameter_Data_Type
cmy_colour	CMY_Data

Output parameters:

parameter_name	Parameter_Data_Type
cmyk_colour	CMYK_Data

Valid return codes:

SUCCESS if valid parameters were passed in. In this case, cmyk_colour is set to the appropriate values.

INVALID_PARAMETER if either parameter is invalid. The output parameter is not modified.

7.3.8 ConvertColourToGivenModel

Table 7.9 — ConvertColourToGivenModel

Property

Description

Purpose:

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

Input parameters:

parameter_name	Parameter_Data_Type
original_colour	Object
new_colour_model	Colour_Model

Output parameters:

parameter_name	Parameter_Data_Type
new_colour	Object

Valid return codes:

SUCCESS and new_colour is set appropriately if valid parameters were passed in.

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

INVALID_SOURCE_COLOUR and no changes are made if original_colour is not a valid <DRM Colour Data> instance.

INVALID_NEW_COLOUR_MODEL and no changes are made if new_colour_model is invalid.

7.3.9 CreateObject

Table 7.10 — CreateObject

Property

Description

Purpose:

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

Input parameters:

parameter_name	Parameter_Data_Type
transmittal	Transmittal
new_object_type	DRM_Class

Output parameters:

parameter_name	Parameter_Data_Type
new_object	Object

Valid return codes:

SUCCESS and the new object is created with its handle placed in new_object if valid parameters were passed in and all operations succeeded.

INVALID_PARAMETER and no change is made if new_object is invalid.

INVALID_TRANSMITTAL and new_object is set to DRM_NULL if transmittal is not a handle to a valid, active (i.e., open) transmittal.

INVALID_ACCESS_MODE and new_object is set to DRM_NULL if transmittal was opened in read-only mode.

OUT_OF_MEMORY and new_object is set to DRM_NULL if memory cannot be allocated for new_object.

FAILURE and new_object is set to DRM_NULL if:

a) new_object_type does not correspond to a valid, concrete (i.e., not abstract) DRM class, or

b) the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.10 CreateSearchFilter

Table 7.11 — CreateSearchFilter

Property

Description

Purpose:

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.

Input parameters:

parameter_name	Parameter_Data_Type
implementation_identifier	String
rules	Search_Rule[*]

Output parameters:

parameter_name	Parameter_Data_Type
search_filter	Search_Filter

Valid return codes:

SUCCESS if valid parameters were passed in and all operations succeeded.

INVALID_REQUIRED_PARAMETER if either the search_filter or rules parameters are invalid.

OUT_OF_MEMORY and search_filter is set to NULL if the API could not allocate memory for the new search filter.

FAILURE if an illegal expression was specified by the rules parameter (for example, if an AND expression within the array only had one parameter). In this case, no value is returned.

7.3.11 CreateSpatialSearchBoundary

Table 7.12 — CreateSpatialSearchBoundary

Property

Description

Purpose:

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.

Input parameters:

parameter_name	Parameter_Data_Type
implementation_identifier	String
search_bounds	Search_Bounds
search_bounds_closure	Search_Bounds_Closure
search_quality	Search_Quality
inclusion	Inclusion_Choice
search_dimension	Search_Dimension

Output parameters:

parameter_name	Parameter_Data_Type
search_boundary	Search_Boundary

Valid return codes:

SUCCESS and a handle for the newly created search boundary is populated if valid parameters were passed in and memory allocation succeeded.

INVALID_REQUIRED_PARAMETER and no changes are made if either the search_bounds or search_boundary are invalid.

OUT_OF_MEMORY and search_boundary is set to the NULL if the API could not allocate memory for the new search boundary.

FAILURE and search_boundary is set to the NULL if:

a) an invalid boundary was specified by the search_bounds parameter (e.g., the minimal and maximal points are not in the same SRF),

b) if an invalid search_bounds_closure, search_quality, inclusion, or search_dimension was specified, or

c) the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.12 DetermineSpatialInclusion

Table 7.13 — DetermineSpatialInclusion

Property

Description

Purpose:

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.

Input parameters:

parameter_name	Parameter_Data_Type
object	Object
search_bounds	Search_Bounds
search_bounds_closure	Search_Bounds_Closure
search_quality	Search_Quality
search_dimension	Search_Dimension

Output parameters:

parameter_name	Parameter_Data_Type
{object_fully_included	Boolean}
{object_partly_included	Boolean}
{object_includes_search_bounds	Boolean}

Valid return codes:

SUCCESS and the Output parameters provided are set to the appropriate values if valid parameters were passed in, and the relationship between the object and the boundary was determined.

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.

UNRESOLVED_START_OBJECT and all provided output parameters are set to FALSE if object is an unresolved SEDRIS object.

UNRESOLVED_OBJECT and all provided output parameters are set to FALSE if an unresolved object was encountered and could not be resolved..

FAILURE and all provided output parameters are set to FALSE if

a) an invalid boundary was specified by the search_bounds parameter (e.g., the minimal and maximal points are not in the same SRF);

b) if an invalid search_bounds_closure, search_quality, or search_dimension was specified; or

c) the determination of the object/search area relationship could not be made; or

d) the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.13 FreeIterator

Table 7.14 — FreeIterator

Property

Description

Purpose:

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

Input parameters:

parameter_name	Parameter_Data_Type
to_free	Iterator

Output parameters:

parameter_name	Parameter_Data_Type
none

Valid return codes:

SUCCESS and the iterator is freed if a valid parameter was passed in and all operations succeeded.

FAILURE and no changes are made if:

a) to_free was not a valid iterator, or

b) the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.14 FreeObject

Table 7.15 — FreeObject

Property

Description

Purpose:

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.

Input parameters:

parameter_name	Parameter_Data_Type
to_free	Object

Output parameters:

parameter_name	Parameter_Data_Type
none

Valid return codes:

SUCCESS and the reference count for this object is decremented a valid parameter was passed in and all operations succeeded. Please note that:

a) the actual object is not freed until the reference count becomes zero, but

b) this object handle is no longer valid, since any contextual information associated with it (e.g., inheritance context) is released.

INVALID_OBJECT and nothing is changed if to_free was not a valid object.

FAILURE and nothing is changed if the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.15 FreePackedHierarchy

Table 7.16 — FreePackedHierarchy

Property

Description

Purpose:

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.

Input/Output parameters:

parameter_name	Parameter_Data_Type
to_free	Packed_Hierarchy

Valid return codes:

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.

INVALID_REQUIRED_PARAMETER and to_free is left unaltered if the to_free parameter is invalid.

FAILURE and no changes are made if the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.16 FreeRemainingObjectsList

Table 7.17 — FreeRemainingObjectsList

Property

Description

Purpose:

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.

Input parameters:

parameter_name	Parameter_Data_Type
to_free	Remaining_Objects_List

Output parameters:

parameter_name	Parameter_Data_Type
none

Valid return codes:

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.

INVALID_REQUIRED_PARAMETER and to_free is left unaltered if to_free is invalid.

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.

FAILURE and no changes are made if:

a) any of the fields of the input parameter are unset;

b) the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time..

7.3.17 FreeRemainingPackedHierarchiesList

Table 7.18 — FreeRemainingPackedHierarchiesList

Property

Description

Purpose:

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.

Input parameters:

parameter_name	Parameter_Data_Type
to_free	Remaining_Packed_Hierarchies_List

Output parameters:

parameter_name	Parameter_Data_Type
none

Valid return codes:

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.

INVALID_REQUIRED_PARAMETER and to_free is left unaltered if to_free is invalid.

FAILURE and no changes are made if the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.18 FreeSearchFilter

Table 7.19 — FreeSearchFilter

Property

Description

Purpose:

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.

Input parameters:

parameter_name	Parameter_Data_Type
to_free	Search_Filter

Output parameters:

parameter_name	Parameter_Data_Type
none

Valid return codes:

SUCCESS and the search filter is freed if valid parameters were passed in and all operations succeeded.

FAILURE and no changes are made if:

a) to_free is not a valid search filter;

b) the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.19 FreeSpatialSearchBoundary

Table 7.20 — FreeSpatialSearchBoundary

Property

Description

Purpose:

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.

Input parameters:

parameter_name	Parameter_Data_Type
to_free	Search_Boundary

Valid return codes:

SUCCESS and the search boundary is freed if a valid parameter was passed in and all operations succeeded.

FAILURE and no changes are made if:

a) to_free is not a valid spatial search boundary;

b) the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.20 FreeTransmittal

Table 7.21 — FreeTransmittal

Property

Description

Purpose:

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.

Input parameters:

parameter_name	Parameter_Data_Type
to_free	Transmittal

Valid return codes:

SUCCESS and the given handle to the transmittal is freed if a valid parameter was passed in.

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.

FAILURE and no changes are made if the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.21 GetAggregate

Table 7.22 — GetAggregate

Property

Description

Purpose:

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, one-shot” 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 one and only one aggregate should be retrieved.

Given an object (object) and a type of aggregate to search for (drm_class), this function will look 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.

Input parameters:

parameter_name	Parameter_Data_Type
object	Object
drm_class	DRM_Class
itr_traversal	ITR_Behaviour

Output parameters:

parameter_name	Parameter_Data_Type
aggregate_object	Object
link_class_object	Object

Valid return codes:

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.

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:

a) valid parameters were passed in,

b) the user requested that the API automatically resolve inter-transmittal references (ITR),

c) an ITR reference was encountered in searching for the aggregate, and

d) the iterator successfully resolved it and retrieved the aggregate from the new, different transmittal

MULTIPLE_OBJECTS and the output parameters are set as for the SUCCESS case if valid parameters were passed in but multiple objects were found that satisfied the specified criteria. In this case, an arbitrary object is chosen that specifies the criteria.

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.

INVALID_REQUIRED_PARAMETER and no changes are made object is invalid.

INVALID_OBJECT if object is invalid or drm_class specifies an invalid value. In this case, the output parameters return NULL.

UNRESOLVED_START_OBJECT and the output parameters return NULL if object is unresolved.

NO_OBJECT and the output parameters return NULL if no aggregate object of the specified DRM class could be found.

OUT_OF_MEMORY and the output parameters return NULL if memory could not be allocated.

FAILURE and the output parameters return NULL if:

e) if itr_traversal is not valid;

f) the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.22 GetAssociate

Table 7.23 — GetAssociate

Property

Description

Purpose:

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

This is a “short form, one-shot” 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.

Input parameters:

parameter_name	Parameter_Data_Type
object	Object
drm_class	DRM_Class
itr_traversal	ITR_Behaviour

Output parameters:

parameter_name	Parameter_Data_Type
associate_object	Object
link_class_object	Object

Valid return codes:

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.

DIFFERENT_TRANSMITTAL and the output parameters are set as for the SUCCESS case, if valid parameters were passed in, the user requested that the API automatically resolve inter-transmittal references (ITR), an ITR reference was encountered in searching for the associate, and the iterator successfully resolved it and retrieved the associate from the new, different transmittal..

UNRESOLVED_OBJECT if valid parameters were passed in and only one object was found that satisfied the specified criteria, but the aggregate object is unresolved. In this case, the output parameters are set as for the SUCCESS case.

MULTIPLE_OBJECTS if valid parameters were passed in but multiple objects were found that satisfied the specified criteria. In this case, an arbitrary object is chosen that specifies the criteria, and the output parameters are set as for the SUCCESS case.

INVALID_REQUIRED_PARAMETER and no changes are made object is invalid.

INVALID_OBJECT if object is invalid or drm_class specifies an invalid value. In this case, the output parameters return NULL.

UNRESOLVED_START_OBJECT and the output parameters return NULL if object is unresolved.

NO_OBJECT and the output parameters return NULL if no aggregate object of the specified DRM class could be found.

OUT_OF_MEMORY and the Output parameters return NULL if memory could not be allocated.

FAILURE and the output parameters return NULL if:

a) if itr_traversal is not valid;

b) the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.23 GetColourModel

Table 7.24 — GetColourModel

Property

Description

Purpose:

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.

Input parameters:

parameter_name	Parameter_Data_Type
transmittal	Transmittal

Output parameters:

parameter_name	Parameter_Data_Type
colour_model	Colour_Model

Valid return codes:

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.

INVALID_REQUIRED_PARAMETER and colour_model is not affected, if colour_model was invalid.

INVALID_TRANSMITTAL and colour_model is not affected, if transmittal is not a handle to a valid, active (i.e., open and unfreed) transmittal.

FAILURE and colour_model is not affected if:

a) the default colour model is in effect but transmittal does not specify a colour model,

b) the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.24 GetComponent

Table 7.25 — GetComponent

Property

Description

Purpose:

This function retrieves the kind of component specified by drm_class from the specified object.

This is a “short form, one-shot” version of a component iterator. It combines the creation of an iterator, making a call to 7.3.35 GetNextObject, and freeing the iterator, in the case when retrieval of one and only one object is desired.

Given an object (object), and a type of object for which to search (drm_class), and the maximum distance to search (max_search_distance), this function will find the first component of the given type that is:

a) A component of the start_object (distance = 1) or

b) A member of the aggregate tree rooted at the start_object (the tree of the components of the start_object) (distance = between 1 and the given maximum search distance for a breadth-first search).

See 7.3.64 InitializeComponentIterator for a description of the effect of the directly_attach_table_components parameter.

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. For example, setting this process_inheritance parameter to TRUE allows asking for the <DRM Inline Colour> component of a <DRM Polygon> without worrying about whether the <DRM Inline Colour> component was an “immediate” or “inherited” component of the <DRM Polygon>. An “immediate” component will always take precedence over an “inherited” component.

max_search_distance is the maximum distance to search using a breadth-first search to traverse the components. A value of 0 indicates that the search has an unlimited depth (and should continue to search until it finds an object of the appropriate type, or until it runs out of objects).

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

c) automatically resolve such references and continue the search within the new transmittal;

d) report all ITR references without resolving them; or

e) ignore such references completely and continue to search within the current transmittal.

Input parameters:

parameter_name	Parameter_Data_Type
object	Object
drm_class	DRM_Class
directly_attach_table_components	Boolean
process_inheritance	Boolean
maximum_search_distance	Short_Integer_Unsigned
itr_traversal	ITR_Behaviour

Output parameters:

parameter_name	Parameter_Data_Type
component_object	Object
link_class_object	Object

Valid return codes:

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.

INVALID_REQUIRED_PARAMETER and no changes are made object is invalid.

INVALID_OBJECT if object is invalid or drm_class specifies an invalid value. In this case, the output parameters return NULL.

UNRESOLVED_START_OBJECT and the output parameters return NULL if object is unresolved.

NO_OBJECT and the output parameters return NULL if no aggregate object of the specified DRM class could be found.

OUT_OF_MEMORY and the output parameters return NULL if memory could not be allocated.

FAILURE and the output parameters return NULL if:

a) if itr_traversal is not valid;

b) the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.25 GetContextTransformation

Table 7.26 — GetContextTransformation

Property

Description

Purpose:

This function retrieves a copy of the current effective transformation of the given object. This is the accumulation of all transformations either:

a) 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. or

b) 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 will be returned.

Input parameters:

parameter_name	Parameter_Data_Type
object	Object

Output parameters:

parameter_name	Parameter_Data_Type
matrix	Matrix_4x4

Valid return codes:

SUCCESS and the current effective transformation of object is returned in matrix, if valid parameters were passed in.

INVALID_REQUIRED_PARAMETER and matrix is left unchanged, if matrix is invalid.

INVALID_OBJECT if object is not valid. In this case, the identify matrix is returned.

UNRESOLVED_START_OBJECT if object is unresolved. In this case, the identify matrix is returned.

FAILURE if the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time. In this case, the identify matrix is returned.

7.3.26 GetDataTable

Table 7.27 — GetDataTable

Property

Description

parameter_name Parameter_Data_Type

Purpose:

This function copies the selected cell elements from the selected area of interest of the given <DRM Data Table> into a space in memory that to which the user has direct access.

A <DRM Data Table> is an n-dimensional collection of cells. Each <DRM Data Table> defines a signature, which applies to the entire <DRM Data Table>, defining how many elements (values) will be contained in each cell, what the type of each element will be (e.g. Short_Integer or Long_Float) and an EDCS_Attribute_Code (the meaning) for each element.

The extent elements are ordered and the data is scanned into the buffer according to the ordering and fields of the <DRM Axis> components of the <DRM Data Table>. For example, if the <DRM Data Table> has:

   Axis 0 = Regular_Axis(
                   axis_type = (Attribute,
                   EAC_SPATIAL_ANGULAR_SECONDARY_COORDINATE),
                   value_unit = EUC_DEGREE_ARC,
                   value_scale = ESC_UNI,
                   axis_value_count = 20,
                   interpolation_type = LINEAR,
                   first_value = 0.0,
                   spacing = 1.0,
                   spacing_type = LINEAR,
                   axis_alignment = LOWER
)

Axis 1 = Regular_Axis(
                   axis_type = (Attribute,
                   EAC_SPATIAL_ANGULAR_PRIMARY_COORDINATE),
                   value_unit = EUC_DEGREE_ARC,
                   value_scale = ESC_UNI,
                   axis_value_count = 30,
                   interpolation_type = LINEAR,
                   first_value = 52.0,
                   spacing = -0.5,
                   type_of_spacing = LINEAR,
                   axis_alignment = LOWER
)

The first element of the Extents.axes_bounds array refers to geodetic longitude and the second element of the Extents.axes_bounds array refers to geodetic latitude. The API function places data into the output buffer with latitude increasing fastest. In the example, because the spacing on the geodetic latitude axis is negative, increasing latitude index actually corresponds to scanning southward through the grid locations.

The extents parameter indicates which region of the <DRM Data Table> to return.

The element_count parameter indicates the number of elements per cell to return and the size of the following selected_elements array.

The table_property_description_number is an array of indices into the ordered list of <DRM Table Property Description> instances aggregated by data_table.

Input parameters:

parameter_name	Parameter_Data_Type
data_table	SE_Object
extents	Data_Table_Extents
element_count	Integer_Positive
table_property_description_number	Integer_Positive[element_count]

Output parameters:

parameter_name	Parameter_Data_Type
data	Property_Data_Value[*]

Valid return codes:

SUCCESS and the requested data is returned, if valid parameters were passed in.

INVALID_REQUIRED_PARAMETER and data is unaffected if extents is empty or invalid, element_count is zero, table_property_description_nmber is invalid, or data is invalid.

INVALID_OBJECT and data is cleared if data_table is not a valid <DRM Data Table> instance.

UNRESOLVED_OBJECT and data is unaffected if data_table is an unresolved object.

OUT_OF_MEMORY and data is cleared if the implementation was unable to allocate sufficient memory.

FAILURE and data is cleared if:

a) the extents are invalid for the <DRM Data Table>;

b) any of the table_proprety_description_number are invalid for data_table, or are not unique within the array,

c) the <DRM Data Table> instance is a <DRM Property Grid> with a data_present field set to FALSE;

d) the <DRM Data Table> instance has been created via the API but has not yet had cells added to it;

e) the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.27 GetDRMClass

Table 7.28 — GetDRMClass

Property

Description

Purpose:

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

Input parameters:

parameter_name	Parameter_Data_Type
object	Object

Output parameters:

parameter_name	Parameter_Data_Type
object_type	DRM_Class

Valid return codes:

SUCCESS and object_type is set appropriately if valid parameters were passed in.

INVALID_REQUIRED_PARAMETER and object_type is left unaltered if object_type is not valid.

INVALID_OBJECT and object_type returns NULL if object is not valid.

UNRESOLVED_OBJECT and object_type returns NULL if object is not valid.

FAILURE and object_type returns NULL if the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.28 GetElementOfDataTable

Table 7.29 — GetElementOfDataTable

Property

Description

Purpose:

This function copies the selected element from the selected area of interest of the given <DRM Data Table> into a space in memory which the user has direct access.

A <DRM Data Table> is an n-dimensional collection of cells. Each <DRM Data Table> defines a signature, which applies to the entire <DRM Data Table>, defining how many elements (values) will be contained in each cell, what the type of each element will be (e.g., Short_Integer or Long_Float) and an EDCS_Attribute_Code (the meaning) for each element.

Axis 0 = Regular_Axis(
                   axis_type = (Attribute,
                      EAC_SPATIAL_ANGULAR_-                           SECONDARY_COORDINATE),
                   value_unit = EUC_DEGREE_ARC,
                   value_scale = ESC_UNI,
                   axis_value_count = 20,
                   interpolation_type = LINEAR,
                   first_value = 0.0,
                   spacing = 1.0,
                   spacing_type = LINEAR,
                   axis_alignment = LOWER
)

Axis 1 = Regular_Axis(
                   axis_type = Attribute,
                      EAC_SPATIAL_ANGULAR_-                           PRIMARY_COORDINATE),
                   value_unit = EUC_DEGREE_ARC,
                   value_scale = ESC_UNI,
                   axis_value_count = 30,
                   interpolation_type = LINEAR,
                   first_value = 52.0,
                   spacing = -0.5,
                   type_of_spacing = LINEAR,
                   axis_alignment = LOWER
)

The first element of the extents start array refers to longitude and the second element of the extents array refers to latitude. The API function places data into the caller-provided buffer with latitude increasing fastest.

In the example, because the spacing on the latitude axis is negative, increasing the latitude index actually corresponds to scanning southward through the grid locations.

Unlike the 7.3.26 GetDataTable function, only one type of element from each cell is returned. The calling program defines a single desired element for this function instead of an array of elements as defined for the 7.3.26 GetDataTable function. Because only one type element is returned, only one type of value is being returned (only one type of value is being copied into the memory provided by the calling function).

Input parameters:

parameter_name	Parameter_Data_Type
data_table	Object
extents	Data_Table_Extents
table_property_description_number	Integer_Positive

Output parameters:

parameter_name	Parameter_Data_Type
results	Property_Data_Value

Valid return codes:

SUCCESS and the requested data is returned by results, if valid parameters were passed in.

INVALID_REQUIRED_PARAMETER and results is unaffected if extents is empty or invalid, element_count is zero, table_property_description_number is invalid, or results is invalid.

INVALID_OBJECT and results is cleared if data_table is not a valid <DRM Data Table> instance.

UNRESOLVED_OBJECT and results is unaffected if data_table is an unresolved object.

OUT_OF_MEMORY and results is cleared if the implementation was unable to allocate sufficient memory.

FAILURE and data is cleared if:

a) the extents are invalid for the <DRM Data Table>;

b) any of the table_property_description_number are invalid for data_table, or are not unique within the array,

c) the <DRM Data Table> is a <DRM Property Grid> with a data_present field set to FALSE;

d) the <DRM Data Table> has been created via the API but has not yet had cells added to it;

e) the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.29 GetErrorDescription

Table 7.30 — GetErrorDescription

Property

Description

Purpose:

This function provides information regarding a failed function call to the API. This function can be called immediately after a non-successful API call to get a verbose description of why the SEDRIS function failed.

Only one error description is extent at any one time. Each error that occurs replaces the previous error description.

Input parameters:

parameter_name	Parameter_Data_Type
none

Output parameters:

parameter_name	Parameter_Data_Type
error_description	String

Valid return codes:

SUCCESS and error_description was set to the appropriate value, if valid parameter was passed in and all operations succeeded.

INVALID_REQUIRED_PARAMETER and error_description is left unaltered if error_description is NULL.

FAILURE and error_description is left unaltered if the function failed for any other reason

7.3.30 GetFields

Table 7.31 — GetFields

Property

Description

Purpose:

This function retrieves a pointer to the field data of an object. The DRM_Class_Fields data type is a variant record which 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.

Input parameters:

parameter_name	Parameter_Data_Type
object	Object

Output parameters:

parameter_name	Parameter_Data_Type
fields	DRM_Class_Fields

Valid return codes:

SUCCESS and the fields of the specified object are returned in fields if valid parameters were passed in and all operations succeeded.

INVALID_OBJECT and the NULL field value is returned if object is not a valid SEDRIS object.

UNRESOLVED_OBJECT and the NULL field value is returned if object is an unresolved object.

OUT_OF_MEMORY and the NULL field value is returned if the implementation was unable to allocate sufficient memory.

FAILURE and the NULL field value is returned if the API implementation does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.31 GetIDForObject

Table 7.32 — GetIDForObject

Property

Description

Purpose:

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

Input parameters:

parameter_name	Parameter_Data_Type
object	Object

Output parameters:

parameter_name	Parameter_Data_Type
id	String

Valid return codes:

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

INVALID_REQUIRED_PARAMETER and id is unaffected if id is NULL.

INVALID_OBJECT and id is set to to the empty string if object is not a valid SEDRIS object.

UNRESOLVED_OBJECT and id is set to the empty string if object is an unresolved object.

FAILURE and id is set to the empty string if the ID string cannot be retrieved for any other reason.

7.3.32 GetImageData

Table 7.33 — GetImageData

Property

Description

Purpose:

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.

Input parameters:

parameter_name	Parameter_Data_Type
image	Object
start_texel	Image_Texel_Location_3D
stop_texel	Image_Texel_Location_3D
mip_level	Short_Integer_Unsigned

Output parameters:

parameter_name	Parameter_Data_Type
data	Byte_Unsigned[*]

Valid return codes:

SUCCESS and the requested data is returned in data, if valid parameters were passed in and all operations succeeded.

INVALID_REQUIRED_PARAMETER and data is unaffected if data is invalid.

INVALID_OBJECT and data is returned NULL if image is not a valid <DRM Image> object.

UNRESOLVED_OBJECT and data is returned NULL if image is an unresolved object.

OUT_OF_MEMORY if the implementation was unable to allocate sufficient memory.

FAILURE and data is returned NULL if:

a) no image data has yet been specified for image;

b) mip_level is invalid for image;

c) level_count of image is zero or its mip_fields_array is empty;

d) any of the start or stop texels were invalid for image;

e) the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.33 GetImplementationIdentifier

Table 7.34 — GetImplementationIdentifier

Property

Description

Purpose:

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

Input parameters:

parameter_name	Parameter_Data_Type
object	Object

Output parameters:

parameter_name	Parameter_Data_Type
implementation_identifier	String

Valid return codes:

SUCCESS and the implementation identifier associated with the object’s API implementation is returned if valid parameters were passed in.

INVALID_REQUIRED_PARAMETER and implementation_identifier is left unaltered if implementation_identifier is invalid.

INVALID_OBJECT and implementation_identifier is left unaltered if image is not a valid SEDRIS <DRM Image> object.

FAILURE and implementation_identifier is left unaltered if: the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.34 GetIterationLengthRemaining

Table 7.35 — GetIterationLengthRemaining

Property

Description

Purpose:

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

Input parameters:

parameter_name	Parameter_Data_Type
iterator	Iterator

Output parameters:

parameter_name	Parameter_Data_Type
count	Integer_Unsigned

Valid return codes:

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

INVALID_REQUIRED_PARAMETER and count is left unaltered if count is invalid.

FAILURE and count is left unaltered if

a) the iterator is invalid; or

b) the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.35 GetNextObject

Table 7.36 — GetNextObject

Property

Description

Purpose:

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.

Input parameters:

parameter_name	Parameter_Data_Type
iterator	Iterator

Output parameters:

parameter_name	Parameter_Data_Type
next_object	Object
link_class_object	Object

Valid return codes:

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.

DIFFERENT_TRANSMITTAL and the output parameter values are set as for SUCCESS if valid parameters were passed in, the iterator is configured to automatically resolve inter-transmittal references (ITR), an ITR reference was encountered in searching for the next object, and the iterator successfully resolved it and continued to search in the new, different transmittal until the next object from the iterator was found. In this case, next_object returns the next object from the iterator, and next_object is set appropriately.

INVALID_REQUIRED_PARAMETER and the output parameter values are left unaltered if next_object is NULL.

UNRESOLVED_OBJECT and the Output parameters are returned NULL if valid parameters were passed in, an inter-transmittal reference (ITR) was encountered in searching for the next object, and either the iterator is configured to automatically resolve ITR references but was unable to do so, or it is configured to stop at ITR references.

NO_OBJECT and the output parameters are returned NULL if the iterator is out of objects to return..

OUT_OF_MEMORY and the output parameters are returned NULL if memory cannot be allocated for the next object to be returned.

FAILURE and the output parameters are returned NULL if:

a) the iterator is invalid;

b) the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.36 GetNthAssociateOfDRMClass

Table 7.37 — GetNthAssociateOfDRMClass

Property

Description

Purpose:

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.

Input parameters:

parameter_name	Parameter_Data_Type
from_object	Object
desired_component_type	DRM_Class
n	Integer_Positive

Output parameters:

parameter_name	Parameter_Data_Type
associate_object	Object
link_class_object	Object

Valid return codes:

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.

INVALID_REQUIRED_PARAMETER and the output parameter values are left unaltered if associate_object is NULL.

INVALID_OBJECT and the output parameters are returned NULL if associate_object is not a valid object.

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.

UNRESOLVED_START_OBJECT and the output parameters are returned NULL if from_object is an unresolved SEDRIS object.

NO_OBJECT and the output parameters are returned NULL if the from_object did not contain “n” associate objects of the desired class.

OUT_OF_MEMORY and the output parameters are returned NULL if sufficient memory could not be allocated.

FAILURE and the output parameters are returned NULL if:

a) n was zero (since this is a one-based index),

b) an invalid value was supplied for desired_associate_class,

c) the given class of associate is not ordered for the given from_object, or

d) the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.37 GetNthComponentOfDRMClass

Table 7.38 — GetNthComponentOfDRMClass

Property

Description

Purpose:

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.

Input parameters:

parameter_name	Parameter_Data_Type
aggregate_object	Object
desired_component_type	DRM_Class
n	Integer_Positive

Output parameters:

parameter_name	Parameter_Data_Type
component_object	Object
link_class_object	Object

Valid return codes:

SUCCESS and component_object returns the n^th component and link_class_object is set appropriately if valid parameters were passed in and all operations succeeded.

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 by component_object is unresolved.

INVALID_REQUIRE_PARAMETER and the output parameter values are left unaltered if component_object is NULL.

INVALID_OBJECT and the output parameters are set to NULL if aggregate_object is not a valid object.

UNRESOLVED_START_OBJECT and the output parameters are returned NULL if aggregate_object is an unresolved SEDRIS object.

NO_OBJECT and the output parameters are set to NULL if the aggregate_object did not contain “n” component objects of the desired class.

OUT_OF_MEMORY and the output parameters are set to NULL if sufficient memory could not be allocated.

FAILURE and the output parameters are set to NULL if:

a) n was zero (since this is a one-based index),

b) desired_component_class was invalid,

c) the given class of component is not ordered for the given aggregate object, or

d) the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.38 GetNumberOfPathsToTransmittalRoot

Table 7.39 — GetNumberOfPathsToTransmittalRoot

Property

Description

Purpose:

This function determines how many different paths can be traversed from the <DRM Transmittal Root> to the given object, where a path is defined as a bi-directional aggregate to component relationship.

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 paths counted are those to the other transmittal’s <DRM Transmittal Root>. Otherwise, the paths are to the <DRM Transmittal Root> within the transmittal containing object.

Input parameters:

parameter_name	Parameter_Data_Type
object	Object

Output parameters:

parameter_name	Parameter_Data_Type
number_of_paths	Integer_Unsigned

Valid return codes:

SUCCESS and number_of_paths is set appropriately if valid parameters were passed in.

INVALID_OBJECT and number_of_paths is set to zero (0), if object is not a valid SEDRIS object. In this case, number_of_paths is set to zero.

UNRESOLVED_START_OBJECT and number_of_paths is set to zero if object is an unresolved.

FAILURE and number_of_paths is set to zero if the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.39 GetObjectForID

Table 7.40 — GetObjectForID

Property

Description

Purpose:

Given an object identifier, get the corresponding SEDRIS object.

Input parameters:

parameter_name	Parameter_Data_Type
id	String

Output parameters:

parameter_name	Parameter_Data_Type
object	Object

Valid return codes:

SUCCESS if valid parameters were passed in and all operations succeeded.

INVALID_REQUIRED_PARAMETER and object is left unaltered, if object is NULL.

INVALID_OBJECT and object is set to NULL if id is not a valid object identifier. In this case, the NULL object is returned.

FAILURE and object is set to NULL if the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.40 GetObjectReferenceCount

Table 7.41 — GetObjectReferenceCount

Property

Description

Purpose:

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 Level 0 functions which 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.

Input parameters:

parameter_name	Parameter_Data_Type
object	Object

Output parameters:

parameter_name	Parameter_Data_Type
reference_count	Short_Integer_Unsigned

Valid return codes:

SUCCESS and reference_count is set appropriately if valid parameters were passed in.

INVALID_REQUIRED_PARAMETER and reference_count is left unaltered if reference_count was NULL.

INVALID_OBJECT and reference_count is set to zero (0) if object is not a valid SEDRIS object.

FAILURE and reference_count t is set to zero (0) if the function cannot execute successfully due to an implementation dependent problem. In this case, the NULL object is returned.

7.3.41 GetPackedDataTable

Table 7.42 — GetPackedDataTable

Property

Description

Purpose:

This function copies the selected cell elements from the selected area of interest of the given <DRM Data Table> into a space in memory that to which the user has direct access.

A <DRM Data Table> is an n-dimensional collection of cells. Each <DRM Data Table> defines a signature, which applies to the entire <DRM Data Table>, defining how many elements (values) will be contained in each cell, what the type of each element will be (e.g., Short_Integer or Long_Float) and an EDCS_Attribute_Code (the meaning) for each element.

   Axis 0 = Regular_Axis(
                   axis_type = (ATTRIBUTE,                                     EAC_SPATIAL_ANGULAR_-                           SECONDARY_COORDINATE),
                   value_unit = EUC_DEGREE_ARC,
                   value_scale = ESC_UNI,
                   axis_value_count = 20,
                   interpolation_type = LINEAR,
                   first_value = 0.0,
                   spacing = 1.0,
                   spacing_type = ARITHMETIC,
                   axis_alignment = LOWER
)

Axis 1 = Regular_Axis(
                   axis_type = (ATTRIBUTE,                                     EAC_SPATIAL_ANGULAR_-                           PRIMARY_COORDINATE),
                   value_unit = EUC_DEGREE_ARC,
                   value_scale = ESC_UNI,
                   axis_value_count = 30,
                   interpolation_type = LINEAR,
                   first_value = 52.0,
                   spacing = -0.5,
                   values_are_ints = FALSE,
                   spacing_type = ARITHMETIC,
                   axis_alignment = LOWER
)

Then, the first element of the extents start_array and the first element of the extents stop_array refer to geodetic longitude and the subsequent element in each array each refer to geodetic latitude. The API function places data into the output buffer with latitude increasing fastest. In the example, because the spacing on the geodetic latitude axis is negative, increasing latitude index actually corresponds to scanning southward through the grid locations.

The only difference between this 7.3.41 GetPackedDataTable function and the 7.3.26 GetDataTable function is that the 7.3.26 GetDataTable function returns an n-dimensional array of PROPERTY_DATA_VALUE instances. A PROPERTY_DATA_VALUE is a variable record type, containing a discriminant to indicate what type of a value it contains, and a representation for each of the possible types of values for a <DRM Data Table> value. That representation is inefficient in terms of storage space, since the user should already know the “type” of each value based on the signature of the <DRM Data Table>, and because a variant record type allowing for all possible data types always takes up as much space as the largest data type.

The GetPackedDataTable function does not waste any space when it returns the cell values. That is because this function returns the cell values as a 1-dimensional array of bytes. The user may then parse this array, based on the user’s knowledge of how many values are present per cell (selected by the user through parameters to this function), the size and type of each value, the order of the values within the returned cells (defined by the user through parameters to this function), and the knowledge of how many cells are present in the returned data array (also defined by the user through parameters to this function). In this “packed” representation, only the actual values are returned. No “typing” information is provided (the “tag” to indicate the type of each value is not present in the data returned by this function).

The extents parameter indicates which region of the <DRM Data Table> to return.

The element_count parameter indicates the number of elements per cell to return and the size of the following selected_elements array.

The table_property_description_number is an array of indices into the ordered list of <DRM Table Property Description> instances aggregated by data_table.

Input parameters:

parameter_name	Parameter_Data_Type
data_table	Object
extents	Data_Table_Extents
element_count	Integer_Positive
table_property_description_number	Integer_Positive[element_count]

Output parameters:

parameter_name	Parameter_Data_Type
data	Byte_Unsigned[*]

Valid return codes:

SUCCESS and the requested data is returned in data if valid parameters were passed in and all operations succeeded.

INVALID_REQUIRED_PARAMETER and no changes are made if:

a) extents was NULL,

b) element_count is zero,

c) table_property_description_number was NULL, or

d) data was NULL.

INVALID_OBJECT and data returns NULL if data_table is not a valid <DRM Data Table> instance.

UNRESOLVED_OBJECT and data returns NULL if data_table is an unresolved object.

OUT_OF_MEMORY and data returns NULL if the implementation was unable to allocate sufficient memory.

FAILURE and data returns NULL if:

e) the extents are invalid for the <DRM Data Table>;

f) any of the selected_elements are not applicable to (are not contained in) the <DRM Data Table>;

g) the <DRM Data Table> is a <DRM Property Grid> with a data_present field set to FALSE;

h) the <DRM Data Table> has been created via the API but has not yet had cells added to it;

i) the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.42 GetPackedHierarchy

Table 7.43 — GetPackedHierarchy

Property

Description

Purpose:

This function retrieves a subhierarchy rooted at a given object into a set of data structures that can be directly traversed by the calling application.

Input parameters:

parameter_name	Parameter_Data_Type
root_object	Object
directly_attach_table_components	Boolean
process_inheritance	Boolean
hierarchy_depth	Integer_Unsigned
itr_traversal	ITR_Behaviour

Output parameters:

parameter_name	Parameter_Data_Type
hierarchy	Packed_Hierarchy

Valid return codes:

SUCCESS and the packed hierarchy is returned in hierarchy if valid parameters were passed in.

DIFFERENT_TRANSMITTAL and the packed hierarchy is returned in hierarchy if valid parameters were passed in but one or more objects encountered were contained in a different transmittal to root_object.

UNRESOLVED_OBJECT and the packed hierarchy is returned in hierarchy if valid parameters were passed in but one or more objects encountered were not resolved. In this case, the object_is_resolved field is set to FALSE in the PACKED_HIERARCHY_OBJECT data structure for those objects that are unresolved.

INVALID_REQUIRED_PARAMETER and hierarchy is unaltered if hierarchy is NULL.

INVALID_OBJECT and hierarchy is unaltered if root_object is not a valid SEDRIS object.

OUT_OF_MEMORY and hierarchy is unaltered if the implementation was unable to allocate sufficient memory.

FAILURE and hierarchy is unaltered if:

a) itr_traversal is not a valid value; or

b) dynamic binding is specified at compile time, but the API implementation specified does not provide this function in its shared library.

7.3.43 GetPublishedLabels

Table 7.44 — GetPublishedLabels

Property

Description

Purpose:

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

Input parameters:

parameter_name	Parameter_Data_Type
object	Object

Output parameters:

parameter_name	Parameter_Data_Type
number_labels	Integer_Unsigned
label_list	String[number_labels]

Valid return codes:

SUCCESS and the output parameters are set appropriately if valid parameters were passed in and all operations succeeded.

INVALID_REQUIRED_PARAMETER and the output parameter values are left unaltered, if either label_list is NULL or number_labels is invalid.

INVALID_OBJECT and label_list is returned empty if object is not a valid object.

UNRESOLVED_OBJECT and label_list is returned empty if object is not a resolved object.

UNPUBLISHED_OBJECT and label_list is returned empty if object is not a published object.

FAILURE and label_list is returned empty if the function fails for any other reason.

7.3.44 GetPublishedObjectList

Table 7.45 — GetPublishedObjectList

Property

Description

Purpose:

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

Input parameters:

parameter_name	Parameter_Data_Type
transmittal	Transmittal

Output parameters:

parameter_name	Parameter_Data_Type
number_published_objects	Integer_Unsigned
published_object_list	Object[number_published_objects]

Valid return codes:

SUCCESS if valid parameters were passed in and published_object_list was successfully returned.

INVALID_REQUIRED_PARAMETER and the output parameters are left unchanged if either of the two output parameters are invalid.

INVALID_TRANSMITTAL and published_object_list is returned empty if transmittal is not a valid transmittal.

OUT_OF_MEMORY and published_object_list is returned empty if memory could not be allocated.

FAILURE and published_object_list is returned empty if the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.45 GetReferencedTransmittalList

Table 7.46 — GetReferencedTransmittalList

Property

Description

Purpose:

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.

Input parameters:

parameter_name	Parameter_Data_Type
transmittal	Transmittal

Output parameters:

parameter_name	Parameter_Data_Type
transmittal_name_count	Integer_Unsigned
transmittal_name_list	String[transmittal_name_count]

Valid return codes:

SUCCESS and the output parameters are set appropriately, if valid parameters were passed in and all operations succeeded.

INVALID_REQUIRED_PARAMETER and the output parameters are left unaltered if either of the two output parameters are invalid.

INVALID_TRANSMITTAL and an empty list is returned if transmittal is not a valid transmittal.

OUT_OF_MEMORY and an empty list is returned if memory could not be allocated.

FAILURE and an empty list is returned if the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.46 GetRelationCounts

Table 7.47 — GetRelationCounts

Property

Description

Purpose:

Given an object, this function returns the counts of

a) the number of components,

b) the number of aggregates, and

c) the number of associates

that the specified object has.

Input parameters:

parameter_name	Parameter_Data_Type
object	Object

Output parameters:

parameter_name	Parameter_Data_Type
component_count	Integer_Unsigned
component_link_count	Integer_Unsigned
aggregate_count	Integer_Unsigned
aggregate_link_count	Integer_Unsigned
association_count	Integer_Unsigned
association_link_count	Integer_Unsigned

Valid return codes:

SUCCESS and the output parameters are set to the appropriate values if valid parameters were passed in.

INVALID_REQUIRED_PARAMETER and the output parameter values are left unaltered if any non-link output parameter is invalid.

INVALID_OBJECT and all output parameter values are set to zero (0) if object is not a valid SEDRIS object.

UNRESOLVED_START_OBJECT and all output parameter values are set to zero (0) if object is not a resolved object.

FAILURE and all output parameter values are set to zero (0) if the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.47 GetRemainingObjectsList

Table 7.48 — GetRemainingObjectsList

Property

Description

Purpose:

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. The valid status codes for these arrays are:

a) SUCCESS - the corresponding object/link class object resides in the same transmittal as the iterator's start object.

b) DIFFERENT_TRANSMITTAL - the corresponding object/link class object resides in a different transmittal than the iterator's start object, and was successfully resolved.

c) UNRESOLVED_OBJECT - the corresponding object/link class object resides in a different transmittal than the iterator's start object, but was not successfully resolved.

d) NO_OBJECT - (only valid for the link_object_status_list array) the corresponding (n^th) value in the remaining_link_objects_list is NULL, because the iterator did not return a link class object for the corresponding (n^th) value in remaining_objects_list.

Input parameters:

parameter_name	Parameter_Data_Type
iterator	Iterator

Output parameters:

parameter_name	Parameter_Data_Type
remaining_objects	Remaining_Objects_List

Valid return codes:

SUCCESS and all remaining objects are returned in remaining_objects if valid parameters were passed in.

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 than the iterator’s start_object.

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.

INVALID_REQUIRED_PARAMETER and remaining_objects is left unaltered if remaining_objects is invalid.

NO_OBJECT and remaining_objects is returned with a zero (0) count and empty lists if the iterator is out of objects to return.

OUT_OF_MEMORY and remaining_objects is returned with a zero (0) count and empty lists if memory could not be allocated.

FAILURE and remaining_objects is returned with a zero (0) count and empty lists if this function fails for any other reason.

7.3.48 GetRemainingPackedHierarchies

Table 7.49 — GetRemainingPackedHierarchies

Property

Description

Purpose:

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.

Input parameters:

parameter_name	Parameter_Data_Type
iterator	Iterator
hierarchy_depth	Integer_Unsigned

Output parameters:

parameter_name	Parameter_Data_Type
remaining_hierarchies	Remaining_Packed_Hierarchies_List

Valid return codes:

SUCCESS and remaining_hierarchies returns the remaining hierarchy list data if valid parameters were passed in.

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.

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_OBJECT data structures for those objects that are unresolved.

INVALID_REQUIRED_PARAMETER and remaining_hierarchies is left unaltered if remaining_hierarchies is invalid.

NO_OBJECT and remaining_hierarchies is returned empty if the iterator is out of objects to return.

FAILURE and remaining_hierarchies is returned empty if:

a) the iterator is invalid;

b) the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.49 GetRootObject

Table 7.50 — GetRootObject

Property

Description

Purpose:

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

Input parameters:

parameter_name	Parameter_Data_Type
transmittal	Transmittal

Output parameters:

parameter_name	Parameter_Data_Type
root_object	Object

Valid return codes:

SUCCESS if valid parameters were passed in and the root object was successfully returned.

INVALID_REQUIRED_PARAMETER and root_object is left unaltered if root_object is invalid.

INVALID_TRANSMITTAL and root_object is set to NULL if transmittal is not a valid transmittal.

FAILURE and root_object is set to NULL if:

a) the transmittal does not have a root object;

b) the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.50 GetSortKey

Table 7.51 — GetSortKey

Property

Description

Purpose:

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.

Input parameters:

parameter_name	Parameter_Data_Type
object	Object

Output parameters:

parameter_name	Parameter_Data_Type
sort_key	Integer_Unsigned

Valid return codes:

SUCCESS and sort_key is set appropriately if valid parameters were passed in.

INVALID_REQUIRED_PARAMETER and sort_key is left unaltered if sort_key is invalid.

INVALID_OBJECT and sort_key returns a zero if the object is not a valid SEDRIS object.

FAILURE and sort_key returns a zero if the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.51 GetSRFParameters

Table 7.52 — GetSRFParameters

Property

Description

Purpose:

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.

Input parameters:

parameter_name	Parameter_Data_Type
object	Object

Output parameters:

parameter_name	Parameter_Data_Type
srf_parameters	SRF_Parameters

Valid return codes:

SUCCESS and the scoping SRF parameters are returned in srf_parameters if valid parameters were passed in.

INVALID_REQUIRED_PARAMETER and srf_parameters is left unaltered if srf_parameters is invalid.

INVALID_OBJECT and srf_parameters is left unaltered if the object is not valid.

FAILURE and srf_parameters is left unaltered if:

a) 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, or

b) API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.52 GetTransmittalFromObject

Table 7.53 — GetTransmittalFromObject

Property

Description

Purpose:

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

Input parameters:

parameter_name	Parameter_Data_Type
object	Object

Output parameters:

parameter_name	Parameter_Data_Type
transmittal	Transmittal

Valid return codes:

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

INVALID_REQUIRED_PARAMETER and transmittal is unaffected if transmittal is invalid.

INVALID_OBJECT and transmittal is set to NULL if object is not a valid object from an open transmittal.

UNRESOLVED_START_OBJECT and transmittal is set to NULL if object is unresolved.

OUT_OF_MEMORY and transmittal is set to NULL if memory could not be allocated.

FAILURE and transmittal is set to NULL if the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.53 GetTransmittalLocation

Table 7.54 — GetTransmittalLocation

Property

Description

Purpose:

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

Input parameters:

parameter_name	Parameter_Data_Type
transmittal	Transmittal

Output parameters:

parameter_name	Parameter_Data_Type
location	URN

Valid return codes:

SUCCESS and the location from which the transmittal was opened is returned if valid parameters were passed in.

INVALID_REQUIRED_PARAMETER and location is left unaltered if location is invalid.

INVALID_TRANSMITTAL and location is set to an empty string if transmittal is not a valid open transmittal.

OUT_OF_MEMORY and location is set to an empty string if memory could not be allocated.

FAILURE and location is set to an empty string if the function fails for any other reason.

7.3.54 GetTransmittalName

Table 7.55 — GetTransmittalName

Property

Description

Purpose:

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

Input parameters:

parameter_name	Parameter_Data_Type
transmittal	Transmittal

Output parameters:

parameter_name	Parameter_Data_Type
name	URN

Valid return codes:

SUCCESS and the transmittal name is returned in name if valid parameters were passed in.

INVALID_REQUIRED_PARAMETER and name is left unaltered if name is invalid.

INVALID_TRANSMITTAL and name is returned as an empty URN if transmittal is not a valid, open SEDRIS transmittal.

OUT_OF_MEMORY and name is returned as an empty URN if memory could not be allocated.

FAILURE and name is returned as an empty URN if this function fails for any other reason.

7.3.55 GetTransmittalVersionInformation

Table 7.56 — GetTransmittalVersionInformation

Property

Description

Purpose:

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.

Input parameters:

parameter_name	Parameter_Data_Type
transmittal	Transmittal

Output parameters:

parameter_name	Parameter_Data_Type
major_DRM_version	Short_Integer_Unsigned
minor_DRM_version	Byte_Unsigned
interim_version_DRM_version	Character
major_EDCS_verson	Short_Integer_Unsigned
minor_EDCS_version	Byte_Unsigned
interim_EDCS_version	Character
major_SRM_verson	Short_Integer_Unsigned
minor_SRM_version	Byte_Unsigned
interim_SRM_version	Character

Valid return codes:

SUCCESS and the output parameters are set appropriately if valid parameters were passed in and all operations succeeded.

INVALID_REQUIRED PARAMETER and none of the output parameters are affected if any output parameter is invalid.

INVALID_TRANSMITTAL and none of the output parameters are affected if transmittal does not represent a valid, active (not previously closed) transmittal.

FAILURE and none of the output parameters are affected if the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.56 GetUniqueTransmittalID

Table 7.57 — GetUniqueTransmittalID

Property

Description

Purpose:

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

Input parameters:

parameter_name	Parameter_Data_Type
transmittal	Transmittal

Output parameters:

parameter_name	Parameter_Data_Type
identifier	String

Valid return codes:

SUCCESS and identifier is set appropriately if valid parameters were passed in and all operations succeeded.

INVALID_REQUIRED_PARAMETER and identifier is left unchanged if identifier is invalid.

INVALID_TRANSMITTAL and identifier is returned empty if transmittal is not a valid open transmittal.

OUT_OF_MEMORY and identifier is returned empty if sufficient memory could not be allocated.

FAILURE and identifier is returned empty if the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.57 GetUnresolvedObjectFromPublishedLabel

Table 7.58 — GetUnresolvedObjectFromPublishedLabel

Property

Description

Purpose:

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 insure 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. Care should be taken to insure the reference is indeed correct. The 7.3.83 ResolveObject function is available to do this, but will require that the referenced transmittal be accessible.

Input parameters:

parameter_name	Parameter_Data_Type
transmittal_name	URN
object_label	String
implementation_identifier	String

Output parameters:

parameter_name	Parameter_Data_Type
object	Object

Valid return codes:

SUCCESS and produces the requested handle in object if valid parameters were passed in and all operations succeeded.

INVALID_REQUIRED_PARAMETER and object remains unaltered if transmittal_name, object_label, or object is invalid.

INVALID_TRANSMITTAL_NAME and object returns NULL if the transmittal URN is not valid according to the SEDRIS URN syntax rules.

INVALID_OBJECT_LABEL and object returns NULL if object_label is not valid according to the label syntax rules.

FAILURE and object returns NULL if the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.58 GetUserData

Table 7.59 — GetUserData

Property

Description

Purpose:

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

Input parameters:

parameter_name	Parameter_Data_Type
object	Object

Output parameters:

parameter_name	Parameter_Data_Type
user_data	User_Data

Valid return codes:

SUCCESS and user_data is set appropriately, if valid parameters were passed in and all operations succeeded.

INVALID_REQUIRED_PARAMETER and user_data is left unaltered if user_data is invalid.

INVALID_OBJECT and user_data is set to NULL if object is not a valid SEDRIS object.

UNRESOLVED_OBJECT and user_data is set to NULL if object is not a currently resolved object.

FAILURE and user_data is set to NULL if the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.59 HasAggregates

Table 7.60 — HasAggregates

Property

Description

Purpose:

Determines whether an object has aggregates that it can reach via a two-way aggregation. If a DRM class is specified, only objects of the specified DRM class are considered. Otherwise, all objects are considered.

This function follows the same searching rules as 7.3.21 GetAggregate.

Input parameters:

parameter_name	Parameter_Data_Type
object	Object
drm_class	DRM_Class
itr_traversal	ITR_Behaviour

Output parameters:

parameter_name	Parameter_Data_Type
result	Boolean

Valid return codes:

SUCCESS and result is set appropriately, if valid parameters were passed in and all operations succeeded.

INVALID_REQUIRED_PARAMETER and result is left unaltered if result is invalid.

INVALID_OBJECT and result is set to FALSE if object is invalid.

UNRESOLVED_START_OBJECT and result is set to FALSE if object is currently unresolved.

NO_OBJECT and result is set to FALSE if no aggregate object of the specified DRM class could be found. In this case, the output parameters return NULL.

FAILURE and result is set to FALSE if:

a) drm_class is invalid;

b) if itr_traversal is invalid;

c) the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.60 HasAssociations

Table 7.61 — HasAssociations

Property

Description

Purpose:

This function determines whether an object has associations to other SEDRIS objects. If a DRM class is specified, only objects of the specified DRM class are considered. Otherwise, all objects are considered.

The following conditions are used to determine the presence of an association for the purposes of this function:

a) Aggregations are not considered associations;

b) One-way associations “to” this object are not considered associations;

c) One-way associations “from” this object are not considered associations;

d) Two-way associations in which this object is involved are considered associations;

e) “link” objects (sometimes called “association” objects) are not considered associations. Consider an association object, called object O, attached to an association between objects A and B. Objects A and B have an association between themselves, but by definition object O does not have an association to object A or to object B.

Input parameters:

parameter_name	Parameter_Data_Type
object	Object
drm_class	DRM_Class
itr_traversal	ITR_Behaviour

Output parameters:

parameter_name	Parameter_Data_Type
result	Boolean

Valid return codes:

SUCCESS and result is set to the result of the check, if valid parameters were passed in and all operations succeeded.

INVALID_REQUIRED_PARAMETER and result is left unaltered if result invalid.

INVALID_OBJECT and result returns FALSE if object is not a handle to a valid object.

UNRESOLVED_START_OBJECT and result returns FALSE if object is unresolved.

FAILURE and result returns FALSE if:

a) drm_class is not valid;

b) itr_traversal is not valid; or

c) the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.61 HasComponents

Table 7.62 — HasComponents

Property

Description

Purpose:

This function determines whether an object has components. If a DRM class is specified, only objects of the specified DRM class are considered. Otherwise, all objects are considered.

This function follows the same searching rules as 7.3.24 GetComponent.

Input parameters:

parameter_name	Parameter_Data_Type
object	Object
drm_class	DRM_Class
directly_attach_table_components	Boolean
process_inheritance	Boolean
itr_traversal	ITR_Traversal

Output parameters:

parameter_name	Parameter_Data_Type
result	Boolean

Valid return codes:

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

INVALID_REQUIRED_PARAMETER and result is left unaltered if result is invalid.

INVALID_OBJECT and result returns FALSE if object is not valid.

UNRESOLVED_START_OBJECT and result returns FALSE if object is unresolved.

FAILURE and result returns FALSE if:

a) drm_class is not valid;

b) itr_traversal is not valid;

c) the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.62 InitializeAggregateIterator

Table 7.63 — InitializeAggregateIterator

Property

Description

Purpose:

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

a) They contain the start_object as an immediate component (a component that is exactly one link away) via a two-way aggregation relationship. If an aggregate contains the start_object with a one-way aggregation, the aggregate will not be included in the list of objects returned by this iterator (because if it is a one-way aggregation, the start_object, by definition, does not know which objects aggregate the start_object).

b) 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 a start_object is contained solely by one-way aggregation relationships (if all of the aggregation relationships in the data nodel diagram go into the start_object with an arrow pointing into the start_object), an aggregate iterator for that start_object will not return any objects. An aggregate iterator would be created, but it would have a length of zero and would not return any objects.

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

Input parameters:

parameter_name	Parameter_Data_Type
start_object	Object
filter	Search_Filter
itr_traversal	ITR_Behaviour

Output parameters:

parameter_name	Parameter_Data_Type
iterator	Iterator

Valid return codes:

SUCCESS and a handle for the newly created aggregate iterator is returned in iterator, if valid parameters were passed in and all operations succeeded.

INVALID_REQUIRED_PARAMETER and iterator is left unaltered if iterator is invalid.

INVALID_OBJECT and iterator returns NULL if start_object is not a valid, active (i.e., unfreed) SEDRIS object.

UNRESOLVED_START_OBJECT and iterator returns NULL if start_object is unresolved.

OUT_OF_MEMORY and iterator returns NULL if sufficient memory could not be allocated.

FAILURE and iterator returns NULL if:

a) itr_traversal is not valid;

b) a search filter is provided, but is not a handle to a valid, active (i.e., unfreed) search filter.

c) the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.63 InitializeAssociateIterator

Table 7.64 — InitializeAssociateIterator

Property

Description

Purpose:

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

a) 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 (because 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).

If a start_object is associated solely by one-way incoming associations, or if the start_object does not participate in any associations, an associate iterator for that start_object will not return any objects. An associate iterator would be created, but it would have a length of zero and would 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 finished with an iterator to free it. Iterators can be freed at any time (e.g., they can be freed before all of their objects have been returned).

Input parameters:

parameter_name	Parameter_Data_Type
start_object	Object
filter	Search_Filter
itr_traversal	ITR_Behaviour

Output parameters:

parameter_name	Parameter_Data_Type
iterator	Iterator

Valid return codes:

SUCCESS and a handle for the newly created associate iterator returned in iterator if valid parameters were passed in.

INVALID_REQUIRED_PARAMETER and iterator is unaltered if iterator is invalid.

INVALID_OBJECT and iterator returns NULL if start_object is not a valid, active (i.e., unfreed) SEDRIS object.

UNRESOLVED_START_OBJECT and iterator returns NULL if start_object is unresolved.

OUT_OF_MEMORY and iterator returns NULL if sufficient memory could not be allocated.

FAILURE and iterator returns NULL if:

a) itr_traversal is not valid;

b) a search filter is provided, but is not a handle to a valid, active (i.e., unfreed) search filter.

c) the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.64 InitializeComponentIterator

Table 7.65 — InitializeComponentIterator

Property

Description

Purpose:

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 far down (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 will search until it has tested every object in the “aggregation-tree” rooted by the start_object.

Objects returned by a component iterator will meet these conditions:

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

b) 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 will only be searched until that maximum search depth has been reached. Components beyond that depth will not be searched.

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

If a 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 would be created, but it would have a length of zero and would not return any objects.

The 7.3.35 GetNextObject function should be 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 finished with an iterator to free it. Iterators can be freed at any time (e.g., they can be freed before all of their objects have been returned).

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

d) If an <DRM Attribute Set Index> would otherwise be returned by the component iterator, the <DRM Attribute Set Index> object will be automatically replaced by the corresponding objects referenced by the primary (1st) <DRM Attribute Set> of the referenced <DRM Attribute Set Table Group>.

e) If a <DRM Colour Index> would otherwise be returned by the component iterator, the <DRM Colour Index> object will 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>).

f) If a <DRM Vertex with Component Indices> object references an element of a <DRM Hierarchical Table> object (<Colour Entry Table>, <DRM Location Table>, <DRM Property Table Reference Table>, <DRM Reference Vector Table>, or <DRM Texture Coordinate Table>), the following objects will be returned as directly attached components of the <DRM Vertex with Component Indices> (effectively traversing up the aggregation tree in order to pull out the indexed object(s) from the appropriate <DRM Hierarchical Table> and making them explicit components of the <DRM Vertex with Component Indices> object):

1) In the case of <DRM Location Table> elements, the indexed <DRM Location 3D> component will be directly attached to the <DRM Vertex with Component Indices> object.

2) In the case of <DRM Property Table Reference Table> elements, the indexed <DRM Property Table Reference> component will be directly attached to the <DRM Vertex with Component Indices> object.

3) In the case of <DRM Reference Vector Table> elements, the indexed <DRM Reference Vector> component will be directly attached to the <DRM Vertex with Component Indices> object.

4) In the case of <DRM Colour Entry Table> elements, and if the <DRM Colour Entry Table> components are <DRM Colour>, the indexed <DRM Colour> will appear as an <DRM Inline Colour> directly attached to the <DRM Vertex with Component Indices>. If the <DRM Colour Entry Table> components are <DRM Colour Set>s, the <DRM Colour> components of the indexed <DRM Colour Set> will appear as direct <DRM Inline Colour> components of the <DRM Vertex with Component Indices>.

If the process_inheritence parameter has value TRUE, “inherited components” will be inherited, and they will show up as components of the appropriate objects. These “inherited” components will be just as “valid” as “direct” components, and they will satisfy the COMPONENT_TYPE_MATCH, COMPONENT_FIELD_MATCH, and COMPONENT_RANGE_MATCH macros just as “direct” components do.

If the transform_locations parameter has value TRUE, all <DRM Location> objects will 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 will 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 will be evaluated, and their results will “overwrite” the appropriate fields 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 any-order-the-API-chooses manner. The depth-first and breadth-first approaches allow for full transformation and inherited component information to be maintained at all times. The API-chooses-an-order approach can be faster, possibly much faster, but there is no guarantee that any 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.

Input parameters:

parameter_name	Parameter_Data_Type
start_object	Object
boundary	Search_Boundary
filter	Search_Filter
directly_attach_table_components	Boolean
process_inheritence	Boolean
transform_locations	Boolean
follow_model_instances	Boolean
evaluate_static_control_links	Boolean
select_parameters	Hierarchy_Select_Parameters
traversal_order_parameters	Hierarchy_Order_Parameters
general_traversal_pattern	Traversal_Order
itr_traversal	ITR_Behaviour

Output parameters:

parameter_name	Parameter_Data_Type
iterator	Iterator

Valid return codes:

SUCCESS and iterator returns a handle for the newly created component iterator if valid parameters were passed in and all operations succeeded.

INVALID_REQUIRED_PARAMETER and iterator is left unaltered if iterator is invalid.

INVALID_OBJECT and iterator returns NULL if start_object is not a valid, active (i.e., unfreed) SEDRIS object.

UNRESOLVED_START_OBJECT and iterator returns NULL if start_object is unresolved. In this case, no iterator is returned.

OUT_OF_MEMORY and iterator returns NULL if memory could not be allocated. In this case, no iterator is returned.

FAILURE and iterator returns NULL if:

a) itr_traversal is not valid;

b) general_traversal_pattern is not valid;

c) selection_parameters are provided but are not valid;

d) traversal order parameters are provided, but are not valid;

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

f) a spatial search boundary is provided, but is not a legal, valid spatial search boundary for the scope of start_object;

g) the start_object, search filter, and/or spatial search boundary came from different transmittals, or

h) the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.65 InitializeInheritedComponentIterator

Table 7.66 — InitializeInheritedComponentIterator

Property

Description

Purpose:

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.

Input parameters:

parameter_name	Parameter_Data_Type
start_object	Object
filter	Search_Filter
directly_attach_table_components	Boolean
itr_traversal	ITR_Behaviour

Output parameters:

parameter_name	Parameter_Data_Type
iterator	Iterator

Valid return codes:

SUCCESS and iterator returns a newly created inherited component iterator if valid parameters were passed in and all operations succeeded.

INVALID_REQUIRED_PARAMETER and iterator is left unaltered if iterator is invalid.

INVALID_OBJECT and iterator returns NULL if start_object is not a valid, active (i.e., unfreed) SEDRIS object.

UNRESOLVED_START_OBJECT and iterator returns NULL if start_object is unresolved.

OUT_OF_MEMORY and iterator returns NULL if memory could not be allocated.

FAILURE and iterator returns NULL if:

a) itr_traversal is not valid;

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

c) the start_object and search filter came from different API implementations, or

d) the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.66 ObjectIsPublished

Table 7.67 — ObjectIsPublished

Property

Description

Purpose:

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

Input parameters:

parameter_name	Parameter_Data_Type
object	Object

Output parameters:

parameter_name	Parameter_Data_Type
result	Boolean

Valid return codes:

SUCCESS and result is set appropriately if valid parameters were passed in.

INVALID_REQUIRED_PARAMETER and result is left unaltered if result is invalid.

INVALID_OBJECT and result is set to FALSE if object is not a valid, active (i.e., unfreed) SEDRIS object.

UNRESOLVED_OBJECT and result is set to FALSE if object is not a resolved object.

FAILURE and result is set to FALSE if if the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.67 ObjectIsResolved

Table 7.68 — ObjectIsResolved

Property

Description

Purpose:

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

Input parameters:

parameter_name	Parameter_Data_Type
object	Object

Output parameters:

parameter_name	Parameter_Data_Type
result	Boolean

Valid return codes:

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

INVALID_REQUIRED_PARAMETER and result is left unaltered if result is invalid.

INVALID_OBJECT and result returns FALSE if object is not a valid, active (i.e., unfreed) SEDRIS object.

FAILURE and result is set to FALSE if the function fails for any other reason.

7.3.68 ObjectsAreSame

Table 7.69 — ObjectsAreSame

Property

Description

Purpose:

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

Input parameters:

parameter_name	Parameter_Data_Type
object_1	Object
object_2	Object

Output parameters:

parameter_name	Parameter_Data_Type
result	Boolean

Valid return codes:

SUCCESS and result returns the result of the check if valid parameters were passed in and all operations succeeded.

INVALID_REQUIRED_PARAMETER and result is left unaltered if result is invalid.

INVALID_OBJECT and result returns FALSE if either object1 or object2 is not a valid SEDRIS object.

UNRESOLVED_OBJECT and result returns FALSE if object1 or object2 is not a currently resolved object.

FAILURE and result returns FALSE if the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.69 OpenTransmittalByLocation

Table 7.70 — OpenTransmittalByLocation

Property

Description

Purpose:

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

Input parameters:

parameter_name	Parameter_Data_Type
location	URN
implementation_identifier	String
access_mode	Access_Mode

Output parameters:

parameter_name	Parameter_Data_Type
transmittal	Transmittal

Valid return codes:

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.

INVALID_REQUIRED_PARAMETER and transmittal is left unaltered if transmittal is invalid.

TRANSMITTAL_INACCESSIBLE and transmittal returns NULL if the location was not accessible.

INVALID_ACCESS_MODE and transmittal returns NULL if the location was found but the security permissions of the underlying system (OS / filesystem) prohibited access to the file in the mode specified. This could occur if:

a) the file was opened for read-only or update and the file did not exist, or

b) the file location specified a non-local file and the API had no transport mechanism for accessing the remote file.

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 implementation(s) of the SEDRIS API linked to the application.

OUT_OF_MEMORY and transmittal returns NULL if sufficient memory could not be allocated.

FAILURE and transmittal returns NULL if:

c) dynamic binding is specified at compile time, but the shared library for the specified API implementation cannot be found,

d) dynamic binding is specified at compile time, but the API implementation specified does not provide this function in its shared library,

any problems not covered by the above are encountered while finding or opening the SEDRIS transmittal specified by the location parameter.

7.3.70 OpenTransmittalByName

Table 7.71 — OpenTransmittalByName

Property

Description

Purpose:

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.

Input parameters:

parameter_name	Parameter_Data_Type
transmittal_name	URN
implementation_identifier	String
access_mode	Access_Mode

Output parameters:

parameter_name	Parameter_Data_Type
transmittal	Transmittal

Valid return codes:

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.

INVALID_REQUIRED_PARAMETER and transmittal is left unaltered if transmittal is invalid.

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.

UNRESOLVED_TRANSMITTAL and transmittal returns NULL if transmittal_name could not be resolved to a file location.

TRANSMITTAL_INACCESSIBLE and transmittal out returns NULL if the transmittal location was not accessible.

INVALID_ACCESS_MODE and transmittal returns NULL if:

a) the resolved file location was found, but the security permissions of the underlying system (OS / filesystem) 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.

b) if create or update mode was requested and the API implementation does not support the write capability.

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.

OUT_OF_MEMORY and transmittal returns NULL if sufficient memory could not be allocated.

FAILURE and transmittal returns NULL if:

c) dynamic binding is specified at compile time, but the shared library for the specified API implementation cannot be found,

d) dynamic binding is specified at compile time, but the API implementation specified does not provide this function in its shared library,

e) any problems not covered by the above are encountered while finding or opening the SEDRIS transmittal specified by the transmittal_name parameter.

7.3.71 PublishObject

Table 7.72 — PublishObject

Property

Description

Purpose:

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.

Input parameters:

parameter_name	Parameter_Data_Type
object	Object
label	String

Output parameters:

parameter_name	Parameter_Data_Type
none

Valid return codes:

SUCCESS and object is successfully published if valid parameters were passed in and all operations succeeded.

INVALID_REQUIRED_PARAMETER and object is not published if label is an empty string.

INVALID_OBJECT and object is not published if object is not a valid, active (i.e., unfreed) SEDRIS object.

UNRESOLVED_OBJECT and object is not published if object is unresolved.

INVALID_OBJECT_LABEL and object is not published if label does not adhere to the required conventions or is already in use.

INVALID_ACCESS_MODE and object is not published if object belongs to a transmittal opened in read-only mode.

FAILURE and object is not published if the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.72 PutDataTable

Table 7.73 — PutDataTable

Property

Description

Purpose:

This function creates all the cells of the given <DRM Data Table>. (7.3.73 PutDataTableExtent is available to create only a section of the <DRM Data Table>.)

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

Input parameters:

parameter_name	Parameter_Data_Type
element_count	Integer_Positive
table_property_description_numbers	Integer_Positive[element_count]
byte_count	Integer_Unsigned
data	Property_Data_Value[element_count]

Input/Output parameters:

parameter_name	Parameter_Data_Type
data_table	Object

Output parameters:

parameter_name	Parameter_Data_Type
none

Valid return codes:

SUCCESS and the cells of data_table are created as specified if valid parameters were passed in and all operations succeeded.

INVALID_REQUIED_PARAMETER and data_table is unaffected if:

a) data is invalid,

b) element_count is zero,

c) table_property_description_number is invalid, or

d) byte_count is zero.

INVALID_OBJECT and data_table is unaffected if data_table is not a valid, active (i.e., unfreed) <DRM Data Table> instance.

UNRESOLVED_OBJECT and data_table is unaffected if data_table is unresolved.

INVALID_ACCESS_MODE and data_table is unaffected if data_table belongs to a transmittal that was opened in read-only mode.

FAILURE and data_table is unaffected if any of the following conditions are encountered:

e) data_table does not belong to an open transmittal;

f) data_table is a <DRM Property Grid> with data_present set to FALSE (note that the default value of this field is TRUE, if the fields of the <DRM Property Grid> have not yet been set);

g) the byte_count is not correct for the given extents and set of table_property_description_number entries;

h) the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.73 PutDataTableExtent

Table 7.74 — PutDataTableExtent

Property

Description

Purpose:

This function creates the specified region of the cells of the given <DRM Data Table>. (PutDataTable is available to create an entire <DRM Data Table>.)

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

Input parameters:

parameter_name	Parameter_Data_Type
extents	Data_Table_Extents
element_count	Integer_Positive
table_property_description_numbers	Integer_Positive[element_count]
byte_count	Integer_Unsigned
data	Property_Data_Value[element_count]

Input/Output parameters:

parameter_name	Parameter_Data_Type
data_table	Object

Output parameters:

parameter_name	Parameter_Data_Type
none

Valid return codes:

SUCCESS and the cells of data_table are created as specified if valid parameters were passed in and all operations succeeded.

INVALID_REQUIRED_PARAMETER and data_table is unaffected if:

a) data is invalid,

b) extents is invalid,

c) element_count is zero,

d) table_property_description_number is invalid, or

e) byte_count is zero.

INVALID_OBJECT and data_table is unaffected if data_table is not a handle to a valid, active (i.e., unfreed) <DRM Data Table> instance.

UNRESOLVED_OBJECT and data_table is unaffected if data_table is an unresolved object.

INVALID_ACCESS_MODE and data_table is unaffected if data_table belongs to a transmittal that was opened in read-only mode.

FAILURE and data_table is unaffected if any of the following conditions are encountered:

f) data_table does not belong to an open transmittal;

g) data_table is a <DRM Property Grid> with data_present set to FALSE (note that the default value of this field is TRUE, if the user has not yet set the fields of the <DRM Property Grid>);

h) the specified extents are not valid for the given <DRM Data Table>;

i) the byte_count is not correct for the given extents and set of table_property_description_number entries, or

j) the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.74 PutElementOfDataTable

Table 7.75 — PutElementOfDataTable

Property

Description

Purpose:

For each cell of the given <DRM Data Table>, this function creates exactly one element from the given data value. (7.3.75 PutElementOfDataTableExtent is available to do this for a subregion of the <DRM Data Table> rather than the entire <DRM Data Table>. 7.3.72 PutDataTable is available to create multiple elements per cell).

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

Input parameters:

parameter_name	Parameter_Data_Type
data_table	Object
table_property_description_number	Integer_Positive
byte_count	Integer_Unsigned
data	Property_Data_Value

Input/Output parameters:

parameter_name	Parameter_Data_Type
data_table	Object

Output parameters:

parameter_name	Parameter_Data_Type
none

Valid return codes:

SUCCESS and the cells are created as specified if valid parameters were passed in and all operations succeeded.

INVALID_REQUIRED_PARAMETER and data_table is unaffected if data_table is zero or byte_count is zero.

INVALID_OBJECT and data_table is unaffected if data_table is not a handle to a valid, active (i.e., unfreed) saved <DRM Data Table> instance.

UNRESOLVED_OBJECT and data_table is unaffected if data_table is an unresolved object

INVALID_ACCESS_MODE and data_table is unaffected if data_table belongs to a transmittal that was opened in read-only mode.

FAILURE and data_table is unaffected if any of the following conditions are encountered:

a) table_property_description_number does not form a valid <DRM Data Table> signature;

b) <DRM Data Table> does not belong to an open transmittal;

c) <DRM Data Table> is a <DRM Property Grid> with data_present set to FALSE (note that the default value of this field is TRUE, if the user has not yet set the fields of the <DRM Property Grid>);

d) byte_count is not correct for the given table_property_description_number.

e) the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.75 PutElementOfDataTableExtent

Table 7.76 — PutElementOfDataTableExtent

Property

Description

Purpose:

This function copies the selected element from a buffer into the selected area of interest of the given <DRM Data Table>.

For each cell in the specified area of interest in the given <DRM Data Table> instance, this function creates exactly one element from the given data. (7.3.74 PutElementOfDataTable is available to do this for the entire <DRM Data Table> instance rather than a subregion. 7.3.73 PutDataTableExtent is available to create multiple elements per cell.)

Input parameters:

parameter_name	Parameter_Data_Type
extents	Data_Table_Extents
table_property_description_number	Integer_Positive
byte_count	Integer_Unsigned
data	Property_Data_Value

Input/Output parameters:

parameter_name	Parameter_Data_Type
data_table	Object

Output parameters:

parameter_name	Parameter_Data_Type
none

Valid return codes:

SUCCESS and the cells are created as specified if valid parameters were passed in and all operations succeeded.

INVALID_REQUIRED_PARAMETER and data_table is unaffected if extents is invalid, table_property_description_number is zero, or byte_count is zero.

INVALID_OBJECT and data_table is unaffected if data_table is not a handle to a valid, active (i.e., unfreed), saved <DRM Data Table> instance.

UNRESOLVED_OBJECT and data_table is unaffected if data_table is an resolved object.

INVALID_ACCESS_MODE and data_table is unaffected if data_table belongs to a transmittal that was opened in read-only mode.

FAILURE and data_table is unaffected if any of the following conditions are encountered:

a) the given table_property_description_number does not form a valid <DRM Data Table> signature;

b) data_table does not belong to an open transmittal;

c) data_table is a <DRM Property Grid> with data_present set to FALSE (note that the default value of this field is TRUE, if the fields of the <DRM Property Grid> have not yet been set);

d) byte_count is not correct for the given table_property_description_number;

e) the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.76 PutFields

Table 7.77 — PutFields

Property

Description

Purpose:

This function is modifies the fields of a given object. existing_object shall be 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.

Input parameters:

parameter_name	Parameter_Data_Type
new_fields	DRM_Class_Fields

Input/Output parameters:

parameter_name	Parameter_Data_Type
existing_object	Object

Output parameters:

parameter_name	Parameter_Data_Type
none

Valid return codes:

SUCCESS and the fields of the given object are replaced with the given fields if valid parameters were passed in and all operations succeeded.

INVALID_OBJECT and existing_object is left unaltered if existing_object is not a valid, active (i.e., unfreed) SEDRIS object.

UNRESOLVED_OBJECT and existing_object is left unaltered if existing_object is unresolved.

INVALID_ACCESS_MODE and existing_object is left unaltered if existing_object belongs to a transmittal opened in read-only mode.

OUT_OF_MEMORY and existing_object is left unaltered if sufficient memory for the new fields could not be allocated.

FAILURE and existing_object is left unaltered if:

a) the class of new_fields does not match the class of existing_object;

b) the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.77 PutImageData

Table 7.78 — PutImageData

Property

Description

Purpose:

This function copies the selected texels from a buffer into the selected area of interest of the given <DRM Image> instance.

A <DRM Image> instance is a set of two-dimensional or three-dimensional collections of texel values. The number of MIP levels for the <DRM Image> instance defines the number of two-dimensional or three-dimensional collections in the <DRM Image> instance. The definition of the <DRM Image> instance will define the number of texels in each MIP level and the number of bits for each texel.

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

Input parameters:

parameter_name	Parameter_Data_Type
start_texel_horizontal	Integer_Unsigned
start_texel_vertical	Integer_Unsigned
start_texel_z	Integer_Unsigned
stop_texel_horizontal	Integer_Unsigned
stop_texel_vertical	Integer_Unsigned
stop_texel_z	Integer_Unsigned
mip_level	Short_Integer_Unsigned
byte_count	Integer_Unsigned
data	Byte_Unsigned[byte_count]

Input/Output parameters:

parameter_name	Parameter_Data_Type
image	DRM_Image

Output parameters:

parameter_name	Parameter_Data_Type
none

Valid return codes:

SUCCESS and the texels of image are created as specified if valid parameters were passed in and all operations succeeded.

INVALID_REQUIRED_PARAMETER and image is unaffected if data is invalid.

INVALID_OBJECT and image is unaffected if image has not yet been added to the transmittal.

UNRESOLVED_OBJECT and image is unaffected if image is an unresolved object.

INVALID_ACCESS_MODE and image is unaffected if image belongs to a transmittal that was opened in read-only mode.

FAILURE and image is unaffected if any of the following conditions are encountered:

a) image does not belong to an open transmittal;

b) mip_level is out of range for the image’s level_count;

c) the image’s mip_extents_array is invalid;

d) the start and stop extents are out of range for the specified mip_level, or stop greater than start for any of the extents;

e) a partial image is specified;

f) the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.78 PutPackedDataTable

Table 7.79 — PutPackedDataTable

Property

Description

Purpose:

This function creates all the cells of the given <DRM Data Table> in a packed format. The 7.3.79 PutPackedDataTableExtent function is available to create only a section of the <DRM Data Table>.

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

Input parameters:

parameter_name	Parameter_Data_Type
element_count	Integer_Positive
table_property_description_number	Integer_Positive[element_count]
byte_count	Integer_Unsigned[element_count]
data	Byte_Unsigned[byte_count]

Input/Output parameters:

parameter_name	Parameter_Data_Type
data_table	Object

Output parameters:

parameter_name	Parameter_Data_Type
none

Valid return codes:

SUCCESS if valid parameters were passed in and all operations succeeded.

INVALID_REQUIED_PARAMETER and data_table is unaffected if:

a) data is invalid,

b) element_count is zero,

c) table_property_description_number is invalid, or

d) byte_count is zero.

INVALID_OBJECT and data_table is unaffected if data_table is not a handle to a valid, active (i.e., unfreed), saved <DRM Data Table> instance.

UNRESOLVED_OBJECT and data_table is unaffected if data_table is an resolved object.

INVALID_ACCESS_MODE and data_table is unaffected if data_table belongs to a transmittal that was opened in read-only mode.

FAILURE and data_table is unaffected if any of the following conditions are encountered:

e) the given table_property_description_number does not form a valid <DRM Data Table> signature;

f) <DRM Data Table> does not belong to an open transmittal;

g) <DRM Data Table> is a <DRM Property Grid> with data_present set to FALSE (note that the default value of this field is TRUE, if the user has not yet set the fields of the <DRM Property Grid>);

h) the byte_count is not correct for the given extents and set of table_property_description_number entries, or

i) the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.79 PutPackedDataTableExtent

Table 7.80 — PutPackedDataTableExtent

Property

Description

Purpose:

This function creates the cells of the specified subregion of the given <DRM Data Table> in a packed format. The PutPackedDataTable function should be used to create the entire <DRM Data Table> at once.

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

Input parameters:

parameter_name	Parameter_Data_Type
extents	Data_Table_Extents
element_count	Integer_Positive
table_property_description_number	Integer_Positive[element_count]
byte_count	Integer_Unsigned
data	Byte_Unsigned[byte_count]

Input/Output parameters:

parameter_name	Parameter_Data_Type
data_table	Object

Output parameters:

parameter_name	Parameter_Data_Type
none

Valid return codes:

SUCCESS and the specified cells of data_table are created as requested if valid parameters were passed in and all operations succeeded.

INVALID_REQUIED_PARAMETER and data_table is unffected if:

a) data is invalid,

b) extents is invalid,

c) table_property_description_number is invalid, or

d) element_count is zero.

INVALID_OBJECT and data_table is unffected if data_table is not a handle to a valid, active (i.e., unfreed), saved instance.

UNRESOLVED_OBJECT and data_table is unffected if data_table is an resolved object.

INVALID_ACCESS_MODE and data_table is unffected if data_table belongs to a transmittal that was opened in read-only mode.

FAILURE and data_table is unffected if any of the following conditions are encountered:

e) the table_property_description_number does not form a valid <DRM Data Table> signature;

f) data_table does not belong to an open transmittal;

g) data_table is a <DRM Property Grid> with data_present set to FALSE (note that the default value of this field is TRUE, if the fields of the <DRM Property Grid> have not yet been set);

h) the specified extents are not valid for the given <DRM Data Table> instance;

i) the byte_count is not correct for the given extents and set of table_property_description_number entries, or

j) the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.80 RemoveAssociateRelationship

Table 7.81 — RemoveAssociateRelationship

Property

Description

Purpose:

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

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

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

Input parameters:

parameter_name	Parameter_Data_Type
remove_two_way	Boolean

Input/Output parameters:

parameter_name	Parameter_Data_Type
from_object	Object
to_object	Object
link_object	Object

Output parameters:

parameter_name	Parameter_Data_Type
none

Valid return codes:

SUCCESS and the relationship is removed if valid parameters were passed in and all operations succeeded.

INVALID_OBJECT and no changes are made if:

a) from_object is not a valid, saved SEDRIS object,

b) to_object is not a valid, saved SEDRIS object,

c) link_object is provided, but is not a valid, saved SEDRIS object.

UNRESOLVED_START_OBJECT and no changes are made if from_object is unresolved or link_object is provided but is unresolved.

UNRESOLVED_OBJECT and no changes are made if remove_two_way has value TRUE and the DRM defines the relationship as bidirectional, but to_object is unresolved, so the relationship from to_object to from_object cannot be removed.

INVALID_ACCESS_MODE and no changes are made if:

d) to_object is in a transmittal that is open in READ_ONLY mode;

e) link_object was provided but is in a transmittal that is open in READ_ONLY mode; and/or

f) to_object is resolved, has a relationship back to from_object and remove_two_way has value TRUE but to_object is in a transmittal that is open in READ_ONLY mode.

IFAILURE and no changes are made if:

g) from_object and to_object are not related by an associate relationship;

h) if link_object is provided, and it is not the link object for the relationship; or

i) the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.81 RemoveComponentRelationship

Table 7.82 — RemoveComponentRelationship

Property

Description

Purpose:

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

The relationship being removed may be one-way or two-way. If it is two-way, both connections are removed, unless the component is unresolved.

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

Input parameters:

parameter_name	Parameter_Data_Type
none

Input/Output parameters:

parameter_name	Parameter_Data_Type
aggregate_object	Object
component_object	Object
link_object	Object

Output parameters:

parameter_name	Parameter_Data_Type
none

Valid return codes:

SUCCESS and the specified relationship is removed if valid parameters were passed inand all operations succeeded.

INVALID_OBJECT and no changes are made if:

a) aggregate_object is not a valid, saved object belonging to a valid DRM class,

b) component_object is not a valid, saved object belonging to a valid DRM class, or

c) link_object is provided, but is not a valid, saved object belonging to a valid DRM class.

UNRESOLVED_START_OBJECT and no changes are made if aggregate_object is unresolved or link_object is provided but is unresolved.

UNRESOLVED_OBJECT and no changes are made if remove_two_way has value TRUE and the DRM defines the relationship as bidirectional, but component_object is unresolved, so the relationship from component_object to aggregate_object cannot be removed.

INVALID_ACCESS_MODE and no changes are made if:

d) aggregate_object is in a transmittal that is open in READ_ONLY mode;

e) link_object was provided but is in a transmittal that is open in READ_ONLY mode; and/or

f) component_object is resolved, has a relationship back to aggregate_object but component_object is in a transmittal that is open in READ_ONLY mode.

FAILURE and no changes are made if:

g) aggregate_object and component_object are not related by a component relationship;

h) if link_object is provided, and it is not the link object for the relationship;

i) the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.82 RemoveFromTransmittal

Table 7.83 — RemoveFromTransmittal

Property

Description

Purpose:

This function removes the specified object from the specified SEDRIS transmittal.

Prior to calling this function, any relationships that old_object has with other objects shall have been removed. Otherwise, dangling references to old_object will result.

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

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

Input parameters:

parameter_name	Parameter_Data_Type
old_object	Object
transmittal	Transmittal

Output parameters:

parameter_name	Parameter_Data_Type
none

Valid return codes:

SUCCESS if valid parameters were passed in and all operations succeeded.

INVALID_OBJECT and no changes are made if old_object is not a valid, active (i.e., unfreed) saved object. (That is, if old_object was never added to a transmittal, it cannot be removed from a transmittal).

INVALID_TRANSMITTAL and no changes are made if transmittal is not a valid, active (i.e., not closed and not freed) transmittal.

DIFFERENT_TRANSMITTAL and no changes are made if old_object is in a different transmittal than the transmittal specified.

UNRESOLVED_START_OBJECT and no changes are made if old_object is unresolved (old_object was removed but the object it referenced in another transmittal was not).

INVALID_ACCESS_MODE and no changes are made if transmittal was opened in read-only mode.

FAILURE and no changes are made if the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.83 ResolveObject

Table 7.84 — ResolveObject

Property

Description

Purpose:

Given an unresolved SEDRIS object, this function attempts to resolve the reference.

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

Note that a SEDRIS transmittal that has been opened in this way cannot be modified. The transmittal shall be explicitly opened for writing or modification to do this.

Input parameters:

parameter_name	Parameter_Data_Type
object	Object

Output parameters:

parameter_name	Parameter_Data_Type
none

Valid return codes:

SUCCESS and object becomes resolved if valid parameters were passed in and all operations succeeded.

INVALID_OBJECT and object is left unaltered if object is not a valid, active (i.e., not freed) SEDRIS object.

UNRESOLVED_OBJECT and object is left unaltered if object passed in could not be resolved. This value indicates that the transmittal name was successfully resolved, but the transmittal did not contained the object label as a published object.

UNRESOLVED_TRANSMITTAL and object is left unaltered if object could not be resolved. This value indicates that the transmittal name portion of the reference could not be resolved.

FAILURE and object is left unaltered if the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.84 ResolveTransmittalName

Table 7.85 — ResolveTransmittalName

Property

Description

Purpose:

Given a character string representing a formal SEDRIS transmittal name, this function returns the file location associated with this name.

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

Input parameters:

parameter_name	Parameter_Data_Type
transmittal_name	String

Output parameters:

parameter_name	Parameter_Data_Type
location	URN

Valid return codes:

SUCCESS and location returns the location associated with the transmittal if valid parameters were passed in and transmittal_name was successfully resolved.

INVALID_REQUIRED_PARAMETER and location is left unaltered if transmittal_name or location is invalid.

INVALID_TRANSMITTAL_NAME and location is left unaltered if transmittal_name did not specify a name that was valid according to the format of the SEDRIS URN namespace.

UNRESOLVED_TRANSMITTAL and location returns an empty URN if transmittal_name could not be resolved to a transmittal location.

OUT_OF_MEMORY and location returns an empty URN if sufficient memory could not be allocated.

FAILURE and location returns an empty URN if this function fails for any other reason.

7.3.85 SetColourModel

Table 7.86 — SetColourModel

Property

Description

Purpose:

This function sets the colour model that will be used to represent all <DRM Colour Data> objects retrieved after this function is called. This function has no effect on <DRM Colour Data> objects that were returned to the user before this function was called. By default (if this function is not called), colours are returned to the user in the format in which the colours were defined in the transmittal from which the colours were extracted. So, if a SEDRIS transmittal contains HSV colours, by default these colours will be returned to the user as <DRM HSV_Colour> objects. If the user calls the 7.3.85 SetColourModel function and sets the colour model to RGB_MODEL, all colours returned after this call would be returned as <DRM RGB_Colour> objects.

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

Input parameters:

parameter_name	Parameter_Data_Type
colour_model	Colour_Model

Valid return codes:

SUCCESS and the current colour model of this API is changed to the colour model specified by colour_model if colour_model is valid.

FAILURE and the current colour model is not changed if colour_model is invalid.

7.3.86 SetFirstErrorMessage

Table 7.87 — SetFirstErrorMessage

Property

Description

Purpose:

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

Input parameters:

parameter_name	Parameter_Data_Type
message	String

Output parameters:

parameter_name	Parameter_Data_Type
none

Valid return codes:

none

7.3.87 SetGeneralCallback

Table 7.88 — SetGeneralCallback

Property

Description

Purpose:

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

A general function (general single function) callback has priority over this general (general for all functions) callback. See the 7.3.88 SetGeneralCallbackForOneFunction function comments for more details about general function callbacks. A specific function/specific status code callback has priority over both general function callbacks and general callbacks. More details may be found under the 7.3.91 SetSpecificCallback function.

Input parameters:

parameter_name	Parameter_Data_Type
user_defined_function	Status_Logger

Input parameters:

parameter_name	Parameter_Data_Type
none

Valid return codes:

none

7.3.88 SetGeneralCallbackForOneFunction

Table 7.89 — SetGeneralCallbackForOneFunction

Property

Description

Purpose:

This function registers a user-defined function as the “callback” function to be called when any status code is about to be returned by the given transmittal API function. This user-defined function shall be defined to match the signature required of a Status_Logger function.

This callback will not be called if a specific status code is about to be returned from the selected transmittal function and that particular function and status code currently has a specific function/specific status code callback set by the 7.3.91 SetSpecificCallback function. A specific function/specific status code callback set by that call takes priority over a general function callback set by this function.

More details may be found under 7.3.91 SetSpecificCallback.

Input parameters:

parameter_name	Parameter_Data_Type
user_defined_function	Status_Logger
function_to_catch	Transmittal_API_Function

Output parameters:

parameter_name	Parameter_Data_Type
none

Valid return codes:

SUCCESS and the specified callback is set if valid parameters were passed in.

FAILURE and no changes are made if function_to_catch is invalid.

7.3.89 SetRootObject

Table 7.90 — SetRootObject

Property

Description

Purpose:

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

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

Input parameters:

parameter_name	Parameter_Data_Type
transmittal	Transmittal
new_root_object	Object

Output parameters:

parameter_name	Parameter_Data_Type
old_root_object	Object

Valid return codes:

SUCCESS and the previously set root object is returned in old_root_object (if requested), and new_root_object is set to be the new root object of transmittal, if valid parameters were passed in and all operations succeeded. If the root object for the transmittal had not been previously set and the old root object had been requested, old_root_object will be set to NULL.

INVALID_REQUIRED_PARAMETER and the output parameters are left unaltered if old_root_object is invalid.

INVALID_TRANSMITTAL and the output parameters are left unaltered if transmittal is not a handle to a valid, active (i.e., open) SEDRIS transmittal.

INVALID_OBJECT and the output parameters are left unaltered if new_root_object is not a valid, active (i.e., unfreed) object.

UNRESOLVED_OBJECT and the output parameters are left unaltered if new_root_object is not a resolved object.

INVALID_ACCESS_MODE and the output parameters are left unaltered if transmittal was opened in read-only mode.

DIFFERENT_TRANSMITTAL and the output parameters are left unaltered if new_root_object does not belong to the given transmittal.

OUT_OF_MEMORY and the output parameters are left unaltered if sufficient memory could not be allocated.

FAILURE and the output parameters are left unaltered if the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.90 SetSecondErrorMessage

Table 7.91 — SetSecondErrorMessage

Property

Description

Purpose:

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

Input parameters:

parameter_name	Parameter_Data_Type
message	String

Output parameters:

parameter_name	Parameter_Data_Type
none

Valid retnrn codes:

none

7.3.91 SetSpecificCallback

Table 7.92 — SetSpecificCallback

Property

Description

Purpose:

This function registers a user-defined function as the “callback” function to be called when the given status code is about to be returned by the specified API function. This user-defined function shall be of type Status_Logger.

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

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

Input parameters:

parameter_name	Parameter_Data_Type
user_defined_function	Status_Logger
function_to_catch	Transmittal_API_Function
status_code_to_catch	Status_Code

Output parameters:

parameter_name	Parameter_Data_Type
none

Valid return codes:

SUCCESS and the callback is set if valid parameters were passed in.

FAILURE and no changes are made if:

a) function_to_catch or status_code_to_catch is invalid;

b) the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.92 SetSRFParameters

Table 7.93 — SetSRFParameters

Property

Description

Purpose:

This function sets the spatial reference frame (SRF) that will be used to represent all <DRM Location> objects returned after this function is called. This function has no effect on <DRM Location> objects that have already been returned to the user before this function was called. Details on the various SRFs supported by SEDRIS may be found in ISO/IEC 18026--Spatial Reference Model (SRM) (see 2.[I18026]).

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

SPECIAL EXCEPTION:

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

Input parameters:

parameter_name	Parameter_Data_Type
new_srf_parameters	SRF_Parameters

Output parameters:

parameter_name	Parameter_Data_Type
none

Valid return codes:

SUCCESS and the current retrieval SRF is set to the SRF specified by new_srf_parameters if valid parameters were passed in.

OUT_OF_MEMORY and the retrieval SRF is not changed, if the API implementation cannot allocate sufficient memory to hold a copy of the new_srf_parameters.

FAILURE and the retrieval SRF is not changed if:

a) new_srf_parameters failed to specify a legal SRF within SEDRIS; or

b) the parameters for the specified SRF were not legal for that SRF.

7.3.93 SetTransmittalName

Table 7.94 — SetTransmittalName

Property

Description

Purpose:

Given a transmittal, this function sets (or modifies) the formal transmittal name associated with the transmittal. This function can be used to supply the first name for a transmittal opened using 7.3.69 OpenTransmittalByLocation or to modify the name of a transmittal that was previously named or opened using 7.3.70 OpenTransmittalByName.

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

CAUTION: While setting the transmittal name is desirable in many cases, care should be taken when invoking this function. The API is not responsible for managing configuration and changing control for the transmittal being modified. Calling this function will permanently change the transmittal name associated with the file containing the SEDRIS transmittal.

Input parameters:

parameter_name	Parameter_Data_Type
new_transmittal_name	String

Input/Output parameters:

parameter_name	Parameter_Data_Type
transmittal	Transmittal

Output parameters:

parameter_name	Parameter_Data_Type
none

Valid return codes:

SUCCESS if valid parameters were passed in and the transmittal name was successfully set.

INVALID_REQUIRED_PARAMETER and the name of the transmittal is left unaltered, if new_transmittal_name is invalid.

INVALID_TRANSMITTAL and the name of the transmittal is left unaltered if transmittal is not a handle to a valid, active (i.e., open) SEDRIS transmittal.

INVALID_TRANSMITTAL_NAME and the name of the transmittal is left unaltered if new_transmittal_name did not specify a name that was valid according to the formal SEDRIS namespace.

INVALID_ACCESS_MODE and the name of the transmittal is left unaltered if transmittal was opened in read-only mode.

FAILURE and the name of the transmittal is left unaltered if the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.94 SetUserData

Table 7.95 — SetUserData

Property

Description

Purpose:

Each SEDRIS Object returned from this API has a field reserved for user data. This field is for the convenience of the user of this API. When an object is first returned, its user_data is empty. A call to SetUserData updates the user_data of an object as many times as desired while the user still has a valid accessor for that object. Once the user has “returned” an object to the API (by calling 7.3.14 FreeObject), the user_data for that object is no longer valid and is set to the NULL object. When the object is no longer active from the user’s point-of-view (when the user has called 7.3.14 FreeObject for that object once for every time the user was returned a reference for that object), the user_data for that object is reset to NULL by the API.

NOTE: Memory management of memory associated with user_data is the sole responsibility of the calling program. If the user_data contains memory that should be freed, the user should free that memory before returning the object to the API. The API will never access, free, or interfere with, in any way, the memory which exists as part of user_data.

In order to assist in determining whether a call to the 7.3.14 FreeObject function will return the object to the API, the 7.3.40 GetObjectReferenceCount function is available. If an invocation of 7.3.40 GetObjectReferenceCount indicates that there is only one reference to the object, the next invocation of 7.3.14 FreeObject will return the object to the API. Any necessary memory management of the memory controlled by the user_data for the object should be released before the object is returned to the API since, once the object is returned to the API by the 7.3.14 FreeObject call, the API will simply replace the user_data with a NULL object, and any memory that the user_data was controlling is in danger of being “orphaned” unless the calling program has also controlled the memory otherwise.

Input parameters:

parameter_name	Parameter_Data_Type
user_data	User_Data

Input parameters:

parameter_name	Parameter_Data_Type
object	Object

Output parameters:

parameter_name	Parameter_Data_Type
none

Valid return codes:

SUCCESS and user_data is stored with object, if valid parameters were passed in. Note that if user_data is empty, this has the effect of “clearing” the pointer.

INVALID_OBJECT and no changes are made if object is not a valid SEDRIS object.

FAILURE and no changes are made if the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.95 TransmittalsAreSame

Table 7.96 — TransmittalsAreSame

Property

Description

Purpose:

Given two transmittal handles, this function determines if they reference the same SEDRIS transmittal.

Input parameters:

parameter_name	Parameter_Data_Type
transmittal_a	Transmittal
transmittal_b	Transmittal

Output parameters:

parameter_name	Parameter_Data_Type
result	Boolean

Valid return codes:

SUCCESS and result returns the result of the evaluation if valid parameters were passed in and the transmittals both referenced valid, open transmittals.

INVALID_REQUIRED_PARAMETER and result is left unaltered if if result is invalid.

INVALID_TRANSMITTAL and result returns FALSE if either of the transmittal parameters is not a handle to a valid, open SEDRIS transmittal.

FAILURE and result returns FALSE the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.96 UnpublishObject

Table 7.97 — UnpublishObject

Property

Description

Purpose:

Given a resolved SEDRIS object, this function removes the object from being published under the given label. The object shall have already been published under the label for this function to work.

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

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

Input parameters:

parameter_name	Parameter_Data_Type
label	String

Input/Output parameters:

parameter_name	Parameter_Data_Type
object	Object

Output parameters:

parameter_name	Parameter_Data_Type
none

Valid return codes:

SUCCESS and object is unpublished if valid parameters were passed in and all operations succeeded.

INVALID_REQUIRED_PARAMETER and object is left unaltered if label is invalid.

INVALID_OBJECT and object is left unaltered if object is not a valid, active (i.e., unfreed) SEDRIS object.

UNRESOLVED_OBJECT and object is left unaltered if object is unresolved.

UNPUBLISHED_OBJECT and object is left unaltered If object was not published under the specified label.

INVALID_ACCESS_MODE and object is left unaltered if object belongs to a transmittal opened in read-only mode.

FAILURE and object is left unaltered if the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

7.3.97 UseDefaultColourModel

Table 7.98 — UseDefaultColourModel

Property

Description

Purpose:

This function places the API into the “default” colour model state, in which <DRM Colour Data> objects are returned based entirely on the colour model used to produce the transmittal from which the <DRM Colour Data> objects are extracted. The API will remain in this state until the 7.3.85 SetColourModel function is invoked, which takes the API out of the current colour model state and places it into whatever colour model was specified in the 7.3.85 SetColourModel call.

For example, if the transmittal was defined with RGB colours, <DRM RGB_Colour> objects will be returned as <DRM Colour Data> objects once 7.3.97 UseDefaultColourModel is called.

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

Instead of returning a value, this function changes the internal state of the API, determining the colour model used to define <DRM Colour Data> objects returned by this API.

Input parameters:

parameter_name	Parameter_Data_Type
none

Output parameters:

parameter_name	Parameter_Data_Type
none

Valid return codes:

none

7.3.98 UseDefaultSRFParameters

Table 7.99 — UseDefaultSRFParameters

Property

Description

Purpose:

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

For example, if a transmittal was defined with AUTM SRF locations, <DRM AUTM Location 3D> objects will be returned as the type of <DRM Location 3D> objects from that transmittal once 7.3.97 UseDefaultSRFParameters is called.

The 7.3.51 GetSRFParameters can be used to find out what the current world coordinate system parameters are, either immediately after a call to 7.3.97 UseDefaultSRFParameters, or at any time before a call to 7.3.92 SetSRFParameters is made.

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

Input parameters:

parameter_name	Parameter_Data_Type
none

Output parameters:

parameter_name	Parameter_Data_Type
none

Valid return codes:

none