OpenClovis Logo

clRuleApi.h
Go to the documentation of this file.
1 /*
2  * Copyright (C) 2002-2012 OpenClovis Solutions Inc. All Rights Reserved.
3  *
4  * This file is available under a commercial license from the
5  * copyright holder or the GNU General Public License Version 2.0.
6  *
7  * The source code for this program is not published or otherwise
8  * divested of its trade secrets, irrespective of what has been
9  * deposited with the U.S. Copyright office.
10  *
11  * This program is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14  * General Public License for more details.
15  *
16  * For more information, see the file COPYING provided with this
17  * material.
18  */
19 /*******************************************************************************
20  * ModuleName : utils
21  * File : clRuleApi.h
22  *******************************************************************************/
23 
24 /*******************************************************************************
25  * Description :
26  *
27  * This module contains common RBE definitions.
28  *
29  *
30  *****************************************************************************/
31 
32 
33 /********************************************************************************/
34 /************************************ Rule APIs *********************************/
35 /********************************************************************************/
36 /* */
37 /* */
38 /* clRuleExprAllocate */
39 /* clRuleExprDeallocate */
40 /* clRuleExprAppend */
41 /* clRuleExprDuplicate */
42 /* clRuleExprEvaluate */
43 /* clRuleDoubleExprEvaluate */
44 /* clRuleExprLocalConvert */
45 /* clRuleExprConvert */
46 /* clRuleExprFlagsSet */
47 /* clRuleExprOffsetSet */
48 /* clRuleExprMaskSet */
49 /* clRuleExprValueSet */
50 /* clRuleExprFlagsGet */
51 /* clRuleExprOffsetGet */
52 /* clRuleExprMaskGet */
53 /* clRuleExprValueGet */
54 /* clRuleExprMemLenGet */
55 /* clRuleExprPack */
56 /* clRuleExprUnpack */
57 /* clRuleExprPrint */
58 /* */
59 /********************************************************************************/
60 
72 #ifndef _CL_RULE_API_H_
73 #define _CL_RULE_API_H_
74 
75 #ifdef __cplusplus
76 extern "C" {
77 #endif
78 
79 #include <clCommon.h>
80 #include <clCommonErrors.h>
81 
82 /******************************************************************************
83  * Constant and Macro Definitions
84  *****************************************************************************/
85 
89 #define CL_RULE_SWAP32(x) ( (((x)>>24)&0xFF) | \
90  (((x)>>8)&0xFF00) | \
91  (((x)&0xFF00)<<8) | \
92  (((x)&0xFF)<<24) )
93 
94 #define CL_RULE_SWAP16(x) ( (((x)>>8)&0xFF) | \
95  (((x)<<8)&0xFF00) )
96 
97 
100 /*******************************************************************************
101  *
102  * Rule Based Engine Library.
103  *
104  * <h1>Overview</h1>
105  *
106  * The Rule Based Engine (RBE) provides mechanism to create filters based on
107  * simple expression. An expression is made of a mask and a value. The
108  * expression is on user data. Expression evaluation consists of
109  * applying the mask on a given offset in the user data and comparing the
110  * result with the value. The expression evaluates to TRUE if the comparision
111  * is successful.
112  *
113  * <h1>Interaction with other components</h1>
114  *
115  * The RBE engine forms a general purpose library that could be used any
116  * any other software component. The RBE library doesn't depend on any
117  * components.
118  *
119  * <h1>Configuration</h1>
120  *
121  * No explicit configuration is needed for RBE.
122  *
123  * <h1>Usage Scenario(s)</h1>
124  *
125  * The RBE is used to filter or select a subset of objects from a group.
126  * For example, group object implements "filtered walk" using RBE which
127  * is used by EM to select qualified subscribers to an event based on
128  * the event data. Similarly IOC provides received message filtering
129  * using RBE.
130  *
131  * Following are some examples on how to use the RBE functions.
132  * <blockquote>
133  * <pre>
134  * **
135  * * Let's say that we have a message header - an array of bytes and
136  * * the RBE is used to look for a perticulr pattern - viz
137  * * message from a perticular destination address and a
138  * * perticular tag.
139  * *
140  * * {
141  * * ClRuleExprT* expr = clRuleExprAllocate(3);
142  * *
143  * * clRuleExprOffsetSet(expr,0);
144  * * clRuleExprMaskSet(expr,0,0xFFFFFFFF);
145  * * clRuleExprMaskSet(expr,2,0xFFFF0000);
146  * *
147  * * clRuleExprValueSet(expr,0,0xABCDABCD);
148  * * clRuleExprValueSet(expr,2,0xDEAD0000);
149  * *
150  * * Rbe expression, user data, data length = 2 32 bit units
151  * * if( clRuleExprEvaluate(expr, &msgHdr, 2) )
152  * * {
153  * * We have received a msg with ABCDABCD as the fist 4 bytes and
154  * * DEAD as the next two bytes.
155  * * }
156  * * }
157  *
158  * <pre/>
159  * <blockquote/>
160  *
161  * @pkgdoc cl.rbe
162  * @pkgdoctid Rule Based Engine Library.
163  *****************************************************************************/
164 
165 #define CL_RULE_EXPR_FLAG_BITS (2)
166 #define CL_RULE_ARCH_FLAG_MASK (0x3)
167 #define CL_RULE_EXPR_FLAG_MASK (~(CL_RULE_ARCH_FLAG_MASK))
168 #define CL_RULE_EXPR_FLAG_DEFAULT (CL_RULE_NON_ZERO_MATCH | CL_RULE_EXPR_CHAIN_AND)
169 
170 /******************************************************************************
171  * Data Types
172  *****************************************************************************/
173 
177 typedef enum
178 {
179 
183  CL_RULE_LITTLE_END = 0x1,
184 
188  CL_RULE_BIG_END = 0x2,
189 
193  CL_RULE_NON_ZERO_MATCH = 0x4,
194 
198  CL_RULE_MATCH_EXACT = 0x8,
199 
203  CL_RULE_EXPR_CHAIN_AND = 0x10,
204 
208  CL_RULE_EXPR_CHAIN_GROUP_OR = 0x40,
212 } ClRuleExprFlagsT;
213 
217 typedef enum
218 {
219 
223  CL_RULE_FALSE = 0,
224 
228  CL_RULE_TRUE,
229 
233  CL_RULE_UNKNOWN
234 } ClRuleResultT;
235 
236 
240 typedef struct ClRuleExpr
241 {
242 
246  ClUint8T flags;
247 
251  ClUint8T len;
252 
256  ClUint16T offset;
257 
261  struct ClRuleExpr *next;
262 #define maskByte BI_u.Byte
263 #define maskInt BI_u.Int
264  union {
268  ClUint8T Byte[1];
269  ClUint32T Int[1];
270  } BI_u;
271 } ClRuleExprT;
272 
273 
274 /*****************************************************************************
275  * Functions
276  *****************************************************************************/
277 
302 ClRcT clRuleExprAllocate (CL_IN ClUint8T len,
303  CL_OUT ClRuleExprT** ppExpr);
304 
325 ClRcT clRuleExprDeallocate (CL_IN ClRuleExprT* pExpr);
326 
349 ClRcT clRuleExprAppend (CL_IN ClRuleExprT* pFirstExpr, CL_IN ClRuleExprT* pNextExpr);
350 
351 /*
352  ************************************
353  * \brief Duplicates a RBE Expression.
354  *
355  * \par Header File:
356  * clRuleApi.h
357  *
358  * \par Library Name:
359  *
360  * \param pSrcExpr Source RBE Expression to Copy.
361  * \param ppDstExpr Pointer to a new copy of the expression.
362  *
363  * \retval CL_OK The API executed successfully.
364  * \retval CL_ERR_NULL_POINTER If any one of the two input expressions is null.
365  *
366  * \par Description:
367  * This function makes a copy of the given RBE Expression.
368  * The API allocates the needed memory that must be freed
369  * by the caller using clRuleExprDeallocate().
370  *
371  * \sa clRuleExprAllocate(), clRuleExprDeallocate()
372  *
373  */
374 ClRcT clRuleExprDuplicate (CL_IN ClRuleExprT* pSrcExpr, CL_OUT ClRuleExprT** ppDstExpr);
375 
376 
402 ClRuleResultT clRuleExprEvaluate(CL_IN ClRuleExprT* pExpr, CL_IN ClUint32T *pData, CL_IN int dataLen);
403 
404 
428 ClRuleResultT clRuleDoubleExprEvaluate (CL_IN ClRuleExprT* pExpr1, CL_IN ClRuleExprT* pExpr2);
429 
430 
431 /*
432  ************************************
433  * \brief Converts a RBE expression to local endianess.
434  *
435  * \par Header File:
436  * clRuleApi.h
437  *
438  * \par Library Name:
439  *
440  * \param pExpr RBE Expression to be converted.
441  *
442  * \retval CL_OK The API executed successfully.
443  * \retval CL_RC_ERROR On error.
444  *
445  * \par Description:
446  * This function converts a RBE expression to match local endianess.
447  *
448  * \sa clRuleExprConvert()
449  *
450  */
451 ClRcT clRuleExprLocalConvert (CL_IN ClRuleExprT* pExpr);
452 
453 
454 /*
455  ************************************
456  * \brief Endian converts a complex RBE Expression.
457  *
458  * \par Header File:
459  * clRuleApi.h
460  *
461  * \par Library Name:
462  *
463  * \param pExpr RBE Expression to be converted.
464  *
465  * \retval CL_OK The API executed successfully.
466  * \retval CL_RC_ERROR On error.
467  *
468  * \par Description:
469  * This function converts endianness of a complex
470  * RBE expression.
471  *
472  * \sa clRuleExprLocalConvert()
473  *
474  */
475 ClRcT clRuleExprConvert (CL_IN ClRuleExprT* pExpr);
476 
477 
500 ClRcT clRuleExprFlagsSet (CL_IN ClRuleExprT* pExpr, CL_IN ClRuleExprFlagsT flags);
501 
502 
525 ClRcT clRuleExprOffsetSet (CL_IN ClRuleExprT* pExpr, CL_IN ClUint16T offset);
526 
527 
555 ClRcT clRuleExprMaskSet (CL_IN ClRuleExprT* pExpr, CL_IN ClUint16T offset, CL_IN ClUint32T mask);
556 
557 
585 ClRcT clRuleExprValueSet (CL_IN ClRuleExprT* pExpr, CL_IN ClUint16T offset, CL_IN ClUint32T value);
586 
587 
609 ClRcT clRuleExprFlagsGet (CL_IN ClRuleExprT* pExpr, CL_OUT ClRuleExprFlagsT *pFlags);
610 
611 
634 ClRcT clRuleExprOffsetGet (CL_IN ClRuleExprT* pExpr, CL_OUT ClUint16T *pOffset);
635 
636 
664 ClRcT clRuleExprMaskGet (CL_IN ClRuleExprT* pExpr, CL_IN ClUint16T offset, CL_OUT ClUint32T *pMask);
665 
666 
694 ClRcT clRuleExprValueGet (CL_IN ClRuleExprT* pExpr, CL_IN ClUint16T offset, CL_OUT ClUint32T *pValue);
695 
696 
718 ClUint32T clRuleExprMemLenGet (CL_IN ClRuleExprT* pExpr);
719 
720 
746 ClRcT clRuleExprPack(CL_IN ClRuleExprT *pSrcExpr,
747  CL_OUT ClUint8T **ppBuf,
748  CL_OUT ClUint32T *pLen);
749 
750 
772 ClRcT clRuleExprUnpack(CL_IN ClUint8T *pBuf,
773  CL_IN ClUint32T len,
774  CL_OUT ClRuleExprT **ppDstExpr);
775 
776 
799 ClRcT clRuleExprPrint (CL_IN ClRuleExprT* pExpr);
800 
801 #ifdef __cplusplus
802 }
803 #endif
804 
805 #endif /* _CL_RULE_API_H_ */
806 
Generated on Tue Jan 10 10:29:15 PST 2012 for OpenClovis SDK using Doxygen