RemoteInputProtocol
|
Size: 8886
Comment:
|
← Revision 33 as of 2009-10-12 16:02:52 ⇥
Size: 13789
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 2: | Line 2: |
<<TableOfContents(3)>> |
|
| Line 25: | Line 27: |
| The credentials length field specifies the total size of the following fields. The NULL fields must be set to 0. These fields put two limits on the username and password: | The credentials length field specifies the total size of the following fields. The NULL field must be set to 0. These fields put two limits on the username and password: |
| Line 40: | Line 42: |
| All communication after the channel has been secured and authenticated must follow the Remote Input Message Protocol. All messages are padded as necessary to have a length of 12 bytes. All values larger than one byte in length are in network byte order. The first four bytes are an unsigned integer specifying the message type. The following messages are supported in version 1 of the remote input message protocol: | All communication after the channel has been secured and authenticated must follow the Remote Input Message Protocol. The remote input client may terminate the connection with the server at any point, and the server must immediately destroy all state associated with the connection. The server must not terminate the connection except after an error message with a type that requires the server to do so. Any other connection termination by the server should be interpreted by the client to be in error. All messages are padded as necessary to have a length of 12 bytes. All values larger than one byte in length are in network byte order. The first four bytes are an unsigned integer specifying the message type. The following messages are supported in version 1 of the remote input message protocol: |
| Line 57: | Line 61: |
| Capability Type; 4; Unsigned Integer; See table below Capability Code; 2; Unsigned Integer; Capability code, specific to capability type, see linux/input.h header file for values }}} ==== Capability Types ==== There a seven capability event categories. To enable event capabilities in a category, the category itself must be enabled. This is accomplished by using the Input Event Capability Category type and the category's type value as defined in linux/input.h. After enabling a capability category, event capabilities may be set. This is accomplished by using the event capability type value listed in the table below with the capability code listed in linux/input.h. /!\ '''Note: The category type values in linux/input.h may or may not equal the category type value specified in the table below.''' {{{#!CSV Description; Value Input Event Capability Category; 0 Key Event; 1 Relative Event; 2 Absolute Event; 3 Miscellaneous Event; 4 Switch Event; 5 LED Output Event; 17 Sound Output Event; 18 |
Capability Category; 2; Unsigned Integer; See capability categories below Capability Code; 2; Unsigned Integer; Capability code, specific to capability type, see rinput.h header file for values }}} ==== Capability Categories ==== The following capability categories are specified for version 1 of the remote input message protocol. Values are provided in the rinput.h header file. {{{#!CSV Value; Description RINPUT_EV_KEY; Key and button presses that have on/off states, i.e. keyboard keys and mouse buttons RINPUT_EV_REL; Relative value events, i.e. mouse pointer movements RINPUT_EV_ABS; Absolute value events, i.e. track pad event locations RINPUT_EV_MSC; Miscellaneous input events, not generally useful for remote input devices RINPUT_EV_SW; Switches that generally have two states, i.e. lid switch RINPUT_EV_LED; Output event sent from server to client, has on/off state RINPUT_EV_SND; Output event sent from server to client, momentary trigger RINPUT_EV_UTF8; Unicode character input event |
| Line 80: | Line 82: |
| === Input Device Set Absolute Axis Parameter === This message informs the remote input server of special parameters related to absolute input events. The maximum and minimum parameters determine the maximum and minimum values that may be generated in an event on the axis. The fuzz parameter sets a zone around the previous absolute event wherein current event values within the zone are gradually averaged with the previous event. The flat parameter specifies a dead zone around the previous event wherein current event values within the zone are ignored. All parameter values for all axes default to 0 if no message specifying otherwise is sent. {{{#!CSV Field; Bytes; Type; Value Message Type; 4; Unsigned Integer; 2 Absolute Axis; 2; Unsigned Integer; An absolute axis, see rinput.h for possible values Parameter Type; 2; Unsigned Integer; An absolute axis parameter, see table below Value; 4; Signed Integer; Parameter value }}} ==== Absolute Axis Parameter Types ==== The following absolute axis parameter types are specified for version 1 of the remote input message protocol. Values are provided in the rinput.h header file. {{{#!CSV Value; Description RINPUT_ABS_PARAM_MAX; Maximum possible value of absolute events for the specified axis RINPUT_ABS_PARAM_MIN; Minimum possible value of absolute events for the specified axis RINPUT_ABS_PARAM_FUZZ; Fuzz factor for absolute events for the specified axis RINPUT_ABS_PARAM_FLAT; Dead zone for absolute events for the specified axis }}} |
|
| Line 81: | Line 107: |
| This message informs the remote input server that the full capabilities of the remote input device have been set. The server must then create the input device. {{{#!CSV Field; Bytes; Type; Value Message Type; 4; Unsigned Integer; 2 |
This message informs the remote input server that the full capabilities of the remote input device have been set. The server must then create the input device. After the server creates the input device it must echo the create message back to the client. When the client receives the create message echo it may begin sending input events. {{{#!CSV Field; Bytes; Type; Value Message Type; 4; Unsigned Integer; 3 |
| Line 93: | Line 119: |
| Message Type; 4; Unsigned Integer; 3 | Message Type; 4; Unsigned Integer; 4 |
| Line 97: | Line 123: |
| This message informs the remote input server that the remote input client had an input event. {{{#!CSV Field; Bytes; Type; Value Message Type; 4; Unsigned Integer; 4 Input Event Type; 2; Unsigned Integer; Input event category type, see linux/input.h for values Input Event Code; 2; Unsigned Integer; Input event code specific to input event category, see linux/input.h for values |
This message informs the receiver of an input event. LED and sound events may only be sent by the server to the client. All other events may only be sent by the client to the receiver. After all events occurring at a single point in time are sent, the RINPUT_EV_SYN event must be sent. This event tells the server to process the preceding events as though they occurred at the same time. For example, if the mouse pointer moved one point up and to the right, an RINPUT_REL_X and RINPUT_REL_Y relative events would be sent followed by an RINPUT_EV_SYN event. The code and value of syn events are undefined. {{{#!CSV Field; Bytes; Type; Value Message Type; 4; Unsigned Integer; 5 Input Event Type; 2; Unsigned Integer; Input event category type, see rinput.h header file for values Input Event Code; 2; Unsigned Integer; Input event code specific to input event category, see rinput.h header file for values |
| Line 107: | Line 135: |
| /!\ '''Note: The input event category type value used in this message must conform to the values in linux/input.h, which may or may not equal the category values used during the set capability message''' | === Input Device UTF-8 event Message === This message informs the remote input server that a key signifying a Unicode character generated an event. It has the same message type as normal input event messages, but the data has a different format. {{{#!CSV Field; Bytes; Type; Value Message Type; 4; Unsigned Integer; 5 Input Event Type; 2; Unsigned Integer; RINPUT_EV_UTF8 Input Event Value; 2; Signed Integer; Input event value specific to input event code and category type Character; 4; Byte Array; UTF-8 encoded Unicode character }}} |
| Line 114: | Line 151: |
| Message Type; 4; Unsigned Integer; 5 Error Code; 4; Unsigned Integer; Error code value |
Message Type; 4; Unsigned Integer; 6 Error Type; 4; Unsigned Integer; Error type value Error Code 1; 2; Unsigned Integer; First error code specific to error type Error Code 2; 2; Unsigned Integer; Second error code specific to error type |
| Line 122: | Line 161: |
| Error Event; When it may occur; Error Code; Server closes connnection Internal error causing premature termination of service of not matching any other error defined below; Any time; 0; Yes Input device allocation failed; After client connects but before the server processes any input event set capability messages; 1; Yes Message type invalid; After client sends a remote input message; 2; No Capability type invalid; After client sends an input device set capability message; 3; No Capability set operation failed; After client sends an input device set capability message; 4; No Input device creation failed; After client sends an input device create message; 5; Yes Input device event message failed; After server receives input device event message; 6; No |
Error Event; When it may occur; Error Type; Error Code 1 Meaning; Error Code 2 Meaning; Server closes connection Internal error causing premature termination of service not matching any other defined error; Any time; 0; ; ; Yes Input device allocation failed; After client connects but before the server processes any input event set capability messages; 1; ; ; Yes Message type invalid; After client sends a remote input message; 2; Received message type; ; No Capability type invalid; After client sends an input device set capability message; 3; Received capability type; ; No Capability set operation failed; After client sends an input device set capability message; 4; Received capability type; Received capability code; No Absolute axis invalid; After client sends an input device set absolute axis parameter message; 5; Received absolute axis; ; No Absolute axis parameter type invalid; After client sends an input device set absolute axis parameter message; 6; Received absolute axis parameter type; ; No Input device creation failed; After client sends an input device create message; 7; ; ; Yes Input device event message failed; After server receives input device event message; 8; Received input event type; Received input event code; No Authenticate revoked by server; Any time; 9; ; ; Yes |
| Line 136: | Line 178: |
| At any point the server may send an error message to the client and, if allowed for the error type, then terminate the connection. | At any point the server may send an error message to the client and, if required for the error type, then terminate the connection. |
| Line 140: | Line 182: |
| === 1. Receive remote input protocol version message from server === | === Receive remote input protocol version message from server === |
| Line 143: | Line 185: |
| === 2. Set input device capabilities === The client must send the capabilities of the input device it represents. First, it must send messages enabling input event category types. Then, it must send messages enabling specific capabilities for each enabled category type. |
=== Set input device capabilities === The client must send the capabilities of the input device it represents. The client must listen for error messages while setting capabilities. These error messages may indicate capabilities that are unsupported by the server. === Set absolute axis parameter values === The client must send absolute axis parameter values for all axes the device sent capability messages for. All parameters default to 0, so only parameters differing from 0 must be specified. |
| Line 147: | Line 192: |
| To set the capabilities for a simple remote mouse with one button and no scroll wheels, send input event set capability messages with the following values: {{{#!CSV Message Type; Capability Type (From Remote Input Set Capability Message Capability Types); Capability Code (From linux/input.h) 1; 0 (Input Event Capability Category); EV_KEY (Enable button capability for mouse button) 1; 0 (Input Event Capability Category); EV_REL (Enable relative capability for mouse movement) 1; 1 (Key Event Capability Category); BTN_MOUSE 1; 2 (Relative Event Capability Category); REL_X 1; 2 (Relative Event Capability Category); REL_Y }}} === 3. Create input device === |
To set the capabilities for a simple remote mouse with one button and no scroll wheels, send input event set capability messages with the following values (defined in rinput.h header file): {{{#!CSV Message Type; Capability Category; Capability Code 1; RINPUT_EV_KEY; RINPUT_BTN_MOUSE 1; RINPUT_EV_REL; RINPUT_REL_X 1; RINPUT_EV_REL; RINPUT_REL_Y }}} === Create input device === |
| Line 160: | Line 203: |
=== Receive input device create echo === The client must receive the input device create message echoed back by the server before it may continue. == Input Device Events == After the remote input device has been initialized, the client may send input device event messages. There is no explicit documentation for the values allowed, but they may be inferred from the rinput.h header file. Input events for unset capabilities and/or events for invalid input types or codes will generate error messages from the server. One special addition to the input protocol is necessary for momentary key presses. When the server receives a key event with value 256 it must immediately propagate two key events with the same code to the input subsystem: the first with value 1 and the second with value 0. In between the two events the server must also pass a syn event to the input subsystem if required for the platform. After any message, the server may send an error message back. The error message is in reference to a previous remote input event message, but the specific message causing the error is left unspecified. When the remote input client intends to end the remote input session it must immediately close the communication channel to the remote input server. |
![Warning /!\](/moin_static198/light/img/icon_eek.png "Warning /!\"){kind=icon}
This protocol is a work in progress and is not complete.
Contents
The remote input server uses an open protocol with encryption and authentication to communicate between the clients and the server.
Security
When the client connects to the server, an SSL connection must be initiated immediately. Most remote input server installations use self-signed certificates, so the client should be able to verify the server through the SSL certificate fingerprint. The fingerprint is a digest (usually SHA1) of the DER form of the SSL certificate. It may be determined on the server by running:
$ openssl x509 -noout -in <certificate file> -fingerprint
If the client cannot verify the certificate through the certificate authority chain or by fingerprint verification it must close the connection immediately.
Authentication
After the SSL connection has been created, the client must send authentication credentials to the server. The credentials have the following form:
The credentials length field specifies the total size of the following fields. The NULL field must be set to 0. These fields put two limits on the username and password:
- The combined length of the username and password, not including the null terminator, must be less than 253.
- The username and the password may not include the null character.
The server must validate the credentials. The server sends a one byte message to the client indicating whether the credentials are valid:
If the result was invalid, the server must immediately close all communication with the client after sending the credential validation result. If the client was authenticated, the client should begin the input device initialization process.
Remote Input Message Protocol
All communication after the channel has been secured and authenticated must follow the Remote Input Message Protocol. The remote input client may terminate the connection with the server at any point, and the server must immediately destroy all state associated with the connection. The server must not terminate the connection except after an error message with a type that requires the server to do so. Any other connection termination by the server should be interpreted by the client to be in error.
All messages are padded as necessary to have a length of 12 bytes. All values larger than one byte in length are in network byte order. The first four bytes are an unsigned integer specifying the message type. The following messages are supported in version 1 of the remote input message protocol:
Remote Input Protocol Version Message
This message, sent by the remote input server, specifies the version of the remote input message protocol. This standard defines only version 1 of the protocol, so the value must be 1.
Input Device Set Capability Message
This message, sent by the remote input client, specifies a capability of the remote input device. The server must ensure that the input device instantiated is capable of receiving events of this type.
Capability Categories
The following capability categories are specified for version 1 of the remote input message protocol. Values are provided in the rinput.h header file.
Event capability categories not listed above, such as force feedback events, are not supported in this version of the remote input message protocol.
Input Device Set Absolute Axis Parameter
This message informs the remote input server of special parameters related to absolute input events. The maximum and minimum parameters determine the maximum and minimum values that may be generated in an event on the axis. The fuzz parameter sets a zone around the previous absolute event wherein current event values within the zone are gradually averaged with the previous event. The flat parameter specifies a dead zone around the previous event wherein current event values within the zone are ignored.
All parameter values for all axes default to 0 if no message specifying otherwise is sent.
Absolute Axis Parameter Types
The following absolute axis parameter types are specified for version 1 of the remote input message protocol. Values are provided in the rinput.h header file.
Input Device Create Message
This message informs the remote input server that the full capabilities of the remote input device have been set. The server must then create the input device. After the server creates the input device it must echo the create message back to the client. When the client receives the create message echo it may begin sending input events.
Input Device Destroy Message
This message informs the remote input server that the input device must be destroyed.
Input Device Event Message
This message informs the receiver of an input event. LED and sound events may only be sent by the server to the client. All other events may only be sent by the client to the receiver.
After all events occurring at a single point in time are sent, the RINPUT_EV_SYN event must be sent. This event tells the server to process the preceding events as though they occurred at the same time. For example, if the mouse pointer moved one point up and to the right, an RINPUT_REL_X and RINPUT_REL_Y relative events would be sent followed by an RINPUT_EV_SYN event. The code and value of syn events are undefined.
Input Device UTF-8 event Message
This message informs the remote input server that a key signifying a Unicode character generated an event. It has the same message type as normal input event messages, but the data has a different format.
Input Device Error Message
The remote input server must send an error message to the client if certain errors are encountered.
Error Events and Codes
If any of the following events occurs in the remote input server, it must send the matching event error code to the client. If the error requires the server to close the connection, the server must close the connection immediately after sending the error message.
Input Device Initialization
After the communication channel has been secured and authenticated, the client must begin initializing the input device to be instantiated by the server. All messages after authentication must conform to the remote input message protocol.
At any point the server may send an error message to the client and, if required for the error type, then terminate the connection.
The following initialization steps must be performed by the client in order:
Receive remote input protocol version message from server
The client must receive the protocol version and determine whether to proceed based on whether the client supports the protocol version. If the client does not proceed, it must immediately terminate communication with the server.
Set input device capabilities
The client must send the capabilities of the input device it represents. The client must listen for error messages while setting capabilities. These error messages may indicate capabilities that are unsupported by the server.
Set absolute axis parameter values
The client must send absolute axis parameter values for all axes the device sent capability messages for. All parameters default to 0, so only parameters differing from 0 must be specified.
Example: Simple one button mouse
To set the capabilities for a simple remote mouse with one button and no scroll wheels, send input event set capability messages with the following values (defined in rinput.h header file):
Create input device
The client must send the input device create message after all the device capabilities have been set.
Receive input device create echo
The client must receive the input device create message echoed back by the server before it may continue.
Input Device Events
After the remote input device has been initialized, the client may send input device event messages. There is no explicit documentation for the values allowed, but they may be inferred from the rinput.h header file. Input events for unset capabilities and/or events for invalid input types or codes will generate error messages from the server.
One special addition to the input protocol is necessary for momentary key presses. When the server receives a key event with value 256 it must immediately propagate two key events with the same code to the input subsystem: the first with value 1 and the second with value 0. In between the two events the server must also pass a syn event to the input subsystem if required for the platform.
After any message, the server may send an error message back. The error message is in reference to a previous remote input event message, but the specific message causing the error is left unspecified.
When the remote input client intends to end the remote input session it must immediately close the communication channel to the remote input server.
RemoteInput/RemoteInputProtocol (last edited 2009-10-12 16:02:52 by cpe-75-180-27-10)