I have updated ITAPI3 to fix a couple of reported bugs -- the TE_FILETERMINAL event wasn't always being raised and the TCall.GenerateCustomTone didn't work properly.  Both of these issues are fixed in the latest drop.  Enjoy!

Great news!  Rotor is an incredible tool for learning about how and why the CLR works the way it does.

For more info -- http://blogs.msdn.com/jasonz/archive/2006/03/23/559581.aspx

A few months ago, I ran into a really weird bug with the System.Net.NetworkInformation.Ping class.  I was using it to monitor the network connectivity to a server and as my program ran, it appeared to leak handles.  I was calling Dispose (as I should) but it was still appeared to be leaking handles when called over and over. 

Here's the basic code I was running (simplified for this example):

Ping icmp = new Ping();
icmp.PingCompleted += delegate(object sender, PingCompletedEventArgs e)
   {
      PingReply reply = e.Reply;
      Console.WriteLine("Address: {0} - {1}", url, reply.RoundtripTime);
      icmp.Dispose();  // Get rid of resources
   };

icmp.SendAsync(url, 100);

// Continue doing work

The code looked ok to me, so I started looking a little deeper.  In reality, I found that if I waited long enough, the GC process was cleaning up the unmanaged handles using the SafeHandle class, but I was confused because Dispose should have done that for me. When I looked at the ping class using Reflector, the problem became obvious and it's a warning to anyone building components that need to free up non-memory related resources.

In order to integrate with the Windows Forms and ASP.NET designer, the Ping component extends System.ComponentModel.Component.  This provides the design-time integration with Visual Studio .NET and it also provides some basic plumbing that used to cleanup the component - specifically it implements IDisposable for you and provides a nice virtual Dispose method which you are supposed to override and free your resources.  The code follows Microsoft's IDisposable pattern exactly - providing the IDisposable.Dispose method which delegates to an internal virtual void Dispose(bool isDisposing) method which is the method you should override.

The Ping component uses an internal socket and the ICMP W2K support under the covers to do its work and this socket needs to be cleaned up.  So, the author implemented IDisposable to indicate this -

public class Ping : Component, IDisposable
{
   private void InternalDispose()
   {
      if (!disposed)
      {
         // Cleanup socket and/or ICMP handle resources..
      }
   }

   IDisposable.Dispose()
   {
      this.InternalDispose();
   }
}

Note how the author used an explicit interface implementation for the Dispose method.  This means we will need to cast the object to an IDisposable interface in order to call the method (something I'm not doing above).  In fact, it won't even show up as a callable method inside VS.NET.  There is nothing wrong with this implementation (except of course it doesn't follow Microsoft's guidelines) until you add in the derivation from Component.  If we add it's implementation into the mix, and expand it out I get something like:

One issue that's always a struggle with building reusable components is managing asynchronous operations.  The problem is that depending on the type of application that is going to use the component, the thread used for callbacks and events may or may not be important.  For example, with Console based applications, callbacks on different threads might be ok - at least as long as the application itself ensures thread safety.  But, with a Windows Forms application, threading is critical - you are not allowed to touch UI controls from any thread other than the main one and so we end up with the Control.BeginInvoke logic in each of our callbacks which sucks.

Enter the Synchronization Context - a new feature of .NET 2.0.  Here's how it works:

You derive your component from System.ComponentModel.Component.Component and provide your typical asynchronous function -- in this example, we will build a PiCalculator:

public class PiCalculator : Component
{
   public PiCalculator();
   public object CalculatePi(int digits, object stateData);
   public void CancelAsync(object asyncTask);
}

Here, what we've done is create a new component with a default constructor and a method called CalculatePi which takes the number of digits, an optional piece of state data and returns an object.  With this component, I'd like to have multiple outstanding asynchronous operations and so I need some way to track each one to identify it when it completes, and also to cancel it if it runs too long.

Microsoft's general pattern for this is to use the stateData parameter and have the application pass in some unique value to identify the request. 

This is an ok way to do it, but it puts several restrictions on our implementation:

1) The state data must be supplied
2) The state data must be unique for each operation

In addition, there's the possibility of a race condition if I re-use the state data after canceling an operation.  So, to avoid all of these issues, I have the component return the task identifier as part of the request - this is the object return value coming back from CalculatePi.  I can then use that object to identify the results, and I can pass it into the component's CancelAsync method to cancel a pending request.

So, how do I get my results?  Through a delegate callback of course!  I need to create a delegate signature that uses it.  The general EventHandler callback signature is: void Method(object sender, EventArgs e) so, we'll use a derivative of this as our delegate:

public delegate void PiCalculationCompletedEventHandler(object sender, PiCalculationEventArgs e);

Then we'll create the class which will be used to report the results.  The class is pretty simple - just a data holder really:

