Aztec® Programming Language
Version 1.1 Alpha 2

Copyright © 2010-2017, Aztec Development Group, All Rights Reserved

Download Aztec

Search        Contact Us

I hope that someone gets my...

Message in a bottle.

- Sting

 

aztec.system.MessageClient

public class MessageClient from<Base>

Base

MessageClient

The MessageClient class is used to connect to a remote Aztec script/application and send it messages. Text and Binary messages are supported. The Aztec script that it connects to (the "remote script") must have already started the message server on the correct TCP/IP port using the Script.StartMessageServer() method. The remote script can reside on the same machine or on any remote machine that is accessible using TCP/IP communication.

MessageClient Methods

MessageClient() Constructor for the MessageClient class
Connect() Connect to a remote Aztec scipt/application message server
SendTextMessage() Sends a text message to the remote Aztec message server
SendBinaryMessage() Sends a binary message to the remote Aztec message server
IsConnected() Returns true if this message client object is successfully connected to a remote Aztec message server
ServerName() Returns the name of the remote Aztec script (empty if not successfully connected)
Port() Returns the port number of the connection to the remote Aztec script (0 if not connected)
Close() Closes the connection to the remote Aztec message server

Derived Classes

See Also

 


MessageClient()

public method MessageClient()

Parameters

None

Return Value

None

Description

Constructor for the MessageClient class.

 

MessageClient Class


Connect()

public method<bool> Connect(string IPAddress, int PortNumber)

Parameters

IPAddress

IP Address of remote computer

PortNumber

Port number for the underlying TCP/IP connection

Return Value

Returns true if the connection is successful and false if not

Description

This method attempts to connect to the Aztec message server at the specified IP address and port number. This will only be successful if the remote Aztec script has started the message server by calling Script.StartMessageServer() with the same port number as specified.

 

MessageClient Class


SendTextMessage()

public method SendTextMessage(string TextMessage, int ApplicationSpecifiedId = 0)

Parameters

TextMessage

String to be sent as message to remote Aztec script

ApplicationSpecificId

Can be any integer for the application to use any way it wants. Default value of zero.

Return Value

True if the message was sent successfully

Description

This method sends the specified text string to the remote Aztec script as a message, resulting in all registered text message event handlers for the remote Aztec script to be executed. The MessageClient object must already be connected to a remote Aztec message server for this operation to work.

 

The application specified Id argument has no effect on the "send" process. It is simply an extra piece of data that the applications (the "sender" of the message AND the "receiver(s)" of the message (event handlers)) can use in any way they want.

 

MessageClient Class


SendBinaryMessage()

public method SendBinaryMessage(MemoryStream BinaryMessageBuffer, int NumberOfBytes = 0, int ApplicationSpecifiedId = 0)

Parameters

MemoryStream

Reference to the MemoryStream object that contains the binary data

NumberOfBytes

Specifies a max number of bytes to write, otherwise uses all data from current I/O position to end of the stream

ApplicationSpecificId

Can be any integer for the application to use any way it wants. Default value of zero.

Return Value

True if the message was sent successfully

Description

This method sends a "binary" message to remote Aztec script. The MessageClient object must already be connected to a remote Aztec message server for this operation to work.

 

The data to be sent in the message is extracted from the MemoryStream object and sent to the remote script as a message. The amount of data to be sent depends on the current I/O position within the stream, the total amount data in the stream, and value of the "NumberOfBytes" argument. If "NumberOfBytes" is zero (which is the default), the message will consist of all data from the current I/O position to the end of the stream. If "NumberOfBytes" is greater than zero, then the amount of data sent will be limited by that amount. If the total amount of data left in the stream exceeds this specified limit, then the message size is truncated at the limit. If the amount of data left in the stream is less than or equal to the limit specified (unless zero), then the remainder of the data in the stream is sent.

 

It is important to set the current position in the memory stream prior to sending the message. After data is written into the memory buffer, the stream position will be after the last write operation, by default. If the memory buffer is sent in that state, the system will try to read from it, and will fire an exception if there is no data to read. After the memory stream is filled, the stream position should be manually set to the correct position before the message is sent.

 

This results in all registered binary message event handlers (for the remote Aztec script) to be executed. When a handler is executed, each handler gets its OWN copy of a MemoryStream object containing that data that was sent from the original incoming MemoryStream object. Each handler's MemoryStream object (and the data within the stream) is unique and independent of each other, as well as independent from the original stream. All changes made to the receiver's copy of the MemoryStream object affect only that object.

 

The application specified Id argument has no effect on the "send" process. It is simply an extra piece of data that the application (the "sender" of the message AND the "receiver(s)" of the message (event handlers)) can use in any way they want.

 

MessageClient Class


IsConnected()

public method<bool> IsConnected()

Parameters

None

Return Value

True if succesfully connected to a remote message server

Description

This method returns true if this MessageClient object is successfully connected to a remote Aztec message script. The SendTextMessage() and SendBinaryMessage() methods will only work properly if this is true.

 

MessageClient Class


ServerName()

public method<string> ServerName()

Parameters

None

Return Value

Name of the remote Aztec script that this object is connected to

Description

This method returns the name of the remote Aztec script that this MessageClient object is connected. An empty string is returned if not currently connected.

 

MessageClient Class


Port()

public method<int> Port()

Parameters

None

Return Value

Port number of the underlying socket connection

Description

This method returns the port number associated with the underlying socket connection being used for the remote messaging. A value of zero is returned if not currently connected.

 

MessageClient Class


Close()

public method Close()

Parameters

None

Return Value

None

Description

This method closes the connection with the remote Aztec message server. No more messages can be sent once the connection is closed. This same MessageClient object can be used again, however. If the Connect() method is successfully called again, messages can then be sent.

 

MessageClient Class

 

Copyright © 2010-2017

Aztec Development Group

All Rights Reserved

Download Aztec