www.pudn.com > NDKforTIDM642DSP.rar > configif.h
//--------------------------------------------------------------------------
// Network Tooks Library
//--------------------------------------------------------------------------
// CONFIGIF.H
//
// Configuration Manager Interface Functions
//
// Author: Michael A. Denio
// Copyright 2000 by Texas Instruments Inc.
//-------------------------------------------------------------------------
#ifndef _CONFIGIF_H
#define _CONFIGIF_H
//-----------------------------------------------------------------------
// Config API
//-----------------------------------------------------------------------
//-----------------------------------------------------------------------
// CfgNew()
//
// Create a new configuration
//-----------------------------------------------------------------------
_extern HANDLE CfgNew();
//-----------------------------------------------------------------------
// CfgFree( HANDLE hCfg )
//
// Destroy a configuration
//-----------------------------------------------------------------------
_extern void CfgFree( HANDLE hCfg );
//-----------------------------------------------------------------------
// CfgSetDefault()
//
// Set the default configuration
//-----------------------------------------------------------------------
_extern void CfgSetDefault( HANDLE hCfg );
//-----------------------------------------------------------------------
// CfgGetDefault()
//
// Get the default configuration
//-----------------------------------------------------------------------
_extern HANDLE CfgGetDefault();
//-----------------------------------------------------------------------
// CfgLoad()
//
// Load a configuration from memory buffer
//
// Returns the number of bytes processed, or <0 on error
//-----------------------------------------------------------------------
_extern int CfgLoad( HANDLE hCfg, int Size, UINT8 *pData );
//-----------------------------------------------------------------------
// CfgSave()
//
// Save configuration to a memory buffer
//
// *pSize is set to the size of the supplied buffer, or zero to get
// required size (the pointer pSize must be valid, but the value at
// the pointer can be zero).
//
// Returns the number of bytes written (0 on size check, <0 on error)
// *pSize is set to the number of bytes required.
//-----------------------------------------------------------------------
_extern int CfgSave( HANDLE hCfg, int *pSize, UINT8 *pData );
//-----------------------------------------------------------------------
// CfgSetExecuteOrder()
//
// Establishes the order in which Tags are loaded and unloaded when
// the Execute status changes.
//
// When a configuration is first created, the order set in ascending
// Tag value order.
//
// The valute of Tags must be set to the EXACT number of tags in the
// configuration system.
//
// Returns 0 on success, or <0 on error
//-----------------------------------------------------------------------
_extern int CfgSetExecuteOrder( HANDLE hCfg, uint Tags,
uint *pOpenOrder, uint *pCloseOrder );
//-----------------------------------------------------------------------
// CfgExecute()
//
// Executes the configuration - loads all loadable entries
//
// When a configuration is first created, config changes do not
// alter the state of the system. Once the configuration is executed,
// all past settings take effect, and any new settings are immediately
// invoked.
//
// When fExecute is set to 0, all invoked entries are shutdown.
//
// Returns 0 on success, or <0 on error
//-----------------------------------------------------------------------
_extern int CfgExecute( HANDLE hCfg, uint fExecute );
//-----------------------------------------------------------------------
// CfgSetService()
//
// Sets the service function for a particular config TAG. Service
// functions default to NULL, and when so, no service is performed.
//
// When invoked, the service callback function is passed back information
// about the affected entry.
//
// int CbSrv( HANDLE hCfg, uint Tag, uint Item, uint Op, HANDLE hCfgEntry )
// hCfg = HANDLE to Config
// Tag = Tag value of entry changed
// Item = Item value of entry changed
// Op = CFGCOP_ADD or CFGOP_REMOVE
// hCfgEntry = Non-Ref'd HANDLE to entry added or removed
//
// Returns 1 on success, 0 on "pass", and <0 on error.
//
// Note: The config entry handle passed to the callback is NOT Ref'd,
// in that its scope expires when the callback function returns.
//
// Returns 0 on success, <0 on error.
//-----------------------------------------------------------------------
_extern int CfgSetService( HANDLE hCfg, uint Tag,
int (*pCb) (HANDLE, uint, uint, uint, HANDLE) );
#define CFGOP_REMOVE 0
#define CFGOP_ADD 1
//-----------------------------------------------------------------------
// CfgAddEntry()
//
// Add a configuration entry to a configuration.
//
// When the pointer phCfgEntry is non-zero, this function write a
// referenced HANDLE to this location.
//
// When finished with a referenced entry HANDLE, an application must
// DeRef it by calling one of the following functions:
// CfgEntryDeRef() - Stop using the entry
// CfgRemoveEntry() - Stop using entry and remove it from cfg
// CfgGetNextEntry() - Stop using entry and get next entry
//
// Returns 1 on successful add and processing.
// Returns 0 on successful add with no processing.
// Returns <0 but > CFGERROR_SERVICE on configuration error
// Returns <= CFGERROR_SERVICE on successful add, but service error
//
//-----------------------------------------------------------------------
_extern int CfgAddEntry( HANDLE hCfg, uint Tag, uint Item, uint Mode,
int Size, UINT8 *pData, HANDLE *phCfgEntry );
// Add Entry Flags
#define CFG_ADDMODE_UNIQUE 0x0001 // Replace all previous instances
#define CFG_ADDMODE_DUPLICATE 0x0002 // Allow duplicate data entry
#define CFG_ADDMODE_NOSAVE 0x0004 // Don't include this entry in CfgSave
//-----------------------------------------------------------------------
// CfgRemoveEntry()
//
// Performs a single DeRef on a configuration entry, and removes it from
// the configuration structure.
//
// Returns 0 on success, or <0 on error
//-----------------------------------------------------------------------
_extern int CfgRemoveEntry( HANDLE hCfg, HANDLE hCfgEntry );
//-----------------------------------------------------------------------
// CfgGetEntryCnt()
//
// Returns the number of entries on a specific tag/item, or <0 on error
//-----------------------------------------------------------------------
_extern int CfgGetEntryCnt( HANDLE hCfg, uint Tag, uint Item );
//-----------------------------------------------------------------------
// CfgGetEntry()
//
// Get a referenced HANDLE to a configuration entry
//
// Index is a relative value (the "n'th" 1-based entry in a list)
//
// DO NOT use the index value to enumerate entry entry in the list.
// The index is valid only at the time of the call as an item can
// move up and down in the list as config changes are made. To
// enumerate every entry for a Tag/Item pair, start with index 1 and
// then use GetNextEntry() to get additional entries.
//
// When finished with this entry, an application must deref it
// by calling one of the following functions:
// CfgEntryDeRef() - Stop using the entry
// CfgRemoveEntry() - Stop using entry and remove it from cfg
// CfgGetNextEntry() - Stop using entry and get next entry
//
// Function returns 1 on success, 0 on "not found", and <0 on error.
//-----------------------------------------------------------------------
_extern int CfgGetEntry( HANDLE hCfg, uint Tag, uint Item,
uint Index, HANDLE *phCfgEntry );
//-----------------------------------------------------------------------
// CfgGetNextEntry()
//
// DeRef supplied entry HANDLE and get referenced HANDLE of
// next configuration entry in the enumerated list.
//
// When finished with this entry, an application must deref it
// by calling one of the following functions:
// CfgEntryDeRef() - Stop using the entry
// CfgRemoveEntry() - Stop using entry and remove it from cfg
// CfgGetNextEntry() - Stop using entry and get next entry
//
// Function returns 1 on success, 0 on "not found", and <0 on error.
//-----------------------------------------------------------------------
_extern int CfgGetNextEntry( HANDLE hCfg, HANDLE hCfgEntry,
HANDLE *phCfgEntryNext );
//-----------------------------------------------------------------------
// CfgGetImmediate()
//
// This function is intened for when an entry is known to most likely
// exist and is of a fixed size. It looks-up the entry, copies the data,
// and de-refs the entry all in one call.
//
// Returns the number of bytes copied.
//-----------------------------------------------------------------------
_extern int CfgGetImmediate( HANDLE hCfg, uint Tag, uint Item, uint Instance,
int MaxSize, UINT8 *pData );
//-----------------------------------------------------------------------
// CfgEntryRef()
//
// Add a reference a configuration entry handle
//
// This function is called by an application when it intends to use an
// entry handle beyond the scope of the function which obtained it
// from the configuration.
//
// When finished with this entry, an application must deref it
// by calling one of the following functions:
// CfgEntryDeRef() - Stop using the entry
// CfgRemoveEntry() - Stop using entry and remove it from cfg
// CfgGetNextEntry() - Stop using entry and get next entry
//
// Returns 0 on success, <0 on error.
//-----------------------------------------------------------------------
_extern int CfgEntryRef( HANDLE hCfgEntry );
//-----------------------------------------------------------------------
// CfgEntryDeRef();
//
// Dereference a configuration entry handle
//
// Returns 0 on success, <0 on error.
//-----------------------------------------------------------------------
_extern int CfgEntryDeRef( HANDLE hCfgEntry );
//-----------------------------------------------------------------------
// CfgEntryGetData()
//
// Get configuration entry user data
//
// *pSize is set to the size of the supplied buffer, or zero to get
// required size (the pointer pSize must be valid, but the value at
// the pointer can be zero).
//
// Returns the number of bytes written. If the supplied size is ZERO or
// too small, the function returns 0 and *pSize is set to the number of
// bytes required. Returns <0 on non-size related error.
//-----------------------------------------------------------------------
_extern int CfgEntryGetData( HANDLE hCfgEntry, int *pSize, UINT8 *pData );
//-----------------------------------------------------------------------
// CfgEntrySetData()
//
// Set configuration entry user data
//
// Size is set to the size of item to replace. It must be an exact
// match for the current entry size. Also, no processing is done on
// the altered data.
//
// * USE WITH CARE *
//
// Returns the number of bytes written. If the supplied size doesn't
// match the old size, function returns 0.
// Returns <0 on non-size related error.
//-----------------------------------------------------------------------
_extern int CfgEntrySetData( HANDLE hCfgEntry, int Size, UINT8 *pData );
//-----------------------------------------------------------------------
// CfgEntryInfo()
//
// Get configuration entry user data info
//
// Returns configuration size and data pointer. When either size or
// data information is not required, the pointer arguments can be NULL.
//
// Returns ZERO on successm or <0 on error
//-----------------------------------------------------------------------
_extern int CfgEntryInfo( HANDLE hCfgEntry, int *pSize, UINT8 **ppData );
//-----------------------------------------------------------------------
// Config API Error Codes
//-----------------------------------------------------------------------
#define CFGERROR_BADHANDLE -1 // Invalid Cfg handle
#define CFGERROR_BADPARAM -2 // Invalid function parameter
#define CFGERROR_RESOURCES -3 // Memory allocation error
#define CFGERROR_REFERROR -4 // Reference count mismatch
#define CFGERROR_ALREADY -5 // Already in desired state
#define CFGERROR_SERVICE -100 // First service error
#define CFG_MAKE_CFGERROR(x) (x+CFGERROR_SERVICE)
#define CFG_GET_SERVICE_ERROR(x) (x-CFGERROR_SERVICE)
#define CFG_IS_SERVICE_ERROR(x) (x<=CFGERROR_SERVICE)
#endif