Trading Router Library Introduction

You can use Trading Router Libarary to develop your own MT4/5 EA to receive messages from Tradingview. Trading Router Libarary maintains the connection between your EA and Trading Router server and receives incoming messages from Trading Router server. When Trading Router Libarary receives a new message from Trading Router server, it put the message in the receive message buffer, and signals a chart event to EA immediately, the EA then immediately retrieves the message from receive message buffer and process this message. The time duration between Trading Router server sending a message and your own EA receiving the message is very quick, it is less than 0.1 second.

1. Trading Router MT4/5 API

You can import TradingRouterLibsMt4.ex4 (for MT4) or TradingRouterLibsMt5.ex5 (for MT5) for using Trading Router Library functions.

There are 7 functions in Trading Router Library

1.1 TR_API_OnInit

Function Name	TR_API_OnInit
Arguments	tr_client_token This is Trading Router Client Token message_buffer_len This is the number of received messages that can be saved in the message buffer. When an incoming message comes, it is saved in the message buffer.You can call TR_API_GetNextMessage function to get the incoming message from the buffer. message_buffer_len defines how many messages can be saved in the message buffer. If the message buffer is full and a new incoming message comes, this new incomming message will be lost. message_buffer_len should be greater than 100, if it is less than 100, the Trading Router Library will use 100.
Description	This function is called in OnInit of EA. It initializes Trading Router Library and send registration message to connect to Trading Router server by using tr_client_token.
Return Value	RET_INIT_OK Trading Router Library has sent registration message to Trading Router server. This means the function TR_API_OnInit finishes successfully. RET_INIT_NETWORK_ISSUE_1 Trading Router Library cannot open socket, which means there is out of resource or the network is disconnected. If you get this return value, we recommend you stop your EA by returning INIT_FAILED. RET_INIT_NETWORK_ISSUE_2 Trading Router Library cannot send registration message. This means network is disconnected. If you get this return value, we recommend you stop your EA by returning INIT_FAILED. RET_INIT_UNKNOWN_ISSUE_3 RET_INIT_UNKNOWN_ISSUE_4 RET_INIT_UNKNOWN_ISSUE_5 These are unknow error. These errors should not happen, if they happen, you should stop your EA

1.2 TR_API_OnDeinit

Function Name	TR_API_OnDeinit
Arguments	No
Description	This function is called in OnDeinit of EA. It deinitializes Trading Router Library.
Return Value	No

1.3 TR_API_OnTimer

Function Name	TR_API_OnTimer
Arguments	No
Description	This function is called in OnTimer of EA. It maintains the connection between Trading Router Library and Trading Router server. It also receives incoming message. After you call TR_API_OnTimer, no matter what return value you get, you should call TR_API_HasNextMessage to check if there are new incomming messages, and call TR_API_GetNextMessage to retrieve new incoming messages.
Return Value	RET_CONNECTION_OK The connection between Trading Router Library and Trading Router server is active. Trading Router Library is able to receive incoming messages RET_CONNECTION_AUTHENTICATING Trading Router server is authenticating the client token sent by Trading Router Library. The client token is from the argument tr_client_token in TR_API_OnInit function. RET_CONNECTION_NETWORK_ISSUE_1 Authentication from Trading Router server failed. It means the client token is invalid, or your Trading Router service is stopped, or network is disconnected. You should stop your EA when getting this return value. RET_CONNECTION_NETWORK_ISSUE_2 Authentication from Trading Router server failed. It means the client token is invalid, or your Trading Router service is stopped. You should stop your EA when getting this return value. RET_RECONNECTING It means the connection to Trading Router server was established before, but the connection drops now, the Trading Router Library is trying to establish the connection again. You don't need to stop your EA when geting this return value, the connection will be automatically established. But if you keep getting this return value for a while, it means your Trading Router service may be stopped, or your network may be disconnected, in this case, you may consider stopping the EA. RET_RECONNECT_FAILURE_1 It means the connection to Trading Router server was established before, but the connection drops now, the Trading Router Library is trying to establish the connection again. But the Trading Router Library cannot open socket. It maybe because you have openned large number of sockets on your system. You don't need to stop your EA when getting this return value, the connection will be automatically established when socket is available. RET_RECONNECT_FAILURE_2 It means the connection to Trading Router server was established before, but the connection drops now, the Trading Router Library is trying to establish the connection again. But the Trading Router Library cannot send your registration message. It means your network is disconnected. You don't need to stop your EA when getting this return value, the connection will be automatically established when your network is connected again. RET_RECONNECT_FAILURE_3 RET_RECONNECT_FAILURE_4 RET_RECONNECT_FAILURE_5 These are unknow error. These errors should not happen, if they happen, you should stop your EA.

1.4 TR_API_OnChartEvent

Function Name	TR_API_OnChartEvent
Arguments	id lparam dparam sparam These are the same arguments as OnChartEvent of EA.
Description	This function is called in OnChartEvent of EA. When a new incoming message comes, a chart event will be triggered, and OnChartEvent of EA will be called, then we call TR_API_OnChartEvent in OnChartEvent. TR_API_OnChartEvent will receive the new incoming message and put the message in receive message buffer(the buffer size is defined by argument message_buffer_len of TR_API_OnInit function). After TR_API_OnChartEvent is called and the return value is true, you should call TR_API_HasNextMessage to check if there is new incomming messages, and call TR_API_GetNextMessage to receive new incoming messages.
Return Value	true It means this chart event is for Trading Router Library, and Trading Router Library has put the incoming message in receive message buffer. You can call TR_API_HasNextMessage and TR_API_GetNextMessage to get the message. false It means this chart event is not for Trading Router Library, and Trading Router Library has not processed this chart event. This chart event may be from on-screen buttons, or from other objects of your EA.

