1/*
2 * Copyright (C) 2008 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17#ifndef bbs_CONTEXT_EM_H
18#define bbs_CONTEXT_EM_H
19
20/* ---- includes ----------------------------------------------------------- */
21
22#include "b_BasicEm/Basic.h"
23#include "b_BasicEm/MemTbl.h"
24#include "b_BasicEm/DynMemManager.h"
25
26/* ---- related objects  --------------------------------------------------- */
27
28struct bbs_Context;
29
30/* ---- typedefs ----------------------------------------------------------- */
31
32/** error handler function pointer */
33typedef void ( *bbs_errorFPtr )( struct bbs_Context* cpA );
34
35/** callback handler function pointer */
36typedef uint32 ( *bbs_callbackFPtr )( struct bbs_Context* cpA );
37
38/* ---- constants ---------------------------------------------------------- */
39
40#define bbs_CONTEXT_MAX_ERRORS			8
41#define bbs_CONTEXT_MAX_MEM_MANAGERS	8
42
43#ifdef bbs_COMPACT_MESSAGE_HANDLING
44/* characters allocated for file name string (string is stored rightbound) (minimum 1)*/
45#define bbs_ERROR_MAX_FILE_CHARS	24
46/* characters allocated for text message (minimum 1) */
47#define bbs_ERROR_MAX_TEXT_CHARS	1
48#else
49/* characters allocated for file name string (string is stored rightbound) (minimum 1)*/
50#define bbs_ERROR_MAX_FILE_CHARS	52
51/* characters allocated for text message (minimum 1) */
52#define bbs_ERROR_MAX_TEXT_CHARS	256
53#endif
54
55/* defined error codes */
56#define bbs_ERR_OK						0	/* no error condition */
57#define bbs_ERR_ERROR					1	/* generic error */
58#define bbs_ERR_OUT_OF_MEMORY			2	/* malloc handler returns with NULL*/
59#define bbs_ERR_MEMORY_OVERFLOW			3	/* not enough memory in a segment or no segment */
60#define bbs_ERR_WRONG_VERSION			4	/* incompatible version in ..._memRead() */
61#define bbs_ERR_CORRUPT_DATA			5	/* corrupt data in ..._memRead()*/
62#define bbs_ERR_CALLBACK_ERROR			6	/* a defined error originiating from a callback function */
63
64/* ---- object definition -------------------------------------------------- */
65
66/** error object */
67struct bbs_Error
68{
69	/* error code */
70	uint32 errorE;
71
72	/* line number */
73	uint32 lineE;
74
75	/* file name */
76	char fileE[ bbs_ERROR_MAX_FILE_CHARS ];
77
78	/* error text */
79	char textE[ bbs_ERROR_MAX_TEXT_CHARS ];
80};
81
82/* ------------------------------------------------------------------------- */
83
84/** context object */
85struct bbs_Context
86{
87
88	/* ---- private data --------------------------------------------------- */
89
90	/** error stack */
91	struct bbs_Error errStackE[ bbs_CONTEXT_MAX_ERRORS ];
92
93	/** error stack index */
94	uint32 errIndexE;
95
96	/** memory table */
97	struct bbs_MemTbl memTblE;
98
99	/** multiple purpose dynamic memory managers */
100	struct bbs_DynMemManager dynMemManagerArrE[ bbs_CONTEXT_MAX_MEM_MANAGERS ];
101
102	/** number of used memory managers */
103	uint32 dynMemManagerArrSizeE;
104
105	/** error function handler */
106	bbs_errorFPtr errorHandlerE;
107
108	/** callback function handler */
109	bbs_callbackFPtr callbackHandlerE;
110
111	/** user-defined pointer */
112	void* userPtrE;
113
114	/* ---- public data ---------------------------------------------------- */
115
116};
117
118/* ---- associated objects ------------------------------------------------- */
119
120/* ---- external functions ------------------------------------------------- */
121
122/* ---- \ghd{ constructor/destructor } ------------------------------------- */
123
124/** initializes bbs_Context  */
125void bbs_Context_init( struct bbs_Context* cpA );
126
127/** frees bbs_Context  */
128void bbs_Context_exit( struct bbs_Context* cpA );
129
130/* ---- \ghd{ operators } -------------------------------------------------- */
131
132/** copy operator */
133void bbs_Context_copy( struct bbs_Context* cpA, const struct bbs_Context* srcPtrA );
134
135/* ---- \ghd{ query functions } -------------------------------------------- */
136
137/* ---- \ghd{ modify functions } ------------------------------------------- */
138
139/** composes an error object */
140struct bbs_Error bbs_Error_create( uint32 errorA, uint32 lineA, const char* fileA, const char* textA, ... );
141
142/* ---- \ghd{ memory I/O } ------------------------------------------------- */
143
144/* ---- \ghd{ exec functions } --------------------------------------------- */
145
146/****** ERROR HANDLING *********/
147
148/** puts an error onto the error stack (returns false if stack was already full) */
149flag bbs_Context_pushError( struct bbs_Context* cpA, struct bbs_Error errorA );
150
151/** takes the last error from stack and returns it (when stack is empty: returns the error at stack position 0)*/
152struct bbs_Error bbs_Context_popError( struct bbs_Context* cpA );
153
154/** returns the last error of stack without removing it (when stack is empty: returns the error at stack position 0)*/
155struct bbs_Error bbs_Context_peekError( struct bbs_Context* cpA );
156
157/** returns true if the error stack is not empty */
158flag bbs_Context_error( struct bbs_Context* cpA );
159
160/** sets error handler; returns pointer to previous error handler
161 *  Pointer to Error handler can be NULL (->no handler call)
162 *  The error handler is called by function pushError diectly after an error was posted
163 */
164bbs_errorFPtr bbs_Context_setErrorHandler( struct bbs_Context* cpA,
165									       bbs_errorFPtr errorHandlerA );
166
167/*******************************/
168
169/****** CALLBACK HANDLING ******/
170
171/** call the callback handler, push error if return value is != bbs_ERR_OK */
172void bbs_Context_doCallback( struct bbs_Context* cpA );
173
174/** sets callback handler; returns pointer to previous callback handler
175 *  Pointer to callback handler can be NULL (->no handler call)
176 *  The callback handler is called by function doCallback
177 */
178bbs_callbackFPtr bbs_Context_setCallbackHandler( struct bbs_Context* cpA,
179									             bbs_callbackFPtr callbackHandlerA );
180
181/*******************************/
182
183/******* MEMORY HANDLING *******/
184
185/** adds a static memory segment to memory table of context */
186void bbs_Context_addStaticSeg(	struct bbs_Context* cpA,
187							    uint16* memPtrA, /* pointer to memory (32bit aligned)*/
188								uint32 sizeA,    /* size of memory segment in 16 bit units */
189								flag sharedA,    /* Indicates that this segment is to be shared among multiple objects */
190								uint32 idA );    /* ID of segment, id=0: unspecified */
191
192/* adds a dynamic memory segment to memory table of context
193 * Upon destruction of the context object any residual will be freed automatically
194 */
195void bbs_Context_addDynamicSeg(	struct bbs_Context* cpA,
196								bbs_mallocFPtr mallocFPtrA,	/* function pointer to external mem alloc function (s. comment of type declaration)*/
197								bbs_freeFPtr freeFPtrA,     /* function pointer to external mem free function */
198								flag sharedA,    /* Indicates that this segment is to be shared among multiple objects */
199								uint32 idA );    /* ID of segment, id=0: unspecified */
200
201
202/** Returns allocated memory in selected exclusive segment in units of 16bits */
203uint32 bbs_Context_exclAllocSize( struct bbs_Context* cpA, uint32 segIndexA );
204
205/** Returns allocated memory in selected exclusive segment in units of 16bits
206 *  Note that in case of static memory the return value might not reflect
207 *  the actually allocated memory amount.
208 */
209uint32 bbs_Context_shrdAllocSize( struct bbs_Context* cpA, uint32 segIndexA );
210
211/*******************************/
212
213
214/** quick compact setup for dynamic memory management environment
215 *  creates an initialized segment with
216 *  - one dynamic exclusive segment
217 *  - one dynamic shared segment
218 *  - error handler (can be NULL)
219 *
220 * Don't forget to call bbs_Context_exit on returned context if it goes out of scope
221 */
222void bbs_Context_quickInit( struct bbs_Context* cpA,
223	 					    bbs_mallocFPtr mallocFPtrA,	/* function pointer to external mem alloc function (s. comment of type declaration)*/
224						    bbs_freeFPtr freeFPtrA,
225						    bbs_errorFPtr errorHandlerA );
226
227
228#endif /* bbs_CONTEXT_EM_H */
229
230