Embedded/common/src/b_BasicEm/Context.h

/*
 * Copyright (C) 2008 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#ifndef bbs_CONTEXT_EM_H
#define bbs_CONTEXT_EM_H

/* ---- includes ----------------------------------------------------------- */

#include "b_BasicEm/Basic.h"
#include "b_BasicEm/MemTbl.h"
#include "b_BasicEm/DynMemManager.h"

/* ---- related objects  --------------------------------------------------- */

struct bbs_Context;

/* ---- typedefs ----------------------------------------------------------- */

/** error handler function pointer */
typedef void ( *bbs_errorFPtr )( struct bbs_Context* cpA );

/** callback handler function pointer */
typedef uint32 ( *bbs_callbackFPtr )( struct bbs_Context* cpA );

/* ---- constants ---------------------------------------------------------- */

#define bbs_CONTEXT_MAX_ERRORS			8
#define bbs_CONTEXT_MAX_MEM_MANAGERS	8

#ifdef bbs_COMPACT_MESSAGE_HANDLING
/* characters allocated for file name string (string is stored rightbound) (minimum 1)*/
#define bbs_ERROR_MAX_FILE_CHARS	24
/* characters allocated for text message (minimum 1) */
#define bbs_ERROR_MAX_TEXT_CHARS	1
#else
/* characters allocated for file name string (string is stored rightbound) (minimum 1)*/
#define bbs_ERROR_MAX_FILE_CHARS	52
/* characters allocated for text message (minimum 1) */
#define bbs_ERROR_MAX_TEXT_CHARS	256
#endif

/* defined error codes */
#define bbs_ERR_OK						0	/* no error condition */
#define bbs_ERR_ERROR					1	/* generic error */
#define bbs_ERR_OUT_OF_MEMORY			2	/* malloc handler returns with NULL*/
#define bbs_ERR_MEMORY_OVERFLOW			3	/* not enough memory in a segment or no segment */
#define bbs_ERR_WRONG_VERSION			4	/* incompatible version in ..._memRead() */
#define bbs_ERR_CORRUPT_DATA			5	/* corrupt data in ..._memRead()*/
#define bbs_ERR_CALLBACK_ERROR			6	/* a defined error originiating from a callback function */

/* ---- object definition -------------------------------------------------- */

/** error object */
struct bbs_Error
{
	/* error code */
	uint32 errorE;

	/* line number */
	uint32 lineE;

	/* file name */
	char fileE[ bbs_ERROR_MAX_FILE_CHARS ];

	/* error text */
	char textE[ bbs_ERROR_MAX_TEXT_CHARS ];
};

/* ------------------------------------------------------------------------- */

/** context object */
struct bbs_Context 
{

	/* ---- private data --------------------------------------------------- */

	/** error stack */
	struct bbs_Error errStackE[ bbs_CONTEXT_MAX_ERRORS ];

	/** error stack index */
	uint32 errIndexE;

	/** memory table */
	struct bbs_MemTbl memTblE;

	/** multiple purpose dynamic memory managers */
	struct bbs_DynMemManager dynMemManagerArrE[ bbs_CONTEXT_MAX_MEM_MANAGERS ];

	/** number of used memory managers */
	uint32 dynMemManagerArrSizeE;

	/** error function handler */
	bbs_errorFPtr errorHandlerE;

	/** callback function handler */
	bbs_callbackFPtr callbackHandlerE;

	/** user-defined pointer */
	void* userPtrE;

	/* ---- public data ---------------------------------------------------- */

};

/* ---- associated objects ------------------------------------------------- */

/* ---- external functions ------------------------------------------------- */

/* ---- \ghd{ constructor/destructor } ------------------------------------- */

/** initializes bbs_Context  */
void bbs_Context_init( struct bbs_Context* cpA );

/** frees bbs_Context  */
void bbs_Context_exit( struct bbs_Context* cpA );

/* ---- \ghd{ operators } -------------------------------------------------- */

/** copy operator */
void bbs_Context_copy( struct bbs_Context* cpA, const struct bbs_Context* srcPtrA );

/* ---- \ghd{ query functions } -------------------------------------------- */

