TNI Socket Interface

From TrainzOnline
(Difference between revisions)
Jump to: navigation, search
(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:

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.

TNISocket Library Calls

OpenRemote

Listen

Close

Poll

NotifyConnection

NotifyPoll

Personal tools