libics: Low-Level Interface

libics v.1.6.6 Online Documentation. ©2000-2010 by Cris Luengo and others.

# Low-level interface to libics

The functions below are provided to add some flexibility to the library. However, I don't see a reason to use them. They are subject to change, don't provide any error checking what so ever (i.e. calling any of these in the wrong order will crash your program), and you shouldn't use them unless you really need to.

You need to add `#include "libics_ll.h"` to your source files.

This functions in this page are organized in the following categories, and sorted alphabetically:

- Main library functionality
- File name manipulation
- DataType structure query
- Support functions

## Main library functionality

### IcsCloseIds

Ics_Error IcsCloseIds (Ics_Header* IcsStruct);

Ends image data reading initialized with `IcsOpenIds`.

errors: `IcsErr_DecompressionProblem`, `IcsErr_FCloseIds`, `IcsErr_UnknownCompression`.

### IcsOpenIds

Ics_Error IcsOpenIds (Ics_Header* IcsStruct);

Initializes image data reading. The functions `IcsReadIdsBlock`, `IcsSkipIdsBlock` and `IcsSetIdsBlock` can subsequently be used to read the interesting portions of the image data. Finally, the file should be closed with `IcsCloseIds`.

errors: `IcsErr_Alloc`, `IcsErr_CorruptedStream`, `IcsErr_DecompressionProblem`, `IcsErr_FOpenIds`, `IcsErr_FReadIds`, `IcsErr_MissingData`, `IcsErr_UnknownCompression`.

### IcsReadIcs

Ics_Error IcsReadIcs (Ics_Header* IcsStruct, char const* filename, int forcename, int forcelocale);

Reads a .ics header file into an `Ics_Header` structure. When `forcename` is non-zero, the `".ics"` extension is not added. If `forcelocale` is 0, the locale is not forced to `"C"`, to make it possible to read ICS files written in the current locale. Note that the standard requires the `"C"` locale to be in effect when writing the ICS header.

errors: `IcsErr_Alloc`, `IcsErr_FCloseIcs`, `IcsErr_FOpenIcs`, `IcsErr_FReadIcs`, `IcsErr_LineOverflow`, `IcsErr_MissBits`, `IcsErr_MissCat`, `IcsErr_MissLayoutSubCat`, `IcsErr_MissParamSubCat`, `IcsErr_MissRepresSubCat`, `IcsErr_MissSensorSubSubCat`, `IcsErr_NotIcsFile`, `IcsErr_TooManyChans`, `IcsErr_UnknownCompression`.

### IcsReadIds

Ics_Error IcsReadIds (Ics_Header* IcsStruct, void* dest, size_t n);

Reads the whole image from disk.

errors: `IcsErr_Alloc`, `IcsErr_BitsVsSizeConfl`, `IcsErr_CorruptedStream`, `IcsErr_DecompressionProblem`, `IcsErr_EndOfStream`, `IcsErr_FCloseIds`, `IcsErr_FOpenIds`, `IcsErr_FReadIds`, `IcsErr_MissingData`, `IcsErr_UnknownCompression`.

### IcsReadIdsBlock

Ics_Error IcsReadIdsBlock (Ics_Header* IcsStruct, void* outbuf, size_t len);

Reads image data block from disk. You need to call `IcsOpenIds` first.

When the data is compressed with `IcsCompr_compress`, this function can only be called once. That is, only one block of data, starting at the beginning, can be read from the file.

errors: `IcsErr_BitsVsSizeConfl`, `IcsErr_BlockNotAllowed`, `IcsErr_CorruptedStream`, `IcsErr_DecompressionProblem`, `IcsErr_EndOfStream`, `IcsErr_FReadIds`, `IcsErr_UnknownCompression`.

### IcsSetIdsBlock

Ics_Error IcsSetIdsBlock (Ics_Header* IcsStruct, long offset, int whence);