/* ---- \ghd{ modify functions } ------------------------------------------- */

/** composes an error object */
struct bbs_Error bbs_Error_create( uint32 errorA, uint32 lineA, const char* fileA, const char* textA, ... );

/* ---- \ghd{ memory I/O } ------------------------------------------------- */

/* ---- \ghd{ exec functions } --------------------------------------------- */

/****** ERROR HANDLING *********/

/** puts an error onto the error stack (returns false if stack was already full) */
flag bbs_Context_pushError( struct bbs_Context* cpA, struct bbs_Error errorA );

/** takes the last error from stack and returns it (when stack is empty: returns the error at stack position 0)*/
struct bbs_Error bbs_Context_popError( struct bbs_Context* cpA );

/** returns the last error of stack without removing it (when stack is empty: returns the error at stack position 0)*/
struct bbs_Error bbs_Context_peekError( struct bbs_Context* cpA );

/** returns true if the error stack is not empty */
flag bbs_Context_error( struct bbs_Context* cpA );

/** sets error handler; returns pointer to previous error handler 
 *  Pointer to Error handler can be NULL (->no handler call)
 *  The error handler is called by function pushError diectly after an error was posted
 */
bbs_errorFPtr bbs_Context_setErrorHandler( struct bbs_Context* cpA,
									       bbs_errorFPtr errorHandlerA );

/*******************************/

/****** CALLBACK HANDLING ******/

/** call the callback handler, push error if return value is != bbs_ERR_OK */
void bbs_Context_doCallback( struct bbs_Context* cpA );

/** sets callback handler; returns pointer to previous callback handler 
 *  Pointer to callback handler can be NULL (->no handler call)
 *  The callback handler is called by function doCallback
 */
bbs_callbackFPtr bbs_Context_setCallbackHandler( struct bbs_Context* cpA,
									             bbs_callbackFPtr callbackHandlerA );

/*******************************/

/******* MEMORY HANDLING *******/

/** adds a static memory segment to memory table of context */
void bbs_Context_addStaticSeg(	struct bbs_Context* cpA,
							    uint16* memPtrA, /* pointer to memory (32bit aligned)*/
								uint32 sizeA,    /* size of memory segment in 16 bit units */
								flag sharedA,    /* Indicates that this segment is to be shared among multiple objects */
								uint32 idA );    /* ID of segment, id=0: unspecified */

/* adds a dynamic memory segment to memory table of context
 * Upon destruction of the context object any residual will be freed automatically
 */
void bbs_Context_addDynamicSeg(	struct bbs_Context* cpA,
								bbs_mallocFPtr mallocFPtrA,	/* function pointer to external mem alloc function (s. comment of type declaration)*/
								bbs_freeFPtr freeFPtrA,     /* function pointer to external mem free function */
								flag sharedA,    /* Indicates that this segment is to be shared among multiple objects */
								uint32 idA );    /* ID of segment, id=0: unspecified */


/** Returns allocated memory in selected exclusive segment in units of 16bits */
uint32 bbs_Context_exclAllocSize( struct bbs_Context* cpA, uint32 segIndexA );
								  
/** Returns allocated memory in selected exclusive segment in units of 16bits 
 *  Note that in case of static memory the return value might not reflect 
 *  the actually allocated memory amount.
 */
uint32 bbs_Context_shrdAllocSize( struct bbs_Context* cpA, uint32 segIndexA );
								  
/*******************************/


/** quick compact setup for dynamic memory management environment 
 *  creates an initialized segment with
 *  - one dynamic exclusive segment
 *  - one dynamic shared segment
 *  - error handler (can be NULL)
 *
 * Don't forget to call bbs_Context_exit on returned context if it goes out of scope
 */
void bbs_Context_quickInit( struct bbs_Context* cpA, 
	 					    bbs_mallocFPtr mallocFPtrA,	/* function pointer to external mem alloc function (s. comment of type declaration)*/
						    bbs_freeFPtr freeFPtrA,
						    bbs_errorFPtr errorHandlerA );

			  
#endif /* bbs_CONTEXT_EM_H */