1.5 TR_API_HasNextMessage

Function Name	TR_API_HasNextMessage
Arguments	No
Description	This function checks if there is new message in receive message buffer. It should be called after TR_API_OnTimer or TR_API_OnChartEvent is called.
Return Value	true It means there is new message in receive message buffer. You can call TR_API_GetNextMessage to retrieve the message. false It means there is no new message in receive message buffer. You don't need to call TR_API_GetNextMessage.

1.6 TR_API_GetNextMessage

Function Name	TR_API_GetNextMessage
Arguments	No
Description	This function returns the first message in receive message buffer, or returns empty string if there is no message in receive message buffer.
Return Value	non empty string The return value is the first message in receive message buffer. empty string It means there is no message in receive message buffer.

1.7 TR_API_CheckAndRestoreMessageLost

Function Name	TR_API_CheckAndRestoreMessageLost
Arguments	No
Description	This function checks if there are lost messages since last call of it. If your EA does not call TR_API_GetNextMessage after calling TR_API_OnTimer or TR_API_OnChartEvent, the new message will keep in the receive message buffer. If there are many messages kept in the receive message buffer, and your EA has not called TR_API_GetNextMessage, the receive message buffer will be full, and new incoming message will be lost. So when you call TR_API_CheckAndRestoreMessageLost, you can know if there are messages lost. TR_API_CheckAndRestoreMessageLost only checks if there are messages lost since last call of TR_API_CheckAndRestoreMessageLost. For example, the receive message buffer is full, you call TR_API_CheckAndRestoreMessageLost twice, and there are no new messages come between the two calls of TR_API_CheckAndRestoreMessageLost, then the first call TR_API_CheckAndRestoreMessageLost returns true which means there are lost messages, but the second call TR_API_CheckAndRestoreMessageLost returns false, because there is no lost messages since last call(the first call). Another example, the receive message buffer is full, you call TR_API_CheckAndRestoreMessageLost once, it returns true which means there are lost messages, then a new message comes and is lost because the receive message buffer is full, you call TR_API_CheckAndRestoreMessageLost again, it also returns true because there are lost messages since last call(the first call). If you always call TR_API_HasNextMessage and TR_API_GetNextMessage after calling TR_API_OnTimer or TR_API_OnChartEvent, no message should be lost unless messages come very frequently (100 messages come in less then 0.1 second), which is impossible.
Return Value	true There have been lost messages since last call of TR_API_CheckAndRestoreMessageLost false There have not been lost messages since last call of TR_API_CheckAndRestoreMessageLost

2. Retrieve Messages

Both TR_API_OnTimer and TR_API_OnChartEvent can put new incoming messages in receive message buffer. So you should call TR_API_HasNextMessage and TR_API_GetNextMessage after calling TR_API_OnTimer or TR_API_OnChartEvent.

When a new message comes, it can be put to receive message buffer by either TR_API_OnTimer or TR_API_OnChartEvent. Consider the following two cases.

Case One: A new incoming message comes, a chart event is triggered and timer out event happens at the same time. The TR_API_OnTimer is called first followed by TR_API_OnChartEvent being called, the new incoming message is put to receive message buffer by TR_API_OnTimer

Case Two: A new incoming message comes, a chart event is triggered, there is no timer out event. Only TR_API_OnChartEvent is called, and the new incoming message is put to receive message buffer by TR_API_OnChartEvent.

In both cases, the message from Trading Router server to receive message buffer is very quick, it should be less than 0.1 second. So if your EA calls TR_API_HasNextMessage and TR_API_GetNextMessage after calling TR_API_OnTimer or TR_API_OnChartEvent, your EA can process the message in less than 0.1 second after the message is sent out from Trading Router server

You can set the size of receive message buffer. The default miminum size is 100, which means the receive message buffer can save 100 messages which is enough. If the buffer is full, new incoming messages will be lost. If you always call TR_API_HasNextMessage and TR_API_GetNextMessage after calling TR_API_OnTimer or TR_API_OnChartEvent, no message should be lost unless messages come very frequently (100 messages come in less then 0.1 second), which is impossible.

3. Message Syntax

You can define your own message syntax as long as the following syntax requirements are met.

1. Message should be english characters
2. A message is composed by fields
3. A field has name and value which is connected by '=', like name=value
4. Fields are seperated by ','
5. The first field is master token
6. The second field is signal
7. Field name and value cannot contain ',' or '|'
8. The message length is less than 2000 characters

When your EA receives the message, the incoming message is in the following format

1. The token field is removed.
2. The fist field is signal field.
3. Field is seperated by '|', and there is an ending '|' at the end of the message.
4. Field name is converted to upper case, field value is the same case as what you send
5. Signal value is converted to upper case.
6. The field order may be different as what you send. For example if you send "token=xxxxxx,signal=ok,field1=1,field2=2", the received message could be "SIGNAL=OK|FIELD1=1|FIELD2=2|" or it could also be "SIGNAL=OK|FIELD2=2|FIELD1=1|"

You can use any signal value, any field name and any field value, as long as they follow the syntax requirements.