4420fcca65b95edfd39c51b6958788efd176e1ea
[scilab.git] / scilab / modules / api_scilab / includes / api_common.h
1 /*
2  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
3  * Copyright (C) 2009 - DIGITEO - Antoine ELIAS
4   * Copyright (C) 2009 - DIGITEO - Allan CORNET
5  *
6  * This file must be used under the terms of the CeCILL.
7  * This source file is licensed as described in the file COPYING, which
8  * you should have received as part of this distribution.  The terms
9  * are also available at
10  * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
11  */
12
13 #ifndef __COMMON_API__
14 #define __COMMON_API__
15
16 #if !defined(__INTERNAL_API_SCILAB__)
17 #error Do not include api_common.h. Include api_scilab.h instead.
18 #endif
19
20 #ifdef __cplusplus
21 extern "C" {
22 #endif
23
24     /**
25      * The error management structure
26      *
27      */
28
29 #define MESSAGE_STACK_SIZE 5
30
31     typedef struct api_Err
32     {
33         int iErr; /**< The error ID */
34         int iMsgCount; /**< Error level */
35         char* pstMsg[MESSAGE_STACK_SIZE]; /**< The error message */
36     } SciErr;
37
38     typedef struct api_Ctx
39     {
40         char* pstName; /**< Function name */
41     } StrCtx, *pStrCtx;
42
43 #ifdef _MSC_VER
44 #ifndef API_SCILAB_EXPORTS
45     __declspec( dllimport ) StrCtx* pvApiCtx;
46 #else
47     extern StrCtx* pvApiCtx;
48 #endif
49 #else
50     extern StrCtx* pvApiCtx;
51 #endif
52
53 #include "api_scilab.h"
54     /* generics functions */
55
56 /*Rhs*/
57     int* getNbInputArgument(void* _pvCtx);
58 #define nbInputArgument(PVCTX) (*getNbInputArgument(PVCTX))
59
60 #ifdef Rhs
61 #undef Rhs
62 #endif
63 #define Rhs (*getNbInputArgument(pvApiCtx))
64
65 /*Top*/
66     int* getNbArgumentOnStack(void* _pvCtx);
67 #define nbArgumentOnStack(PVCTX) (*getNbArgumentOnStack(PVCTX))
68
69 #ifdef Top
70 #undef Top
71 #endif
72 #define Top (*getNbArgumentOnStack(pvApiCtx))
73
74 /*Lhs*/
75     int* getNbOutputArgument(void* _pvCtx);
76 #define nbOutputArgument(PVCTX) (*getNbOutputArgument(PVCTX))
77 #ifdef Lhs
78 #undef Lhs
79 #endif
80 #define Lhs (*getNbOutputArgument(pvApiCtx))
81
82 /*PutLhs*/
83     int* assignOutputVariable(void* _pvCtx, int _iVal);
84 #define AssignOutputVariable(PVCTX, x) (*assignOutputVariable(PVCTX, x))
85 #ifdef LhsVar
86 #undef LhsVar
87 #endif
88 #define LhsVar(x) (*assignOutputVariable(pvApiCtx, x))
89
90 /*PutLhsVar*/
91     int returnArguments(void* _pvCtx);
92 #define ReturnArguments(PVCTX) if (! returnArguments(PVCTX)) { return 0; }
93 #ifdef PutLhsVar
94 #undef PutLhsVar
95 #endif
96 #define PutLhsVar() if (! returnArguments(pvApiCtx)) { return 0; }
97
98     /**
99      * Check input argument count
100      * @param[in] _iMin min value
101      * @param[in] _iMax : max value
102      * @return if _iMin >= rhs >= _iMax
103      */
104     int checkInputArgument(void* _pvCtx, int _iMin, int _iMax);
105 #define CheckInputArgument(ctx, min, max) \
106     if(checkInputArgument(ctx, min, max) == 0) \
107     { \
108         return 0; \
109     }
110 #ifdef CheckRhs
111 #undef CheckRhs
112 #endif
113 #define CheckRhs(min, max) \
114     if(checkInputArgument(pvApiCtx, min, max) == 0) \
115     { \
116         return 0; \
117     }
118     /**
119      * Check input argument count
120      * @param[in] _iMin min value
121      * @return if rhs >= _iMin
122      */
123     int checkInputArgumentAtLeast(void* _pvCtx, int _iMin);
124 #define CheckInputArgumentAtLeast(ctx, min) \
125     if(checkInputArgumentAtLeast(ctx, min) == 0) \
126     { \
127         return 0; \
128     }
129
130     /**
131      * Check input argument count
132      * @param[in] _iMax : max value
133      * @return if rhs <= max
134      */
135     int checkInputArgumentAtMost(void* _pvCtx, int _iMax);
136 #define CheckInputArgumentAtMost(ctx, max) \
137     if(checkInputArgumentAtMost(ctx, max) == 0) \
138     { \
139         return 0; \
140     }
141
142     /**
143      * Check output argument count
144      * @param[in] _iMin min value
145      * @param[in] _iMax : max value
146      * @return if _iMin >= lhs >= _iMax
147      */
148     int checkOutputArgument(void* _pvCtx, int _iMin, int _iMax);
149 #define CheckOutputArgument(ctx, min, max) \
150     if(checkOutputArgument(ctx, min, max) == 0) \
151     { \
152         return 0; \
153     }
154 #ifdef CheckLhs
155 #undef CheckLhs
156 #endif
157 #define CheckLhs(min, max) \
158     if(checkOutputArgument(pvApiCtx, min, max) == 0) \
159     { \
160         return 0; \
161     }
162
163     /**
164      * Check output argument count
165      * @param[in] _iMin min value
166      * @return if lhs >= _iMin
167      */
168     int checkOutputArgumentAtLeast(void* _pvCtx, int _iMin);
169 #define CheckOutputArgumentAtLeast(ctx, min) \
170     if(checkOutputArgumentAtLeast(ctx, min) == 0) \
171     { \
172         return 0; \
173     }
174
175     /**
176      * Check output argument count
177      * @param[in] _iMax : max value
178      * @return if lhs <= max
179      */
180     int checkOutputArgumentAtMost(void* _pvCtx, int _iMax);
181 #define CheckOutputArgumentAtMost(ctx, max) \
182     if(checkOutputArgumentAtMost(ctx, max) == 0) \
183     { \
184         return 0; \
185     }
186
187     int callOverloadFunction(void* _pvCtx, int _iVar, char* _pstName, unsigned int _iNameLen);
188 #define CallOverloadFunction(x) callOverloadFunction(pvApiCtx, x, fname, strlen(fname))
189 #ifdef OverLoad
190 #undef OverLoad
191 #endif
192 #define OverLoad(x) callOverloadFunction(pvApiCtx, x, fname, (unsigned int)strlen(fname))
193     /**
194      * Get the memory address of a variable from the variable position
195      * @param[in] _iVar variable number
196      * @param[out] _piAddress return variable address
197      * @return if the operation succeeded ( 0 ) or not ( !0 )
198      */
199     SciErr getVarAddressFromPosition(void* _pvCtx, int _iVar, int** _piAddress);
200
201     /**
202      * Get the name of a variable from the variable position
203      * @param[in] _iVar variable number
204      * @param[out] _pstName variable name
205      * @return if the operation succeeded ( 0 ) or not ( !0 )
206      */
207     SciErr getVarNameFromPosition(void* _pvCtx, int _iVar, char* _pstName);
208
209     /**
210      * Get the memory address of a variable from the variable name
211      * @param[in] _pstName variable name
212      * @param[out] _piAddress return variable address
213      * @return if the operation succeeded ( 0 ) or not ( !0 )
214      */
215     SciErr getVarAddressFromName(void* _pvCtx, const char* _pstName, int** _piAddress);
216
217     /**
218      * Get the variable type
219      * @param[in] _piAddress variable address
220      * @param[out] _piType return variable type ( sci_matrix, sci_strings, ... )
221      * @return if the operation succeeded ( 0 ) or not ( !0 )
222      */
223     SciErr getVarType(void* _pvCtx, int* _piAddress, int* _piType);
224
225     /**
226      * Get the variable type from the variable name
227      * @param[in] _pstName variable name
228      * @param[out] _piType return variable type ( sci_matrix, sci_strings, ... )
229      * @return if the operation succeeded ( 0 ) or not ( !0 )
230      */
231     SciErr getNamedVarType(void* _pvCtx, const char* _pstName, int* _piType);
232
233     /**
234      * Check if the variable type is complex double, complex sparse double or complex polynomial
235      * @param[in] _piAddress variable address
236      * @return if complex 1 otherwise 0
237      */
238     int isVarComplex(void* _pvCtx, int* _piAddress);
239
240     /**
241     * Check if the named variable type is complex double, complex sparse double or complex polynomial
242     * @param[in] _pstName variable name
243     * @return if complex 1 otherwise 0
244     */
245     int isNamedVarComplex(void* _pvCtx, const char *_pstName);
246
247     /**
248      * Get variable dimensions
249      * @param[in] _piAddress variable address
250      * @param[out] _piRows return number of rows
251      * @param[out] _piCols return number of cols
252      * @return if the operation succeeded ( 0 ) or not ( !0 )
253      */
254     SciErr getVarDimension(void* _pvCtx, int* _piAddress, int* _piRows, int* _piCols);
255
256     /**
257      * Get named variable dimensions
258      * @param[in] _pstName variable name
259      * @param[out] _piRows return number of rows
260      * @param[out] _piCols return number of cols
261      * @return if the operation succeeded ( 0 ) or not ( !0 )
262      */
263     SciErr getNamedVarDimension(void* _pvCtx, const char *_pstName, int* _piRows, int* _piCols);
264
265     /**
266      * Check if a variable is a matrix form ( row x col )
267      * @param[in] _piAddress variable address
268      * @return if matrix form type variable 1 otherwise 0
269      */
270     int isVarMatrixType(void* _pvCtx, int* _piAddress);
271
272     /**
273      * Check if a named variable is a matrix form ( row x col )
274      * @param[in] _pstName variable name
275      * @return if matrix form type variable 1 otherwise 0
276      */
277     int isNamedVarMatrixType(void* _pvCtx, const char *_pstName);
278
279     /**
280      * Get process mode from input variable
281      * @param[in] _iPos variable position in function call
282      * @param[in] _piAddRef variable address
283      * @param[out] _piMode return process mode ( 0 -> All, 1 -> Row, 2 -> Col )
284      * @return if the operation succeeded ( 0 ) or not ( !0 )
285      */
286     SciErr getProcessMode(void* _pvCtx, int _iPos, int* _piAddRef, int *_piMode);
287
288     /**
289      * Get dimension for variable, extract value from a single value
290      * @param[in] _piAddress variable address ( double or int variable )
291      * @param[out] _piVal return value
292      * @return if the operation succeeded ( 0 ) or not ( !0 )
293      */
294     SciErr getDimFromVar(void* _pvCtx, int* _piAddress, int* _piVal);
295
296     /**
297      * Get dimension for a named variable, extract value from a single value
298      * @param[in] _pstName variable name
299      * @param[out] _piVal return value
300      * @return if the operation succeeded ( 0 ) or not ( !0 )
301      */
302     SciErr getDimFromNamedVar(void* _pvCtx, const char* _pstName, int* _piVal);
303
304     /**
305      * Get Rhs value from variable address
306      * @param[in] _piAddress varaible address
307      * @return rhs value of the variable, if failed returns 0
308      */
309     int getRhsFromAddress(void* _pvCtx, int* _piAddress);
310
311     /**
312      * Check if a variable is a row vector
313      * @param[in] _piAddress variable address
314      * @return 1 for true and 0 for false
315      */
316     int isRowVector(void* _pvCtx, int* _piAddress);
317
318     /**
319      * Check if a variable is a column vector
320      * @param[in] _piAddress variable address
321      * @return 1 for true and 0 for false
322      */
323     int isColumnVector(void* _pvCtx, int* _piAddress);
324
325     /**
326      * Check if a variable is a vector ( row or column )
327      * @param[in] _piAddress variable address
328      * @return 1 for true and 0 for false
329      */
330     int isVector(void* _pvCtx, int* _piAddress);
331
332     /**
333      * Check if a variable is a scalar
334      * @param[in] _piAddress variable address
335      * @return 1 for true and 0 for false
336      */
337     int isScalar(void* _pvCtx, int* _piAddress);
338
339     /**
340      * Check if a variable is a square matrix
341      * @param[in] _piAddress variable address
342      * @return 1 for true and 0 for false
343      */
344     int isSquareMatrix(void* _pvCtx, int* _piAddress);
345
346     /**
347      * Check matrix dimension
348      * @param[in] _piAddress variable address
349      * @param[in] _iRows accepted number of rows ( if -1, don't check )
350      * @param[in] _iCols accepted number of columns ( if -1, don't check )
351      * @return 1 for true and 0 for false
352      */
353     int checkVarDimension(void* _pvCtx, int* _piAddress, int _iRows, int _iCols);
354
355     /**
356      * Check if type of variable
357      * @param[in] _iVar variable position
358      * @return 1 for true and 0 for false
359      */
360     int getInputArgumentType(void* _pvCtx, int _iVar);
361
362     /**
363      * Check if type of variable
364      * @param[in] _iVar variable position
365      * @param[in] _iType variable type to check
366      * @return 1 for true and 0 for false
367      */
368     int checkInputArgumentType(void* _pvCtx, int _iVar, int _iType);
369
370     /**
371      * Check if a matrix is empty
372      * @param[in] _piAddress variable address
373      * @return 1 for true and 0 for false
374      */
375     int isEmptyMatrix(void* _pvCtx, int* _piAddress);
376
377     /**
378      * Create an empty matrix
379      * @param[in] _iVar variable number
380      * @return if the operation succeeded ( 0 ) or not ( !0 )
381      */
382     int createEmptyMatrix(void* _pvCtx, int _iVar);
383
384     /**
385      * Create a named empty matrix
386      * @param[in] _pstName variable name
387      * @return if the operation succeeded ( 0 ) or not ( !0 )
388      */
389     int createNamedEmptyMatrix(void* _pvCtx, const char* _pstName);
390
391     /**
392      * Check if a named variable exists
393      * @param[in] _pstName variable name
394      * @return if the operation succeeded ( 0 ) or not ( !0 )
395      */
396     int isNamedVarExist(void* _pvCtx, const char* _pstName);
397
398     /**
399      * Check if a named variable is a row vector
400      * @param[in] _pstName variable name
401      * @return 1 for true and 0 for false
402      */
403     int isNamedRowVector(void* _pvCtx, const char* _pstName);
404
405     /**
406      * Check if a named variable is a column vector
407      * @param[in] _pstName variable name
408      * @return 1 for true and 0 for false
409      */
410     int isNamedColumnVector(void* _pvCtx, const char* _pstName);
411
412     /**
413      * Check if a named variable is a vector ( row or column )
414      * @param[in] _pstName variable name
415      * @return 1 for true and 0 for false
416      */
417     int isNamedVector(void* _pvCtx, const char* _pstName);
418
419     /**
420      * Check if a named variable is a scalar
421      * @param[in] _pstName variable name
422      * @return 1 for true and 0 for false
423      */
424     int isNamedScalar(void* _pvCtx, const char* _pstName);
425
426     /**
427      * Check if a named variable is a square matrix
428      * @param[in] _pstName variable name
429      * @return 1 for true and 0 for false
430      */
431     int isNamedSquareMatrix(void* _pvCtx, const char* _pstName);
432
433     /**
434      * Check if a named variable is an empty matrix
435      * @param[in] _pstName variable name
436      * @return 1 for true and 0 for false
437      */
438     int isNamedEmptyMatrix(void* _pvCtx, const char* _pstName);
439
440     /**
441      * Delete a variable for stack
442      * @param[in] _pstName variable name
443      * @return 1 for true and 0 for false
444      */
445     int deleteNamedVariable(void* _pvCtx, const char* _pstName);
446
447 #ifdef __cplusplus
448 }
449 #endif
450 #endif /* __COMMON_API__ */