ISO/IEC 18024-4:2006(E)

This binding incorporates the rules of conformance for implementations of the application program interface (API) defined in Part 1 of ISO/IEC 18023 with those additional requirements specifically defined for this binding of the API to the C programming language.

The following criteria shall determine conformance of an implementation to this binding:

3.3 Functions versus macros

An implementation may substitute macros for functions. However, the macros shall be designed so that side-effects work properly. In general, a macro cannot be used to replace functions that correspond to the function data types.

3.4 Character strings

The C language represents character strings as an array of characters terminated by the null character (i.e., ‘\0’). The null character is therefore not usable as a printable character. However, the various string types defined in this part of ISO/IEC 18024 are designed to store characters represented in UTF-8 as defined in ISO/IEC 10646.

3.5 Function identifiers

ISO/IEC 9899 requires that compilers recognize internal identifiers that are distinct in at least 31 characters. That standard also requires that external identifiers (i.e., those seen by the linker) be recognized to a minimum of 6 characters, independent of case.

The function names of the API are all mapped to C functions whose names begin with the letter sequence “SE_ ”. Some words and phrases used in the API function names may be abbreviated in the representation. The set of such abbreviations is given in Table 4.2.

Implementations that run in environments where two distinct C internal identifiers would be equivalent if they were both external identifiers shall include a set of #define macros in the header file that equate the long names to a set of short names.

3.6 Registration

Part 1 of ISO/IEC 18023 reserves certain value ranges for registration¹⁾ as graphical items. The registered graphical items will be bound to the C programming language (and other programming languages). The registered item binding shall be consistent with the binding presented in this part of ISO/IEC 18024.

3.7 Identifiers for registered items

Part 1 of ISO/IEC 18023 defines selection item and set data types. These data types may introduce new values for those data types. These new values are referenced via identifiers formed by identifiers specified as part of the registration.

The format of the identifiers for unregistered selection item selection and set data type values shall be:

EXAMPLE The form of the identifier for new unregistered image mapping method -3 would be:

3.8 Return values

All API functions return a value of type SE_Return_Code. This data type contains values indicating the manner of completion of the function. The function data types define functions that return other data types.

3.9 Header files

C provides a mechanism to allow external files to be included in a compilation. 5 Definition of fundamental data types describes the data types that shall be defined in the file sedris.h that shall be included in any application program that uses the API C binding.

The file sedris.h shall also contain prototypes for all API functions as defined in 6 Function definitions.

C data types and macros for EDCS are defined in Part 4 of ISO/IEC 18041. The header file(s) specified therein shall be included in any application program that uses the API C binding. The EDCS header file(s) shall precede the sedris.h header file.

C data types and macros for SRM are defined in Part 4 of ISO/IEC 18042. The header files specified therein shall be included in any application program uses the API C binding. The SRM header files shall precede the sedris.h header file.

3.10 Memory management

3.10.1 Overview

The application shall allocate the memory needed for the data returned by the implementation. In general, the application will allocate a C structure and pass a pointer to that structure to a function which is to return information. This function will then place information into the structure. However, a number of functions return variable length data, the length of which is not known a priori by the application. Such functions shall use the mechanism described below.

The data returned by some functions can be complex in structure and highly variable in size. The binding of these functions requires that the application allocate a type of buffer called a store (i.e., an implementation-managed block of memory) and the implementation will place this structured data in this block of memory.

Stores may be reused. When a store is reused, the implementation may reallocate the buffer as necessary to accommodate the new data request. Hence, any data that may previously have been contained in the store will be discarded. In this manner, the amount of data necessary for transferring information from the implementation to the application can be optimized.

3.10.2 Store concepts

A store is used by the implementation to manage the memory needed by the functions that return complex data structures or data structures whose exact size is unknown by the application. The store resource is opaque to the application. The application does not know the structure of the store or how it is implemented. The store is defined as a void * pointer. This part of ISO/IEC 18024 defines two new functions that create (SE_CreateStore) and free (SE_FreeStore) a store.

The semantics of the store resource provide two levels of memory management. The implementation is responsible for managing the memory at a low level because it uses, re-uses, allocates and deallocates memory from the system in order to return information to the application. But the application is ultimately responsible for managing the memory at a high level because it creates and frees stores.

A store is passed as a parameter to a function returning complex data. Another parameter to this function is a pointer to a pointer to the structure that defines the format of the returned data. The store contains memory for the structure and any additional memory reference by fields within the structure. The application accesses the returned data through its pointer to the structure; it does not use the store to access data.

A store continues to hold the information returned from the function until the store is freed by the SE_FreeStore function, or until the store is used as an argument to a subsequent function that returns complex data. At that time, the old information is replaced with the new. Thus, multiple calls to functions overwrite the contents of a store. The actual memory managed by a store may change each time the store is passed as an argument thus invalidating old pointers that may have been returned in previous calls. A store only contains the results of the last function. An application may create more than one store.

This binding defines two new errors that can occur when using or creating a store; these errors are described in 3.11.2 C-specific SEDRIS status codes. For all functions using a store, these and other errors are returned as the return value for the function. Whenever an error occurs that involves a store, the pointer being returned shall have value NULL.

3.11 Error handling

3.11.1 Error codes

All errors reported by an implementation are returned by functions using the data type SE_Return_Code. Further information about a FAILURE return is provided by using the function SE_GetLastFunctionStatus which returns a value of type SE_Status_Code. Error status values defined in Part 1 of ISO/IEC 18023 are assigned positive selection values.

3.11.2 C-specific SEDRIS status codes

This binding defines errors specific to the C language binding. These are defined in Table 3.2.

Enumerant	Selector	Message
SE_ENUMERATION_VALUE_INVALID	2401	Enumeration type out of range.
SE_STORE_INVALID	2402	Store provided is invalid.

¹⁾ For the purpose of this International Standard and according to the rules for the designation and operation of registration authorities in the ISO Directives, the ISO council has designated the National Geospatial-Intelligence Agency to act as registration authority.