4ba03fdb49a005b431556ffba9fcaa0e05860572
[scilab.git] / scilab / modules / api_scilab / help / en_US / 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 version="5.0-subset Scilab" xml:id="Pointer_writing_API"
14           xml:lang="en" xmlns="http://docbook.org/ns/docbook"
15           xmlns:xlink="http://www.w3.org/1999/xlink"
16           xmlns:svg="http://www.w3.org/2000/svg"
17           xmlns:ns5="http://www.w3.org/1999/xhtml"
18           xmlns:mml="http://www.w3.org/1998/Math/MathML"
19           xmlns:db="http://docbook.org/ns/docbook">
20
21     <refnamediv>
22         <refname>Pointer writing (Scilab gateway)</refname>
23         <refpurpose>
24             How to write pointer in a gateway.
25         </refpurpose>
26     </refnamediv>
27     <refsection>
28         <title>Description</title>
29         <para>This help describes how pointer can be handled through the Scilab API.</para>
30         <para>There are 2 types of functions which can be used to write in the memory of Scilab.</para>
31     </refsection>
32     <refsection>
33         <title>Create from existing data</title>
34         <programlisting><![CDATA[
35 int createPointer(int* _piAddress, void* _pvPtr)
36 ]]></programlisting>
37     </refsection>
38     <refsection>
39         <title>Parameters</title>
40         <variablelist>
41             <varlistentry>
42                 <term>_piAddress</term>
43                 <listitem>
44                     <para>
45                         Address of the Scilab variable.
46                     </para>
47                 </listitem>
48             </varlistentry>
49             <varlistentry>
50                 <term>_pvPtr</term>
51                 <listitem>
52                     <para>
53                         Address of pointer.
54                     </para>
55                 </listitem>
56             </varlistentry>
57         </variablelist>
58     </refsection>
59     <refsection>
60         <title>Write directly in Scilab memory</title>
61         <programlisting><![CDATA[
62 int allocPointer(int* _piAddress, void** _pvPtr)
63 ]]></programlisting>
64     </refsection>
65     <refsection>
66         <title>Parameters</title>
67         <variablelist>
68             <varlistentry>
69                 <term>_piAddress</term>
70                 <listitem>
71                     <para>
72                         Address of the Scilab variable.
73                     </para>
74                 </listitem>
75             </varlistentry>
76             <varlistentry>
77                 <term>_pvPtr</term>
78                 <listitem>
79                     <para>
80                         Return address of pointer.
81                     </para>
82                 </listitem>
83             </varlistentry>
84         </variablelist>
85     </refsection>
86     <refsection>
87         <!--File_gateway: SCI/modules/api_scilab/tests/unit_tests/pointer_reading_api.c-->
88         <!--File_scilab: SCI/modules/api_scilab/tests/unit_tests/pointer_reading_api.tst-->
89         <!--Lib_name: pointer_reading-->
90         <!--Func_list: read_pointer-->
91         <title>Gateway Source</title>
92         <programlisting role="code_gateway">
93             <![CDATA[
94 int read_pointer(char *fname,unsigned long fname_len)
95 {
96     int iRet    = 0;
97
98     CheckRhs(0,1);
99     CheckLhs(1,1);
100
101     if(Rhs == 0)
102     {//create mode
103         double* pdblData    = (double*)malloc(sizeof(double) * 2 * 2);
104         pdblData[0]         = 1;
105         pdblData[1]         = 3;
106         pdblData[2]         = 2;
107         pdblData[3]         = 4;
108
109         iRet = createPointer(Rhs + 1, (void*)pdblData);
110     }
111     else
112     {//read mode
113         int* piAddr         = NULL;
114         void* pvPtr         = NULL;
115         double* pdblData    = NULL;
116
117         iRet = getVarAddressFromPosition(1, &piAddr);
118         if(iRet)
119         {
120             return 1;
121         }
122
123         if(getVarType(piAddr) != sci_lufact_pointer)
124         {
125             return 1;
126         }
127
128         iRet = getPointer(piAddr, &pvPtr);
129         if(iRet)
130         {
131             return 1;
132         }
133
134         pdblData = (double *) ((unsigned long int)((double*)pvPtr)[0]);
135
136         iRet = createMatrixOfDouble(Rhs + 1, 2, 2, pdblData);
137     }
138
139     if(iRet)
140     {
141         return 1;
142     }
143
144     LhsVar(1) = Rhs + 1;
145     return 0;
146 }
147             ]]>
148         </programlisting>
149     </refsection>
150
151     <refsection>
152         <title>Scilab test script</title>
153         <programlisting role="code_scilab">
154             <![CDATA[
155 b_ref = [1,2;3,4];
156 a = read_pointer();
157 b = read_pointer(a);
158 if or(b <> b_ref) then error("failed"), end
159             ]]>
160         </programlisting>
161     </refsection>
162 </refentry>