Cosm API - Program Config File Functions

[Cosm Logo]

Program Config File Functions

CosmConfigLoad
CosmConfigSave
CosmConfigSet
CosmConfigGet
CosmConfigFree

CosmConfigLoad

Syntax

#include "config.h"
s32 CosmConfigLoad( cosm_CONFIG * config, const ascii * filename );

Description

Attempt to open the filename and read in the config data. See CosmFileOpen in os_file.h for how to specify the path and file name. If filename is NULL, create an empty config.

A config file will look something like this.

<begin file>
[section1]\n
key1=value1\n
key2=value2\n
\n
[section2]\n
key1=value1\n
key2=value2\n
\n
</end file>

Config files follow these conventions:

They are binary files, not text. You're not supposed to have to edit them.
No linefeeds (\n) in section/keys/values - those are line separators.
No '=' or '[' in keys, and avoid ']'.
Everything is case sensitive.
Blank lines are ignored, but added at the end of sections for humans.
Any improperly formatted line is discarded.
Comment lines don't exist, that's what documentation is for.
In the majority of cases the config will only be read, so optimize for reading.

Return Values

COSM_PASS on success, or a file error code (COSM_FILE_ERROR_*) on failure.

Errors

None.

Example

  cosm_CONFIG * config;
  s32 result;

  config = CosmMemAlloc( sizeof( cosm_CONFIG ) );

  result = CosmConfigLoad( config, "program.cfg" );
  if ( result != COSM_PASS )
  {
    /* error */
  }

CosmConfigSave

Syntax

#include "config.h"
s32 CosmConfigSave( const cosm_CONFIG * config, const ascii * filename );

Description

Write out the config data to the file specified by filename. See CosmFileOpen in os_file.h for how to specify the path and file name. See CosmConfigLoad for more information on config files.

Return Values

COSM_PASS on success, or a file error code (COSM_FILE_ERROR_*) on failure.

Errors

None.

Example

  cosm_CONFIG * config;
  s32 result;

  config = CosmMemAlloc( sizeof( cosm_CONFIG ) );

  result = CosmConfigLoad( config, "program.cfg" );
  if ( result != COSM_PASS )
  {
    /* error */
  }

  /* ... */

  result = CosmConfigSave( config, "program.cfg" );
  if ( result != COSM_PASS )
  {
    /* error */
  }

CosmConfigSet

Syntax

#include "config.h"
s32 CosmConfigSet( cosm_CONFIG * config, const utf8 * section,
  const utf8 * key, const utf8 * value );

Description

Set the value for the section/key pair. If value is NULL then key is deleted.

Return Values

COSM_PASS on success, or COSM_FAIL on failure.

Errors

None.

Example

  cosm_CONFIG * config;
  s32 result;

  config = CosmMemAlloc( sizeof( cosm_CONFIG ) );

  result = CosmConfigLoad( config, "program.cfg" )
  if ( result != COSM_PASS )
  {
    /* error */
  }

  result = CosmConfigSet( config, "Options",
     "logging", "1" );

  if ( result != COSM_PASS )
  {
    /* error */
  }

CosmConfigGet

Syntax

#include "config.h"
const utf8 * CosmConfigGet( cosm_CONFIG * config, const utf8 * section,
  const utf8 * key );

Description

Get the value of the section/key pair. The returned pointer will no longer be valid once another CosmConfig* call is made.

Return Values

A pointer to the value on success, or NULL on failure.

Errors

None.

Example

  cosm_CONFIG * config;
  s32 result;
  utf8 * value;

  config = CosmMemAlloc( sizeof( cosm_CONFIG ) );

  result = CosmConfigLoad( config, "program.cfg" );
  if ( result != COSM_PASS )
  {
    /* error */
  }

  value = CosmConfigGet( config, "Program",
     "interval" );

CosmConfigFree

Syntax

#include "config.h"
void CosmConfigFree( cosm_CONFIG * config );

Description

Free the internal config data.

Return Values

None.

Errors

None.

Example

  cosm_CONFIG * config;

  config = CosmMemAlloc( sizeof( cosm_CONFIG ) );

  /* use the config */

  CosmConfigFree( config );

  CosmMemFree( config );