{{tag>igde testing remote network}}
<WRAP youarehere>
[[:start|Start Page]] >> [[:gamedev|Game Development with the Drag[en]gine]] >> [[gamedev:remotelaunching|Remote Launching]] >> **Remote Launcher Network Protocol**
</WRAP>

====== Remote Launcher Network Protocol ======

The Remote Launcher Network Protocol uses the [[gamedev:dnp|Drag[en]gine Network Protocol]] as protocol and defines a set of ''messages'' and ''linked states'' supported by IGDE and Remote Launchers. The specification can change with upcoming Drag[en]gine updates but stays backwards compatible. Servers and clients are required to ignore unknown messages and linked states.

To implement this protocol best use [[https://github.com/LordOfDragons/denetwork/releases|Drag[en]gine Network Library]] and add the necessary message and state handling.

====== Messages ======

These are all messages the server and the client can send to each other.

===== Connect Request =====

Upon connecting the client has to send this message to request access to IGDE indicating the kinds of features it supports. The connect request message has this format:

^  Type  ^  Name  ^  Description  ^
| [[gamedev:dnp#data_types|Byte]] | Code | Message code. Is value ''1'' |
| [[gamedev:dnp#data_types|Byte]][16] | Signature | Identifies the connecting client as a Remote Launcher client. Value has to be ''![DERemLaunchCnt-0]!''. |
| [[gamedev:dnp#data_types|UInt]] | SupportedFeatures | <WRAP>
Features supported by the client. Flags value with these possible values:
  * //No flags defined. Reserved for future expansion//
</WRAP> |
| [[gamedev:dnp#data_types|String8]] | Name | Name describing the remote client connecting. This is a free form name of short length chosen by the developer to distinguish multiple connected clients in the IGDE. |
|  -  | Reserved | Reserved for future expansion. Ignore any additional bytes in the message |

The server will then respond with a [[#connect_accepted|Connect Accepted]] message or disconnect the client if rejected.

===== Connect Accepted =====

Send by the server after a client connects which send [[#connect_request|Connect Request]] message identifying itself as a Remote Launcher client. This is the first message received from the server. The client should not send any messages until it has received this message as this will get him disconnected. The message is send reliable and has this format:

^  Type  ^  Name  ^  Description  ^
| [[gamedev:dnp#data_types|Byte]] | Code | Message code. Is value ''2'' |
| [[gamedev:dnp#data_types|Byte]][16] | Signature | Identifies the server as a Remote Launcher server. Value is <wrap hi>''![DERemLaunchSrv-0]!''</wrap>. If this value is not matching the client has to disconnect immediately as it is not connecting to a Remote Launcher server. |
| [[gamedev:dnp#data_types|UInt]] | EnabledFeatures | Enabled features supported by both the connecting client and the server. Same possible values as in ''SupportedFeatures'' in [[#connect_request|Connect Request]] message |
|  -  | Reserved | Reserved for future expansion. Ignore any additional bytes in the message |

===== Request File Layout =====

Send by the server to request the file layout of the client. The client has to scan the entire date storage where the project files are located and record the file parameters. Since this process can be lengthy the client typically stores the file layout in memory and updates it as files are modified. The message is send reliable and has this format:

^  Type ^  Name  ^  Description  ^
| [[gamedev:dnp#data_types|Byte]] | Code | Message code. Is value ''3'' |
|  -  | Reserved | Reserved for future expansion. Ignore any additional bytes in the message. |

Once the file layout is ready a [[#response_file_layout|Response File Layout]] message is send.

===== Response File Layout =====

Send by the client in response to a [[#request_file_layout|Request File Layout]] message containing the scanned file layout. The message is send reliable and has this format:

^  Type  ^  Name  ^  Description  ^
| [[gamedev:dnp#data_types|Byte]] | Code  | Message code. Is value ''4'' |
| [[gamedev:dnp#data_types|UInt]] | Count | Count of file entries. |
| FileInfo | Files[Count] | File information. |
|  -  | Reserved | Reserved for future expansion. Ignore any additional bytes in the message. |

Where ''FileInfo'' is:
^  Type  ^  Name  ^  Description  ^
| [[gamedev:dnp#data_types|String16]] | Path | File path relative to root of data directory. |
| [[gamedev:dnp#data_types|ULong]] | Size | File size in bytes. |
| [[gamedev:dnp#data_types|String8]] | Hash | Hash of file (SHA-256). |

===== Request File Block Hashes =====

Send by the server to request block wise hashes of a file from the client. Block wise hashes are useful for large files to avoid updating the entire file. Since this process can be lengthy the client typically stores the block wise hashes for a file in memory if requested. The message is send reliable and has this format:

^  Type ^  Name  ^  Description  ^
| [[gamedev:dnp#data_types|Byte]] | Code | Message code. Is value ''5'' |
| [[gamedev:dnp#data_types|String16]] | Path | File path relative to root of data directory. |
| [[gamedev:dnp#data_types|UInt]] | BlockSize | Size of blocks in bytes. |

Once the block wise hashes are calculated a [[#response_file_block_hashes|Response File Block Hashes]] message is send.

===== Response File Block Hashes =====

Send by the client in response to a [[#request_file_block_hashes|Request File Block Hashes]] message containing the file block hashes. The message is send reliable and has this format:

^  Type  ^  Name  ^  Description  ^
| [[gamedev:dnp#data_types|Byte]] | Code  | Message code. Is value ''6'' |
| [[gamedev:dnp#data_types|String16]] | Path | File path relative to root of data directory. |
| [[gamedev:dnp#data_types|UInt]] | Count | Count of blocks. |
| BlockInfo | Blocks[Count] | Blocks in file order. |
|  -  | Reserved | Reserved for future expansion. Ignore any additional bytes in the message. |

Where ''BlockInfo'' is:
^  Type  ^  Name  ^  Description  ^
| [[gamedev:dnp#data_types|String8]] | Hash | Block hash (SHA-256). |

===== Request Delete File =====

Send by the server to request the client to delete a file. The message is send reliable and has this format:

^  Type ^  Name  ^  Description  ^
| [[gamedev:dnp#data_types|Byte]] | Code | Message code. Is value ''7'' |
| [[gamedev:dnp#data_types|String16]] | Path | Path relative to to root of data directory. |
|  -  | Reserved | Reserved for future expansion. Ignore any additional bytes in the message. |

Once the operation finished (either successfully or not) a [[#response_delete_file|Response Delete File]] message is send.

===== Response Delete File =====

Send by the client in response to a [[#request_delete_file|Request Delete File]] message. Indicates if the operation succeeded or not. The message is send reliable and has this format:

^  Type  ^  Name  ^  Description  ^
| [[gamedev:dnp#data_types|Byte]] | Code  | Message code. Is value ''8'' |
| [[gamedev:dnp#data_types|String16]] | Path | File path relative to root of data directory. |
| [[gamedev:dnp#data_types|Byte]] | Result | <WRAP>Result of delete operation. Can be one of these values:
  * ''0'': File has been deleted.
  * ''1'': File could not be deleted.
Additional result codes can be added in the future to indicate better what has been the problem. Servers have to consider all values except ''0'' as a failure.</WRAP> |
|  -  | Reserved | Reserved for future expansion. Ignore any additional bytes in the message. |

===== Request Write File =====

Send by the server to request the client to start writing a file. The message is send reliable and has this format:

^  Type ^  Name  ^  Description  ^
| [[gamedev:dnp#data_types|Byte]] | Code | Message code. Is value ''9'' |
| [[gamedev:dnp#data_types|String16]] | Path | File path relative to root of data directory. |
| [[gamedev:dnp#data_types|ULong]] | FileSize | File size in bytes. |
| [[gamedev:dnp#data_types|ULong]] | BlockSize | Block size in bytes. |
| [[gamedev:dnp#data_types|UInt]] | BlockCount | Block count. |
|  -  | Reserved | Reserved for future expansion. Ignore any additional bytes in the message. |

The client has to mark the file as in progress for writing. If the file size is shorter than the existing file the file has to be truncated. File writing has to be done in overwrite mode hence the file content is retained. This allows updating only ranges of data inside large files. Data to write is send using reliable [[#send_file_data|Send File Data]] messages.

Once ready the client has to send back a [[#response_write_file|Response Write File]].

===== Response Write File =====

Send by the client in response to a [[#request_write_file|Request Write File]] message. The message is send reliable and has this format:

^  Type ^  Name  ^  Description  ^
| [[gamedev:dnp#data_types|Byte]] | Code | Message code. Is value ''10'' |
| [[gamedev:dnp#data_types|String16]] | Path | File path relative to root of data directory. |
| [[gamedev:dnp#data_types|Byte]] | Result | <WRAP>Result of operation. Can be one of these values:
  * ''0'': File is ready to be written to.
  * ''1'': File can not be written.
Additional result codes can be added in the future. Servers have to consider all values except ''0'' as a failure.</WRAP> |
|  -  | Reserved | Reserved for future expansion. Ignore any additional bytes in the message. |

===== Send File Data =====

Message send by the server to client with data to write to a file. For each block a message is send. Blocks are send in order from first to last. The message is send reliable and has this format:

^  Type ^  Name  ^  Description  ^
| [[gamedev:dnp#data_types|Byte]] | Code | Message code. Is value ''11'' |
| [[gamedev:dnp#data_types|String16]] | Path | File path relative to root of data directory. |
| [[gamedev:dnp#data_types|UInt]] | Block | Index of block to write the data to. |
| [[gamedev:dnp#data_types|Byte]][*] | Data | Remaining bytes in the message is the data to write to the block. |

Receiving and processing the message (successful or not) requires the client to send a [[#file_data_received|File Data Received]] message.
===== File Data Received =====

Send by the client after receiving a [[#send_file_data|Send File Data]] message. The message is send reliable and has this format:

^  Type  ^  Name  ^  Description  ^
| [[gamedev:dnp#data_types|Byte]] | Code  | Message code. Is value ''12'' |
| [[gamedev:dnp#data_types|String16]] | Path | File path relative to root of data directory. |
| [[gamedev:dnp#data_types|UInt]] | Block | Index of block that has been written to. |
| [[gamedev:dnp#data_types|Byte]] | Result | <WRAP>Result of write operation. Can be one of these values:
  * ''0'': Writing data has been successful.
  * ''1'': Writing data has failed.
Additional result codes can be added in the future to indicate better what has been the problem. Servers have to consider all values except ''0'' as a failure.</WRAP> |
|  -  | Reserved | Reserved for future expansion. Ignore any additional bytes in the message. |

===== Request Finish Write File =====

Send by the server to request the client to finish writing a file. The message is send reliable and has this format:

^  Type ^  Name  ^  Description  ^
| [[gamedev:dnp#data_types|Byte]] | Code | Message code. Is value ''13'' |
| [[gamedev:dnp#data_types|String16]] | Path | Path relative to root of data directory to finish writing. |
| [[gamedev:dnp#data_types|String8]] | Hash | Hash of file (SHA-256) to verify file synchronized correctly. |
|  -  | Reserved | Reserved for future expansion. Ignore any additional bytes in the message. |

The client has to mark the file as finished writing and ready to be used.

Once ready the client has to send back a [[#response_finish_write_file|Response Finish Write File]].

===== Response Finish Write Files =====

Send by the client in response to a [[#request_finish_write_file|Request Finish Write File]] message. The message is send reliable and has this format:

^  Type ^  Name  ^  Description  ^
| [[gamedev:dnp#data_types|Byte]] | Code | Message code. Is value ''14'' |
| [[gamedev:dnp#data_types|String16]] | Path | File path relative to root of data directory. |
| [[gamedev:dnp#data_types|Byte]] | Result | <WRAP>Result of operation. Can be one of these values:
  * ''0'': File has been successfully written.
  * ''1'': Writing file failed.
  * ''2'': After write file hash verification failed.
Additional result codes can be added in the future. Servers have to consider all values except ''0'' as a failure.</WRAP> |
|  -  | Reserved | Reserved for future expansion. Ignore any additional bytes in the message. |

===== Start Application =====

Send by the server to request the client to start application. The message is send reliable and has this format:

^  Type  ^  Name  ^  Description  ^
| [[gamedev:dnp#data_types|Byte]] | Code | Message code. Is value ''15'' |
| [[gamedev:dnp#data_types|String16]] | GameConfig | Content of ''*.degame'' file used to launch the application. |
| [[gamedev:dnp#data_types|String8]] | ProfileName | Name of profile to use for launching the application. Use default if empty string. |
| [[gamedev:dnp#data_types|String16]] | Arguments | Command line arguments to use. Use none if empty string. |
|  -  | Reserved | Reserved for future expansion. Ignore any additional bytes in the message |


===== Stop Application =====

Send by the server to request the client to stop application. The message is send reliable and has this format:

^  Type  ^  Name  ^  Description  ^
| [[gamedev:dnp#data_types|Byte]] | Code | Message code. Is value ''16'' |
| [[gamedev:dnp#data_types|Byte]] | Mode | <WRAP>How to stop the application. Can be one of these values:
  * ''0'': Request closing application using system means. This can be for example a close application or close window event.
  * ''1'': Kill application. Used if the application is not responding to closing.
Additional result codes can be added in the future. Clients have to ignore unknown values.</WRAP> |
|  -  | Reserved | Reserved for future expansion. Ignore any additional bytes in the message |

===== Logs =====

Send by the client to send logs to the server. Logs are send as lines. The message is send reliable and has this format:

^  Type  ^  Name  ^  Description  ^
| [[gamedev:dnp#data_types|Byte]] | Code | Message code. Is value ''17'' |
| [[gamedev:dnp#data_types|Byte]] | Level | <WRAP>Log level. Can be one of these values:
  * ''0'': Information.
  * ''1'': Warning.
  * ''2'': Error.
Additional levels can be added in the future. Servers have to consider all unknown values as being ''0''.</WRAP> |
| [[gamedev:dnp#data_types|String8]] | Timestamp | Timestamp in text form. |
| [[gamedev:dnp#data_types|String16]] | Message | Log message. |
|  -  | Reserved | Reserved for future expansion. Ignore any additional bytes in the message. |


===== Request System Property =====

Send by the server to request information about the system the client is running on. The server indicates which property to query. The client has to return the requested property value if it is supported and the value can be determined. Otherwise the client has to return an empty response. The message is send reliable and has this format:

^  Type ^  Name  ^  Description  ^
| [[gamedev:dnp#data_types|Byte]] | Code | Message code. Is value ''18'' |
| [[gamedev:dnp#data_types|String8]] | Property | <WRAP>Name of property to query. Can be one of these values:
  * ''properties.names'': List of all properties supported by the client. The server can safely query any of these properties. This is the only property name the client has to support.
  * ''profiles.names'': List of launcher profile names. 
  * ''profiles.default'': Name of default profile or empty string if there is none.
Additional property names can be added in the future. Applications can define custom property names. Clients have to return empty value for unknown properties.</WRAP> |
|  -  | Reserved | Reserved for future expansion. Ignore any additional bytes in the message. |

The client sends back a [[#response_system_property|Response System Property]] message.

===== Response System Property =====

Send by the client in response to a [[#request_system_property|Request System Property]] message. The response contains the property value if the client supports the property and can determine the value. Otherwise the client sends an response with empty data. The message is send reliable and has this format:

^  Type  ^  Name  ^  Description  ^
| [[gamedev:dnp#data_types|Byte]] | Code  | Message code. Is value ''19'' |
| [[gamedev:dnp#data_types|String8]] | Property | Same value as ''Property'' in request. |
| [[gamedev:dnp#data_types|Strgin16]] | PropertyData | <WRAP>Value of property depending of type or empty if not supported.
The length and format of ''PropertyData'' depends on the property type.
  * ''properties.names'': Newline separated list of property names. For example ''Profile A\nProfile B''.
  * ''profiles.names'': Newline separated list of profile names. For example ''Profile A\nProfile B''.
  * ''profiles.default'': Name of default profile or empty string if there is none.
Additional property names can be added in the future. Applications can define custom property names. Clients have to return empty value for unknown properties.</WRAP> |
|  -  | Reserved | Reserved for future expansion. Ignore any additional bytes in the message. |

===== Keep-Alive =====

Send by the server and the client to verify the other side is still alive. This catches situations where the other side crashed or the network connection between the two sides ruptured. This messages requires no response since it is send reliable. Failure to receive it closes the connection. The message has this format:

^  Type ^  Name  ^  Description  ^
| [[gamedev:dnp#data_types|Byte]] | Code | Message code. Is value ''20'' |
|  -  | Reserved | Reserved for future expansion. Ignore any additional bytes in the message. |

====== Linked States ======

These are all linked states the server can request.

===== Run State =====

Send by the server to link the running state. The link message has this format:

^  Type  ^  Name  ^  Description  ^
| [[gamedev:dnp#data_types|Byte]] | Code | Message code. Is value ''1'' |
|  -  | Reserved | Reserved for future expansion. Ignore any additional bytes in the message |

The client has to add these values to the state in this specified order:
^  Index  ^  Type  ^  Name  ^  Description  ^
|  ''0''  | [[gamedev:dnp#state_value_data_types|UInt8]] | Status | <WRAP>
Status of the application. Can be one of these values:
  * ''0'': Stopped.
  * ''1'': Running.
</WRAP> |

===== Revision =====

^ Date      | Changes                                   |