public class PiCalculationEventArgs : EventArgs
{
   private int _digits;
   private string _value;
   private bool _canceled;
   private object _stateData;
   private object _taskId;

   public object TaskId
   {
      get { return _taskId; }
   }

   public object State
   {
      get { return _stateData; }
   }

   public bool Canceled
   {
      get { return _canceled; }
   }

   public int Digits
   {
      get { return _digits; }
   }

   public string Result
   {
      get { return _value; }
   }

   internal PiCalculationEventArgs(object taskId, int digits, string value, object stateData, bool canceled)
   {
      _digits = digits;
      _value = value;
      _canceled = canceled;
      _stateData = stateData;
      _taskId = taskId;
   }
}

Now we can implement out component.  First, we'll add a Completed event:

public event PiCalculationCompletedEventHandler CalculationComplete;

This will be used by the application to hook into the results of our component's calculation.  The next part is the key to all of this - AsyncOperation.  The AsyncOperation class is new to 2.0 and provides the facility to perform callbacks on the appropriate thread.  Essentially, it acts as a callback mediator - detecting the type of thread it was created on and then providing the appropriate marshaling code for it's internal delegate.  You utilize the callback through a new delegate type -- SendOrPostCallback.  We tie our callback to this delegate type and it will marshal us to the correct threading model.  We can then execute our own internal CalculationComplete event.  Here's the basic skeleton:  First, we will create an internal contained class which will be used to track the request.  This will actually be the object type we return from the CalculatePi method:

class AsyncStateData
{
   public AsyncOperation asyncOperation;
   public volatile bool canceled = false;
   public volatile bool running = true;

   public AsyncStateData(object stateData) 
   { 
      asyncOperation = AsyncOperationManager.CreateOperation(stateData); 
   }
}

Notice the call to AsyncOperationManager.CreateOperation?  This is where we create our AsyncOperation class and this factory creator is the context detector.  We will have an AsyncOperation for each event we intend to fire back into the client - in our case one for each Pi calculation.  But, I could also create a single instance for the client as well - this is actually what is done in the ITapi3 component to allow it to be integrated onto a Windows Form even though events are being received on a background thread.  The Tapi events are always fired on the appropriate thread - the background one for non-WinForms apps and the UI thread for WinForms apps.

Next, we will create our internal callback - this is the callback that will actually be fired internally and then call the real application event, so we'll hook that up with an anonymous delegate in the constructor of our component:

private SendOrPostCallback completionMethodDelegate;

public PiCalculator()
{
   completionMethodDelegate = delegate(object evt)
   {
      // Called on the synchronization thread.
      if (CalculationComplete != null)
         CalculationComplete(this, (PiCalculationEventArgs)evt);
   };
}

Now, let's implement our CalculatePi method - it's pretty simple, we'll use an asynch delegate to our internal calculator, invoke it and return the AsyncStateData structure we create to identify each task submitted to the component.  Then the calculation will be performed on a thread pool thread and we'll callback to the client when it is finished.

public object CalculatePi(int digits, object stateData)
{
   PiDelegate piDel = InternalCalculatePi;
   AsyncStateData asyncData = new AsyncStateData(stateData);
   piDel.BeginInvoke(digits, asyncData, delegate(IAsyncResult ar) { piDel.EndInvoke(ar); }, null);
   return asyncData;
}

CancelAsync is pretty simple too -- it will simply set the Canceled flag of the request:

public void CancelAsync(object asyncTask)
{
   AsyncStateData asyncData = asyncTask as AsyncStateData;
   if (asyncData != null && asyncData.running == true)
      asyncData.canceled = true;
}

Now, we need to implement our PiCalculator.  We're going to cheese out here and just "pretend" to calculate Pi since that wasn't really the point of this component   We'll define a delegate to use for the asynch execution and then implement our function:

private delegate void PiDelegate(int digits, AsyncStateData asyncData);
private void InternalCalculatePi(int digits, AsyncStateData asyncData)
{
   string PI_DIGITS = "3.141592637309238932482438234724782347234";
   if (digits > PI_DIGITS.Length - 2)
      digits = PI_DIGITS.Length - 2;

   // This would be a real calculator here..
   int completedDigits = 0;
   for (; !asyncData.canceled && completedDigits < digits; completedDigits++)
   {
      Thread.Sleep(1000);
   }

   asyncData.running = false;
   string data = PI_DIGITS.Substring(0, completedDigits + 2);
   asyncData.asyncOperation.PostOperationCompleted(
      completionMethodDelegate,
      new PiCalculationEventArgs(asyncData, digits, data, asyncData.asyncOperation.UserSuppliedState, asyncData.canceled));
}

