NGWS SDK Documentation  

This is preliminary documentation and subject to change.
To comment on this topic, please send us email at ngwssdk@microsoft.com. Thanks!

Message

Message Concepts

Messages can be thought of as a container for communicating data between co-operating message sinks. These message sinks could be anywhere along the message sink chain: in the client sink chains or in the server sink chains. A message object is passed from message sink to message sink, through the chain and carries set of named properties such as, but not limited to, action identifiers, envoy information, and parameters.

An object that implements the interface IMessage meets the minimum qualification to be considered a message object. Also, there is no restriction that the exact object received by a message sink must be passed on to the next sink, though this will often be the case.

Although it is not a requirement that the objects in the property bag be serializable, it is certainly something that the message sink implementer would want to consider since an properties that need to flow out of the application domain will need to be serializable. Objects should also be agile if they are to be used in cross-context, same app-domain calls.

Message Reference

IMessage Reference

interface IMessage
{
   public IDictionary Properties();
}

GetProperties

Returns a dictionary, which represents a collection of associated keys and values. The message properties are made available for read and write via the dictionary.

IMethodMessage Reference

Defines the method message interface. A method message is specialized for methods.

public interface IMethodMessage : IMessage
{
  String URI                      { get; }
  String MethodName               { get; }
  String TypeName                 { get; }
  Object MethodSignature          { get; }
 
  int ArgCount                    { get; }
  Object GetArg(int argNum);
  String GetArgName(int index);
  Object[] Args                  { get; }

  bool HasVarArgs                 { get; }
}

Args

Return an array of all the arguments. An Object array containing the arguments. Although this method is redundant since the same functionality may be achieved via GetArgCount/GetArg, there may be performance optimization available to the implementor if s/he understands when all of the arguments will be retrieved. IMessage Dictionary property key “__Args”.

GetArgCount

Return the number of arguments. IMessage Dictionary property key “__Args” via array object.

GetArgName

Return the name of a specific argument. A string representing the name of the argument specified or null if this method is not implemented. IMessage Dictionary property key “__Args” via array object.

GetArg

Return a specific argument as an Object. IMessage Dictionary property key “__Args” via array object.

HasVarArgs

Returns a boolean indicating if the message has varargs.

MethodName

Return the method name. A string which is the name of the method to be called. IMessage Dictionary property key “__MethodName”.

MethodSignature

Return the method signature. An array of byte’s containing a method signature. IMessage Dictionary property key “__MethodSignature”.

TypeName

Return the type name. IMessage Dictionary property key “__TypeName”.

URI

Return the URI string to which the message is issued. The URI (Uniform Resource Identifier) of the object and method parameters. The URI determines to specific object a call is destined for. IMessage Dictionary property key “__URI”.

IMethodCallMessage Reference

Defines the method call message interface. A method call message is a message, which represent a method call on an object at the end of the message sink. Method Call Messages implement the IMethodCallMessage interface.

public interface IMethodCallMessage : IMethodMessage
{
  int InArgCount                  { get; }
  Object GetInArg(int argNum);
  String GetInArgName(int index);
  Object[] InArgs                { get; }
}

InArgCount

Return the number of IN arguments. IMessage Dictionary property key “__InArgs” via array object”.

GetInArg

Return a specific IN argument as an object. IMessage Dictionary property key “__InArgs” via array object.

GetInArgName

Return the name of a specific IN argument. A string representing the name of the IN argument specified or null if this method is not implemented. IMessage Dictionary property key “__InArgs” via array object.

InArgs

Return an array of all the IN arguments. An Object array containing the IN arguments. Although this method is redundant since the same functionality may be achieved via InArgCount/GetInArg, there may be performance optimization available to the implementor if s/he understands when all of the arguments will be retrieved. IMessage Dictionary property key “__InArgs”.

IMethodReturnMessage Reference

Defines the method call return message interface. A method call return message is a message, which represent the response to a method call on an object at the end of the message sink.

public interface IMethodReturnMessage : IMethodMessage
{
  int OutArgCount                 { get; }
  Object GetOutArg(int argNum);
  String GetOutArgName(int index);
  Object[] OutArgs               { get; }
  Exception Exception             { get; }
  Object ReturnValue             { get; }
}

Exception

Return the exception object for the method call. If an exception did not occur on the call, the return value is null. IMessage Dictionary property key “__Fault”.

GetOutArg

Return a specific out argument as an Object. IMessage Dictionary property key “__OutArgs” via array object.

OutArgCount

Return the number of out arguments. IMessage Dictionary property key “__OutArgs” via array object”.

GetOutArgName

Return the name of a specific out argument. A string representing the name of the out argument specified or null if this method is not implemented. IMessage Dictionary property key “__OutArgs” via array object.

OutArgs

Return an array of all the out arguments. An Object array containing the out arguments. Although this method is redundant since the same functionality may be achieved via GetOutArgCount/GetOutArg, there may be performance optimization available to the implementor if they understand when all of the arguments will be retrieved. IMessage Dictionary property key “__OutArgs”.

ReturnValue

Return the return value as a variant for the call. IMessage Dictionary property key “__Return”.

IMessageSink Reference

When a method call is made on the proxy, the remoting infrastructure provides the necessary support for:

Remote method calls is defined in terms of Messages that goes from the client end to the server end and possibly back again. As it crosses interesting boundaries on the way, it passes through a chain of MessageSink objects. Each sink in the chain receives the IMessage object, performs a specific operation and delegates to the next sink in the chain. The Proxy object contains a reference to the first IMessageSink it needs to use, to start off the chain.

For asynchronous calls, at the time of delegation, each sink provides a reply sink (another IMessageSink object) that will be called by the next sink when the reply is on its way back.

The nature of the operation performed by an IMessageSink when it receives a IMessage object to process may be radically different for different types of sinks. For example, one sink could cause a lock to be taken, another could enforce call security, another could be performing flow call control / reliability services and yet another could be responsible for transporting the call to a different appdomain / process / machine. Two or more message sinks in the chain may communicate and interact with each other in regard to each specific action.

public interface IMessageSink
{
  public IMessage SyncProcessMessage(IMessage msg);
  public IMessageCtrl AsyncProcessMessage(
                  IMessage msg, 
                  IMessageSink replySink);
  public IMessageSink NextSink { get; }
}

AsyncProcessMessage

Invoked on the message sink by the remoting infrastructure or by a previous sink for asynchronous messages. Returns an IMessageCtrl interface that provides a way to control asynchronous messages once they have dispatched.

NextSink

Retrieves the next message sink held by this sink.

SyncProcessMessage

Invoked on the message sink by the remoting infrastructure or by a previous sink for synchronous messages. Returns the reply message in response to the request.

IMessageCtrl Reference

The IMessageCtrl interface provides a way to control asynchronous messages once they have dispatched via IMessageSink.AsyncProcessMessage.

public interface IMessageCtrl
{
  public void Cancel (int msToCancel);
};

Cancel

Used to cancel an asynchronous message. The number of milliseconds in which to cancel the message is passed.