LRSN Fundamentals

LRSN is a TCP/IP based protocol. By default, an LRSN enabled device listens for new connections on TCP port 3700 (this port is registered with IANA).

Once a connection is made to the LRSN port, all communication between the LRSN server and client takes form of XML messages. Some messages are only valid when sent from the client to the server, or from the server to the client. Other messages, however, may be sent by either side.

LRSN Message Transport

All messages are XML based. With some XML parsers, it is difficult to process a continuous XML stream. To ease parsing incoming messages, the following message framing scheme is used:

Newline characters (’\n’) are used to delimit the end of a message. The data between two newlines should form a parsable XML document (i.e. all tags balanced).
Newline characters are not allowed except to delimit messages. This is not an issue for most mes- sages used in the LRSN. In cases where a newline is required in the text of an element, the newline character should be replaced with the character reference for newline ( ).

Logging into the LRSN

The procedure for a client to logon to an LRSN server is as follows:

Connect to port 3700/TCP.
Receive message.
Send message with appropriate login credentials.

Message

When the connection to an LRSN server is opened, the LRSN server first sends an message, informing the client of what type of device it has connected to, what services it offers, and the login method required by the server. It is only sent by the server, it is the first message sent after the initial connection, and it is only sent at the initial connection.

<LRSN services="serv1:ver;...;servn:ver" device="devname" hwver="..." swver="..." login="..." />

Attribute	Description	Details
`services`	The services attribute provides a list of the services which are available on the server. The services list is semicolon delimited. Optionally, the version of the service may be specified by a colon following the service name, followed by the version. Example: `services="NetPage:2.1;TableMan"`	Always present
`device`	The device attribute specifies the type of device the client has connected to. Example: `device="T7500"`	Present if server is an LRS hardware unit
`hwver`	The hwver attribute specifies the hardware version the server is running on. This attribute is only included for LRSN servers which run on custom LRS hardware. Some applications, such as NetPage Server, may run on a PC. These types of servers will not include an hwver tag.	Always present
`swver`	The swver attribute specifies the software or firmware version the server is running.	Always present
`serno`	The serial number of the hardware unit the LRSN server is running on. Absent if server does not have a serial number.	Present if server has a serial number
`login`	The login attribute specifies the login method the server requires. Values may be `none` or `passwd`. If login is `none`, then no authentication is required by the server. However, a `<Login>` message is required to register for services on the server. If login is `passwd`, then a `<Login>` message with proper login credentials must be sent by the client before continuing.	Always present

Message

The client must send a <Login> message to the server for two reasons.

The <Login> message contains the list of services that the client is wishing to use.
The <Login> message verifies the client is authorized to use the LRSN server. The verification method required depends upon the value of the login attribute in the <LRSN> message.

Attribute	Description	Details
services	The `services` attribute is a semi-colon delimited list of LRSN services the client wishes to use. If the services attribute is missing, then the server will assume the client wishes to use all services the server offers. Otherwise, the server will limit the services it provides the client based on the list returned here. Any services the client specifies but the server does not provide are silently ignored. Example: `services="NetPage;KeyCallTX"`	Optional

If the login attribute in the <LRSN> message was "passwd", then the client should include user and passwd attributes in its <Login> message. The user name and password should be a valid pair for the server. Example (client uses all services by omitting services attribute):

<Login user="authorized_user" passwd="correct_password" />

Example logging in use password, requesting only NetPage service:

<Login user="geoffrey" passwd="mypassword" services="NetPage" />

After receiving a <Login> message, the LRSN server will respond with a <LoginAck> message, indicating the success or failure of the Login.

Message

If a <Login> message is required from the client, the server responds to the client’s <Login> message with a <LoginAck> message.

The <LoginAck> message contains a single attribute, ret, which indicates the success or failure of the login. If the login failed, the ret element will indicate the reason the login failed. The master list of return codes lists a large number of possible responses from the server. However, for a <LoginAck>, the common responses would be ESUCCESS, ELOGIN, ELICEXCEED, ELICEXPIRE, ESERVDOWN, and EMAXCLIENTS.

The <LoginAck> message also contains a services attribute, indicating which services the client is actually subscribed to.

Example of successful login:

<LoginAck ret="0" services="KeyCallTX;Heartbeat"/>

Example of login that failed due to too many clients for server license:

<LoginAck ret="2" />

If the ret attribute is anything other than ESUCCESS (0), then the server will disconnect the client immediately after transmitting the <LoginAck> message. If the result is ESUCCESS, then the session begins after the server sends the <LoginAck> message.