/*
 *  preferences.h -- Core Foundation Preferences API wrapper for Asterisk
 *
 *  Provides property list support to the Asterisk telephony server core. 
 *
 *  Created by benjk on 2/18/06 -- Version 1.00
 *  
 *  Copyright (C) 2006 Sunrise Telephone Systems Ltd. All rights reserved.
 *
 *  Released under the GNU General Public License (GPL) version 2.
 *
 *  Dependencies: Core Foundation or CF-Lite, C pthread library.
 */

#import <CoreFoundation/CoreFoundation.h>

// --------------------------------------------------------------------------
// Status codes
// --------------------------------------------------------------------------
//
typedef enum {
	AST_PREFS_UNDEFINED = -1,
	AST_PREFS_SUCCESS = 1,
	AST_PREFS_ALREADY_INITIALIZED = 2,
	AST_PREFS_NOT_INITIALIZED = 3,
	AST_PREFS_SYNCHRONIZATION_FAILED = 4,
	AST_PREFS_CANNOT_OBTAIN_APPID = 5,
	AST_PREFS_DICTIONARY_INVALID = 6,
	AST_PREFS_DICTIONARY_NOT_FOUND = 7,
	AST_PREFS_DICTIONARY_ENCODING_INVALID = 8,
	AST_PREFS_KEY_NOT_FOUND = 9,
	AST_PREFS_KEY_NULL_OR_EMPTY = 10,
	AST_PREFS_KEY_ENCODING_INVALID = 11,
	AST_PREFS_VALUE_TYPE_INVALID = 12
} ast_prefs_status;

// --------------------------------------------------------------------------
// Predefined dictionaries
// --------------------------------------------------------------------------
//
#define AST_DEBUGGING_DICT		"Debugging"
#define AST_DIRECTORIES_DICT	"Directories"
#define AST_FILENAMES_DICT		"Filenames"
#define AST_LOGFILES_DICT		"Logfiles"
#define AST_MGRAPI_DICT			"MgrAPI"
#define AST_MODULES_DICT		"Modules"
#define AST_OPTIONS_DICT		"Options"

// --------------------------------------------------------------------------
// function ast_prefs_init()
// --------------------------------------------------------------------------
//
// Initialises preferences with the default property list.
//
// Does nothing if initialisation status is true.
// 
// Returns a status code as defined by ast_prefs_status.
//
ast_prefs_status ast_prefs_init();

// --------------------------------------------------------------------------
// function ast_prefs_initWithAppID(appID)
// --------------------------------------------------------------------------
//
// Initialises preferences with the property list passed in 'appID' which
// must be in Java package name format.
//
// Does nothing if initialisation status is true.
//
// Returns a status code as defined by ast_prefs_status.
//
ast_prefs_status ast_prefs_initWithAppID(const char *appID);

// --------------------------------------------------------------------------
// function ast_prefs_initialized()
// --------------------------------------------------------------------------
//
// Obtains the current initialisation status.
//
// Returns true if preferences have been initialised, otherwise false.
//
Boolean ast_prefs_initialized();

// --------------------------------------------------------------------------
// function ast_prefs_copyStrCurrentAppID(valueReturned)
// --------------------------------------------------------------------------
//
// Passes the current application ID as a string in valueReturned. Passes
// an empty string in valueReturned if initialisation status is false.
//
// Returns a status code as defined by ast_prefs_status.
//
ast_prefs_status ast_prefs_copyStrCurrentAppID(char *valueReturned);	

// --------------------------------------------------------------------------
// function ast_prefs_copyStrValueForKey(valueReturned, inDictionary, key)
// --------------------------------------------------------------------------
//
// Returns the value of key 'key' in dictionary 'inDictionary' as a C string
// in 'valueReturned'.
//
// Does nothing if initialisation status is false.
//
// Returns a status code as defined by ast_prefs_status.
// 
ast_prefs_status ast_prefs_copyStrValueForKey(char *valueReturned,
											  const char *inDictionary,
											  const char *key);

// --------------------------------------------------------------------------
// function ast_prefs_synchronize()
// --------------------------------------------------------------------------
//
// Writes all pending changes to preference data to permanent storage,
// and reads latest preference data from permanent storage.
//
// Does nothing if initialisation status is false.
//
// Returns a status code as defined by ast_prefs_status.
//
ast_prefs_status ast_prefs_synchronize();

// --------------------------------------------------------------------------
// function ast_prefs_reset()
// --------------------------------------------------------------------------
//
// Writes all pending changes to preference data to permanent storage
// and resets the preferences system to pre-initialisation status.
//
// Does nothing if initialisation status is false.
//
// Returns a status code as defined by ast_prefs_status.
//
ast_prefs_status ast_prefs_reset();	

// END OF FILE