System.Runtime.Remoting.Channels.Tcp.TcpChannel Class

Assembly: System.Runtime.Remoting.dll
Namespace: System.Runtime.Remoting.Channels.Tcp
Summary
Provides an implementation for a sender-receiver channel that uses the TCP protocol to transmit messages.
C# Syntax:
public class TcpChannel : IChannelReceiver, IChannel, IChannelSender
Remarks
The TcpChannel class is a combined channel, which combines the TcpServerChannel and TcpClientChannel for convenience. The TcpChannel uses a binary formatter to serialize all outbound messages to a binary stream and transports the stream to the target URI using the TCP protocol. For inbound messages the process is reversed.

Channels transport messages between applications across remoting boundaries (for example application domains, processes, and machines). These crossings include both inbound and outbound. The current channel listens on an endpoint for inbound messages and sends the outbound messages to the endpoint. TcpChannel converts the messages sent along it to and from the binary format, receiving and sending them using the TCP protocol.

On the client side, messages are handed off to the client channel sink chain after they traverse the client Context chain. The first channel sink is typically an IClientFormatterSink which serializes the message into a stream that is passed down the channel sink chain to the client transport sink. The client transport sink then writes this stream out to the wire.

On the server side, the server transport sink reads requests off of the wire and passes the request stream to the server channel sink chain. The server formatter sink at the end of this chain will deserialize the request into a message. It will then hand this message off to the Remoting infrastructure which will dispatch it to the server Context chain.

IChannel implementations use channel configuration properties to configure the channel at run time. Channel properties can be specified in a configuration file, or programmatically, inside of an IDictionary. In a configuration file all values are represented by strings, but when building a property IDictionary programmatically, value types can be specified with their native values or with strings.

The following table shows the channel configuration properties that can be specified for the current channel.



Property Description
name Indicates the name of the channel. This property is used to retrieve a specific channel when calling ChannelServices.GetChannel . If this property is not set, the system defaults to "http". If you want to register more than one HttpChannel , each must have a unique name. Set this property to the String.Empty string ("") if you want to ignore names, but avoid naming collisions. The system will allow any number of channels with the String.Empty name.
priority An integer representing the priority assigned to this channel. Higher numbers indicate a higher chance of being chosen to connect first. The default priority is 1, and negative numbers are allowed.
port An integer specifying the port on which the channel will listen.
supressChannelData true or false . Specifies that the channel will not contribute to the HttpChannel.ChannelData .
useIpAddress true or false . Specifies whether the channel whall use the IP address in the publication URL instead of the computer name.
rejectRemoteRequests true or false . Specifies whether to refuse requests originating from other computers. Specifying true allows only inter-application-domain calls from the local computer.
bindTo An IP address resolving to the current computer that specifies which NIC to bind the current channel to.
machineName A string that specifies the machine name used with the current channel. Overrides the useIpAddress configuration property and the machine name channel data.
See also:
System.Runtime.Remoting.Channels.Tcp Namespace | BinaryFormatter

System.Runtime.Remoting.Channels.Tcp.TcpChannel Member List:

Public Constructors
ctor #1 Overloaded:
.ctor()

Default constructor. This constructor is called by derived class constructors to initialize state in this type.
Initializes a new instance of the TcpChannel class, activating only a client channel, and not a server channel.
ctor #2 Overloaded:
.ctor(int port)

Initializes a new instance of the TcpChannel class, activating a server channel at the specified port.
ctor #3 Overloaded:
.ctor(IDictionary properties, IClientChannelSinkProvider clientSinkProvider, IServerChannelSinkProvider serverSinkProvider)

Initializes a new instance of the TcpChannel class with the provided channel properties, a IClientChannelSinkProvider and a IServerChannelSinkProvider.
Public Properties
ChannelData Read-only

Gets the channel-specific data.
ChannelName Read-only

Gets the name of the current channel.
ChannelPriority Read-only

Returns the priority of the current channel.
Public Methods
CreateMessageSink Returns a channel message sink that delivers messages to the specified URL or channel data object.
Equals
(inherited from System.Object)
See base class member description: System.Object.Equals

Derived from System.Object, the primary base class for all objects.
GetHashCode
(inherited from System.Object)
See base class member description: System.Object.GetHashCode

Derived from System.Object, the primary base class for all objects.
GetType
(inherited from System.Object)
See base class member description: System.Object.GetType

Derived from System.Object, the primary base class for all objects.
GetUrlsForUri Returns an array of all the URLs for an object with the specified URI, hosted on the current TcpChannel.
Parse Extracts the channel URI and the remote well known object URI from the specified URL.
StartListening Instructs the current channel to start listening for requests.
StopListening Instructs the current channel to stop listening for requests.
ToString
(inherited from System.Object)
See base class member description: System.Object.ToString

