update api_scilab documention with changes on pvApiCtx
[scilab.git] / scilab / modules / api_scilab / help / en_US / low_level_functions / pointer_writing_api.xml
1 <?xml version="1.0" encoding="utf-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) 2009  - DIGITEO - Antoine ELIAS
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 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" version="5.0-subset Scilab" xml:id="Pointer_writing_API" xml:lang="en">
14   <refnamediv>
15     <refname>Pointer writing (Scilab gateway)</refname>
16     <refpurpose>
17       How to write pointer in a gateway.
18     </refpurpose>
19   </refnamediv>
20   <refsynopsisdiv>
21     <refsection>
22       Create from existing data.
23     </refsection>
24     <title>Calling Sequence</title>
25     <para>Input argument profile:</para>
26     <synopsis>SciErr createPointer(void* _pvCtx, int _iVar, void* _pvPtr)</synopsis>
27     <para>Named variable profile:</para>
28     <synopsis>SciErr createNamedPointer(void* _pvCtx, const char* _pstName, void** _pvPtr)</synopsis>
29   </refsynopsisdiv>
30   <refsection>
31     <title>Arguments</title>
32     <variablelist>
33       <varlistentry>
34         <term>_pvCtx</term>
35         <listitem>
36           <para>
37             Scilab environment pointer, pass in "pvApiCtx" provided by api_scilab.h
38           </para>
39         </listitem>
40       </varlistentry>
41       <varlistentry>
42         <term>_iVar</term>
43         <listitem>
44           <para>
45             Position in the Scilab memory where you want to put the variable
46           </para>
47         </listitem>
48       </varlistentry>
49       <varlistentry>
50         <term>_pstName</term>
51         <listitem>
52           <para>
53             Name of the variable for "named" functions.
54           </para>
55         </listitem>
56       </varlistentry>
57       <varlistentry>
58         <term>_pvPtr</term>
59         <listitem>
60           <para>
61             Address of pointer.
62           </para>
63         </listitem>
64       </varlistentry>
65       <varlistentry>
66         <term>SciErr</term>
67         <listitem>
68           <para>
69             Error structure where is stored errors messages history and first error number.
70           </para>
71         </listitem>
72       </varlistentry>
73     </variablelist>
74   </refsection>
75   <refsynopsisdiv>
76     <refsection>
77       Write directly in Scilab memory.
78     </refsection>
79     <title>Calling Sequence</title>
80     <synopsis>SciErr allocPointer(void* _pvCtx, int _iVar, void** _pvPtr)</synopsis>
81   </refsynopsisdiv>
82   <refsection>
83     <title>Arguments</title>
84     <variablelist>
85       <varlistentry>
86         <term>_pvCtx</term>
87         <listitem>
88           <para>
89             Scilab environment pointer, pass in "pvApiCtx" provided by api_scilab.h.
90           </para>
91         </listitem>
92       </varlistentry>
93       <varlistentry>
94         <term>_piAddress</term>
95         <listitem>
96           <para>
97             Address of the Scilab variable.
98           </para>
99         </listitem>
100       </varlistentry>
101       <varlistentry>
102         <term>_pvPtr</term>
103         <listitem>
104           <para>
105             Return address of pointer.
106           </para>
107         </listitem>
108       </varlistentry>
109       <varlistentry>
110         <term>SciErr</term>
111         <listitem>
112           <para>
113             Error structure where is stored errors messages history and first error number.
114           </para>
115         </listitem>
116       </varlistentry>
117     </variablelist>
118   </refsection>
119   <refsection>
120     <title>Description</title>
121     <para>This help describes how pointer can be handled through the Scilab API.</para>
122     <para>Two types of functions can be used to write in the memory of Scilab.</para>
123   </refsection>
124   <refsection>
125     <!--File_gateway: SCI/modules/api_scilab/tests/unit_tests/pointer_reading_api.c-->
126     <!--File_scilab: SCI/modules/api_scilab/tests/unit_tests/pointer_reading_api.tst-->
127     <!--Lib_name: pointer_reading-->
128     <!--Func_list: read_pointer-->
129     <title>Gateway Source</title>
130     <programlisting role="code_gateway">
131     <![CDATA[ 
132 #include "api_scilab.h"
133 int read_pointer(char *fname,unsigned long fname_len)
134 {
135         SciErr sciErr;
136
137         CheckInputArgument(pvApiCtx, 0, 1);
138     CheckOutputArgument(pvApiCtx, 1, 1);
139
140         if(nbInputArgument(pvApiCtx) == 0)
141         {//create mode
142                 double* pdblData    = (double*)malloc(sizeof(double) * 2 * 2);
143                 pdblData[0]                     = 1;
144                 pdblData[1]                     = 3;
145                 pdblData[2]                     = 2;
146                 pdblData[3]                     = 4;
147                 sciErr = createPointer(pvApiCtx, nbInputArgument(pvApiCtx) + 1, (void*)pdblData);
148         }
149         else if(nbInputArgument(pvApiCtx) == 1)
150         {//read mode
151                 int iType                       = 0;
152                 int* piAddr                     = NULL;
153                 void* pvPtr                     = NULL;
154                 double* pdblData        = NULL;
155                 sciErr = getVarAddressFromPosition(pvApiCtx, 1, &piAddr);
156                 if(sciErr.iErr)
157                 {
158                         printError(&sciErr, 0);
159                         return 0;
160                 }
161                 sciErr = getPointer(pvApiCtx, piAddr, &pvPtr);
162                 if(sciErr.iErr)
163                 {
164                         printError(&sciErr, 0);
165                         return 0;
166                 }
167                 pdblData = (double*)pvPtr;
168                 sciErr = createMatrixOfDouble(pvApiCtx, nbInputArgument(pvApiCtx) + 1, 2, 2, pdblData);
169         }
170         else
171         {
172                 return 0;
173         }
174         if(sciErr.iErr)
175         {
176                 printError(&sciErr, 0);
177                 return 0;
178         }
179         AssignOutputVariable(pvApiCtx, 1) = nbInputArgument(pvApiCtx) + 1;
180         return 0;
181 }
182  ]]></programlisting>
183   </refsection>
184   <refsection>
185     <title>Scilab test script</title>
186     <programlisting role="code_scilab"><![CDATA[ 
187 b_ref = [1,2;3,4];
188 a = read_pointer();
189 b = read_pointer(a);
190 if or(b <> b_ref) then error("failed"), end
191  ]]></programlisting>
192   </refsection>
193 </refentry>