+This chapter describes SWIG's support of Java. +It covers most SWIG features, but certain low-level details are covered in less depth than in earlier chapters. +

17.1 Overview

+COM is a component technology included in the Windows operating system. It is supported by a wide range of tools - scripting languages +(VBScript, Perl, Python), compiled languages (Delphi, Visual Basic, C#) and even complex applications (MS Office, OpenOffice.org). Thus +writing a COM component is a good way to extend all of these applications at one time. Unfortunately writing COM components is C/C++ +is a non-trivial task which is even harder if you do not use Microsoft's tools (especially if you use some form of GCC). +

+SWIG's COM extension allows you to easily make your C/C++ code accessible to COM-aware tools using the compiler of your choice. It takes care +of many low-level tasks like component registration, memory management, object layout, etc. It preserves the class hierarchy contained in +the C++ code with some limitations - notably only single inheritance is supported. You should try using the COM extension if you have +a large code base using a custom programming interface. On the other hand if you need to implement a fixed COM interface (e.g. a 'visual component' +or a DirectShow filter) then SWIG will probably not be the right tool for you. +

+This chapter is focused mostly on COM-aware scripting languages. The examples - unless noted otherwise - are provided in a subset of Basic +which should work in Visual Basic (including VBA), VBScript and OpenOffice.org Basic. This should not discourage you if you plan to use another language - +the code should be very similar, if not identical, in other scripting languages. The code generated by the COM extension has also been verified to work well in +Delphi and C#. +

17.2 Preliminaries

+To compile the generated code you will need a compiler that supports generating DLLs and understands the __stdcall calling convention. +The compilers that have been tested extensively are MS Visual C++ and MinGW. OpenWatcom, Digital Mars C++, Borland C++ and Cygwin are +tested occasionally and should have no problems. Winegcc can be used on Unix systems but has some limitations. Please note that the +code has only been tested on 32-bit x86 processors. You will also need an IDL compiler - most probably this will +be MIDL (shipped with the Windows SDK, previously known as Platform SDK) but WIDL (shipped with WINE) can be used +too. +

17.2.1 Running SWIG

+/* File: example.i */
+%module test
+%{
+#include "stuff.h"
+%}
+int fact(int n);
+

+%swig -com example.i
+

+$ swig -c++ -com example.i
+

+This will generate four files: example_wrap.c (or example_wrap.cxx), +example.idl, example.def and example_rc.rc. The first file +contains code responsible for object layout, reference counting, etc. The example.idl +file contains a description of the interface exposed to the client applications. The remaining +two files are used during compilation. All these files need to be linked with the rest of +your C/C++ application. +

+The name of the wrapper file is derived from the name of the input file. For example, if the +input file is example.i, the name of the wrapper file is example_wrap.c. +To change this, you can use the -o option. +It is also possible to change the output directory that the COM files are generated into using -outdir. +

+The following sections have further practical examples and details on how you might go about +compiling and using the generated files. +

17.2.2 Additional Commandline Options

+The following table list the additional commandline options available for the COM module. They can also be seen by using: +

+Their use will become clearer by the time you have finished reading this section on SWIG and Java. +

COM specific options
-nopgcpp	suppress the premature garbage collection prevention parameter
-noproxy	generate the low-level functional interface instead of proxy classes
-package <name>	set name of the Java package to <name>

17.2.3 Compiling a dynamic module

+Before your module can be used by COM clients it needs to be built as a dynamically linked library (DLL). +This process is compiler specific. Examples are provided below for Visual C++: +

+$ # MS Visual Studio 2008
+$ midl example.idl
+$ rc example_rc.rc
+$ cl /LD /Feexample.dll example_wrap.c example.def example_rc.res ole32.lib uuid.lib advapi32.lib oleaut32.lib
+

+$ # MinGW and WIDL
+$ widl -t -I /usr/include/wine/windows example.idl
+$ i586-mingw32msvc-windres example_rc.rc example_rc.o
+$ i586-mingw32msvc-gcc -shared -o example.dll example_wrap.c example.def example_rc.o -lole32 -luuid -ladvapi32 -loleaut32
+

+On a Windows installation of MinGW the names of the executables will most probably simply be windres and +gcc, and midl can be used in place of widl. +

+Warning
+A common source of mistakes is the omission of example_rc.[res|o] during compilation. This produces no +errors or warnings but results in a non-working module. +

+Before you can use your module you need to register it (on the machine where it will be used): +

+$ regsvr32 example.dll
+

+This will create entries in the registry needed to locate your module. Please note that this will store +the filesystem path to example.dll so you should not move this file to another location. If +you wish to unregister your module simply type: +

+$ regsvr32 /u example.dll
+

17.2.4 Using your module

+The precise way how you can load your module depends on the target language. In Basic you can use the +CreateObject subroutine: +

+Dim example
+Set example = CreateObject("example.example")
+
+
+
+The variable example now contains a reference to an object of the module class which
+allows you to call global functions and access global variables defined in your module. It also
+allows you to create instances of C++ classes and to call static member functions.
+
+
+17.3 A tour of basic C/C++ wrapping
+
+
+
+SWIG will try to create an interface as similar to the C/C++ code as possible. However because
+of differences between C/C++ and COM there are some aspects that need
+special attention. They are described in this section
+
+
+17.3.1 Global functions
+
+
+
+In COM there are no global functions and therefore SWIG uses a workaround. It defines a class known as
+the module class which contains the global functions and variables from your C/C++ module.
+The example below shows how you can call a global function from a COM client:
+
+
++%module example
+int fact(int n);
+
+
+
+From VB (and most other languages derived from Basic) you can invoke it as follows:
+
+
++Dim example
+Set example = CreateObject("example.example")
+Print example.fact(4)
+
+
+
+17.3.2 Global variables
+
+
+
+Global variables are wrapped as COM properties. This allows you to use them just as you would use them in
+C/C++. For example this module:
+
+
++// SWIG interface file with global variables
+%module example
+...
+%inline %{
+extern int My_variable;
+extern double density;
+%}
+...
+
+
+
+Can be used in the following way:
+
+
++Dim example
+Set example = CreateObject("example.example")
+
+Rem Print out the value of a C global variable
+Print example.My_variable
+
+Rem Set the value of a C global variable
+example.density = 0.8442
+
+
+
+If a variable is declared as const, it is wrapped as a read-only property.
+This means that its value can be read, but cannot be modified. To make ordinary variables read-only,
+you can use the %immutable directive. For example:
+
+
+
++%{
+extern char *path;
+%}
+%immutable;
+extern char *path;
+%mutable;
+
+
+
+
+The %immutable directive stays in effect until it is explicitly disabled or cleared using
+%mutable.
+See the Creating read-only variables section for further details.
+
+
+
+If you just want to make a specific variable immutable, supply a declaration name.  For example:
+
+
+
++%{
+extern char *path;
+%}
+%immutable path;
+...
+extern char *path;      // Read-only (due to %immutable)
+
+
+
+
+17.3.3 Constants
+
+
+
+C/C++ constants are wrapped as immutable properties. This applies both to constants
+created using #define preprocessor directive and the SWIG %constant
+directive. Examples are provided below:
+
+
+
++#define PI 3.14159
+#define VERSION "1.0"
+%constant int FOO = 42;
+%constant const char *path = "/usr/local";
+
+
+
+
+Please note that SWIG can infer the C type from the #define directive - PI
+is wrapped as a floating point value while VERSION is wrapped as a string.
+
+
+17.3.4 Enumerations
+
+
+
+TODO
+
+
+17.3.5 Pointers
+
+
+
+C/C++ pointers are fully supported by SWIG.  Furthermore, SWIG has no problem working with
+incomplete type information.  Here is a rather simple interface:
+
+
+
++%module example
+
+FILE *fopen(const char *filename, const char *mode);
+int fputs(const char *, FILE *);
+int fclose(FILE *);
+
+
+
+
+When wrapped, you will be able to use the functions in a natural way from a COM client. For example:
+
+
+
++Dim example
+Dim f
+
+Set example = CreateObject("example.example")
+Set f = example.fopen("junk","w")
+example.fputs("Hello World", f)
+example.fclose(f)
+
+
+
+
+Since the FILE structure is not known to SWIG the pointer is stored as a void * pointer. You
+can pass this pointer to other functions that expect to receive a pointer to FILE. You cannot dereference
+the pointer or manipulate it in any other way.
+
+
+
+To allow for static type checking a class is generated for each unknown type. In this case the FILE *
+pointer is wrapped as an object implementing interface ISWIGTYPE_p_FILE.
+
+
+
+If you need to perform any complex operations (like casting, dereferencing, etc. ) on the pointer consider creating some
+helper functions. For example:
+
+
+
++%inline %{
+/* C-style cast */
+Bar *FooToBar(Foo *f) {
+   return (Bar *) f;
+}
+
+/* C++-style cast */
+Foo *BarToFoo(Bar *b) {
+   return dynamic_cast<Foo*>(b);
+}
+
+Foo *IncrFoo(Foo *f, int i) {
+    return f+i;
+}
+%}
+
+
+
+
+When working with C++ classes you should use the C++ style casts (static_cast, dynamic_cast).
+This is especially important when you use a cast from a supertype to a subtype; in this
+case only dynamic_cast is guaranteed to work reliably.
+
+
+17.3.6 Structures
+
+
+
+A C structure will in most cases work as you would expect. For example,
+
+
++struct Vector {
+	double x,y,z;
+};
+
+
+
+
+is used as follows:
+
+
++Dim v
+v = CreateObject("example.Vector")
+v.x = 3.5
+v.y = 7.2
+Dim x, y
+x = v.x
+y = v.y
+
+
+
+Similar access is provided for unions and the public data members of C++ classes.
+In fact structures are handled in exactly the same way as C++ classes. More details
+about how SWIG handles C++ classes is provided in the next section.
+
+
+
+17.3.7 C++ classes
+
+
+
+C++ classes are wrapped as COM interfaces. Additionally if a class is not abstract and has
+a default (possibly implicit) constructor then a class definition and a class factory
+are also generated. For example, if you have this class,
+
+
++class List {
+public:
+  List();
+  ~List();
+  int  search(char *item);
+  void insert(char *item);
+  void remove(char *item);
+  char *get(int n);
+  int  length;
+};
+
+
+
+you can use it in Basic like this:
+
+
++Dim l
+Set l = CreateObject("example.List")
+l.insert("Ale")
+l.insert("Stout")
+l.insert("Lager")
+Dim item
+item = l.get(2)
+Dim length
+length = l.length
+
+
+
+Class data members are accessed in the same manner as C structures.  
+
+
+
+Static class members can be accessed in two ways. Let us consider the following
+class:
+
+
+
++class Spam {
+public:
+   static void foo();
+   static int bar;
+};
+
+
+
+
+You can access Spam's static members just like you would access any non-static members:
+
+
+
++Dim Spam
+Set Spam = CreateObject("example.Spam")
+Spam.foo()
+Dim bar
+bar = Spam.bar
+
+
+
+
+In some circumstances it might be necessary to access Spam's static members without
+having an instance of Spam. This could be because Spam is an abstract class
+or because creating it has some side effects. In this case you can use Spam's static
+members in the following way:
+
+
+
++Dim example
+Set example = CreateObject("example.example")
+example.Spam.foo()
+Dim bar
+bar = example.Spam.bar
+
+
+
+
+The code above uses the module class object example and the class object example.Spam.
+As was shown in the previous sections the module class object can serve for accessing global
+functions and variables. The class object serves the same purpose but for static functions and
+static variables of the class Spam. Please note that neither creating the module class object
+nor creating the class object has any side effects. You should also note that SWIG does not provide any
+synchronization of access for static functions and variables (or in fact for any other global/member
+functions/variable). If you plan to create a multi-threaded program you should ensure synchronization
+either within the wrapped C/C++ code or in the target language.
+
+
+17.3.8 C++ inheritance
+
+
+
+SWIG's COM module currently only supports single inheritance. While it might be possible
+to support multiple inheritance it would greatly increase the complexity of the code
+generator and also of the generated code. If your C++ class has more than one superclass
+then all but the first one will be ignored. If this is not what you want you can use
+%feature("ignore") for the unwanted base classes.
+
+
+
+SWIG generates a class hierarchy which mirrors that of the C++ code. Therefore,
+if you have code like this
+
+
+
++class Foo {
+...
+};
+
+class Bar : public Foo {
+...
+};
+
+void spam(Foo *f);
+
+
+
+
+you can use an instance of Bar as argument to spam:
+
+
+
++Dim example, b
+Set example = CreateInstance("example.example")
+Set b = CreateInstance("example.bar")
+example.spam(b)
+
+
+
+
+17.3.9 Pointers, references, arrays and pass by value
+
+
+
+COM expects all complex objects to be passed by pointer. Therefore if you define
+your function in any of these ways:
+
+
+
++void spam1(Foo *x);      // Pass by pointer
+void spam2(Foo &x);      // Pass by reference
+void spam3(Foo x);       // Pass by value
+void spam4(Foo x[]);     // Array of objects
+
+
+
+
+COM will wrap the functions as if they would accept pointers to Foo.
+Naturally in the case of spam3 there is a difference in semantics
+i.e. all changes made by the function will be done on a copy of the passed
+object, just as you would expect in C++.
+
+
+
+All of these functions are called in the same way:
+
+
+
++Dim example, f
+
+Set example = CreateObject("example.example")
+Set f = CreateObject("example.Foo")
+example.spam1(f)
+example.spam2(f)
+example.spam3(f)
+example.spam4(f)
+
+
+
+
+Similar behavior occurs for return values.  For example, if you had
+functions like this,
+
+
+
++Foo *spam5();
+Foo &spam6();
+Foo  spam7();
+
+
+
+
+then all three functions will return a pointer to some Foo object.
+Since the third function (spam7) returns a value, newly allocated memory is used 
+to hold the result and a pointer is returned (the generated COM code will free this
+memory when the object is no longer needed, that is when its reference count reaches 0).
+
+
+17.3.9.1 Null pointers
+
+
+
+TODO
+
+
+
++example.spam1(null);   // Pointer - ok
+example.spam2(null);   // Reference - NullPointerException
+example.spam3(null);   // Value - NullPointerException
+example.spam4(null);   // Array - ok
+
+
+
+
+For spam1 and spam4 above the Java null gets translated into a NULL pointer for passing to the C/C++ function. 
+The converse also occurs, that is, NULL pointers are translated into null Java objects when returned from a C/C++ function.
+
+
+17.3.10 C++ overloaded functions
+
+
+
+Unfortunately COM does not support overloading functions (including constructors). Thus all
+functions with the same name except for the first one will be ignored. If this is not what
+you want you will need to either rename or ignore
+some of the methods. For example:
+
+
+
++%rename(spam_ushort) spam(unsigned short);
+...
+void spam(int);    
+void spam(unsigned short);   // Now renamed to spam_ushort
+
+
+
+
+or
+
+
+
++%ignore spam(unsigned short);
+...
+void spam(int);    
+void spam(unsigned short);   // Ignored
+
+
+
+
+17.3.11 C++ default arguments
+
+
+
+In SWIG function with a default argument is wrapped by generating an additional function for each argument
+that is defaulted. However since COM does not support function overloading the additional functions
+will be ignored. You can change this behavior using the %rename directive:
+
+
+
++%module example
+
+%rename(defaults2) defaults(double);
+%rename(defaults3) defaults();
+void defaults(double d=10.0, int i=0);
+
+
+
+
+17.3.12 C++ namespaces
+
+
+
+SWIG is aware of C++ namespaces, but namespace names do not appear in
+the module nor do namespaces result in a module that is broken up into
+submodules or packages.  For example, if you have a file like this,
+
+
+
++%module example
+
+namespace foo {
+   int fact(int n);
+   struct Vector {
+       double x,y,z;
+   };
+};
+
+
+
+
+it works in Basic as follows:
+
+
+
++Dim example, f, v, y
+
+Set example = CreateObject("example.example")
+f = example.fact(3)
+Set v = CreateObject("example.Vector")
+v.x = 3.4
+y = v.y
+
+
+
+
+If your program has more than one namespace, name conflicts (if any) can be resolved using %rename
+For example:
+
+
+
++%rename(Bar_spam) Bar::spam;
+
+namespace Foo {
+    int spam();
+}
+
+namespace Bar {
+    int spam();
+}
+
+
+
+
+If you have more than one namespace and you want to keep their
+symbols separate, consider wrapping them as separate SWIG modules.
+
+
+17.3.13 Constructors
+
+
+
+COM has no specific support for constructors. Thus constructors are wrapped by SWIG's COM
+module as methods inside of the class object. For example if you have the following definition:
+
+
+
++class Vector {
+public:
+  double x, y;
+  Vector(double a_x, double a_y): x(a_x), y(a_y) {}
+};
+
+
+
+
+you can use the constructor in the following way:
+
+
+
++Dim example, v
+
+example = CreateObject("example.example")
+v = example.Vector.new_Vector(1.42, 10)
+
+
+
+
+Remember that COM does not support method overloading and therefore if there are multiple
+constructors that you would like to use then you will need to rename some of them.
+
+
+
+If your class has a default constructor then you can also use an alternate way of creating
+objects. In this case you can use the following code:
+
+
+
++Dim v
+
+v = CreateObject("example.Vector")
+
+
+
+
+Obviously there is no way to use this syntax for calling a constructor that expects to
+receive parameters.
+
+
+17.3.14 C++ templates
+
+
+
+C++ templates don't present a huge problem for SWIG.  However, in order
+to create wrappers, you have to tell SWIG to create wrappers for a particular
+template instantiation.  To do this, you use the %template directive.
+For example:
+
+
+
++%module example
+%{
+#include <utility>
+%}
+
+template<class T1, class T2>
+struct pair {
+   typedef T1 first_type;
+   typedef T2 second_type;
+   T1 first;
+   T2 second;
+   pair();
+   pair(const T1&, const T2&);
+  ~pair();
+};
+
+%template(pairii) pair<int,int>;
+
+
+
+
+In Basic:
+
+
+
++Dim example, p, first, second
+
+Set example = CreateObject("example.example")
+Set p = example.pairii.new_pairii(3, 4)
+first = p.first
+second = p.second
+
+
+
+
+Obviously, there is more to template wrapping than shown in this example.
+More details can be found in the SWIG and C++ chapter.   
+
+
+17.3.15 C++ Smart Pointers
+
+
+
+TODO
+
+
+
+17.4 Further details on COM wrapping
+
+
+
+The previous sections were meant as a quick start guide for wrapping C/C++ code as
+COM objects. For users wanting to have a better understanding of how things work
+beneath the surface this section provides some mor details.
+
+
+17.4.1 Classes and interfaces
+
+
+
+There is no direct COM counterpart to a C++ class. COM defines two entities - the
+interface which is comparable to a 'pure virtual' class, and the COM class which
+is an implementation of one or more interfaces. There is no hierarchy of COM classes
+but there is a hierarchy of interfaces. For each C++ class SWIG creates an interface
+containing declarations of public functions and property getters and setters. If the
+C++ class derives from a superclass then this relationship is preserved for their
+corresponding interfaces (but as was stated before only single inheritance is supported).
+The definition of a COM class serves the purpose of providing a way to locate a class's
+factory object. Therefore the COM class in defined only when the class is not abstract
+and has a default constructor. The following example shows two C++ classes
+
+
+
++class A {
+public:
+  virtual int foo(A *) = 0;
+};
+
+class B : public A {
+public:
+  int foo(A *) { return 0; }
+  int bar() { return 0; }
+};
+
+
+
+
+and their corresponding definitions in the generated IDL file:
+
+
+
++[ ... ]
+interface IA : IDispatch {
+  HRESULT foo(A *arg1, [ retval, out ] int *SWIG_result);
+};
+
+[ ... ]
+interface IB : IA {
+  HRESULT bar([ retval, out ] int *SWIG_result);
+};
+
+[ ... ]
+coclass BImpl {
+  interface IB;
+  interface ISWIGWrappedObject;
+};
+
+
+
+
+Some notable things above are the use of IDispatch as the base interface,
+the use of HRESULT as return value along with the wrapping of the real return
+value as an out parameter, and the ISWIGWrappedObject interface.
+They will be described in later subsections.
+
+
+17.4.2 Module class and class objects
+
+
+
+Since COM does not support global functions and variables the module class is used as
+a workaround. The name of the module class is the same as the name of the module itself.
+There may be multiple objects of the module class but all of them will work on the
+same data - your module's global variables. SWIG does not provide any synchronization
+and therefore if you plan to use global variables from multiple threads you will need
+to take care of multithreading issues either in the C/C++ code or in the target language.
+
+
+
+Class objects serve a very similar purpose as the module class with regard to static
+member functions and variables. Note: They should not be confused with what COM calls
+'class objects' which is just another name for class factories.
+Technically static functions and variables could be
+a part of the module class and the class objects created by SWIG serve only the purpose of creating
+a logical namespace layout. Class objects can be accessed as read-only properties
+of the module class, e.g. if you have the following class:
+
+
+
++%module example
+
+class A {
+public:
+  static int func(void) { return 15; }
+};
+
+
+
+
+then SWIG will define definitions in the IDL file similar to these:
+
+
+
++[ ... ]
+interface IAStatic : IDispatch {
+  HRESULT func([ retval, out ] int *SWIG_result);
+};
+
+[ ... ]
+interface Iexample : IDispatch {
+  [ propget ]
+  HRESULT A([ retval, out ] IAStatic **SWIG_result);
+}
+
+
+
+
+The code can then be used in the following way:
+
+
+
++Dim example
+
+Set example = CreateObject("example.example")
+Print example.A.func()
+
+
+
+
+The same considerations apply for class objects as for the module class object. Even though
+there might be several objects for the class A defined above they will all be
+accessing the same static variables. Please note that currently you cannot directly create
+a class object (e.g. using CreateObject in Basic) and need to use the module
+class. There is no good reason for it other than that it has not yet been implemented.
+
+
+17.4.3 GUID handling
+
+
+
+COM uses 128-bit identifiers called GUIDs (or UUIDs) for uniquely identifying classes, interfaces
+and type libraries. Ideally you should generate CLSIDs (class GUIDs) and IIDs (interface GUIDs)
+for each wrapped class and change them each time that you make an incompatible change to a
+class's public interface. Since this is a time consuming process you can delegate some of this
+work to SWIG.
+
+
+
+You can specify a CLSID and an IID for each class using the %feature directive:
+
+
+
++%feature("iid"="12345678-1234-1234-1234-000000000000") A;
+%feature("clsid"="12345678-1234-1234-1234-000000000001") A;
+
+
+
+
+For the module class you can define the CLSID and IID as part of the module directive:
+
+
+
++%module(moduleiid="12345678-1234-1234-1234-000000000002", moduleclsid="12345678-1234-1234-1234-000000000003") example
+
+
+
+
+Finally there is also a GUID (called TLBID) for the type library which is the COM description of your
+whole module. You can customize it in this way:
+
+
+
++%module(tlbid="12345678-1234-1234-1234-000000000004") example
+
+
+
+
+If you do not want to provide all of the above GUIDs you can offload some work to SWIG. To do this
+you can define a 'master' GUID which will serve as a seed value for automatically generating GUIDs:
+
+
+
++%module(master_guid="12345678-1234-1234-1234-000000000005") example
+
+
+
+
+When SWIG wraps a class for which no IID or CLSID has been specified it will concatenate the
+binary representation of master_guid, the module name, the class name and a suffix
+specifying whether the GUID is generated for a class, interface or type library. Then it
+will compute the SHA-1 hash of this string and use the resulting bits for generating a GUID
+(this process has been described in RFC 4122 as variant 5 of the generation algorithm).
+
+
+
+This process reduces the number of GUIDs you need to generate to only one - the master GUID.
+You can generate it in various ways, e.g. by using guidgen from Microsoft's SDK or
+one of many GUID/UUID generators available on the web. The procedure described above ensures
+that your GUIDs will remain the same when you re-run SWIG. If for some reason you need to
+change the public interface of some of your wrapped classes you can do this either by
+manually specifying their new CLSIDs and IIDs, or by changing the master GUID.
+
+
+17.4.4 Class factories and aggregation
+
+
+
+SWIG creates class factories for all defined COM classes. This means that class factories
+are created for proxies of non-abstract classes with a default destructor and also for the
+module class.
+
+
+
+SWIG supports COM aggregation for proxy classes. The module class currently cannot be
+aggregated.
+
+
+17.4.5 IDispatch and HRESULT as return value
+
+
+
+All interfaces generated by SWIG are dual interfaces - this means that they support
+both early binding (sometimes called VTBL binding - used mostly by compiled languages)
+and late binding (sometimes called 'name binding' - used in scripting languages) by
+implementing the IDispatch interface. As a result the return values of all interface
+functions need to be instances of HRESULT. This is used for reporting whether the
+function call succeeded or failed (e.g. when the call is made remotely using DCOM).
+The 'real' return value, if any, needs to be therefore transformed to an out parameter
+of the function. If you use the generated COM object from a scripting language then most
+likely you will not see any difference - you will be able to use the function just as
+it would be returning a value. However if you use a compiled language (like C, C++ or Delphi)
+then you will need to explicitly provide a pointer to the address where the return value
+is to be stored.
+
+
+17.4.6 ISWIGWrappedObject interface
+
+
+17.4.7 Memory management
+
+
+17.4.8 Exceptions
+
+
+17.5 Customization features
+
+
+17.5.1 Typemaps
+
+
+17.5.2 Exception handling
+
+
+
+
+
diff --git a/Doc/Manual/CSharp.html b/Doc/Manual/CSharp.html
index 97cb75409..94e3eca79 100644
--- a/Doc/Manual/CSharp.html
+++ b/Doc/Manual/CSharp.html
@@ -5,7 +5,7 @@
 
 
 
-17 SWIG and C#
+18 SWIG and C#
 
 
 
@@ -39,7 +39,7 @@
 
 
 
-17.1 Introduction
+18.1 Introduction
 
 
 
@@ -59,7 +59,7 @@ The Microsoft Developer Network (MSDN) h
 Monodoc, available from the Mono project, has a very useful section titled Interop with native libraries.
 
 
-17.2 Differences to the Java module
+18.2 Differences to the Java module
 
 
 
@@ -397,7 +397,7 @@ Windows users can also get the examples working using a
 Cygwin or MinGW environment for automatic configuration of the example makefiles.
 Any one of the three C# compilers (Portable.NET, Mono or Microsoft) can be detected from within a Cygwin or Mingw environment if installed in your path. 
 
-
17.3 C# Exceptions
+18.3 C# Exceptions
 
 
 
@@ -494,7 +494,7 @@ set so should only be used when a C# exception is not created.
 
 
 
-17.3.1 C# exception example using "check" typemap
+18.3.1 C# exception example using "check" typemap
 
 
 
@@ -676,7 +676,7 @@ method and C# code does not handle pending exceptions via the canthrow attribute
 Actually it will issue this warning for any function beginning with SWIG_CSharpSetPendingException.
 
 
-17.3.2 C# exception example using %exception
+18.3.2 C# exception example using %exception
 
 
 
@@ -741,7 +741,7 @@ The managed code generated does check for the pending exception as mentioned ear

17.3.3 C# exception example using exception specifications

18.3.3 C# exception example using exception specifications

@@ -798,7 +798,7 @@ SWIGEXPORT void SWIGSTDCALL CSharp_evensonly(int jarg1) { Multiple catch handlers are generated should there be more than one exception specifications declared.

17.3.4 Custom C# ApplicationException example

18.3.4 Custom C# ApplicationException example

17.4 C# Directors

18.4 C# Directors

@@ -945,7 +945,7 @@ The following sections provide information on the C# director implementation and However, the Java directors section should also be read in order to gain more insight into directors.

17.4.1 Directors example

18.4.1 Directors example

17.4.2 Directors implementation

18.4.2 Directors implementation

@@ -1252,7 +1252,7 @@ void SwigDirector_Base::BaseBoolMethod(Base const &b, bool flag) { -

17.4.3 Director caveats

18.4.3 Director caveats

@@ -1300,7 +1300,7 @@ However, a call from C# to CSharpDefaults.DefaultMethod() will of cours should pass the call on to CSharpDefaults.DefaultMethod(int)using the C++ default value, as shown above.

17.5 C# Typemap examples

18.5 C# Typemap examples

17.5.1 Memory management when returning references to member variables

18.5.1 Memory management when returning references to member variables

@@ -1432,7 +1432,7 @@ public class Bike : IDisposable { Note the addReference call.

17.5.2 Memory management for objects passed to the C++ layer

18.5.2 Memory management for objects passed to the C++ layer

@@ -1551,7 +1551,7 @@ The 'cscode' typemap simply adds in the specified code into the C# proxy class. -

17.5.3 Date marshalling using the csin typemap and associated attributes

18.5.3 Date marshalling using the csin typemap and associated attributes

17.5.4 A date example demonstrating marshalling of C# properties

18.5.4 A date example demonstrating marshalling of C# properties

17.5.5 Turning wrapped classes into partial classes

18.5.5 Turning wrapped classes into partial classes

@@ -1988,7 +1988,7 @@ demonstrating that the class contains methods calling both unmanaged code - The following example is an alternative approach to adding managed code to the generated proxy class.

33.1 Bugs

34.1 Bugs

@@ -45,7 +45,7 @@ Currently the following features are not implemented or broken:

C Array wrappings

33.2 Using R and SWIG

34.2 Using R and SWIG

@@ -99,7 +99,7 @@ Without it, inheritance of wrapped objects may fail. These two files can be loaded in any order

33.3 Precompiling large R files

34.3 Precompiling large R files

In cases where the R file is large, one make save a lot of loading @@ -117,7 +117,7 @@ will save a large amount of loading time. -

33.4 General policy

34.4 General policy

@@ -126,7 +126,7 @@ wrapping over the underlying functions and rely on the R type system to provide R syntax.

33.5 Language conventions

34.5 Language conventions

@@ -135,7 +135,7 @@ and [ are overloaded to allow for R syntax (one based indices and slices)

33.6 C++ classes

34.6 C++ classes

@@ -147,7 +147,7 @@ keep track of the pointer object which removes the necessity for a lot of the proxy class baggage you see in other languages.

33.7 Enumerations

34.7 Enumerations

diff --git a/Doc/Manual/Ruby.html b/Doc/Manual/Ruby.html index 9cd83d494..7360f732d 100644 --- a/Doc/Manual/Ruby.html +++ b/Doc/Manual/Ruby.html @@ -26,7 +26,7 @@ -

31 SWIG and Ruby

32 SWIG and Ruby

31.1 Preliminaries

32.1 Preliminaries

SWIG 1.3 is known to work with Ruby versions 1.6 and later. @@ -190,7 +190,7 @@ of Ruby.

31.1.1 Running SWIG

32.1.1 Running SWIG

To build a Ruby module, run SWIG using the -ruby @@ -244,7 +244,7 @@ to compile this file and link it with the rest of your program.

31.1.2 Getting the right header files

32.1.2 Getting the right header files

In order to compile the wrapper code, the compiler needs the ruby.h @@ -288,7 +288,7 @@ installed, you can run Ruby to find out. For example:

31.1.3 Compiling a dynamic module

32.1.3 Compiling a dynamic module

Ruby extension modules are typically compiled into shared @@ -443,7 +443,7 @@ manual pages for your compiler and linker to determine the correct set of options. You might also check the SWIG Wiki for additional information.

31.1.4 Using your module

32.1.4 Using your module

Ruby module names must be capitalized, @@ -498,7 +498,7 @@ begins with:

31.1.5 Static linking

32.1.5 Static linking

An alternative approach to dynamic linking is to rebuild the @@ -519,7 +519,7 @@ finally rebuilding Ruby.

31.1.6 Compilation of C++ extensions

32.1.6 Compilation of C++ extensions

On most machines, C++ extension modules should be linked @@ -571,7 +571,7 @@ extension, e.g.

31.2 Building Ruby Extensions under Windows 95/NT

32.2 Building Ruby Extensions under Windows 95/NT

Building a SWIG extension to Ruby under Windows 95/NT is @@ -610,7 +610,7 @@ files.

31.2.1 Running SWIG from Developer Studio

32.2.1 Running SWIG from Developer Studio

If you are developing your application within Microsoft @@ -752,7 +752,7 @@ directory, then run the Ruby script from the DOS/Command prompt:

31.3 The Ruby-to-C/C++ Mapping

32.3 The Ruby-to-C/C++ Mapping

This section describes the basics of how SWIG maps C or C++ @@ -762,7 +762,7 @@ declarations in your SWIG interface files to Ruby constructs.

31.3.1 Modules

32.3.1 Modules

The SWIG %module directive specifies @@ -931,7 +931,7 @@ Ruby's built-in names.

31.3.2 Functions

32.3.2 Functions

Global functions are wrapped as Ruby module methods. For @@ -994,7 +994,7 @@ module that can be used like so:

31.3.3 Variable Linking

32.3.3 Variable Linking

C/C++ global variables are wrapped as a pair of singleton @@ -1094,7 +1094,7 @@ effect until it is explicitly disabled using %mutable. -

31.3.4 Constants

32.3.4 Constants

C/C++ constants are wrapped as module constants initialized @@ -1138,7 +1138,7 @@ constant values, e.g.

31.3.5 Pointers

32.3.5 Pointers

"Opaque" pointers to arbitrary C/C++ types (i.e. types that @@ -1190,7 +1190,7 @@ the Ruby nil object.

31.3.6 Structures

32.3.6 Structures

C/C++ structs are wrapped as Ruby classes, with accessor @@ -1365,7 +1365,7 @@ pointers. For example,

31.3.7 C++ classes

32.3.7 C++ classes

Like structs, C++ classes are wrapped by creating a new Ruby @@ -1451,7 +1451,7 @@ class. -

31.3.8 C++ Inheritance

32.3.8 C++ Inheritance

The SWIG type-checker is fully aware of C++ inheritance. @@ -1682,7 +1682,7 @@ Typing").

31.3.9 C++ Overloaded Functions

32.3.9 C++ Overloaded Functions

C++ overloaded functions, methods, and constructors are @@ -1878,7 +1878,7 @@ and C++" chapter for more information about overloading.

31.3.10 C++ Operators

32.3.10 C++ Operators

For the most part, overloaded operators are handled @@ -1959,7 +1959,7 @@ on operator overloading.

31.3.11 C++ namespaces

32.3.11 C++ namespaces

SWIG is aware of C++ namespaces, but namespace names do not @@ -2035,7 +2035,7 @@ identical symbol names, well, then you get what you deserve.

31.3.12 C++ templates

32.3.12 C++ templates

C++ templates don't present a huge problem for SWIG. However, @@ -2079,7 +2079,7 @@ directive. For example:

31.3.13 C++ Standard Template Library (STL)

32.3.13 C++ Standard Template Library (STL)

On a related note, the standard SWIG library contains a @@ -2332,7 +2332,7 @@ chapter.

31.3.14 C++ STL Functors

32.3.14 C++ STL Functors

Some containers in the STL allow you to modify their default @@ -2532,7 +2532,7 @@ b
-

31.3.15 C++ STL Iterators

32.3.15 C++ STL Iterators

The STL is well known for the use of iterators. There @@ -2743,7 +2743,7 @@ i
-

31.3.16 C++ Smart Pointers

32.3.16 C++ Smart Pointers

In certain C++ programs, it is common to use classes that @@ -2868,7 +2868,7 @@ method. For example:

31.3.17 Cross-Language Polymorphism

32.3.17 Cross-Language Polymorphism

SWIG's Ruby module supports cross-language polymorphism @@ -2881,7 +2881,7 @@ using this feature with Ruby.

31.3.17.1 Exception Unrolling

32.3.17.1 Exception Unrolling

Whenever a C++ director class routes one of its virtual @@ -2919,7 +2919,7 @@ caught here and a C++ exception is raised in its place.

31.4 Naming

32.4 Naming

Ruby has several common naming conventions. Constants are @@ -3015,7 +3015,7 @@ planned to become the default option in future releases.

31.4.1 Defining Aliases

32.4.1 Defining Aliases

It's a fairly common practice in the Ruby built-ins and @@ -3107,7 +3107,7 @@ Features") for more details).

31.4.2 Predicate Methods

32.4.2 Predicate Methods

Ruby methods that return a boolean value and end in a @@ -3196,7 +3196,7 @@ Features") for more details).

31.4.3 Bang Methods

32.4.3 Bang Methods

Ruby methods that modify an object in-place and end in an @@ -3260,7 +3260,7 @@ Features") for more details).

31.4.4 Getters and Setters

32.4.4 Getters and Setters

Often times a C++ library will expose properties through @@ -3330,7 +3330,7 @@ methods to be exposed in Ruby as value and value=. -

`31.5 Input and output parameters`

+32.5 Input and output parameters A common problem in some C programs is handling parameters @@ -3581,10 +3581,10 @@ of %apply -31.6 Exception handling +32.6 Exception handling -31.6.1 Using the %exception directive +32.6.1 Using the %exception directive The SWIG %exception directive can be @@ -3679,7 +3679,7 @@ Features for more examples. -31.6.2 Handling Ruby Blocks +32.6.2 Handling Ruby Blocks One of the highlights of Ruby and most of its standard library @@ -3860,7 +3860,7 @@ RUBY_YIELD_SELF ); For more information on typemaps, see Typemaps. -31.6.3 Raising exceptions +32.6.3 Raising exceptions There are three ways to raise exceptions from C++ code to @@ -4621,7 +4621,7 @@ the built-in Ruby exception types. -31.6.4 Exception classes +32.6.4 Exception classes Starting with SWIG 1.3.28, the Ruby module supports the %exceptionclass @@ -4679,7 +4679,7 @@ providing for a more natural integration between C++ code and Ruby code. -31.7 Typemaps +32.7 Typemaps This section describes how you can modify SWIG's default @@ -4702,7 +4702,7 @@ of the primitive C-Ruby interface. -31.7.1 What is a typemap? +32.7.1 What is a typemap? A typemap is nothing more than a code generation rule that is @@ -4964,7 +4964,7 @@ to be used as follows (notice how the length parameter is omitted): -31.7.2 Typemap scope +32.7.2 Typemap scope Once defined, a typemap remains in effect for all of the @@ -5012,7 +5012,7 @@ where the class itself is defined. For example: -31.7.3 Copying a typemap +32.7.3 Copying a typemap A typemap is copied by using assignment. For example: @@ -5114,7 +5114,7 @@ rules as for -31.7.4 Deleting a typemap +32.7.4 Deleting a typemap A typemap can be deleted by simply defining no code. For @@ -5166,7 +5166,7 @@ typemaps immediately after the clear operation. -31.7.5 Placement of typemaps +32.7.5 Placement of typemaps Typemap declarations can be declared in the global scope, @@ -5250,7 +5250,7 @@ string - 31.7.6 Ruby typemaps +32.7.6 Ruby typemaps The following list details all of the typemap methods that @@ -5260,7 +5260,7 @@ can be used by the Ruby module: -31.7.6.1 "in" typemap +32.7.6.1 "in" typemap Converts Ruby objects to input @@ -5503,7 +5503,7 @@ arguments to be specified. For example: -31.7.6.2 "typecheck" typemap +32.7.6.2 "typecheck" typemap The "typecheck" typemap is used to support overloaded @@ -5544,7 +5544,7 @@ on "Typemaps and Overloading." -31.7.6.3 "out" typemap +32.7.6.3 "out" typemap Converts return value of a C function @@ -5776,7 +5776,7 @@ version of the C datatype matched by the typemap. - 31.7.6.4 "arginit" typemap +32.7.6.4 "arginit" typemap The "arginit" typemap is used to set the initial value of a @@ -5801,7 +5801,7 @@ applications. For example: -31.7.6.5 "default" typemap +32.7.6.5 "default" typemap The "default" typemap is used to turn an argument into a @@ -5843,7 +5843,7 @@ default argument wrapping. -31.7.6.6 "check" typemap +32.7.6.6 "check" typemap The "check" typemap is used to supply value checking code @@ -5867,7 +5867,7 @@ arguments have been converted. For example: -31.7.6.7 "argout" typemap +32.7.6.7 "argout" typemap The "argout" typemap is used to return values from arguments. @@ -6025,7 +6025,7 @@ some function like SWIG_Ruby_AppendOutput. -31.7.6.8 "freearg" typemap +32.7.6.8 "freearg" typemap The "freearg" typemap is used to cleanup argument data. It is @@ -6061,7 +6061,7 @@ abort prematurely. -31.7.6.9 "newfree" typemap +32.7.6.9 "newfree" typemap The "newfree" typemap is used in conjunction with the %newobject @@ -6092,7 +6092,7 @@ ownership and %newobject for further details. -31.7.6.10 "memberin" typemap +32.7.6.10 "memberin" typemap The "memberin" typemap is used to copy data from an @@ -6125,7 +6125,7 @@ other objects. -31.7.6.11 "varin" typemap +32.7.6.11 "varin" typemap The "varin" typemap is used to convert objects in the target @@ -6136,7 +6136,7 @@ This is implementation specific. -31.7.6.12 "varout" typemap +32.7.6.12 "varout" typemap The "varout" typemap is used to convert a C/C++ object to an @@ -6147,7 +6147,7 @@ This is implementation specific. -31.7.6.13 "throws" typemap +32.7.6.13 "throws" typemap The "throws" typemap is only used when SWIG parses a C++ @@ -6206,7 +6206,7 @@ handling with %exception section. -31.7.6.14 directorin typemap +32.7.6.14 directorin typemap Converts C++ objects in director @@ -6460,7 +6460,7 @@ referring to the class itself. - 31.7.6.15 directorout typemap +32.7.6.15 directorout typemap Converts Ruby objects in director @@ -6720,7 +6720,7 @@ exception. - 31.7.6.16 directorargout typemap +32.7.6.16 directorargout typemap Output argument processing in director @@ -6960,7 +6960,7 @@ referring to the instance of the class itself - 31.7.6.17 ret typemap +32.7.6.17 ret typemap Cleanup of function return values @@ -6970,7 +6970,7 @@ referring to the instance of the class itself - 31.7.6.18 globalin typemap +32.7.6.18 globalin typemap Setting of C global variables @@ -6980,7 +6980,7 @@ referring to the instance of the class itself - 31.7.7 Typemap variables +32.7.7 Typemap variables @@ -7090,7 +7090,7 @@ being created.

-31.7.8 Useful Functions +32.7.8 Useful Functions When you write a typemap, you usually have to work directly @@ -7114,7 +7114,7 @@ across multiple languages. -31.7.8.1 C Datatypes to Ruby Objects +32.7.8.1 C Datatypes to Ruby Objects @@ -7170,7 +7170,7 @@ SWIG_From_float(float) -31.7.8.2 Ruby Objects to C Datatypes +32.7.8.2 Ruby Objects to C Datatypes Here, while the Ruby versions return the value directly, the SWIG @@ -7259,7 +7259,7 @@ Ruby_Format_TypeError( "$1_name", "$1_type","$symname", $argnum, $input - 31.7.8.3 Macros for VALUE +32.7.8.3 Macros for VALUE RSTRING_LEN(str) @@ -7322,7 +7322,7 @@ Ruby_Format_TypeError( "$1_name", "$1_type","$symname", $argnum, $input -31.7.8.4 Exceptions +32.7.8.4 Exceptions void rb_raise(VALUE exception, const char *fmt, @@ -7489,7 +7489,7 @@ arguments are interpreted as with printf(). -31.7.8.5 Iterators +32.7.8.5 Iterators void rb_iter_break() @@ -7591,7 +7591,7 @@ VALUE), VALUE value) -31.7.9 Typemap Examples +32.7.9 Typemap Examples This section includes a few examples of typemaps. For more @@ -7602,7 +7602,7 @@ directory. -31.7.10 Converting a Ruby array to a char ** +32.7.10 Converting a Ruby array to a char ** A common problem in many C programs is the processing of @@ -7657,7 +7657,7 @@ after the execution of the C function. -31.7.11 Collecting arguments in a hash +32.7.11 Collecting arguments in a hash Ruby's solution to the "keyword arguments" capability of some @@ -7936,7 +7936,7 @@ directory of the SWIG distribution. -31.7.12 Pointer handling +32.7.12 Pointer handling Occasionally, it might be necessary to convert pointer values @@ -8035,7 +8035,7 @@ For example: -31.7.12.1 Ruby Datatype Wrapping +32.7.12.1 Ruby Datatype Wrapping VALUE Data_Wrap_Struct(VALUE class, void @@ -8086,7 +8086,7 @@ and assigns that pointer to ptr.

17 SWIG and COM

17.1 Overview

17.2 Preliminaries

17.2.1 Running SWIG

17.2.2 Additional Commandline Options

17.2.3 Compiling a dynamic module

17.2.4 Using your module

17.3 A tour of basic C/C++ wrapping

17.3.1 Global functions

17.3.2 Global variables

17.3.3 Constants

17.3.4 Enumerations

17.3.5 Pointers

17.3.6 Structures

17.3.7 C++ classes

17.3.8 C++ inheritance

17.3.9 Pointers, references, arrays and pass by value

17.3.9.1 Null pointers

17.3.10 C++ overloaded functions

17.3.11 C++ default arguments

17.3.12 C++ namespaces

17.3.13 Constructors

17.3.14 C++ templates

17.3.15 C++ Smart Pointers

17.4 Further details on COM wrapping

17.4.1 Classes and interfaces

17.4.2 Module class and class objects

17.4.3 GUID handling

17.4.4 Class factories and aggregation

17.4.5 IDispatch and HRESULT as return value

17.4.6 ISWIGWrappedObject interface

17.4.7 Memory management

17.4.8 Exceptions

17.5 Customization features

17.5.1 Typemaps

17.5.2 Exception handling

17 SWIG and C#

18 SWIG and C#

17.1 Introduction

18.1 Introduction

17.2 Differences to the Java module

18.2 Differences to the Java module

17.3 C# Exceptions

18.3 C# Exceptions

17.3.1 C# exception example using "check" typemap

18.3.1 C# exception example using "check" typemap

17.3.2 C# exception example using %exception

18.3.2 C# exception example using %exception