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. Please review LICENSE.TXT * BEFORE you write with a request for support or you send a contribution PLEASE read the last section of this document. 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. 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, 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 (see above) 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. ------------------------------------------------------------------------------------------------------------------ Imports NCT.IaxClientWrapper.supported Imports NCT.IaxClientWrapper.Unsupported Public Class Form1 Inherits System.Windows.Forms.Form ‘ … windows forms required stuff *************** Dim iaxc As NCT_IaxClientWrapper Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) _ Handles Button1.Click iaxc = New NCT_IaxClientWrapper iaxc.initialize(NCT_IaxClientWrapper.AudioTypes.AUDIO_INTERNAL_PA, 1) iaxc.placeCall("user:password@asterisk.localdomain.com/extension") End Sub End class ------------------------------------------------------------------------------------------------------------------ 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.