VideoOS.Platform.Messaging.MessageCommunication Class Reference

Communication between EventServer and all other MIP Environments can be done via this class.
Each starting application or service will have one EndPoint ( Unique for each execution ), and a EndPointType.
The EventServer is defined as a EndPointType.Server and all other MIP Environments are in this context a EndPointType.Client.
Any MIP plug-in can get a list of all currently executing MIP Environments and store their EndPointFQID for communication purpose. For each EndPoint is is possible to get hold of the EndPointIdentityData class to identify the login user name for a given EndPoint.
See the WhoAreOnlineRequest and WhoAreOnlineResponse MessageId's for more on this.

This class is created through the MessageCommunicationManager static class. More...

Inheritance diagram for VideoOS.Platform.Messaging.MessageCommunication:

Public Member Functions
void	Dispose ()
	Disposed internally.
object	RegisterCommunicationFilter (MessageReceiver messageReceiver, CommunicationIdFilter communicationIdFilter, FQID endPoint, EndPointType endPointType)
	Register to receive specific messages, from the specified EndPoint and EndpointType. If the EndPoint is null, all EndPoints are requested to transmit the specific messages. The filter information is send to the EventServer, and again forwarded to relevant clients. This will allow message filtering to be done at the source of the messages and keep network transmission to a minimum. Filters are stored in the EventServer in case of short network problems, and will be re-transmitted to clients that are re-connecting within 60 seconds. If a client is not connected for 60 seconds, all filters issued on other machines to that machine will be deleted (Unregistered).
object	RegisterCommunicationFilter (MessageReceiver messageReceiver, CommunicationIdFilter messageFilter)
	Register to receive specific messages, from any other machine. Please use this filter mechanism with care, as it can impact network traffic.
void	TransmitMessage (Message message, FQID destinationEndPoint, FQID destinationObject, FQID source)
	Transmit a message. When destinationEndPoint is null, the message will be sent to the EventServer itself for processing, where the receiving message filters will be used to determine who should receive the message. When the destinationEndPoint is filled, the message is first sent to the EventServer, that again will forward to the specified endpoint - without any validation of the message filters. Use of the destinationEndPoint is a direct way for two clients to communicate with each other without any filters. If the destinationEndPoint is filled with an ObjectId of Guid.Empty the message is considered a broadcast, and will be transmitted to all clients currently logged in.
void	UnRegisterCommunicationFilter (object communicationFilterObject)
	To Unregister a previously registered filter.
void	WaitForCommunicationFilterRegistration (CommunicationIdFilter messageFilter)
	Waits for the communication filter to be registered on server. Use the overload with timeout if you wish to limit the wait.
void	WaitForCommunicationFilterRegistration (CommunicationIdFilter messageFilter, TimeSpan timeout)
	Waits for the communication filter to be registered on server Throws TimeoutException if the timeout is exceeded.

Static Public Attributes
const string	EndPointCloseIndication = "MessageCommunication.EndPointCloseIndication"
	Send by the EventServer when new clients are logging out.
const string	EndPointTableChangedIndication = "MessageCommunication.EndPointTableChangedIndication"
	A client connection has been opened or closed. The WhoAreOnlineRequest can be used to get a full list of online clients.
const string	NewEndPointIndication = "MessageCommunication.NewEndPointIndication"
	Send by the EventServer when new clients are logging on.
const string	ProvideCurrentStateRequest = "MessageCommunication.ProvideCurrentStateRequest"
	Used to get a the current state for Items. The response is returned as another message - see MessageCommunication.ProvideCurrentStateResponse. This message should be used as few times as possible, as the result can be very large.
const string	ProvideCurrentStateResponse = "MessageCommunication.ProvideCurrentStateResponse"
	The Data field contains a Collection<ItemState> with all known Items in one flat Collection.
const string	WhoAreOnlineRequest = "MessageCommunication.WhoAreOnlineRequest"
	This request can be send to the Event Server to ask who is connected right now. The response is coming in a message with id=WhoAreOnlineResponse.
const string	WhoAreOnlineResponse = "MessageCommunication.WhoAreOnlineResponse"
	Contains a Collection of EndPointIdentityData for each connected user.

Protected Member Functions
virtual void	Dispose (bool disposing)

Properties
static FQID	BroadcastEndPointFQID [get]
	Get the FQID that can be used for broadcasting a message to all clients. Note: Please use with care!
bool	IsConnected [get]
	Returns the status of the communication to the EventServer's Communication service.
FQID	ServerEndPointFQID [get]
	Get the FQID that identifies the EventServer instance.
ServerId	ServerId [get]
	Provide the ServerId used during the Start operation.
Uri	Uri [get]
	The Uri used for message communication.

Events
EventHandler	ConnectionStateChangedEvent
	You can register on this event, if you need to know when the session to the Event Server is changing. When receiving the event call, check the IsConnected property for the actual state.

Detailed Description

