3 The C language binding of SEDRIS
3.1 Introduction and table of contents
This clause defines the conformance criteria and overall characteristics of the binding defined in this standard.
See Table 3.1 for the table of contents for this clause.
Table 3.1 -- Table of contents
This binding incorporates the rules of conformance for implementations of the SEDRIS application programmer interface (API) defined in the ISO/IEC 18023-1 SEDRIS (see [I18023-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. 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. In addition, an implementation shall also make visible all of the declarations from the C binding for the Environmental Data Coding Specification (EDCS) (see [I18041-4]) and the Spatial Reference Model (SRM) (see [I18042-4]) as used within declarations in this part of this International Standard.
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.
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. However, the various string types defined in this part of this International Standard are designed to store characters represented in UTF-8 as defined in [I10646-1].
ISO/IEC 9899 C (see [I9899]) requires that compilers recognize internal identifiers which 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 #defines in the header file which equate the long names to a set of short names.
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 International Standard.
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).
For 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)
Most SEDRIS API functions return a value of type SE_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 Definition of fundamental data types.
C provides a mechanism to allow external files to be included in a compilation. Clause 5 of this binding describes the data types that shall be defined in the file sedris.h which should be included in any application program that intends to use the SEDRIS API via the C binding.
The file sedris.h shall also contain prototypes for all SEDRIS API functions as defined in Clause 6 of this binding.
Additional implementation-dependent items may be placed in this file if needed.
Data types and macros for EDCS are defined in ISO/IEC 18041-4 (see [I18041-4]) which contains the EDCS Binding to C. The header file(s) specified therein shall be included in any application program that intends to use the SEDRIS API via the C binding. The EDCS header file(s) shall precede the sedris.h header file.
Data types and macros for SRM are defined in ISO/IEC 18042-4 (see [I18042-4]) which contains the SRM Binding to C. The header files specified therein shall be included in any application program that intends to use the SEDRIS API via the C binding. The SRM header files shall precede the sedris.h header file.
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:
a) As an extra parameter, the application shall pass a pointer of type SE_Store which points to the buffer. This pointer has been allocated by the utility function
SE_StatusCode SE_CreateStore (SE_Store *store)
b) 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.
c) 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 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 functions that create (CreateStore, bound as SE_CreateStore) and free (FreeStore, bound as 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 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 which involves a Store, the pointer being returned shall have value NULL.
The definitions for the functions CreateStore and FreeStore follow:
SE_CreateStore CreateStore
SE_StatusCode SE_CreateStore (
SE_Store *store
);
SE_FreeStore FreeStore
SE_Store store,
);
3.11.1 Application specific error handlers
. . .
All errors reported by an implementation are returned in 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.3 C-specific SEDRIS status codes
This binding defines errors specific to the C language binding. These are defined in C-specific SEDRIS .
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 NIMA to act as registration authority.