/tags/rel-1-3-29/SWIG/Examples/java/pointer/index.html

# · HTML · 167 lines · 131 code · 36 blank · 0 comment · 0 complexity · 7392e5dc351e8e7c126b8c9afda815b9 MD5 · raw file

  1. <html>
  2. <head>
  3. <title>SWIG:Examples:java:pointer</title>
  4. </head>
  5. <body bgcolor="#ffffff">
  6. <tt>SWIG/Examples/java/pointer/</tt>
  7. <hr>
  8. <H2>Simple Pointer Handling</H2>
  9. <tt>$Header$</tt><br>
  10. <p>
  11. This example illustrates a couple of techniques for handling
  12. simple pointers in SWIG. The prototypical example is a C function
  13. that operates on pointers such as this:
  14. <blockquote>
  15. <pre>
  16. void add(int *x, int *y, int *r) {
  17. *r = *x + *y;
  18. }
  19. </pre>
  20. </blockquote>
  21. By default, SWIG wraps this function exactly as specified and creates
  22. an interface that expects pointer objects for arguments.
  23. SWIG wraps a C pointer with a type wrapper class, for example, SWIGTYPE_p_int for an int*.
  24. The only problem is how does one go about creating these objects from a Java program?
  25. <p>
  26. <h2>Possible Solutions</h2>
  27. <ul>
  28. <li>Write some helper functions to explicitly create objects. For
  29. example:
  30. <blockquote>
  31. <pre>
  32. int *new_int(int ivalue) {
  33. int *i = (int *) malloc(sizeof(ivalue));
  34. *i = ivalue;
  35. return i;
  36. }
  37. int get_int(int *i) {
  38. return *i;
  39. }
  40. void delete_int(int *i) {
  41. free(i);
  42. }
  43. </pre>
  44. </blockquote>
  45. <p>
  46. <li>The SWIG pointer library provides an easier way. <br>
  47. For example, in the interface file
  48. you would do this:
  49. <blockquote>
  50. <pre>
  51. %include cpointer.i
  52. %pointer_functions(int, intp);
  53. </pre>
  54. </blockquote>
  55. and from Java you would use pointers like this:
  56. <blockquote>
  57. <pre>
  58. SWIGTYPE_p_int a = example.new_intp();
  59. SWIGTYPE_p_int b = example.new_intp();
  60. SWIGTYPE_p_int c = example.new_intp();
  61. example.intp_assign(a,37);
  62. example.intp_assign(b,42);
  63. // Note that getCPtr() has package access by default
  64. System.out.println(" a =" + Long.toHexString(SWIGTYPE_p_int.getCPtr(a)));
  65. System.out.println(" b =" + Long.toHexString(SWIGTYPE_p_int.getCPtr(b)));
  66. System.out.println(" c =" + Long.toHexString(SWIGTYPE_p_int.getCPtr(c)));
  67. // Call the add() function with some pointers
  68. example.add(a,b,c);
  69. // Now get the result
  70. int res = example.intp_value(c);
  71. System.out.println(" 37 + 42 =" + res);
  72. // Clean up the pointers
  73. example.delete_intp(a);
  74. example.delete_intp(b);
  75. example.delete_intp(c);
  76. </pre>
  77. </blockquote>
  78. <p>
  79. <li>Use the SWIG typemap library. This library allows you to completely
  80. change the way arguments are processed by SWIG. For example:
  81. <blockquote>
  82. <pre>
  83. %include "typemaps.i"
  84. void add(int *INPUT, int *INPUT, int *OUTPUT);
  85. </pre>
  86. </blockquote>
  87. And in a Java program:
  88. <blockquote>
  89. <pre>
  90. int[] r = {0};
  91. example.sub(37,42,r);
  92. System.out.println("Result =" + r[0]);
  93. </pre>
  94. </blockquote>
  95. Needless to say, this is substantially easier although a bit unusual.
  96. <p>
  97. <li>A final alternative is to use the typemaps library in combination
  98. with the %apply directive. This allows you to change the names of parameters
  99. that behave as input or output parameters. For example:
  100. <blockquote>
  101. <pre>
  102. %include "typemaps.i"
  103. %apply int *INPUT {int *x, int *y};
  104. %apply int *OUTPUT {int *r};
  105. void add(int *x, int *y, int *r);
  106. void sub(int *x, int *y, int *r);
  107. void mul(int *x, int *y, int *r);
  108. ... etc ...
  109. </pre>
  110. </blockquote>
  111. </ul>
  112. <h2>Example</h2>
  113. The following example illustrates the use of these features for pointer
  114. extraction.
  115. <ul>
  116. <li> <a href="example.c">example.c</a> (C Source)
  117. <li> <a href="example.i">example.i</a> (Swig interface)
  118. <li> <a href="main.java">main.java</a> (Java program)
  119. </ul>
  120. <h2>Notes</h2>
  121. <ul>
  122. <li>Since pointers are used for so many different things (arrays, output values,
  123. etc...) the complexity of pointer handling can be as complicated as you want to
  124. make it.
  125. <p>
  126. <li>More documentation on the typemaps.i and cpointer.i library files can be
  127. found in the SWIG user manual. The files also contain documentation.
  128. </ul>
  129. <hr>
  130. </body>
  131. </html>