Communication between EventServer and all other MIP Environments can be done via this class.
Each starting application or service will have one EndPoint ( Unique for each execution ), and a EndPointType.
The EventServer is defined as a EndPointType.Server and all other MIP Environments are in this context a EndPointType.Client.
Any MIP plug-in can get a list of all currently executing MIP Environments and store their EndPointFQID for communication purpose. For each EndPoint is is possible to get hold of the EndPointIdentityData class to identify the login user name for a given EndPoint.
See the WhoAreOnlineRequest and WhoAreOnlineResponse MessageId's for more on this.

This class is created through the MessageCommunicationManager static class.

Member Function Documentation

Dispose() [1/2]

void VideoOS.Platform.Messaging.MessageCommunication.Dispose ( )

inline

Disposed internally.

Dispose() [2/2]

virtual void VideoOS.Platform.Messaging.MessageCommunication.Dispose ( bool disposing )

inlineprotectedvirtual

Parameters

disposing

RegisterCommunicationFilter() [1/2]

object VideoOS.Platform.Messaging.MessageCommunication.RegisterCommunicationFilter ( MessageReceiver messageReceiver, CommunicationIdFilter communicationIdFilter, FQID endPoint, EndPointType endPointType )

inline

Register to receive specific messages, from the specified EndPoint and EndpointType.
If the EndPoint is null, all EndPoints are requested to transmit the specific messages.
The filter information is send to the EventServer, and again forwarded to relevant clients. This will allow message filtering to be done at the source of the messages and keep network transmission to a minimum.
Filters are stored in the EventServer in case of short network problems, and will be re-transmitted to clients that are re-connecting within 60 seconds. If a client is not connected for 60 seconds, all filters issued on other machines to that machine will be deleted (Unregistered).

Note: It can take 3-4 seconds before this registration takes effect!

Parameters

messageReceiver	The method to be called when a message matching the other parameters is received.
communicationIdFilter	The filter specifying the type of message to receive.
endPoint	A specific endpoint to receive messages from. If set to null messages from all endpoints will be received.
endPointType	A specific type of endpoint to receive messages from. If set to null (along with endPoint parameter) messages from all endpoints will be received.

Returns

An object to be used for UnRegistrationCommunicationFilter

RegisterCommunicationFilter() [2/2]

object VideoOS.Platform.Messaging.MessageCommunication.RegisterCommunicationFilter ( MessageReceiver messageReceiver, CommunicationIdFilter messageFilter )

inline

Register to receive specific messages, from any other machine.
Please use this filter mechanism with care, as it can impact network traffic.

Note: It can take 3-4 seconds before this registration takes effect! Use WaitForCommunicationFilterRegistration(CommunicationIdFilter, TimeSpan) if you need to ensure it's registered

Parameters

messageReceiver
messageFilter

Returns

TransmitMessage()

void VideoOS.Platform.Messaging.MessageCommunication.TransmitMessage ( Message message, FQID destinationEndPoint, FQID destinationObject, FQID source )

inline

Transmit a message. When destinationEndPoint is null, the message will be sent to the EventServer itself for processing, where the receiving message filters will be used to determine who should receive the message.
When the destinationEndPoint is filled, the message is first sent to the EventServer, that again will forward to the specified endpoint - without any validation of the message filters.
Use of the destinationEndPoint is a direct way for two clients to communicate with each other without any filters.
If the destinationEndPoint is filled with an ObjectId of Guid.Empty the message is considered a broadcast, and will be transmitted to all clients currently logged in.

For security reasons, a limitation has been put on the system types allowed to be used as the Message.Data content. See the "Introduction to MIP Message communication" for more details on the types allowed.

Parameters

