SEDRIS logo

Part 4 — Language binding to C

3 Concepts

3.1 Introduction and table of contents

3.1.1 Introduction

This clause defines the conformance criteria and overall characteristics of the binding defined in this part of ISO/IEC 18024.

3.1.2 Table of contents

See Table 3.1 for the table of contents for this clause.

Table 3.1 — Table of contents

3 Concepts

3.1 Introduction and table of contents

3.1.1 Introduction

3.1.2 Table of contents

3.2 Conformance

3.3 Functions versus macros

3.4 Character strings

3.5 Function identifiers

3.6 Registration

3.7 Identifiers for graphical items

3.8 Return values

3.9 Header files

3.10 Memory management

3.10.1 Overview

3.10.2 Store concepts

3.11 Error handling

3.11.1 Error codes

3.11.2 C-specific SEDRIS status codes

3.2 Conformance

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

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

In order to conform, an implementation of the C binding of the SEDRIS API shall make visible all of the declarations in the C binding specified in this part of ISO/IEC 18024. The syntax of the function names shall be precisely as specified in this part of ISO/IEC 18024 and parameters shall be of the data types stated in this part of ISO/IEC 18024. In addition, an implementation shall also make visible all of the declarations from the C binding for the Environmental Data Coding Specification (EDCS) (see ISO/IEC 18041-4) and the Spatial Reference Model (SRM) (see ISO/IEC 18042-4) as used within declarations in this part of ISO/IEC 18024.

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 the error handling function.

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

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 SEDRIS API are all mapped to C functions whose names begin with the letter sequence “SE_”. Some words and phrases used in the SEDRIS 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

ISO/IEC 18023-1 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 graphical items

ISO/IEC 18023-1 defines several selection item data types. These data types may introduce new values for those data types. These new values are referenced via identifiers formed from the registration number of the item. This binding specifies the format of the identifiers but it does not specify the registration of the identifiers.

The format of the identifiers for graphical items is:

SE_datatypeprefix_Tn

where:

datatypeprefix is the set of characters used for normative value names of this data type.
T is the type of the item, “R” for registered and “U” for unregistered.
n is the registration number (for unregistered items, the absolute value of the item number shall be used).

EXAMPLE  The identifier for new registered image mapping method 1015 would be:

#define SE_IMM_R1015 (SE_ImageMappingMethod)(1015)

The identifier for new unregistered image mapping method -3 would be:

#define SE_IMM_U3 (SE_ImageMappingMethod)(-3)

3.8 Return values

All SEDRIS API functions return a value of type SE_Return_Code. This data type contains values indicating the manner of completion of the function.

3.9 Header files

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

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

Additional implementation-dependent items may be placed in this file if needed.

C data types and macros for EDCS are defined in ISO/IEC 18041-4. The header file(s) specified therein shall be included in any application program that uses the SEDRIS 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 ISO/IEC 18042-4. The header files specified therein shall be included in any application program uses the SEDRIS 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.

The following steps specify how this form of memory management works:

  1. As an extra parameter, the application shall pass a pointer of type SE_Store that points to the buffer. This pointer has been allocated by the utility function:

    SE_Return_Code SE_CreateStore (SE_Store *store)
  2. The implementation allocates an appropriate amount of data for the information to be returned and returns a pointer to a pointer of a type appropriate for the data being returned. This type is specified by the output parameter in which the pointer is returned.
  3. The data returned in the store can be directly referenced using the pointer. The pointer is only valid until the next use of the store. Therefore, such data should be transferred as appropriate to a more stable location by the application program.

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

The definitions for the functions SE_CreateStore and SE_FreeStore follow:

SE_CreateStore

SE_Return_Code SE_CreateStore (

 

SE_Store

*store

);

SE_FreeStore

SE_Return_Code SE_FreeStore (

 

SE_Store

store

);

3.11 Error handling

3.11.1 Error codes

All errors reported by an implementation are returned by functions using the data type SE_StatusCode. Errors status values defined in ISO/IEC 18023-1 (see [I18023-1]) 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.

Table 3.2 — C-specific SEDRIS status codes

Enumerant Message

SE_ENUMERATION_VALUE_INVALID

Enumeration type out of range.

SE_STORE_INVALID

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 NGA to act as registration authority.

http://www.iso.ch/iso/en/ittf/PubliclyAvailableStandards/ISO_IEC_18024-4_Ed1.html