am_properties_get_with_default()

Retrieves the value (or the specified default) associated with the specified key from the specified properties object.

Details

am_properties_get_with_default() checks for the presence of the specified key and returns its value, if present. Contrary to am_properties_get(), if no value is present, it returns the specified default value.

Syntax

#include "am_properties.h"
AM_EXPORT am_status_t
am_properties_get_with_default(am_properties_t properties,
                               const char *key, 
                               const char *default_value,
                               const char **value_ptr);

Parameters

This function takes the following parameters:

properties

The specified properties object.

key

Pointer to the specified key in the specified properties object.

default_value

Pointer to the value to be returned in case of no associated value.

value_ptr

Pointer to a pointer to the location where the returned value will be stored.

Returns

One of the following values as well as value_ptr containing an unparsed string with the address of the location of the value.

AM_SUCCESS

If no error is detected.

AM_INVALID_ARGUMENT

If the properties, key, or value_ptr argument is NULL.

AM_NOT_FOUND

If the specified key has no associated value and a default value is not provided.

AM_INVALID_VALUE

If the value associated with the specified key is cannot be parsed as required by the particular accessor function.

AM_NO_MEMORY

If insufficient memory is available to look up the key.

Memory Concerns

Do not modify value_ptr or free the memory.