Auxilary -- Auxilary (.aux) Files

Auxilary files are simple text files used to associate auxilary information with a target file. The name of the auxilary file is based on the name of the target file. In order to make access for reading and writing auxilary files more convenient an API exists for managing them. The primary use for auxilary files is to hold information pertaining to a GDB supported file format that does not have built in support for items such as georeferencing or channel descriptors.

ReadAuxFile()

Read an auxilary information text file.

char    **ReadAuxFile( target_file );

const char *target_file;
           The target file to which the auxilary files refers.
           The auxilary filename will be derived from this name.

A NULL is returned if no appropriate auxilary file is found, or a pointer to a StringList containing the lines is returned. The actual attributes should be accessed with SetAuxEntry() and GetAuxEntry(). The StringList should be freed with DestroyStringList().

SetAuxEntry()

Set a value in an auxilary information StringList before writing it to an auxilary file with WriteAuxFile().

char    **SetAuxEntry( aux_info, field_name, field_value );

char    **aux_info;
           A StringList to add this entry to.  If NULL a new
           StringList will be created.

const char *field_name;
           The name of the field being assigned a value in the
           aux_info StringList.

const char *field_value;
           The value to be assigned to the field in the StringList.

This function returns a pointer to the modified StringList which is usually different than the StringList passed in as aux_info.

DeleteAuxEntries()

Deletes one or more auxilliary entries to the StringList.

char **DeleteAuxEntries(aux_info, field_name_regex,
                       field_value_regex, bCaseSensitive);

char **aux_info;
       A string list to remove the entry from.

const char *field_name_regex;
       A globbing/regular  expression to specify fields to delete.
       May be NULL is equivalent to "*".

const char *field_value_regexp;
       A globbing/regular expression to specify field values to
       match.  May be NULL which is equivalent to "*"

TBool   bCaseSensitive;
       Flag that indicates whether matching should be case sensitive
       or not.

This function will delete any entries that match both regular expressions provided as parameters. Case is significant.

The shortented list is returned.

AddAuxEntry()

Add a value in an auxilary information StringList associate with a field name. The difference between AddAuxEntry() and SetAuxEntry() is that AddAuxEntry() will add multiple values for the same field name while SetAuxEntry() will just reset the first occurance of the field.

char    **AddAuxEntry( aux_info, field_name, field_value );

char    **aux_info;
           A StringList to add this entry to.  If NULL a new
           StringList will be created.

const char *field_name;
           The name of the field being assigned a value in the
           aux_info StringList.

const char *field_value;
           The value to be assigned to the field in the StringList.

This function returns a pointer to the modified StringList which is often different than the StringList passed in as aux_info.

FetchAuxEntry()

Fetch the value of a named field in an auxilary information StringList.

const char *FetchAuxEntry( aux_info, field_name );

char    **aux_info;
           A StringList to search for the named field.

const char *field_name;
           The name of the field being searched for in the StringList.

This function returns a pointer to the value of the requested field if it exists, or NULL if it is not found.

FetchNextAuxEntry()

Fetch the value of a named field in an auxilary information StringList, starting just after a previously fetch entry. This is useful for finding all occurances of a particular field type in an auxilary list.

const char *FetchNextAuxEntry( aux_info, field_name, last_value );

char    **aux_info;
           A StringList to search for the named field.

const char *field_name;
           The name of the field being searched for in the StringList.

const char *last_value;
           A value field returned by a previous call to 
          FetchAuxEntry(), or FetchNextAuxEntry().

This function returns a pointer to the value of the requested field if it exists, or NULL if it is not found.

Example:

 const char     *pszValue;

 for( pszValue = FetchAuxEntry(aux,"menu");
      pszValue != NULL;
      pszValue = FetchNextAuxEntry(aux,"menu",pszValue) )
 {
     ...
 }

WriteAuxFile()

Write an auxilary information StringList created with SetAuxEntry() to an auxilary text file.

void    WriteAuxFile( target_name, aux_info );

const char *target_name;
           The name of the "target" of the auxilary file.  This
           name is used to derive the name of the auxilary file.

char    **aux_info;
           The StringList containing the field name, value pairs
           as created by FetchAuxEntry().

File Format

The .aux auxilary files are simple text lines with one "value" per line. The files always start with a line identifying the "target" of this auxilary file. Normally this is another file. This target name is the one provided when reading and writing auxilary files. The target name is prefixed with the string "AuxilaryTarget:".

Each subsequent lines contains a value name followed by a colon, a space and the value associated with the name.

eg.

 AuxilaryTarget: test.tif
 MapUnits: UTM   11 S E000
 ChanDesc-1: untitled

EXAMPLE

This example shows reading an auxilary file, and using it to extract various field values for projection information.

RawList->AuxilaryInfo = ReadAuxFile(fp2filename(fp));

value = FetchAuxEntry( RawList->AuxilaryInfo, "MapUnits" );
if( value != NULL )
  strncpy( proj_info->Units, value, 16 );
proj_info->Units[16] = '\0';

value = FetchAuxEntry( RawList->AuxilaryInfo, "ProjParms" );
if( value != NULL )
  ProjParms2Info( value, proj_info );

DestroyStringList( RawList->AuxilaryInfo );

This example code shows the converse where an auxilary file is written on the basis of existing projection information.

RawList->AuxilaryInfo = NULL;

RawList->AuxilaryInfo = 
  SetAuxEntry( RawList->AuxilaryInfo, "MapUnits", proj_info->Units );

value = ProjInfo2Parms( proj_info );
RawList->AuxilaryInfo = 
  SetAuxEntry( RawList->AuxilaryInfo, "ProjParms", value );
HFree( value );

WriteAuxFile( fp2filename(fp) );

DestroyStringList( RawList->AuxilaryInfo );

1      ParseAuxEntry()
@alias{ParseAuxEntry}

This function parses a line of auxilary data and returns a pointer 
to the field name and associated value.

@call
TBool   ParseAuxEntry( pszEntry, ppszFieldName, ppszFieldValue );

const char *pszEntry;
                Line of auxilary data to parse.

const char **ppszFieldName;
                Pointer to a char * into which a pointer to the
                field name should be written.

const char **ppszFieldValue;
                Pointer to a char * into which a pointer to the
                field value should be written.

ParseAuxEntry() returns TRUE if the line of auxilary data could be succesfully parsed. In this case, *ppszFieldName will point to a static internal buffer containing the field name (its value will be valid only until the next call to one of the Auxilary API routines) and *ppszFieldValue will point to the field value.

Note: It is important that you make your own copy of the string returned in *ppszFieldName if you want to use it for a long time, otherwise it can be overwritten by subsequent calls to other functions that use the Auxilary API.

BuildAuxEntry()

Given a field name and value, BuildAuxEntry() will return a new string in the auxilary data format.

char *  BuildAuxEntry( pszFieldName, pszFieldValue );

const char *pszFieldName;
           The name of the field being assigned a value.

const char *pszFieldValue;
           The value to be assigned to the field.

The returned string should be deallocated with HFree().

About PCI Help Gateway