Derived from System.Object, the primary base class for all objects.
Protected Methods
Finalize
(inherited from System.Object)
See base class member description: System.Object.Finalize

Derived from System.Object, the primary base class for all objects.
MemberwiseClone
(inherited from System.Object)
See base class member description: System.Object.MemberwiseClone

Derived from System.Object, the primary base class for all objects.

Hierarchy:


System.Runtime.Remoting.Channels.Tcp.TcpChannel Member Details

Overloaded ctor #1
Summary
Initializes a new instance of the TcpChannel class, activating only a client channel, and not a server channel.

Default constructor. This constructor is called by derived class constructors to initialize state in this type.
C# Syntax:
public TcpChannel();
Remarks
The default constructor initializes all fields to their default values. If the default constructor is used, the channel functions only as a client channel, and does not listen on any ports.

Return to top


Overloaded ctor #2
Summary
Initializes a new instance of the TcpChannel class, activating a server channel at the specified port.
C# Syntax:
public TcpChannel(
   int port
);
Parameters:

port

The port number at which to activate the TCP server channel.

Example
The following example demonstrates the creation of a TcpChannel that listence on the specified port. For a complete listing of the current example, see the example for the RemotingConfiguration.RegisterWellKnownServiceType method.
        // Registers the server and waits until the user hits enter.
        TcpChannel chan = new TcpChannel(8084);
        ChannelServices.RegisterChannel(chan);

        RemotingConfiguration.RegisterWellKnownServiceType(Type.GetType("HelloServer,server"), 
                                                          "SayHello", 
                                                           WellKnownObjectMode.SingleCall);
        System.Console.WriteLine("Hit <enter> to exit...");
        System.Console.ReadLine();

    

Return to top


Overloaded ctor #3
Summary
Initializes a new instance of the TcpChannel class with the provided channel properties, a IClientChannelSinkProvider and a IServerChannelSinkProvider.
C# Syntax:
public TcpChannel(
   IDictionary properties,
   IClientChannelSinkProvider clientSinkProvider,
   IServerChannelSinkProvider serverSinkProvider
);
Parameters:

properties

An IDictionary of the channel properties which hold the configuration information for the current channel.

clientSinkProvider

The IClientChannelSinkProvider that creates the client channel sinks for the underlying TcpClientChannel through which remoting messages flow through.

serverSinkProvider

The IServerChannelSinkProvider that creates server channel sinks for the underlying TcpServerChannel through which remoting messages flow through.

Exceptions
Exception Type Condition
ArgumentException A provided channel property was improperly formatted.
Remarks
Channel sinks provide a plug-in point that allows access to the underlying messages flowing through the channel as well as the stream used by the transport mechanism to send messages to a remote object. Channel sinks are also responsible for transporting messages between the client and the server. Channel sinks are linked together in a chain, and all channel messages flow through this chain of sinks before the message is finally serialized and transported.

When the IClientChannelSinkProvider.CreateSink method is called on a sink provider, it should create its own channel sink, forward the CreateSink call to the next sink provider in the chain, and ensure that the next sink and the current one are linked together. The provider then returns its sink to the caller. Channel sinks are responsible for forwarding all calls made on them to the next sink in the chain.



Note Channel properties are used to configure the channel at run time. For a list of possible channel properties and an example, see the conceptual topic at MSDN: channelformatterconfigurationproperties.
See also:
MSDN: channelformatterconfigurationproperties

Return to top


Property: ChannelData (read-only)
Summary
Gets the channel-specific data.
C# Syntax:
public object ChannelData {get;}
Implements:
IChannelReceiver.ChannelData
Remarks
This property is used when RemotingServices.Marshal is called and an ObjRef is created.

Return to top


Property: ChannelName (read-only)
Summary
Gets the name of the current channel.
C# Syntax:
public string ChannelName {get;}
Implements:
IChannel.ChannelName
Remarks
This property is used to retrieve a specific channel when calling ChannelServices.GetChannel. If this property is not set, the system defaults to "tcp". If you want to register more than one TcpChannel, each must have a unique name. Set this property to the String.Empty string ("") if you want to ignore names, but avoid naming collisions. The system will allow any number of channels with the String.Empty.

Return to top


Property: ChannelPriority (read-only)
Summary
Returns the priority of the current channel.
C# Syntax:
public int ChannelPriority {get;}
Implements:
IChannel.ChannelPriority
Remarks
Higher numbers indicate a higher chance of being chosen to connect first. The default priority is 1, and negative numbers are allowed.

Return to top


Method: CreateMessageSink(
   string url,
   object remoteChannelData,
   out string objectURI
)
Summary
Returns a channel message sink that delivers messages to the specified URL or channel data object.
C# Syntax:
public IMessageSink CreateMessageSink(
   string url,
   object remoteChannelData,
   out string objectURI
);
Parameters:

url

The URL to which the new sink should deliver messages. Can be null.

remoteChannelData

The channel data object of the remote host to which the new sink should deliver messages. Can be null.

objectURI

When this method returns, contains a URI of the new channel message sink that delivers messages to the specified URL or channel data object. This parameter is passed uninitialized.

Return Value:
A channel message sink, that delivers messages to the specified URL or channel data object.
Implements:
IChannelSender.CreateMessageSink
Remarks
The TcpChannel.CreateMessageSink method returns a channel message sink that delivers messages to either the specified URL or channel data object. If the uri parameter is null, remoteChannelData is used as a target for the sink. Either the url or remoteChannelData parameters can be null, but not both.

Channel sinks provide a plug-in point that allows access to the underlying messages flowing through the channel as well as the stream used by the transport mechanism to send messages to a remote object. Channel sinks are linked together in a chain of ChannelSinkProviders and all channel messages flow through this chain of sinks before the message is finally serialized and transported.

Return to top


Method: Equals(
   object obj
)
Inherited
See base class member description: System.Object.Equals
C# Syntax:
public virtual bool Equals(
   object obj
);

For more information on members inherited from System.Object click on the link above.

Return to top


Method: Finalize()
Inherited
See base class member description: System.Object.Finalize
C# Syntax:
~TcpChannel();

For more information on members inherited from System.Object click on the link above.

Return to top


Method: GetHashCode()
Inherited
See base class member description: System.Object.GetHashCode
C# Syntax:
public virtual int GetHashCode();

For more information on members inherited from System.Object click on the link above.

Return to top


Method: GetType()
Inherited
See base class member description: System.Object.GetType
C# Syntax:
public Type GetType();

For more information on members inherited from System.Object click on the link above.

Return to top


Method: GetUrlsForUri(
   string objectURI
)
Summary
Returns an array of all the URLs for an object with the specified URI, hosted on the current TcpChannel.
C# Syntax:
public string[] GetUrlsForUri(
   string objectURI
);
Parameters:

objectURI

The URI of the object for which URLs are required.

Return Value:
An array of the URLs for an object with the specified URI, hosted on the current TcpChannel.
Implements:
IChannelReceiver.GetUrlsForUri
Remarks
This method is used by ChannelServices.GetUrlsForObject.
Example
using System;
using System.Runtime.Remoting;
using System.Runtime.Remoting.Channels.Tcp;

class SampleClass {
   public static void Main() {

      // Create a remotable object.
      TcpChannel tcpChannel = new TcpChannel(8085);

      WellKnownServiceTypeEntry WKSTE = 
         new WellKnownServiceTypeEntry(typeof(HelloService),
                                       "Service", 
                                       WellKnownObjectMode.Singleton);
      RemotingConfiguration.RegisterWellKnownServiceType(WKSTE);

      RemotingConfiguration.ApplicationName = "HelloServer";

      // Print out the urls for the HelloServer.
      string[] urls = tcpChannel.GetUrlsForUri("HelloServer");
      
      foreach (string url in urls)
         System.Console.WriteLine("{0}", url);
      
   }
}

    

Return to top


Method: MemberwiseClone()
Inherited
See base class member description: System.Object.MemberwiseClone
C# Syntax:
protected object MemberwiseClone();

For more information on members inherited from System.Object click on the link above.

Return to top


Method: Parse(
   string url,
   out string objectURI
)
Summary
Extracts the channel URI and the remote well known object URI from the specified URL.
C# Syntax:
public string Parse(
   string url,
   out string objectURI
);
Parameters:

url

The URL from which to extract the URI of the remote well known object.

objectURI

When this method returns, contains a String that holds the URI of the remote well known object. This parameter is passed uninitialized.

Return Value:
The URI of the current channel.
Implements:
IChannel.Parse
Remarks
A URI of an object is a value that uniquely identifies a specific object instance.
See also:
Uri

Return to top


Method: StartListening(
   object data
)
Summary
Instructs the current channel to start listening for requests.
C# Syntax:
public void StartListening(
   object data
);
Parameters:

data

Optional initialization information.

Implements:
IChannelReceiver.StartListening
Remarks
The data object can be used to pass a specific initialization state to the channel.

Return to top


Method: StopListening(
   object data
)
Summary
Instructs the current channel to stop listening for requests.
C# Syntax:
public void StopListening(
   object data
);
Parameters:

data

Optional state information for the channel.

Implements:
IChannelReceiver.StopListening
Remarks
The data object can be used to pass a specific state to the channel.

Return to top


Method: ToString()
Inherited
See base class member description: System.Object.ToString
C# Syntax:
public virtual string ToString();

For more information on members inherited from System.Object click on the link above.

Return to top


Top of page

Copyright (c) 2002 Microsoft Corporation. All rights reserved.