ISO/IEC 18042-4:2006(E) -- 3 Concepts

This clause defines the conformance criteria and overall characteristics of the binding defined in this standard.

3.1.2 Topics

3 Concepts

3.1 Introduction and topics

3.1.1 Introduction

3.1.2 Topics

3.2 Conformance

3.3 Functions versus macros

3.4 Function identifiers

3.8.2 C-specific SRM errors

3.2 Conformance

This binding incorporates the rules of conformance defined in ISO/IEC 18026 for implementations of the SRM application program interface (API), with those additional requirements specifically defined for C bindings of the SRM API.

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

EXAMPLE The syntax of the function names shall be precisely as specified in the binding and parameters shall be of the data types stated in the binding.

3.3 Functions versus macros

An implementation may substitute macros for functions. However, the macros shall be designed so that side-effects as defined in ISO/IEC 9899 work properly.

3.4 Function identifiers

The C standard (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 SRM API are all mapped to C functions whose names begin with the letter sequence “SRM_”. Some words and phrases used in the SRM 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 constructs in the header file that equate the long names to a set of short names.

3.5 Registration

ISO/IEC 18026 reserves certain value ranges for registration.^‡ The registered 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 18042.

3.6 Return values

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

3.7 Header files

The C language provides a mechanism to allow external files to be included in a compilation. 5 Type definitions specifies the data types that shall be defined in the file srm_types.h. 6 Object class definitions specifies the object classes that shall be defined in the file srm.h. The file srm.h.shall also include a reference to srm_types.h at the beginning. The file srm_types.h should only be used alone if the particular type of conformance only requires access to the SRM data types and the object classes are not being used.

These header files should be included in any application program that intends to use the SRM API via the C binding. Additional implementation-dependent items may be placed in these files, if needed.

3.8 Error handling

3.8.1 Error codes

All method and function implementations return error status of data type SRM_Status_Code. Errors status values defined in ISO/IEC 18026 are assigned positive selector values (see 5.2.5 Selection data types).

3.8.2 C-specific SRM errors

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

SRM_Status_Code selector	Selector value	Message
SRM_BUFFER_OVERFLOW	2401	Buffer too small to hold data.
SRM_ENUMERATION_VALUE_INVALID	2402	Enumeration type out of range.

^‡ At the time this International Standard was published, the ISO International Registration Authority for Graphical Items was the United States National Geospatial-Intelligence Agency (NGA). The mailing address was: Registration Authority, National Geospatial-Intelligence Agency, c/o Joint Interoperability Test Command, Building 57305, Room 263A, Fort Huachuca, Arizona 85613-7020. US.