Cosm API - Program Config File Functions

[Cosm Logo]

Program Config File Functions

v3ConfigLoad
v3ConfigSave
v3ConfigSet
v3ConfigGet
v3ConfigFree

v3ConfigLoad

Syntax

#include "config.h"
s32 v3ConfigLoad( v3_CONFIG * config, const ascii * filename );

Description

Attempt to open the filename and read in the config data. See v3FileOpen in cosmfile.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.
Config files contain ascii, not unicode.
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

V3_PASS on success, or a file error code (V3_FILE_ERROR_*) on failure.

Errors

None.

Example

  v3_CONFIG * config;
  s32 result;

  config = v3MemAlloc( v3u64u32( sizeof(v3_CONFIG) ), V3_MEM_NORMAL );

  result = v3ConfigLoad( config, (ascii *) "program.cfg" );
  if ( result != V3_PASS )
  {
    /* error */
  }

v3ConfigSave

Syntax

#include "config.h"
s32 v3ConfigSave( const v3_CONFIG * config, const ascii * filename );

Description

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

Return Values

V3_PASS on success, or a file error code (V3_FILE_ERROR_*) on failure.

Errors

None.

Example

  v3_CONFIG * config;
  s32 result;

  config = v3MemAlloc( v3u64u32( sizeof(v3_CONFIG) ), V3_MEM_NORMAL );

  result = v3ConfigLoad( config, (ascii *) "program.cfg" );
  if ( result != V3_PASS )
  {
    /* error */
  }

  /* ... */

  result = v3ConfigSave( config, (ascii *) "program.cfg" );
  if ( result != V3_PASS )
  {
    /* error */
  }

v3ConfigSet

Syntax

#include "config.h"
s32 v3ConfigSet( v3_CONFIG * config, const ascii * section,
  const ascii * key, const ascii * value );

Description

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

Return Values

V3_PASS on success, or V3_FAIL on failure.

Errors

None.

Example

  v3_CONFIG * config;
  s32 result;

  config = v3MemAlloc( v3u64u32( sizeof(v3_CONFIG) ), V3_MEM_NORMAL );

  result = v3ConfigLoad( config, (ascii *) "program.cfg" )
  if ( result != V3_PASS )
  {
    /* error */
  }

  result = v3ConfigSet( config, (ascii *) "Options",
    (ascii *) "logging", (ascii *) "1" );

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

v3ConfigGet

Syntax

#include "config.h"
const ascii * v3ConfigGet( v3_CONFIG * config, const ascii * section,
  const ascii * key );

Description

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

Return Values

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

Errors

None.

Example

  v3_CONFIG * config;
  s32 result;
  ascii * value;

  config = v3MemAlloc( v3u64u32( sizeof(v3_CONFIG) ), V3_MEM_NORMAL );

  result = v3ConfigLoad( config, (ascii *) "program.cfg" );
  if ( result != V3_PASS )
  {
    /* error */
  }

  value = v3ConfigGet( config, (ascii *) "Program",
    (ascii *) "interval" );

v3ConfigFree

Syntax

#include "config.h"
void v3ConfigFree( v3_CONFIG * config );

Description

Free the internal config data.

Return Values

None.

Errors

None.

Example

  v3_CONFIG * config;

  config = v3MemAlloc( v3u64u32( sizeof(v3_CONFIG) ), V3_MEM_NORMAL );

  /* use the config */

  v3ConfigFree( config );

  v3MemFree( config );