mozilla

Compare Revisions

Using js-ctypes

Change Revisions

Revision 347577:

Revision 347577 by smcgregor on

Revision 419151:

Revision 419151 by ethertank on

Title:
Using js-ctypes
Using js-ctypes
Slug:
Mozilla/js-ctypes/Using_js-ctypes
Mozilla/js-ctypes/Using_js-ctypes
Tags:
"js-ctypes", "NeedsTechnicalReview", "JavaScript"
"js-ctypes", "NeedsTechnicalReview", "JavaScript"
Content:

Revision 347577
Revision 419151
n7    <p>n7    <div>
8      {{ gecko_minversion_header("2.0") }}8      {{gecko_minversion_header("2.0")}} {{draft}}
9    </p>9    </div>
10    <p>
11      {{ draft() }}
12    </p>
n16    <pre class="eval">n13    <pre>
17<span class="nowiki">Components.utils.import("resource://gre/modu14Components.utils.import("resource://gre/modules/ctypes.jsm")
>les/ctypes.jsm")</span> 
n23      Once you've imported the code module, you can call the <a hn20      Once you've imported the code module, you can call the <a h
>ref="/en/js-ctypes/js-ctypes_reference/ctypes#open()" title="en/j>ref="/en-US/docs/js-ctypes/js-ctypes_reference/ctypes#open()"><co
>s-ctypes/js-ctypes reference/ctypes#open()"><code>ctypes.open()</>de>ctypes.open()</code></a> method to load each native library yo
>code></a> method to load each native library you wish to use. On >u wish to use. On Windows, for example, you might load the system
>Windows, for example, you might load the system user32 library li> user32 library like this:
>ke this: 
n29      On Mac OS&nbsp;X, you can load the Core Foundation library n26      On Mac OS X, you can load the Core Foundation library from 
>from the Core Foundation framework like this:>the Core Foundation framework like this:
n38      <strong>Note:</strong> js-ctypes only works with C librarien35      <strong>Note:</strong> js-ctypes only works with C librarie
>s; you can't use C++&nbsp;methods directly. Instead, you'll need >s; you can't use C++ methods directly. Instead, you'll need to cr
>to create a shim library that uses C functions that then call int>eate a shim library that uses C functions that then call into the
>o the C++&nbsp;library for you.> C++ library for you.
n67      <strong>Note:</strong> This information comes from <a classn64      <strong>Note:</strong> This information comes from <a href=
>="external" href="http://msdn.microsoft.com/en-us/library/ms68258>"http://msdn.microsoft.com/en-us/library/ms682586(VS.85).aspx">th
>6(VS.85).aspx" title="http://msdn.microsoft.com/en-us/library/ms6>is article on MSDN</a>.
>82586(VS.85).aspx">this article on MSDN</a>. 
n73      When you're finished using a library, you should close it bn70      When you're finished using a library, you should close it b
>y calling the <code>Library</code> object's <a href="/en/js-ctype>y calling the <code>Library</code> object's <a href="/en-US/docs/
>s/js-ctypes_reference/Library#close()" title="en/js-ctypes/js-cty>js-ctypes/js-ctypes_reference/Library#close()"><code>close()</cod
>pes reference/Library#close()"><code>close()</code></a> method:>e></a> method:
n85      You may need to declare new types. These can be simple typen82      You may need to declare new types. These can be simple type
>s or more complex types such as structures. See <a href="/en/js-c>s or more complex types such as structures. See <a href="/en-US/d
>types/Using_js-ctypes/Declaring_types" title="en/js-ctypes/Using >ocs/js-ctypes/Using_js-ctypes/Declaring_types">Declaring types</a
>js-ctypes/Declaring types">Declaring types</a> for details. You w>> for details. You will almost certainly need to <a href="/en-US/
>ill almost certainly need to <a href="/en/js-ctypes/Using_js-ctyp>docs/js-ctypes/Using_js-ctypes/Declaring_and_calling_functions">d
>es/Declaring_and_calling_functions" title="en/js-ctypes/Using js->eclare one or more functions</a>, so that you can call them.
>ctypes/Declaring and calling functions">declare one or more funct 
>ions</a>, so that you can call them. 
86    </p>
87    <p>83    </p>
84    <p>
88      Once you've declared the types and functions, you can write85      Once you've declared the types and functions, you can write
> your code to make use of them. Instantiating C data objects and > your code to make use of them. Instantiating C data objects and 
>referencing them is covered in the article <a href="/en/js-ctypes>referencing them is covered in the article <a href="/en-US/docs/j
>/Using_js-ctypes/Working_with_data" title="en/js-ctypes/Using js->s-ctypes/Using_js-ctypes/Working_with_data">Working with data</a>
>ctypes/Working with data">Working with data</a>.>.
n106      <li>A function or static data declared using the <a href="/n103      <li>A function or static data declared using the <a href="/
>en/js-ctypes/js-ctypes_reference/Library#declare()" title="en/js->en-US/docs/js-ctypes/js-ctypes_reference/Library#declare()"><code
>ctypes/js-ctypes reference/Library#declare()"><code>declare()</co>>declare()</code></a> method will hold that library alive.
>de></a>&nbsp;method will hold that library alive. 
n108      <li>A <a href="/en/js-ctypes/js-ctypes_reference/CType" titn105      <li>A <a href="/en-US/docs/js-ctypes/js-ctypes_reference/CT
>le="en/js-ctypes/js-ctypes reference/CType"><code>CType</code></a>ype"><code>CType</code></a> will hold referent <a href="/en-US/do
>> will hold referent <a href="/en/js-ctypes/js-ctypes_reference/C>cs/js-ctypes/js-ctypes_reference/CType"><code>CType</code></a> ob
>Type" title="en/js-ctypes/js-ctypes reference/CType"><code>CType<>jects alive.
>/code></a> objects alive. 
n110      <li>A <code><a href="/en/js-ctypes/js-ctypes_reference/CDatn107      <li>A <code><a href="/en-US/docs/js-ctypes/js-ctypes_refere
>a" title="en/js-ctypes/js-ctypes reference/CData">CData</a></code>nce/CData">CData</a></code> will hold referent <code><a href="/en
>> will hold referent <code><a href="/en/js-ctypes/js-ctypes_refer>-US/docs/js-ctypes/js-ctypes_reference/CData">CData</a></code> ob
>ence/CData" title="en/js-ctypes/js-ctypes reference/CData">CData<>jects alive, in specific circumstances. For example, a <code><a h
>/a></code> objects alive, in specific circumstances. For example,>ref="/en-US/docs/js-ctypes/js-ctypes_reference/CData">CData</a></
> a <code><a href="/en/js-ctypes/js-ctypes_reference/CData" title=>code> object produced by accessing a field of a structure or the 
>"en/js-ctypes/js-ctypes reference/CData">CData</a></code> object >internals of an array will hold the referent objects alive.
>produced by accessing a field of a structure or the internals of  
>an array will hold the referent objects alive. 
n117      It's important to note that getting direct access to the con114      It's important to note that getting direct access to the co
>ntents of a <code><a href="/en/js-ctypes/js-ctypes_reference/CDat>ntents of a <code><a href="/en-US/docs/js-ctypes/js-ctypes_refere
>a" title="en/js-ctypes/js-ctypes reference/CData">CData</a></code>nce/CData">CData</a></code> object using <a href="/en-US/docs/js-
>> object using <a href="/en/js-ctypes/js-ctypes_reference/CData#a>ctypes/js-ctypes_reference/CData#address()"><code>address()</code
>ddress()" title="en/js-ctypes/js-ctypes reference/CData#address()>></a>, <a href="/en-US/docs/js-ctypes/js-ctypes_reference/CData#a
>"><code>address()</code></a>, <a href="/en/js-ctypes/js-ctypes_re>ddressOfElement()"><code>addressOfElement()</code></a>, or <a hre
>ference/CData#addressOfElement()" title="en/js-ctypes/js-ctypes r>f="/en-US/docs/js-ctypes/js-ctypes_reference/CData#contents"><cod
>eference/CData#addressOfElement()"><code>addressOfElement()</code>e>contents</code></a>, will result in a <code><a href="/en-US/doc
>></a>, or <a href="/en/js-ctypes/js-ctypes_reference/CData#conten>s/js-ctypes/js-ctypes_reference/CData">CData</a></code> object th
>ts" title="en/js-ctypes/js-ctypes reference/CData#contents"><code>at <strong>does not</strong> hold its referent alive. Be sure to 
>>contents</code></a>, will result in a <code><a href="/en/js-ctyp>hold an explicit reference to be sure the referent object doesn't
>es/js-ctypes_reference/CData" title="en/js-ctypes/js-ctypes refer> get garbage collected before you're done using it.
>ence/CData">CData</a></code> object that <strong>does not</strong 
>> hold its referent alive. Be sure to hold an explicit reference  
>to be sure the referent object doesn't get garbage collected befo 
>re you're done using it. 
n135      These examples offer a quick look at how js-ctypes is used.n132      These examples offer a quick look at how js-ctypes is used.
> See <a href="/en/js-ctypes/Examples" title="en/js-ctypes/Example> See <a href="/en-US/docs/js-ctypes/Examples">js-ctypes examples<
>s">js-ctypes examples</a> for more intricate examples.>/a> for more intricate examples.
n163      In line 3, the <code>user32.dll</code> system library is lon160      In line 3, the <code>user32.dll</code> system library is lo
>aded. Line 6 declares <code>msgBox()</code> to be a method that c>aded. Line 6 declares <code>msgBox()</code> to be a method that c
>alls the Windows function <a class="external" href="http://msdn.m>alls the Windows function <a href="http://msdn.microsoft.com/en-u
>icrosoft.com/en-us/library/ms645505%28VS.85%29.aspx" title="http:>s/library/ms645505%28VS.85%29.aspx"><code>MessageBoxW</code></a>.
>//msdn.microsoft.com/en-us/library/ms645505(VS.85).aspx"><code>Me> Line 15 calls the <code>msgBox()</code> routine, which displays 
>ssageBoxW</code></a>. Line 15 calls the <code>msgBox()</code> rou>the alert.
>tine, which displays the alert. 
n175      How we knew how to declare the function was by going to MSDn172      How we knew how to declare the function was by going to MSD
>N site and looking at the MessageBox (MessageBoxW is just a unico>N site and looking at the MessageBox (MessageBoxW is just a unico
>de version of same function) function. Also learn about the lib.d>de version of same function) function. Also learn about the lib.d
>eclare function used here: <a href="/en-US/docs/Mozilla/js-ctypes>eclare function used here: <a href="/en-US/docs/Mozilla/js-ctypes
>/js-ctypes_reference/Library#declare%28%29" title="/en-US/docs/Mo>/js-ctypes_reference/Library#declare%28%29">lib.declare</a>. Lear
>zilla/js-ctypes/js-ctypes_reference/Library#declare%28%29">lib.de>n about the data types used here: <a href="/en-US/docs/Mozilla/js
>clare</a>. Learn about the data types used here: <a href="/en-US/>-ctypes/js-ctypes_reference/ctypes?redirectlocale=en-US&amp;redir
>docs/Mozilla/js-ctypes/js-ctypes_reference/ctypes?redirectlocale=>ectslug=js-ctypes%2Fjs-ctypes_reference%2Fctypes#Predefined_data_
>en-US&amp;redirectslug=js-ctypes%2Fjs-ctypes_reference%2Fctypes#P>types">Data Types</a>. We see that it needs to be defined like th
>redefined_data_types" title="/en-US/docs/Mozilla/js-ctypes/js-cty>is:
>pes_reference/ctypes?redirectlocale=en-US&amp;redirectslug=js-cty 
>pes%2Fjs-ctypes_reference%2Fctypes#Predefined_data_types">Data Ty 
>pes</a>. We see that it needs to be defined like this: 
176    </p>
177    <pre>173    </p>
178<span style="color:Blue;">int</span> WINAPI MessageBox(174    <pre>
175int WINAPI MessageBox(
n186      So we read this article here on defining types and replicatn183      So we read this article here on defining types and replicat
>e it: <a href="/en-US/docs/Mozilla/js-ctypes/Using_js-ctypes/Decl>e it: <a href="/en-US/docs/Mozilla/js-ctypes/Using_js-ctypes/Decl
>aring_types" title="/en-US/docs/Mozilla/js-ctypes/Using_js-ctypes>aring_types">Declaring Types</a>
>/Declaring_types">Declaring Types</a> 
n204      <strong>Note:</strong>This example will not work on 64bit On201      <strong>Note:</strong> This example will not work on 64bit 
>S X, you will likely need to change to the Cocoa API.>OS X, you will likely need to change to the Cocoa API.
n241      Line 11 declares the <code>stdAlert()</code> function, whicn238      Line 11 declares the <code>stdAlert()</code> function, whic
>h will call the Carbon <code>StandardAlert</code> routine. It use>h will call the Carbon <code>StandardAlert</code> routine. It use
>s the default ABI, returns a 16-bit integer (which is a Carbon <c>s the default ABI, returns a 16-bit integer (which is a Carbon <c
>ode>OSErr</code> value), and accepts an integer (the alert type),>ode>OSErr</code> value), and accepts an integer (the alert type),
> two strings, a pointer to a parameter block, which we aren't usi> two strings, a pointer to a parameter block, which we aren't usi
>ng, and another integer, which is used to return the hit item. Se>ng, and another integer, which is used to return the hit item. Se
>e Apple's documentation for <a class="external" href="http://deve>e Apple's documentation for <a href="http://developer.apple.com/l
>loper.apple.com/legacy/mac/library/documentation/Carbon/Reference>egacy/mac/library/documentation/Carbon/Reference/Dialog_Manager/R
>/Dialog_Manager/Reference/reference.html#//apple_ref/c/func/Stand>eference/reference.html#//apple_ref/c/func/StandardAlert"><code>S
>ardAlert" title="http://developer.apple.com/legacy/mac/library/do>tandardAlert</code></a> for details.
>cumentation/Carbon/Reference/Dialog_Manager/Reference/reference.h 
>tml#//apple_ref/c/func/StandardAlert"><code>StandardAlert</code>< 
>/a> for details. 
n264    /* Linux */n261  /* Linux */
265    var libc = ctypes.open("libc.so.6");262  var libc = ctypes.open("libc.so.6");
n267    /* Most other Unixes */n264  /* Most other Unixes */
268    libc = ctypes.open("libc.so");265  libc = ctypes.open("libc.so");
t274                        ctypes.int,       /* return type */t271                        ctypes.int,         /* return type */

Back to History