README for Emdros SWIG-C#
Created: 2/12-2003 (February 12, 2003)
Last update: 9/27-2007

Introduction
============

This document explains how to use the SWIG C# bindings for Emdros.


General usage
=============

There are two ways to use the code:

1) Link your application with EmdrosDotNet.dll using the 

   /r:EmdrosDotNet.dll

   switch to your C# compiler,

   Then simply use 

   using Emdros;

   in your C# code.


   - or -

2) Compile your program with all the C# source files generated by
   SWIG.  You can find them in the ZIP file

   CSharpSources.zip

   which you can find here:

   SWIG/csharp/ -- in the sources
   doc\csharp\ -- in the Win32 binaries
   $(DMG-IMAGE)/development/SWIG/csharp -- in the Mac DMG   


Test program
============

There is a test program, TestEmdros.cs, which shows how to use the
csemdros module.  It is available in the source directory SWIG/csharp
after compilation, or in the documentation directory of the
emdros-VERSION package if installed via RPM, e.g.,
/usr/share/doc/emdros-1.2.0.pre236/.


To run the test:

1) ... TODO: How to set DYLD_LIBRARY_PATH on Mac.
   ... TODO: Refer to 
       - http://www.mono-project.com/Interop_with_Native_Libraries
       - http://www.mono-project.com/Config_DllMap

2) $(DOTNETCOMPILER) /target:exe /r:EmdrosDotNet.dll TestEmdros.cs

   e.g.

   mcs -target:exe -r:EmdrosDotNet.dll TestEmdros.cs

4) $(DOTNOTRUNNER) TestEmdros.exe

   e.g.

   mono TestEmdros.exe




Installation
============

Win32
-----

You need to install:

- csemdros.dll -- This is the native code that has been SWIG-wrapped
- EmdrosDotNet.dll -- This is the import library containing the C# part


Linux/Unix/Mac OS X
-------------------

- libcsemdros.{so,dylib} -- This is the native code that has been SWIG-wrapped
- EmdrosDotNet.dll -- This is the import library containing the C# part



Building
========

Linux
-----

When building from source, you will need to pass the following option
to the configure script in the top-level directory:

--with-swig-language-csharp

Additionally, you will a C# compiler and a C# runtime.

The configure script will complain if it can't find these.


Win32
-----

In win32\config.mak:

1) uncomment the line that says "WITH_SWIG_CSHARP=yes",

Then just proceed as described in win32\README.txt.



Using
=====

The online Programmer's Reference Guide shows most of the API that is
accessible, and all of the API that you are likely to need.  Follow
these guidelines to convert between the C++ method signatures and
their C# counterparts:

- The namespace Emdros should be used.

  using Emdros;

- C++ classes are wrapped with the exact same name, e.g., C++
  "EmdrosEnv" is called the same in C#.

- pointers to objects are generally converted to their C#
  equivalents.  Just use C# references, and assume that garbage
  collection works.

- C++ enums are wraped as C# enums.

  For example:

  eCharsets.kCSUTF8

- const std::string& is a C# String
- std::string is a C# String
- std::string& needs the ref keyword (explained below)

- bool is a C# boolean
- bool& needs the ref keyword (explained below)

- int/long/monad_m/id_d_t are C# int's
- C++ references to these need the C# ref keyword (explained below)

- All public functions, constants, and #defines are gathered together
  in the Emdros.csemdros class.  In particular:

  - std::cout (stdout) is wrapped as Emdros.csemdros.KSTDOUT.
  - std::cerr (stderr) is wrapped as Emdros.csemdros.KSTDERR.


bool&, long&, std::string&
--------------------------

These are output parameters, and need the ref keyword when passing the
variable or member to Emdros.

bool bResult = false;
env.executeString(query,	
                  ref bResult, // Compiler result *** NOTE ref ***
   	          true,  // Print result
  	          true);


Exceptions
----------

All C++ exceptions are caught and transformed to an ApplicationException.

ApplicationException.what() gives the expected result.

Furthermore, all Emdros exceptions are passed on as
ApplicationException objects, with the what() method returning the
result of what() on the Emdros exception, and the name of the Emdros
exception being added to the front of the message.

For example, if EmdrosException e is caught, it is thrown as a C#
ApplicationException with what() returning "EmdrosException: " +
e.what().


out methods
-----------

The "out" methods on EmdrosEnv and EMdFOutput have been renamed to
"csout".
