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

3.1.2 Table of contents

Table 3.1 lists the topics for this clause.

Table 3.1 — Topics

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 Return values

3.8 Header files

3.9 Error handling

3.9.1 Error codes

3.9.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 programmer 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:

In order to conform, an implementation of the C binding of the SRM API shall make visible all of the declarations in the C binding specified in this part of ISO/IEC 18042. Thus, for 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 Character strings

The C language represents character strings as an array of characters terminated by the null character (i.e., ‘\0’). This means that the null character is not usable as a printable character.

3.5 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.6 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.7 Return values

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

Some API functions return other values. The data types for these values are defined in 5 Type definitions.

3.8 Header files

C 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. Similarly, 6 Object class definitions specifies the object classes that shall be defined in the file srm_objects.h. The order of these files is srm_types.h first followed by srm_objects.h.

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. In addition, a composite header file srm.h shall be provided that contains C include statements for both srm_types.h and srm_functions.h. An application may use either the two header files, srm_types.h and srm_functions.h, or the composite header file srm.h.

Since the SRM also uses data types from ISO/IEC 18025, the header file edcs.h shall precede the SRM header files.

3.9 Error handling

3.9.1 Error codes

All errors reported by an implementation are returned by functions using the data type SRM_StatusCode. Errors status values defined in ISO/IEC 18026 are assigned positive enumerant values.

3.9.2 C-specific SRM errors

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

Table 3.2 — C-specific SRM errors

Enumerant

Message

SRM_BUFFER_OVERFLOW

Buffer too small to hold data.

SRM_ENUMERATION_VALUE_INVALID

Enumeration type out of range.

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_18042-4_Ed1.html