TNI Socket Interface
(Created page with "TNISocket is a builtin TNILibrary within Trainz which allows TNI plugins to communicate via TCP/IP sockets. Before continuing, it is recommended you first familiarise yoursel...") |
Revision as of 10:12, 12 December 2017
TNISocket is a builtin TNILibrary within Trainz which allows TNI plugins to communicate via TCP/IP sockets.
Before continuing, it is recommended you first familiarise yourself with the following pages:
- TrainzNativeInterface - For an overview of TNI and the associated licensing requirements
- TNI Core Interface - For details of the core TNI functionality, object types, etc.
NOTE: This page is a work in progress, and reflects technologies which are not yet present in retail versions of Trainz.
Contents |
Overview
TNISocket is a TNILibrary built into Trainz native code. It is entirely thread safe, and may be loaded and called at any time from within any TNI plugin DLL.
TNISocket communication is implemented through TNIStream. Certain stream operations, such as TNIStreamTell(), TNIStreamGetSize(), and TNIStreamStoreObjectReference(), are not available on socket streams. All TNIStream operations are blocking, and are interrupted by stream closure.
As TNISocket is a blocking interface, any call made will block the calling thread until it completes or fails. Care must be taken to ensure that your TNI Plugin does not become unresponsive - this will not affect the Trainz client but may affect your plugin's user experience and may be cause for rejection of your plugin. The simplest approach is to spawn a new thread per socket, ensuring that delays on a socket do not lead to delays on your TNI Plugin's librarycall interface. Since most TNI plugins will only work with one socket, this is not expected to cause any difficulties or performance concerns.
All data is encoded as raw binary with no additional protocol. Text strings are sent as a 32-bit length followed by raw UTF8. AssetIDs do not yet have a standardised format and should not be used. Raw data bytes may be sent using TNIStreamWriteInt8Array().
Text-based protocols can be implemented by building the desired string and sending it via TNIStreamWriteInt8Array(), and by reading character-at-a-time using TNIStreamReadInt8() until encountering the appropriate CR/LF sequence.
