Supporting a Wide Range of Devices - Marmalade SDK Mobile Game Development Essentials - page 214

The first function we will look at is s3eConfigGetString , which takes the section
identifier and setting name we want to access and also a pointer to an array of char
that will be used to return the value of the setting when the function completes. Since
the app.icf file is really little more than an ASCII text file, all this function does is
return the string of text following the equals sign for the specified ICF setting.

The char array supplied to s3eConfigGetString should be at least of length S3E_
CONFIG_STRING_MAX , as this is the largest string size the function can return. If the
requested setting can't be found in the ICF file this buffer will not be changed, which
is very useful as it allows us to set up a default value for the parameter in our code.

// Set default first level
char lLevelName[S3E_CONFIG_STRING_MAX];
strcpy(lLevelName, "level1");

s3eConfigGetString("GAME_DEBUG", "SkipToLevel", &lLevelName);
// lLevelName will still contain "level1" if the SkipToLevel setting
// could not be found in the ICF file

Quite often we will want to specify ICF settings, which just need a numeric
value. To make this easier for us, Marmalade provides another function called
s3eConfigGetInt , which, instead of a pointer to a char array, takes a pointer to an
int variable.

This function will read the setting string from the ICF file and then attempt to
convert it into an integer value. If this fails (for example, the string contains non-
numeric characters or is out of the range of an int ) or the setting does not exist in
the ICF file, the variable's current value will not be changed, thus allowing default
values to be specified in code.

Both functions will return S3E_RESULT_SUCCESS if the setting value could
be retrieved, or S3E_RESULT_ERROR if there was a problem. The function
s3eConfigGetError will let us discover what the problem was by returning one of
the following values:

Value Description

S3E_CONFIG_ERR_NONE No error occurred.

S3E_CONFIG_ERR_PARAM

One of the parameters to s3eConfigGetInt or
s3eConfigGetString was not valid. For example,
a NULL value passed in.

S3E_CONFIG_ERR_NOT_FOUND The requested ICF setting could not be found.

S3E_CONFIG_ERR_PARSE

There was a problem converting the ICF setting value
to an integer when using s3eConfigGetInt .