I've create a wrapper class in Visual Studio .NET 2003 to handle interaction with the iaxClient Library as compiled to iaxclient.dll.  

The goal of this project was to create something which was complete enough to be used by someone with mid level skills in any of the vs.net application programming languages without them needing to deal with any of the platform invoke nastiness themselves.  

Since I had to learn P/Invoke to make this, I can tell you honestly that it is very powerful and very terrible at the same time.

Note: This page is essentially the README.TXT file with better example pictures and downloads at the end which include the source and the compiled library.

NCT IAXClient Library Wrapper
Copyright 2006, Northern Collaborative Technologies

Released under the LGPL as described in LICENSE.TXT

README Updated May 26, 2006
Contact: andrewp@thenorth.com

For information about me or my company, see http://www.thenorth.com where you can check out the about page and the leadership page.

BEFORE you write with a request for support or you send a contribution PLEASE read the last section of this document.

IMPORTANT NOTE:  I recommend that you take the output DLL from this project, which is the wrapper and use it as described to build your own clients a distinct projects, rather than attempting to use this project as the basis for your work.

Contents of this file:

1. What is this wrapper good for?
2. How to build this wrapper
3. How to install the compiled wrapper
4. The two namespaces in this library
5. Using Native VS.Net Events to control the iaxclient library
6. A simple example making a phone call with this wrapper
7. Questions & Bug Reporting
8. Contributing to this project

NCT_IaxClientWrapper Uses:

1.  You could use the NCT_IaxClientWrapper class to create your client application without ever worrying about the underlying iaxclient.dll other than making sure you actually have it.  The supported methods and properties should be enough for most general phone client applications.

2.  You could use the NCT_IaxClientWrapper class to initialize the iaxclient.dll and dispatch the events for you, and make all the rest of your calls to the iaxclient.dll directly.  This give you access to the full range of features in the library, but takes care of the one really painful part of calling it which is the event handling.

3.  You could use only the unsupported direct calls to the dll and ignore the entire supported class.  That would buy you very little other than the enumerations and so on.  If you're good enough at programming to do this, I'm not sure why you need this library -- but you can if you like.

Building this wrapper