message	The actual message to be transmitted.
destinationEndPoint	Identification of a specific client endpoint to receive the message. If null it will be sent to all.
destinationObject	Id of a specific object within the receiving application, that is to receive the message.
source	The id of the sender (or null if the recipients doesn't care).

UnRegisterCommunicationFilter()

void VideoOS.Platform.Messaging.MessageCommunication.UnRegisterCommunicationFilter ( object communicationFilterObject )

inline

To Unregister a previously registered filter.

Parameters

communicationFilterObject

The object returned from the RegisterCommunicationFilter method

WaitForCommunicationFilterRegistration() [1/2]

void VideoOS.Platform.Messaging.MessageCommunication.WaitForCommunicationFilterRegistration ( CommunicationIdFilter messageFilter )

inline

Waits for the communication filter to be registered on server. Use the overload with timeout if you wish to limit the wait.

Parameters

messageFilter

The communication filter

WaitForCommunicationFilterRegistration() [2/2]

void VideoOS.Platform.Messaging.MessageCommunication.WaitForCommunicationFilterRegistration ( CommunicationIdFilter messageFilter, TimeSpan timeout )

inline

Waits for the communication filter to be registered on server Throws TimeoutException if the timeout is exceeded.

Parameters

messageFilter	The communication filter
timeout	Maximum timeout to wait, pass TimeSpan.Zero for unlimited waiting

Member Data Documentation

EndPointCloseIndication

const string VideoOS.Platform.Messaging.MessageCommunication.EndPointCloseIndication = "MessageCommunication.EndPointCloseIndication"

static

Send by the EventServer when new clients are logging out.

EndPointTableChangedIndication

const string VideoOS.Platform.Messaging.MessageCommunication.EndPointTableChangedIndication = "MessageCommunication.EndPointTableChangedIndication"

static

A client connection has been opened or closed. The WhoAreOnlineRequest can be used to get a full list of online clients.

NewEndPointIndication

const string VideoOS.Platform.Messaging.MessageCommunication.NewEndPointIndication = "MessageCommunication.NewEndPointIndication"

static

Send by the EventServer when new clients are logging on.

ProvideCurrentStateRequest

const string VideoOS.Platform.Messaging.MessageCommunication.ProvideCurrentStateRequest = "MessageCommunication.ProvideCurrentStateRequest"

static

Used to get a the current state for Items. The response is returned as another message - see MessageCommunication.ProvideCurrentStateResponse.
This message should be used as few times as possible, as the result can be very large.

Sample - as part of some initialization code

MessageCommunicationManager.Start(EnvironmentManager.Instance.MasterSite.ServerId);
MessageCommunication _messageCommunication = MessageCommunicationManager.Get(EnvironmentManager.Instance.MasterSite.ServerId);
 
_object = _messageCommunication.RegisterCommunicationFilter(ProvideCurrentStateResponseHandler,
            new VideoOS.Platform.Messaging.CommunicationIdFilter(MessageCommunication.ProvideCurrentStateResponse));
try {
    _messageCommunication.TransmitMessage(
        new VideoOS.Platform.Messaging.Message(MessageCommunication.ProvideCurrentStateRequest), null, null, null);             <br>
} catch (MIPException ex)
{
    EnvironmentManager.Instance.ExceptionDialog("Unable to get status", ex);
}

For asking for a set of Items, fill the Message.Data field with an array of guids (as String), like

_messageCommunication.TransmitMessage(
    new VideoOS.Platform.Messaging.Message(MessageCommunication.ProvideCurrentStateRequest, new String[] {item.FQID.ObjectId.ToString()}), null, null, null);               <br>

To get the status of one specific item.

ProvideCurrentStateResponse

const string VideoOS.Platform.Messaging.MessageCommunication.ProvideCurrentStateResponse = "MessageCommunication.ProvideCurrentStateResponse"

static

The Data field contains a Collection<ItemState> with all known Items in one flat Collection.

Sample handler code:

private object ProvideCurrentStateResponseHandler(VideoOS.Platform.Messaging.Message message, FQID dest, FQID source)
{
    if (InvokeRequired)
    {   // If we are doing UI updates, we better switch to our thread
        BeginInvoke(new MessageReceiver(ProvideCurrentStateResponseHandler), message, dest, source);
    } else
    {
        Collection\<ItemState\> result = message.Data as Collection\<ItemState\>;
        if (result != null)
        {
            foreach (ItemState itemState in result)
            {
                Do something with itemState
            }
        }
    }
    return null;
}

WhoAreOnlineRequest

const string VideoOS.Platform.Messaging.MessageCommunication.WhoAreOnlineRequest = "MessageCommunication.WhoAreOnlineRequest"

static

This request can be send to the Event Server to ask who is connected right now.
The response is coming in a message with id=WhoAreOnlineResponse.

WhoAreOnlineResponse

const string VideoOS.Platform.Messaging.MessageCommunication.WhoAreOnlineResponse = "MessageCommunication.WhoAreOnlineResponse"

static

Contains a Collection of EndPointIdentityData for each connected user.

Property Documentation

BroadcastEndPointFQID

FQID VideoOS.Platform.Messaging.MessageCommunication.BroadcastEndPointFQID

staticget

Get the FQID that can be used for broadcasting a message to all clients.
Note: Please use with care!

IsConnected

bool VideoOS.Platform.Messaging.MessageCommunication.IsConnected

get

Returns the status of the communication to the EventServer's Communication service.

ServerEndPointFQID

FQID VideoOS.Platform.Messaging.MessageCommunication.ServerEndPointFQID

get

Get the FQID that identifies the EventServer instance.

ServerId

ServerId VideoOS.Platform.Messaging.MessageCommunication.ServerId

get

Provide the ServerId used during the Start operation.

Uri

Uri VideoOS.Platform.Messaging.MessageCommunication.Uri

get

The Uri used for message communication.

Event Documentation

ConnectionStateChangedEvent

EventHandler VideoOS.Platform.Messaging.MessageCommunication.ConnectionStateChangedEvent

You can register on this event, if you need to know when the session to the Event Server is changing.
When receiving the event call, check the IsConnected property for the actual state.