What Goes In... (IInputChannel)

Last week I introduced the different kinds of channel shapes that are available with WCF.  This week I'm going to take a look at the interfaces for working with those channel shapes in code.  Today and tomorrow are going to be the one-way channel shape interfaces, IInputChannel and IOutputChannel.  You get the two-way duplex channel shape entirely for free.  A duplex channel is just the combination of an input and output channel with no additional methods.  The two-way request-reply channel shape will take up another few days.

Here's the one-way channel shape illustration again from the channel shape article.  Today, we'll look at the reader side, which is represented by IInputChannel.

Let's jump right in to look at the interface.  As a reminder, we've already had some exposure to IChannel, ICommunicationObject, and the Message class if you need a reference.

 public interface IInputChannel : IChannel, ICommunicationObject, IDisposable
{
   EndpointAddress LocalAddress { get; }

   IAsyncResult BeginReceive(AsyncCallback callback, object state);
   IAsyncResult BeginReceive(TimeSpan timeout, AsyncCallback callback, object state);
   IAsyncResult BeginTryReceive(TimeSpan timeout, AsyncCallback callback, object state);
   IAsyncResult BeginWaitForMessage(TimeSpan timeout, AsyncCallback callback, object state);
   Message EndReceive(IAsyncResult result);
   bool EndTryReceive(IAsyncResult result, out Message message);
   bool EndWaitForMessage(IAsyncResult result);
   Message Receive();
   Message Receive(TimeSpan timeout);
   bool TryReceive(TimeSpan timeout, out Message message);
   bool WaitForMessage(TimeSpan timeout);
}

Aside from the LocalAddress property, which tells us the location this channel corresponds to, the methods are all variations on the idea of receiving a message.  For the most part, you'll be using the Receive(timeout) variety, in either its asynchronous or synchronous flavor.  Go back to the overview of working with timeouts if you're wondering why you should be specifying a timeout.

The other two varieties are useful in specialized situations.  Use TryReceive when you think it's likely that a message will not arrive within the allotted time.  TryReceive will give you back a boolean return value that tells you whether a message arrived and gives you the message itself back as an out parameter.  Use WaitForMessage when you want to prime the channel for another reader to pull the message out with no waiting.  Like TryReceive, WaitForMessage lets you know whether a message arrived using the return value.  Both TryReceive and WaitForMessage come in synchronous and asynchronous flavors as well.

Next time: ...Can Also Come Out (IOutputChannel)