1.  Dependencies -  I created this wrapper class and tested it against the iaxClient Library build 566 (http://sourceforge.net/projects/iaxclient), which so far I've found to be mostly excellent.  I have a patch or two added to mine which I will describe later.  

2.  I've added a popup on the initialization.  I did this prior to releasing the source.  You may remove it or disable it for your own application, however it must remain in any source code you distribute.

3.  Since this compiles to .NET byte code, it doesn't matter which language you're using as long as its part of the .NET family.  I've written this in vb.net -- for no reason other that I felt like it.  C# would do the same thing, but I find switching between C# and Java during the same to be painful.  The byte code in the dll should work for anyone.  

4.  What has been distributed in this package is a Visual Studio .NET 2003 project folder.  You should be able to unpack the folder and open it with Visual Studio .NET 2003, hit build, and be off to the races with your DLL.   I recommend that you take the output DLL and use it as described later in this document rather than trying to make this source the basis for your projects.

How to install this library and add it to your project

1.  Compile the wrapper to a DLL
2.  Create a new vs.net project
3.  Add the wrapper library dll to your new vs.net project folder, or at least put it somewhere you won't loose it.
3.  In Visual Studio .NET 2003, use menu commands "Project - Add Reference", then use the browse button to find and add a reference to the library dll for your project.
4.  On any module, class, or whatever that is going to use import one or both of the new namespaces.  For example:  

Imports NCT.IaxClientWrapper.supported
Imports NCT.IaxClientWrapper.unsupported

Once you've done that, you have access to the classes and methods, including type ahead help

The Two Namespaces - Supported & Unsupported

There are two namespaces.  The first, "supported" one contains the methods and properties as managed code.  Everything you need if you don't want to touch the dll directly is in the supported namespace.

Imports NCT.IaxClientWrapper.supported
Imports NCT.IaxClientWrapper.unsupported

The "unsupported" namespace contains function prototypes which wrap the iaxclient.dll directly.  The reason they are “unsupported” is simply that I haven’t tested them enough to be confident they are right, and I haven’t wrapped them with vs.net code so in some cases they may be calling for pointers and things.

You can call unsupported functions yourself, but you're on your own.  You're calling out to unmanaged code so sometimes you'll need pointers to unmanaged memory.  You can crash your application, leak memory, and cause all kinds of pain with these.  My advice is to ignore them and used them the way I've wrapped them.  It’s your funeral though.  Enjoy.

Using Native VS.NET events with the IAXClient with NCT_IaxClientWrapper

One of the hardest things to do in wrapping the iaxclient.dll calls is handling the event model from within Visual Studio .Net applications.   That's because the events happen outside of managed memory.  To make life so much easier the NCT_IaxClientWrapper class includes an event called "IAXClientEvent" which gets raised by the NCT_IaxClientWrapper whenever the underlying IAXClient Library raises one.

The way this works, is that once you've called NCT_IaxClientWrapper.Initialize(), all the events thrown by the IAX Client Library itself are caught by the NCT_IaxClientWrapper class.  Once caught, the data they contain is copied into managed memory and passed as an event arguement to a native vs.net event.  You can create your own method and define a native vs.net event handler to handle the NCT_IaxClientWrapper.IAXClientEvent and do whatever you like.  The NCT_IaxClientWrapper will also be processing that event data, and updating its own properties as needed.

The best news about these events is, if you don't want to, you don't have to deal with them.  The methods and properties on the NCT_IaxClientWrapper class itself will take care of what needs to be taken care of.  If you need to check on the status of a call, for example, you can look at the callinfo property which contains all the data for each call and is updated as events come up with changes.

Most people will want to receive events and do things with them.   To do that, you'll want to define your own event handler like this:

Sub handleIaxClientEvent(ByVal sender As Object, ByVal e As NctIaxClientWrapper.NctIaxcEventArgsClass) Handles myCallHandler.IAXClientEvent Select Case e.eventType ' first, figure out what kind of event it is, and set the object type Case NctIaxClientWrapper.EventTypes.IAXC_EVENT_REGISTRATION e.iaxcEvent = CType(e.iaxcEvent, NctIaxClientWrapper.iaxc_ev_registration) Case NctIaxClientWrapper.EventTypes.IAXC_EVENT_STATE e.iaxcEvent = CType(e.iaxcEvent, NctIaxClientWrapper.iaxc_ev_call_state) Case NctIaxClientWrapper.EventTypes.IAXC_EVENT_LEVELS e.iaxcEvent = CType(e.iaxcEvent, NctIaxClientWrapper.iaxc_ev_levels) Case NctIaxClientWrapper.EventTypes.IAXC_EVENT_NETSTAT e.iaxcEvent = CType(e.iaxcEvent, NctIaxClientWrapper.iaxc_ev_netstats) Case NctIaxClientWrapper.EventTypes.IAXC_EVENT_TEXT e.iaxcEvent = CType(e.iaxcEvent, NctIaxClientWrapper.iaxc_ev_text) Case NctIaxClientWrapper.EventTypes.IAXC_EVENT_URL e.iaxcEvent = CType(e.iaxcEvent, NctIaxClientWrapper.iaxc_ev_url) Case NctIaxClientWrapper.EventTypes.IAXC_EVENT_VIDEO e.iaxcEvent = CType(e.iaxcEvent, NctIaxClientWrapper.iaxc_ev_video) End Select ' now do something useful with e.iaxcEvent ' which has at this point been set to the right structure type ' for the event. End Sub

A very small, simple, example of using NCT_IaxClientWrapper to make a call

This is the simplest example I can imagine creating, almost a 'hello world' kind of thing.  Of course, you'll want to add a lot more.  You'll want to have text fields for the phone number, a dial pad, hangup buttons, and other cool stuff.  This example is, however, all you need to make a call and start talking.

1.  Create a VS.net Windows Application project.
2.  Add a reference to the NCT_IaxClientWrapper library (<a href='#Install'>see above</a>)
3.  Add a button to the form.
4.  Add the following code to your class -- notice that the NCT_IaxClientWrapper is declared globally, so it doesn't go away when the button click event is over.



Questions & Bug Reporting

This is an open source project.  If you write a question to me, I’ll try to answer within a day or two.  Sometimes I’m very quick, sometimes I’m not.  You have the best chance of getting an answer if your question is specific, concise, and well considered.  Flattery helps, but my ego is fairly large already so don’t try too hard on that one.  I will not likely respond to requests that require me to pour over your source code unless you have a lot of money to spend, in which case I can be bought.  However, keep in mind the immortalized words of Han Solo …. “I don’t know, your highness, I can imagine an awful lot.”

I do monitor the ‘iaxclient-devel’ mailing list.  You can subscribe here: https://lists.sourceforge.net/lists/listinfo/iaxclient-devel

Contributing to this project

If you’d like to contribute to the project, you should follow the coding style as it is in the project now.  If you don’t like that style, you should pick another project.  The fact that it’s written in vb.Net does not mean I will tolerate undeclared variables, weird branching, or other poor coding practices.

For now, discuss contributions on the iaxclient-devel mailing list.  You can send me code for inclusion.  I don’t have a formal process for inclusion at this time.  If it becomes an issue, I’ll make one up.

One thing that needs doing is the rest of function calls currently in the “Unsupported” namespace need to be having supported methods created and tested for them.   We will still leave all the methods available in the unsupported name space so they can be called directly, but I’d like to see them all available as supported native calls as well.

Finally, the downloads you wanted

Remember... If you try this I'd like to hear what you think. I want to know how many people try it and any feedback they have. Send email to andrewp@thenorth.com.

---

HERE IS THE SOURCE CODE

---

HERE IS THE COMPILED OBJECT CODE - READY TO USE

Of course, use all of these at your own risk. If you break something with them, its your fault.

Here's the NCT_IaxClientWrapper Library	This is a patch for build 566 of the IaxClient Library that adds a new audio type during initialization. The new type tells the iaxclient library to leave your port mixer settings alone rather than automatically resetting to the Microphone. You must apply this diff and recompile (or use my dll) if you want to initalize using: AUDIO_INTERNAL_PA_PRESETMIXER	I'm not sure how this works with respect to the license so I may have to take it down. For now, here's a copy of a precompiled IaxClient.dll libary. Its built 566 with my own patch added.

---