Specifies where next to read within the image data on disk. You need to call `IcsOpenIds` first. `whence` is one of the `fseek` values `SEEK_SET` or `SEEK_CUR`, defined in `<stdio.h>`.

This function does currently not work when the data is compressed with `IcsCompr_compress`.

errors: `IcsErr_Alloc`, `IcsErr_BlockNotAllowed`, `IcsErr_CorruptedStream`, `IcsErr_DecompressionProblem`, `IcsErr_EndOfStream`, `IcsErr_FReadIds`, `IcsErr_IllParameter`, `IcsErr_UnknownCompression`.

### IcsSkipIdsBlock

Ics_Error IcsSkipIdsBlock (Ics_Header* IcsStruct, size_t len);

Skips image data block on disk. You need to call `IcsOpenIds` first.

This function does currently not work when the data is compressed with `IcsCompr_compress`.

errors: `IcsErr_Alloc`, `IcsErr_BlockNotAllowed`, `IcsErr_CorruptedStream`, `IcsErr_DecompressionProblem`, `IcsErr_EndOfStream`, `IcsErr_FReadIds`, `IcsErr_UnknownCompression`.

### IcsWriteIcs

Ics_Error IcsWriteIcs (Ics_Header* IcsStruct, char const* filename);

Writes an Ics_Header structure into a .ics file.

errors: `IcsErr_FailWriteLine`, `IcsErr_FCloseIcs`, `IcsErr_FOpenIcs`, `IcsErr_FWriteIcs`, `IcsErr_NoLayout`, `IcsErr_TooManyChans`, `IcsErr_TooManyDims`, `IcsErr_UnknownCompression`, `IcsErr_UnknownDataType`.

### IcsWriteIds

Ics_Error IcsWriteIds (Ics_Header const* IcsStruct);

Writes the whole image to disk.

errors: `IcsErr_Alloc`, `IcsErr_CompressionProblem`, `IcsErr_FCloseIds`, `IcsErr_FOpenIds`, `IcsErr_FWriteIds`, `IcsErr_MissingData`, `IcsErr_UnknownCompression`.

## File name manipulation

### IcsGetIcsName

char* IcsGetIcsName (char* dest, char const* src, int forcename);

If `forcename` is zero, replaces an existing extension with `".ics"` while preserving case. If no extension could be found then `".ics"` is appended to the filename. If `forcename` is non-zero, only the `".ids"` extension is converted into `".ics"`, any other extension is left intact. This is to force the library to open a specific file with a wrong extension.

### IcsGetIdsName

char* IcsGetIdsName (char* dest, char const* src);

Replaces an existing extension with `".ids"` while preserving case. If no extension could be found then `".ids"` is appended to the filename.

### IcsExtensionFind

char* IcsExtensionFind (char const* str);

Finds the start of the `".ics"`, `".ids"`, `".ids.Z"`, or `".ids.gz"` extension. All character comparisons are done case insensitive. When no extension could be found a NULL pointer is returned.

## DataType structure query

### IcsGetDataTypeProps

void IcsGetDataTypeProps (Ics_DataType* DataType, Ics_Format format, int sign, size_t bits);

Gets the data type according to `format`, `sign` and `bits`.

## Support functions

### IcsGetDataTypeSize

size_t IcsGetDataTypeSize (Ics_DataType DataType);

Returns the size in bytes of the data type.

### IcsGetPropsDataType

void IcsGetPropsDataType (Ics_DataType DataType, Ics_Format* format, int* sign, size_t* bits);

Fills in `format`, `sign` and `bits` according to the data type.

### IcsInit

void IcsInit (Ics_Header* IcsStruct);

Initializes the `Ics_Header` structure to default values and zeros.

errors: none.

### IcsFreeHistory

void IcsFreeHistory (Ics_Header* IcsStruct);

Frees the History structure in the `Ics_Header` structure. This structure is allocated and accessed by a set of high-level interface functions.

errors: none.