[Copyright]
[Table of Contents]
XYMessenger
XYMessenger is the key component responsible for inter-process communication in XYSystem. The Win32 version is XYMessenger.ocx, the Java version is the XYMessenger class in the XYMessenger package contained in the XYSystem.jar file. To use the Win32 version, you need to either embed it in a window (typically a dialog box or a form) or use it within a console application with the help of ATL or the XYDispDriver class. To use the Java version, you derive a class from the XYMessenger class. The important thing is that the two versions are compatible so that you can easily write windows programs and java programs that can talk to each other. Both versions of XYMessenger are documented here.
Note that the java interface of XYMessenger in XYSystem 2.0 is slightly different from that of XYSystem 1.0. Click here to see documentation of the old version of XYMessenger.
In XYSystem, a set of inter-connected XYMessenger objects form a communication tree. Each process can have one or more XYMessenger objects embedded. And each XYMessenger object is a node in a communication tree. There can be multiple trees, of course. Any two nodes in the same tree can communicate with each other by sending and receiving messages.
Here is how it works. First, determine what mode you want to use by calling the SetSecurityMode method. Note that all objects to be connected together must be running in the same mode. Then, connects to the system using the ConnectDirect method. After successfully connected, you can send messages to or receive messages from other connected party. When a message arrived from another connected party, the system will invoke the corresponing event handler automatically.
In order to send a message to a connected pary (a node in the communication tree), there must be a way to uniquely identify it. In XYSystem, each node is identified by a string of the form UserName@XXXX, which is called the user identifier. UserName string is the name used by the current node to connect to the system and XXXX represents a string of 0 or more digits, which is generated by the system at run-time. The GetUser method returns the user identifier of a specific node. If you are using the XYRoot component, there is a query user feature that can be invoked to get a semi-colon delimited list of user identifiers matching a string pattern you provided. If you are not using XYRoot, you can either implement your own query user feature or let each connected party advertising its own user identifier by sending or broadcasting messages.
boolean
BroadcastBinaryMsg(long
pDataPtr, long nDataSize, boolean bToParent, long nAppSpecific);
[Java] public
final boolean BroadcastBinaryMsg(byte[]
pData, boolean bToParent, int nAppSpecific);
This method broadcasts a binary message. pDataPtr is a pointer to the data, nDataSize is the number of bytes pointed by pDataPtr. If bToParent is FALSE, then only descendent nodes of the current node in the communication tree will receive the message. Otherwise all nodes in the communication tree will receive the message. nAppSpecific is a user defined code. All negative values of nAppSpecific are reserved by the system.
void
BroadcastTextMsg(BSTR
strTitle, BSTR strText, boolean bToParent, long nAppSpecific);
[Java] public
final boolean BroadcastTextMsg(String
strTitle, String strText, boolean bToParent, int nAppSpecific);
This method broadcasts a text message. strTitle is the message title. strText is the message text. If bToParent is FALSE, then only descendent nodes of the current node in the communication tree will receive the message. Otherwise all nodes in the communication tree will receive the message. nAppSpecific is a user defined code. All negative values this parameterare are reserved by the system.
void Close(long
nIndex);
[Java] public
final void Close(int
nIndex);
This method closes the connections between the current node and other nodes in the communication tree. Child nodes of the current node are indexed from 0 to MaxClientCount - 1. If the argument nIndex is within this range, then connection to the corresponding client will be closed. If nIndex equals -1, then connection to all nodes will be closed.
boolean Connet( ); [Win32 only]
This method is implemented using the following method ConnectDirect. Calling this method will pop up a built-in dialog. After entering user name and password, you can enter the ip address and port number of the server you want to establish connection with. You can also enter a port number for the current instance if you plan to have it accept connections from other instances of XYMessenger. Clicking the OK button will send your login request to the server. If you check the server box but not the client box on the dialog, then current instance will be the root node in a new communication tree. With XYSystem, it is possible and common for a process to be both a server and a client. Here server means it can accept connection requests, and client means it sends a connection request to an already connected instance of XYMessenger. The return value indicates whether the connection is successful.
boolean
ConnetDirect(BSTR
strUserName, BSTR strPassword, BSTR strServerAddress, long nServerPort,
long nLocalPort, long nMaxClientCount, long nTimeout );
[Java] public
final synchronized boolean ConnectDirect(String
strUserName, String strPassword, String strServerAddress, int nServerPort,
int nLocalPort, long nMaxClientCount, int nTimeout);
This method is the only way to connect to the "system". strUserName and strPassword have to be non-empty strings identifying the user connecting to the system. The three special characters <, >, and / are not allowed in the strUserName and strPassword strings. strServerAddress is the ip address or the name of the server machine to which the current instance is trying to connect. The empty string value for this parameter means that the server is running on the same machine as the current instance. nServerPort is an integer that is the port number of the server instance to which the current instance is trying to connect. The 0 value for this parameter means that the current instance is the root node in the communication tree. nLocalPort is the port number for the current instance, other instances use this port number to connect to it. The 0 value for this parameter means that the current instance does not accept connections. nMmMaxClientCount is an integer that is the maximum number of clients that can connect to the current instance. The default is set to 1000 in the Connect method. Note that by default, each of these 1000 clients can have 1000 clients connected to it. The nTimeout parameter is the number of seconds to wait for the server to respond to the connection request . The Connect method uses the default timeout value 32. The return value is true if successfully connected, otherwise it returns false.
Note that by default, XYMessenger will automatically reconnect when the connection to its server is broken. See the SetReconnectDelay method on how to change the default behavior.
boolean
ConnetRandom(BSTR
strUserName, BSTR strPassword, BSTR strServerAddress, long nServerPortStart,
long nServerPortCount, long nLocalPort, long nMaxClientCount );
[Java] public
final synchronized boolean ConnectRandom(String
strUserName, String strPassword, String strServerAddress, int nServerPortStart,
int nServerPortCount, int nLocalPort, int nMaxClientCount );
This method is implemented by the ConnectDirect method. When it is called, the current instance of XYMessenger will connect to a randonly selected a port between in range from nServerPortStart to nServerPortStart+nServerPortCount-1. The return value is true if successfully connected, otherwise it returns false.
long GetClientCount(
);
[Java] public
final int GetClientCount(
);
This method returns the total number of client instances of XYMessenger connected to the current instance.
long
GetMsgAppSpecificCode(long
nMsgIndex);
[Java] public
final int GetMsgAppSpecificCode(int
nMsgIndex);
Get the app specific code for the message identified by nMsgIndex. nMsgIndex is an integer value returned by GetMsgIndex or GetMsgIndexWithSenderMsgID.
long GetMsgCount(
);
[Java] public
final int GetMsgCount(
);
This method returns the total number of messages stored in the system.
long GetMsgData(long
nMsgIndex);
[Java] public
final byte[] GetMsgData(int
nMsgIndex);
Get a pointer to the message data field for the message identified by nMsgIndex. nMsgIndex is an integer value returned by GetMsgIndex or GetMsgIndexWithSenderMsgID. This method applies to both text and binary messages. For text messages, the message data field is the same as the message text field. In the Win32 version, the returned value is a long integer which needs to be casted to a pointer.
BSTR GetMsgDateTime(long
nMsgIndex);
[Java]
public final Date GetMsgDateTime(int
nMsgIndex);
Get the date and time indicating when the message identified by nMsgIndex was received. nMsgIndex is an integer value returned by GetMsgIndex or GetMsgIndexWithSenderMsgID.
long GetMsgIndex(long
nMsgID);
[Java] public
final int GetMsgIndex(int
nMsgID);
Get the index of the message in the internal message list with message id equals to nMsgID. The return value is -1 if there is no such message.
long
GetMsgIndexWithSenderMsgID(long
nSenderMsgID);
[Java] public
final int GetMsgIndexWithSenderMsgID(int
nSenderMsgID);
Get the index of the first message in the internal message list with sender message id equals to nSenderMsgID. The return value is -1 if there is no such message.
BSTR GetMsgReceiver(long
nMsgIndex);
[Java] public
final String GetMsgReceiver(int
nMsgIndex);
Get the user identifier of the receiver for the message identified by nMsgIndex. nMsgIndex is a value returned by GetMsgIndex or GetMsgIndexWithSenderMsgID.
BSTR GetMsgSender(long
nMsgIndex);
[Java]
public final String GetMsgSender(int
nMsgIndex);
Get the user identifier of the sender for the message identified by nMsgIndex. nMsgIndex is a value returned by GetMsgIndex or GetMsgIndexWithSenderMsgID.
long GetMsgSize(long
nMsgIndex);
[Java]
public final int GetMsgSize(int
nMsgIndex);
Get the number of bytes of the binary message data for the message identified by nMsgIndex. nMsgIndex is a value returned by GetMsgIndex or GetMsgIndexWithSenderMsgID. This method only applies to binary messages.
long GetMsgType(long
nMsgIndex);
[Java]
public final int GetMsgType(int
nMsgIndex);
Get message type for the message identified by nMsgIndex. nMsgIndex is a value returned by GetMsgIndex or GetMsgIndexWithSenderMsgID. The return value can be one of the following: -33796000 (text message), -33797000 (broadcasted text message), -33798000 (binary message), -33799000 (broadcasted binary message). The return value is -1 if there is no such message.
BSTR GetMsgTitle(long
nMsgIndex);
[Java]
public final String GetMsgTitle(int
nMsgIndex);
Get message title for the message identified by nMsgIndex. nMsgIndex is a value returned by GetMsgIndex or GetMsgIndexWithSenderMsgID. This method only applies to text messages.
BSTR GetMsgText(long
nMsgIndex);
[Java]
public final String GetMsgText(int
nMsgIndex);
Get message text for the message identified by nMsgIndex. nMsgIndex is a value returned by GetMsgIndex or GetMsgIndexWithSenderMsgID. This method only applies to text messages.
BSTR GetParent(
);
[Java] final
public String GetParent(
);
This method returns the user identifier of the parent node in the communication tree.
boolean
GetSecurityMode(
);
[Java]
public final boolean GetSecurityMode(
);
This method returns TRUE if the current instance is in secured mode. Otherwise it returns FALSE.
long GetSenderMsgID(long
nMsgIndex);
[Java]
public final int GetSenderMsgID(int
nMsgIndex);
Return the message id from the sender for the message identified by nMsgIndex. nMsgIndex is a value returned by GetMsgIndex or GetMsgIndexWithSenderMsgID.
BSTR GetUser(long
nIndex);
[Java]
public final String GetUser(int
nIndex);
Returns the user identifier of the user with index nIndex in the internal user list. If nIndex equals -1, then the returned string is the user identifier of the current instance of XYMessenger. See the query user feature in XYRoot for more details.
long GetUserCount(
);
[Java]
public final int GetUserCount(
);
Get the total number of users known by the current node. See the query user feature in XYRoot for more details.
BOOL Ping(LPCTSTR
strTarget, long nTimeout);
[Java] public
final boolean Ping(String
strTarget, int nTimeout);
Send a ping message to another node in the communication tree identified by the user id strTarget. It returns TRUE if there is a response from the target node before timeout occurs. Otherwise it will return FALSE. The nTimeout parameter is in seconds.
void
PublishUserListToChild(boolean
bPublish);
[Java] public
final void PublishUserListToChild(boolean
bPublish);
By default, each XYMessenger object (a node) in the communication tree has an internal list that contains current users. This list is updated whenever a user logs on or logs off the system. If you call this method on a node with a FALSE input parameter, then a child node will not receive updates for user logons and logoffs from the current node. This reduces network traffic and saves processing power when there are a lot of users in the same communication tree. Note that the root node in the communication tree always maintains the list of all connected users. See the query user feature in XYRoot for more details.
boolean RemoveMsg(long
nMsgIndex);
[Java]
public final boolean RemoveMsg(int
nMsgIndex);
Calling this method will remove the message with index nMsgIndex. nMsgIndex is a value returned by GetMsgIndex or GetMsgIndexWithSenderMsgID.
boolean
ReplySyncBinaryMsg(long
nMsgID, BSTR strTo, long pDataPtr, long nDataSize, long nAppSpecific)
[Java] public
final boolean ReplySyncBinaryMsg(int
nMsgID, String strTo, byte[] pData, int nAppSpecific) ;
This method is identifical to SendBinaryMsg except an extra (the first) parameter for specifying the message id. This method is typically used to reply to a message sent by a call to SendSyncTextMsg or SendSyncBinaryMsg. The first parameter should be the sender message id of the message to which this method is replying.
boolean
ReplySyncTextMsg(long
nMsgID, BSTR strTo, BSTR strTitle, BSTR strText, long nAppSpecific);
[Java]
public final boolean ReplySyncTextMsg(int
nMsgID, String strTo, String strTitle, String strText, int nAppSpecific);
This method is identifical to SendTextMsg except an extra (the first) parameter for specifying the message id. This method is typically used to reply to a message sent by a call to the method SendSyncTextMsg or SendSyncBinaryMsg. The first parameter should be the sender message id of the message to which this method is replying.
boolean
SendBinaryMsg(BSTR
strTo, long pDataPtr, long nDataSize, long nAppSpecific );
[Java]
public final boolean SendBinaryMsg(String
strTo, byte[] pData, int nAppSpecific );
Call this method to send a block of binary data. strTo is the user identifier of the message destination. pDataPtr is a pointer to the message data. nDataSize is the number of bytes pointed by pDataPtr. nAppSpecific is a user defined code. All negative values of nAppSpecific are reserved by the system.
long
SendSyncBinaryMsg(BSTR
strTo, long pDataPtr, long nDataSize, long nAppSpecific, long nTimeout
);
[Java]
public final int SendSyncBinaryMsg(String
strTo, byte[] pData, int nAppSpecific, int nTimeout );
This method is similar to SendBinaryMsg except that the call is synchronous. That is, the call will not return until the message has been replied by the receiver or timeout occurs. nTimeout is the timeout value in seconds. The return value can be used as the input parameter to GetMsgIndexWithSenderMsgID to retrieve (the index of) the reply message. The receiving party should use the ReplySyncTextMsg method or the ReplySyncBinaryMsg method to send back the reply message.
long SendSyncTextMsg(BSTR
strTo, BSTR strTitle, BSTR strText, long nAppSpecific, long nTimeout );
[Java]
public final int SendSyncTextMsg(String
strTo, String strTitle, String strText, int nAppSpecific, int nTimeout
);
This method is similar to SendTextMsg except that the call is synchronous. That is, the call will not return until the message has been replied by the receiver or timeout occurs. nTimeout is the timeout value in seconds. The return value can be used as the input parameter to GetMsgIndexWithSenderMsgID to retrieve (the index of) the reply message. The receiving party should use the ReplySyncTextMsg method or the ReplySyncBinaryMsg method to send back the reply message.
boolean SendTextMsg(BSTR
strTo, BSTR strTitle, BSTR strText, long nAppSpecific);
[Java]
public final boolean SendTextMsg(String
strTo, String strTitle, String strText, int nAppSpecific);
Call this method to send a text message. strTo is the user identifier of the message destination. strTitle is the title of the message. strText is the text of the message. nAppSpecific is a user defined code. All negative values of nAppSpecific are reserved by the system.
void
SetReconnectDelay(long
nSeconds);
[Java]
public final void SetReconnectDelay(int
nSeconds);
This method changes the behavior when connection to the server is broken. The default behavior is, when the connection is broken, XYMessenger will wait an average of 60 seconds and then reconnect to the server using the set of parameters (user name and passwords, etc.) that was used last time to successfully connect. This process will repeat up to 30 times until it is successfully connected. The parameter nSeconds is used to specify a new number, the average number of seconds to wait, before attempting the reconnection. If nSecondes is 0 or negative, then reconnection will not be attempted (disabled).
void SetSecurityMode(boolean
bSecure);
[Java]
public final void SetSecurityMode(boolean
bSecure);
Call this method to enter or leave secured mode. Note that an instance of XYMessenger in secured mode cannot communicate with other instances in non-secured mode.
void Shutdown(long
nIndex);
[Java]
public final void Shutdown(int
nIndex);
This method will shutdown the client process represented by index nIndex. nIndex must be a number between 0 and MaxClientCount - 1.
XYMessenger generates various events to notify user changes in the system. Win32 applications handle these events by implementing COM event handlers. Java applications handle these events by overriding the corresponding virtual event handler methods of the class XYMessenger. Here are the descriptions of these event handlers.
void XYAcceptClient(BSTR
strClientAddress, boolean* pAcceptClient);
[Java]
public boolean AcceptClient(String
strClientAddress);
This is the first event fired when a client instance calls Connect or ConnectDirect to login to the current instance. strClientAddress is the ip address of the machine that the client is running. The current instance can refuse the connection request from the corresponding client by setting the boolean value pointed by pAcceptClient to false (or simply returning false in the java case). Otherwise the connection request will be processed and other events such as XYLoginMsg will be fired.
void XYBinaryMsg(long
nMsgID, long nSenderMsgID, BSTR strFrom, long nAppSpecific);
[Java]
public void BinaryMsgHandler(int
nMsgID, int nSenderMsgID, String strFrom, int nAppSpecific);
This event is fired when a binary message is received. nMsgID is the message id which can be used to call GetMsgIndex. nSenderMsgID is the message id from the sender, which should be used to reply to a synchronous message. strFrom is the user identifier of the sender. nAppSpecific is a user defined code.
void
XYBinaryMsgBroadcast(long
nMsgID, long nSenderMsgID, BSTR strFrom, long nAppSpecific);
[Java]
public void BinaryMsgBroadcastHandler(int
nMsgID, int nSenderMsgID, String strFrom, int nAppSpecific);
This event is fired when a broadcasted binary message is received. nMsgID is the message id which can be used to call GetMsgIndex. nSenderMsgID is the message id from the sender. strFrom is the user identifier of the sender. nAppSpecific is a user defined code.
void XYErrorMsg(long
nErrorCode, BSTR strErrorText);
[Java] public
void ErrorHandler(int
nError, String strError);
This event is fired when an XYSystem error occurs. See error code for more details.
void XYLoginMsg(long
nIndex, BSTR strUserName, BSTR strPassword);
[Java]
public void LoginMsgHandler(int
nClientIndex, String strUserName, String strPassword);
This event is fired when a client instance calls Connect or ConnectDirect to login to the current instance. nIndex is an index which uniquely identifies a client of the current instance. strUserName and strPassword are the input provided to the connect functions by the client. The same event is also fired on the client that is completing the connection process, but in that case the value of strPassword will be the empty string. To implement user authentication, an XYSystem process needs to check whether the provided user name and password are valid when handling this event, and call the Close method if user name or password is invalid.
void XYMsgFilter(long
nSenderMsgID, long nMsgType, BSTR strFrom, BSTR strTo, long nAppSpecific,
boolean* pMsgFilterFlag);
[Java]
public boolean MsgFilter(int
nSenderMsgID, int nMsgType, String strfrom, String strTo, int nAppSpecific);
This event is fired when a text or binary message arrives from a child node. The current node can refuse to process the message by setting the boolean value pointed by pMsgFilterFlag to FALSE or simply returning false in the java case. Otherwise the message will be processed as usual.
void XYNewUser(long
nIndex, BSTR strUserName, BSTR strPassword);
[Java]
public void NewUserHandler(int
nClientIndex, String strUserName, String strPassword);
This event is fired when a descendent node of the current node is added to the communication tree. nIndex identifies the client instance whose subbranch the new node belongs to. strUserName and strPassword are the input parameters provided to the connect functions by the instance that represents the new node. To implement user authentication, an XYSystem process needs to check whether the provided user name and password are valid when handling this event, and call the Close or the Shutdown method if user name or password is invalid.
void XYTextMsg(long
nMsgID, long nSenderMsgID, BSTR strFrom, BSTR strTitle, BSTR strText, long
nAppSpecific);
[Java]
public void TextMsgHandler(int
nMsgID, int nSenderMsgID, String strFrom, String strTitle, String strText,
int nAppSpecific);
This event is fired when a text message is received. nMsgID is the message id which can be used to call GetMsgIndex. nSnSenderMsgID is the message id from the sender, which should be used to reply to a synchronous message. strFrom is the user identifier of the sender. strTitle is the message title. strText is the message text. nAppSpecific is a user defined code.
void
XYTextMsgBroadcast(long
nMsgID, long nSenderMsgID, BSTR strFrom, BSTR strTitle, BSTR strText, long
nAppSpecific);
[Java]
public void TextMsgBroadcastHandler(int
nMsgID, int nSenderMsgID, String strFrom, String strTitle, String strText,
int nAppSpecific);
This event is fired when a broadcasted text message is received. nMsgID is the message id which can be used to call GetMsgIndex. nSenderMsgID is the message id from the sender. strFrom is the user identifier of the sender. strTitle is the message title. strText is the message text. nAppSpecific is a user defined code.