This clause defines the conformance criteria and overall characteristics of the binding defined in this standard.
Table 3.1 lists the topics for this clause.
This binding incorporates the rules of conformance defined in ISO/IEC 18026 (see 2.[I18026]) 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.
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.
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.
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 #defines in the header file that equate the long names to a set of short names.
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.
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.
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.h which 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 this file if needed.
The file srm.h shall also contain prototypes for all SRM API functions.
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 “store” 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 illustrate how this form of memory management works:
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 which 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.
A Store is used by the implementation to manage the memory needed by the functions which 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 *. The binding defines two new function that create (CreateStore, bound as SRM_CreateStore) and destroy (DeleteStore, bound as SRM_DeleteStore) 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 destroys 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 destroyed by the DeleteStore 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.10.2 C-specific SRM errors. For all functions using a Store, these and other errors are returned as the return value for the function. Whenever, an error occurs which involves a Store, the pointer being returned shall have value NULL.
The definitions for the functions CreateStore and DeleteStore follow:
SRM_CreateStore
Abstract Function: CreateStore
SRM_StatusCode SRM_CreateStore (
SRM_Store *store /* OUT store construct */
);
SRM_DeleteStore
Abstract Function: DeleteStore
SRM_StatusCode SRM_DeleteStore (
SRM_Store store, /* store construct */
);
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.
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. |
|
SRM_CANNOT_ALLOCATE_MEMORY |
Cannot allocate memory. |
|
SRM_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 NIMA to act as registration authority.