The key to the callback is the invocation of the PostOperationCompleted method from the AsyncOperation instance we created.  It is what calls our handler which will in turn call the client.  Once PostOperationCompleted is called, no further work may be done with the AsyncOperation.  So, it's not appropriate for progress reporting - instead you can use PostOperateration for that which allows for multiple calls. 

Now, when using this component, we can simply call it as expected:

static void Main(string[] args)
{
   ArrayList taskIds = new ArrayList();
   
   PiCalculator piCalc = new PiCalculator();
   piCalc.CalculationComplete += delegate(object sender, PiCalculationEventArgs e)
   {
      Console.WriteLine("[{0}] {1} = {2}, Canceled = {3}", 
         Thread.CurrentThread.ManagedThreadId, e.Digits, e.Result, e.Canceled);
   }         

   foreach (string s in args)
   {
      taskIds.Add(piCalc.CalculatePi(Convert.ToInt32(s), s));
   }

   Console.WriteLine("Waiting for results .. press ENTER to cancel.");
   Console.ReadLine();

   foreach (object task in taskIds)
   {
      piCalc.CancelAsync(task);
   }

   Console.WriteLine("Press ENTER to terminate");
   Console.ReadLine();
}

Here's the output:

Waiting for results .. press ENTER to cancel.
[3] 10 = 3.1415926373, Canceled = False
[4] 11 = 3.14159263730, Canceled = False
[5] 14 = 3.14159263730923, Canceled = False
[5] 15 = 3.141592637309238, Canceled = False
[5] 17 = 3.14159263730923893, Canceled = False

Press ENTER to terminate
[5] 20 = 3.1415926373092389324, Canceled = True

Not real exciting right?  Notice the thread id in the [brackets] is different for some of the callbacks.  This indicates we are getting called back on different threads - certainly not the main thread which is waiting for console input.  The cool part of this component is that I can use it exactly the same way in a Windows Forms application!  So, I don't have to know that the callback is on a different thread!  I don't have to worry about doing a BeginInvoke or Invoke to get back to the UI thread.  So, here's an example WinForm application:

public partial class CalcPiTestForm : Form
{
   ArrayList _pendingTasks = new ArrayList();

   public CalcPiTestForm()
   {
      InitializeComponent();
   }

   private void CalcPiTestForm_Load(object sender, EventArgs e)
   {
      piCalculator1.CalculationComplete += new UserMath.PiCalculationCompletedEventHandler(piCalculator1_CalculationComplete);
   }

   void piCalculator1_CalculationComplete(object sender, UserMath.PiCalculationEventArgs e)
   {
      lock(_pendingTasks)
      {
         _pendingTasks.Remove(e.TaskId);
      }

      // No need to do BeginInvoke here!!
      listBox1.Items.Add(string.Format("[{0}] {1} = {2}, Canceled = {3}",
         System.Threading.Thread.CurrentThread.ManagedThreadId, e.Digits, e.Result, e.Canceled));
   }

   private void btnCalculate_Click(object sender, EventArgs e)
   {
      if (maskedTextBox1.Text.Length > 0)
      {
         lock(_pendingTasks)
            _pendingTasks.Add(piCalculator1.CalculatePi(Convert.ToInt32(maskedTextBox1.Text)));
      }
   }

   private void btnCancel_Click(object sender, EventArgs e)
   {
      lock(_pendingTasks)
      {
         foreach (object task in _pendingTasks)
            piCalculator1.CancelAsync(task);
      }
   }
}

Notice the output here -- we haven't done anything special with the component's callbacks, but now the callback is always on thread [1].  This is the magic of AsyncOperation and synchronization contexts.  Now go out there and write some thread-aware components!  If you'd like this entire sample, here is the project: http://www.julmar.com/samples/asyncop.zip

I love anonymous delegates - I think they are extremely useful and allow me to solve some problems in very elegant ways.  However, once you really get into them, you start to see the dark side of anonymous delegates and that is unregistration.

Here's the basic problem: when binding an instance delegate to an event to handle some activity, the delegate will cache off the instance reference - thereby keeping the reference alive.  So for example, if I had a form which wanted to process some activity from an object:

class Publisher
{
   public event EventHandler OnEvent;
   ...
}

class MainForm : Form
{
   Publisher _pub = new Publisher();
   void ActivateChildForm() 
   {
      ChildForm f = new ChildForm(_pub);
      f.Show();
   }
}

class ChildForm : Form
{
   public ChildForm(Publisher pub) 
   {
      pub.OnEvent += ProcessEvent;
   }
   void ProcessEvent(object sender, EventArgs e)
   {
      listBox1.Items.Add("Event was fired!");      
   }
}

When the ChildForm instance is closed, the form won't be collected because the Publisher (_pub) is holding a reference to it.  This is easily fixed by adding some code into the FormClosing event:

class ChildForm : Form
{
   Publisher _pub;

   public ChildForm(Publisher pub)
   {
      _pub = pub;
      _pub.OnEvent += ProcessEvent;
   }

   void FormClosing(object sender, FormClosingEventArgs e)
   {
      _pub.OnEvent -= ProcessEvent; 
   }
}

I've posted a new version of ATAPI.NET which supports consultation transfers and a simple phone sample that shows off how to use the features.  In addtiion, this version of ATAPI.NET has a couple of bug fixes that were rolled in from a production project over the past couple of weeks to fix some weird startup/shutdown issues when a LINE_REINIT is reported by TAPI.  You can get the new code from our samples link -- http://www.julmar.com/samples.htm

Forwarding lines with ATAPI.NET is simple and easy (assuming, of course, that the underlying TSP supports it).

The first step is knowing whether a given line device even supports forwarding.  This is trivial:

TapiManager mgr = new TapiManager("ForwardingTest");

foreach (TapiLine line in mgr.Lines)
{
   if (line.Capabilities.SupportsForwarding)
   {
      Console.WriteLine("Line {0} supports forwarding!", line.Name);
   }
}

Once we've identified a specific line, we can look at each address and get more information such as the types of forwarding supported.  For example, we might be able to forward to different numbers based on specific conditions such as whether the call goes unanswered vs. whether the address is in use and returning a busy signal.  We might also be able to forward specific inbound callers (very useful to get rid of your bosses calls).  We can get this information from the Capabilities of the TapiAddress object:

foreach (TapiAddress addr in line.Addresses)
{
   Console.WriteLine("Forwarding modes supported on {0} are {1}", addr.Address, addr.Capabilities.SupportedForwardingModes);
}

We can also retrieve any existing forwarding information through the Status of the TapiAddress:

foreach (ForwardInfo fwd in addr.Status.ForwardingInformatioin)
   Console.WriteLine("\t{0} to {1}:{2}", fwd.ForwardMode, fwd.DestinationAddressType, fwd.DestinationAddress);

I got hit with this problem from two separate clients last week - a .NET 1.1 application ported to .NET 2.0 is now terminating abruptly for no apparent reason.  Well, of course there's a reason - and it's that both applications had "hidden" exceptions being thrown in some background thread that weren't being caught.  Under .NET 1.1, the CLR would print any exceptions that occurred on threadpool threads to the console and then return the thread to the pool.  In addition, the CLR would silently eat any exception thrown on the finalizer thread (again printing the stack trace to the console).  Under .NET 2.0, the behavior has changed and it will cause the AppDomain to be unloaded (yikes!).  So, for example:

class BadClass
{
  ~BadClass()
  {
    throw new Exception("I'm Bad"); 
  }
}

The above code would run forever under CLR 1.1, but will terminate immediately when run under CLR 2.0 with an unhandled exception. 

Unhandled Exception: System.Exception: I'm bad
   at BadClass.Finalize() in W:\Projects\TestApp\TestApp\Program.cs:line 11

There are a couple of ways to deal with this - the best is to do all your testing and close the holes.  You really shouldn't have unhandled exceptions loose in your program.  But for a really large program, or one where you don't know where the exception is happening, Microsoft has given you a couple of options.  The first one is the <legacyUnhandledExceptionPolicy>  tag which you can put into your app.config file:

<configuration> 
  <runtime> 
    <legacyUnhandledExceptionPolicy enabled="1" /> 
  <runtime>
<configuration>

Bottom line is: be aware of this new, breaking change -- look for places where you might not be handling exceptions properly and implement good audit trail mechanisms to log failures when/if they occur.  This will allow you to find and fix issues before they become production problems as you port your legacy code over to .NET 2.0!

So, a question was asked "How do I determine what's happening in the TAPI3 wrapper"?  The answer is you turn on the internal trace source -- ITapi3 was built with a build in tracing facility to tell you when it had any underlying interface or COM failures and it's easy to activate.  First, add an Application Configuration File to your project.  Open that file and add the following lines:

Matthias Moetje (Tapi MVP) has graciously taken one of the VB6 Platform SDK samples and ported it to the ITapi3 library and allowed me to distribute it in the Tapi3 Wrapper sample set.  It allows you to select an address, place a call on it and then monitor or generate digits.  Great sample - thanks Matthias!

I got an email question today asking about how to write a .WAV file out to an active call using our TAPI3 wrapper.  It's actually pretty easy to do and it follows along with the normal SDK method used in C++.  Here's the relevant code (for the full example, download the http://www.julmar.com/samples/tapi3wrapper.zip and look at the AutoAttendant sample).

First, when a new offering call shows up, get hold of the file playback terminal for it and set it up to play your .WAV files.  We cannot play the files until the call is answered, but this will essentially "queue" it up.