Changes between Version 3 and Version 4 of pjsua2/SWIG_Quirks


Ignore:
Timestamp:
Jul 23, 2012 7:27:18 AM (7 years ago)
Author:
bennylp
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • pjsua2/SWIG_Quirks

    v3 v4  
    1515[[BR]] 
    1616 
    17 == SWIG Quirks == 
    18  
     17= SWIG Quirks = 
     18 
     19== Common == 
    1920=== Quirks with the use of namespace === 
    2021 
     
    4243}}} 
    4344 
     45=== No pass by reference === #byref 
     46Continue reading below. 
     47=== "const" in parameter matters === 
     48 
     49Otherwise conversion from Python list to std::vector doesn't work. E.g.: 
     50 
     51 {{{ 
     52// example.h 
     53class A 
     54{ 
     55  public: 
     56        void func_a( const vector<int> & param ); 
     57        void func_b( vector<int> & param ); 
     58}; 
     59 }}} 
     60 
     61 {{{ 
     62a.func_a( [0, 1, 2] )        # <-- OK 
     63a.func_b( [0, 1, 2] )        # <-- ERROR 
     64 }}} 
     65 
     66 
     67 
     68=== Must use exception specification in C++ functions === 
     69 
     70Otherwise SWIG will terminate the app when it catches unspecified exception. E.g.: 
     71 
     72 {{{ 
     73// example.h 
     74void raise_1() throw(Error) 
     75{ 
     76   throw Error(); 
     77} 
     78 
     79void raise_2() 
     80{ 
     81   throw Error() 
     82} 
     83 }}} 
     84 
     85 {{{ 
     86 # Python 
     87 try: 
     88    raise_1() 
     89 except Error, e: 
     90    pass               # <-- OK 
     91 
     92 try: 
     93    raise_2()          # <-- ERROR (SWIG terminates app), even with catch-anything 
     94 except: 
     95    pass 
     96 }}} 
     97 
     98=== Undeclared types will be (silently) converted to pointer === 
     99 
     100Yes we know that, but it will catch you anyway, so I'll mention it again here. 
     101 
     102 {{{ 
     103// example.h 
     104#include <pj/types.h> 
     105 
     106class Error 
     107{ 
     108public: 
     109    pj_status_t   status; 
     110    string        reason; 
     111 
     112    Error(pj_status_t err, const string &res) : status(err), reason(res) {} 
     113}; 
     114 }}} 
     115 
     116  {{{ 
     117// example.i 
     118%module example 
     119%{ 
     120#include “example.h” 
     121%} 
     122%include “example.h” 
     123  }}} 
     124 
     125 {{{ 
     126# test.py 
     127err = pj.Error(-1, "Unknown error") 
     128print "%d" % err.status 
     129 }}} 
     130 
     131The code above compiles fine, but pj_status_t will be treated as pointer to unknown structure by SWIG, because the declaration is in <pj/types.h> which is not included in example.i. Hence the Python code above will not print -1 but the pointer value of status. 
     132 
     133 
     134 
     135== Python == 
    44136=== std::vector as attributes doesn't work as expected === 
    45137 
     
    103195   }}} 
    104196 
    105 === No pass by reference === #byref 
    106 Continue reading below. 
    107 === "const" in parameter matters === 
    108  
    109 Otherwise conversion from Python list to std::vector doesn't work. E.g.: 
    110  
    111  {{{ 
    112 // example.h 
    113 class A 
    114 { 
    115   public: 
    116         void func_a( const vector<int> & param ); 
    117         void func_b( vector<int> & param ); 
    118 }; 
    119  }}} 
    120  
    121  {{{ 
    122 a.func_a( [0, 1, 2] )        # <-- OK 
    123 a.func_b( [0, 1, 2] )        # <-- ERROR 
    124  }}} 
    125  
    126  
    127  
    128 === Must use exception specification in C++ functions === 
    129  
    130 Otherwise SWIG will terminate the app when it catches unspecified exception. E.g.: 
    131  
    132  {{{ 
    133 // example.h 
    134 void raise_1() throw(Error) 
    135 { 
    136    throw Error(); 
    137 } 
    138  
    139 void raise_2() 
    140 { 
    141    throw Error() 
    142 } 
    143  }}} 
    144  
    145  {{{ 
    146  # Python 
    147  try: 
    148     raise_1() 
    149  except Error, e: 
    150     pass               # <-- OK 
    151  
    152  try: 
    153     raise_2()          # <-- ERROR (SWIG terminates app), even with catch-anything 
    154  except: 
    155     pass 
    156  }}} 
    157  
    158 === Undeclared types will be (silently) converted to pointer === 
    159  
    160 Yes we know that, but it will catch you anyway, so I'll mention it again here. 
    161  
    162  {{{ 
    163 // example.h 
    164 #include <pj/types.h> 
    165  
    166 class Error 
    167 { 
    168 public: 
    169     pj_status_t   status; 
    170     string        reason; 
    171  
    172     Error(pj_status_t err, const string &res) : status(err), reason(res) {} 
    173 }; 
    174  }}} 
    175  
    176   {{{ 
    177 // example.i 
    178 %module example 
     197== Java == 
     198=== Java attributes: none of them! === #javaattr 
     199 
     200C++ attributes will be converted to get/set functions in Java! E.g.: 
     201 
     202 {{{ 
     203// example.h 
     204class A 
     205{ 
     206public: 
     207   int data; 
     208}; 
     209 }}} 
     210 
     211The "data" member will be converted to "getData()" and "setData()" in Java. 
     212 
     213=== No mapping between std::vector to Java array === 
     214 
     215Even after applying the patch in [http://sourceforge.net/tracker/?func=detail&aid=3393025&group_id=1645&atid=301645 this SWIG ticket], std::vector is still not mapped to Java array. So we're left with awkward syntax to pass an array: 
     216 
     217  {{{ 
     218// ua.h 
     219void set_array(const std::vector<std::string> &arr) {} 
     220  }}} 
     221 
     222  {{{ 
     223// ua.i 
     224%module ua 
    179225%{ 
    180 #include “example.h” 
     226#include "../ua.h" 
    181227%} 
    182 %include “example.h” 
    183   }}} 
    184  
    185  {{{ 
    186 # test.py 
    187 err = pj.Error(-1, "Unknown error") 
    188 print "%d" % err.status 
    189  }}} 
    190  
    191 The code above compiles fine, but pj_status_t will be treated as pointer to unknown structure by SWIG, because the declaration is in <pj/types.h> which is not included in example.i. Hence the Python code above will not print -1 but the pointer value of status. 
    192  
    193  
    194 === Java attributes: none of them! === #javaattr 
    195  
    196 C++ attributes will be converted to get/set functions in Java! E.g.: 
    197  
    198  {{{ 
    199 // example.h 
    200 class A 
    201 { 
    202 public: 
    203    int data; 
    204 }; 
    205  }}} 
    206  
    207 The "data" member will be converted to "getData()" and "setData()" in Java. 
    208  
     228 
     229%include "std_string.i" 
     230%include "std_vector.i" 
     231 
     232namespace std 
     233{ 
     234        %template(StringVector) std::vector<std::string>; 
     235} 
     236 
     237%include "ua.h" 
     238  }}} 
     239 
     240  {{{ 
     241// UaTest.java 
     242public class UaTest { 
     243  static { 
     244    System.loadLibrary("ua3"); 
     245  } 
     246 
     247  public static void main(String argv[]) { 
     248        String[] sarr = { "Hello", "world"}; 
     249        StringVector sv = new StringVector(sarr); 
     250 
     251        ua.set_array(sarr);     // <=----- ERROR 
     252        lc.set_the_svalues(sv); // <=------ OK 
     253  } 
     254} 
     255  }}} 
    209256 
    210257{{{