Recent changes to API

API modified by WHR

WHR — Fri, 03 Jan 2020 06:26:37 -0000

--- v29
+++ v30
@@ -1,6 +1,6 @@
 This page describes version 1 of the API.

-Copyright 2018 Rivoreo
+Copyright 2018-2020 Rivoreo

 The SSHOUT API is designed to make uses of a SSH channel, used to implement independent clients.
 Since this protocol is based on SSH protocol, it assume the user is already authenticated, and the channel is secure.

API modified by WHR

WHR — Fri, 03 Jan 2020 06:24:27 -0000

--- v28
+++ v29
@@ -103,7 +103,7 @@
 SSHOUT_API_MESSAGE_TYPE_RICH 2
 SSHOUT_API_MESSAGE_TYPE_IMAGE 3
 ```
-FIXME: defined the format of rich messages (`SSHOUT_API_MESSAGE_TYPE_RICH`).
+The internal format for the type `SSHOUT_API_MESSAGE_TYPE_RICH` is currently HTML 4.
 The type `SSHOUT_API_MESSAGE_TYPE_IMAGE` indicate the message is a JPEG image.
 # Server to client status
 Server may send status packets to client at any time after handshake.

API modified by WHR

WHR — Fri, 03 Jan 2020 06:20:14 -0000

--- v27
+++ v28
@@ -50,7 +50,7 @@
 SSHOUT identify users based only on user names. Each user name must not longer than 32 bytes (USER_NAME_MAX_LENGTH).
 # Querying On-line users
 Packet SSHOUT_API_GET_ONLINE_USER is used to query on-line user from client; then the server responses the request with packet SSHOUT_API_ONLINE_USERS_INFO.
-Packet SSHOUT_API_GET_ONLINE_USER is not have any extra data, so it has no format.
+Packet SSHOUT_API_GET_ONLINE_USER does not have any extra data, so it has no format.
 The format of packet SSHOUT_API_ONLINE_USERS_INFO is:
 ```
 uint16 your_id

API modified by WHR

WHR — Fri, 03 Jan 2020 06:18:31 -0000

--- v26
+++ v27
@@ -1,4 +1,4 @@
-This page descripts version 1 of the API.
+This page describes version 1 of the API.

 Copyright 2018 Rivoreo

API modified by WHR

WHR — Wed, 14 Nov 2018 09:36:35 -0000

--- v25
+++ v26
@@ -14,7 +14,7 @@
 uint8 type
 uint8 data[]
 ```
-The `length` field descripts the length of the whole packet, subtracting its own length; thus the length of `data` field should be `length + 1`. Packets can be no extra data at all, so the minimum value of `length` will be `1` for such packets.
+The `length` field descripts the length of the whole packet, subtracting its own length; thus the length of `data` field should be `length - 1`. Packets can be no extra data at all, so the minimum value of `length` will be `1` for such packets.
 # Packet types
 ```
 SSHOUT_API_HELLO 1

API modified by WHR

WHR — Mon, 29 Oct 2018 20:50:02 -0000

--- v24
+++ v25
@@ -1,4 +1,4 @@
-Warning: this API is still under development; it is not considered stable.
+This page descripts version 1 of the API.

 Copyright 2018 Rivoreo

API modified by WHR

WHR — Fri, 01 Jun 2018 18:34:29 -0000

--- v23
+++ v24
@@ -31,12 +31,21 @@
 # Handshake
 To start the protocol, handshake must be done to make sure the client is connected to a SSHOUT API server, before any other packets; the packets used to handshake are SSHOUT_API_HELLO and SSHOUT_API_PASS, they are, respectively, client to server handshake and server to client handshake.
 The client at first send packet SSHOUT_API_HELLO to server; then the server response with packet SSHOUT_API_PASS.
-The format of those 2 packets are:
+The format of packet SSHOUT_API_HELLO is:
 ```
 uint8 magic[6]
 uint16 version
 ```
 The `magic` field is a fixed length string which must be `SSHOUT` to identify the protocol; the `version` field is the API version number, currently `1`.
+
+The format of packet SSHOUT_API_PASS is:
+```
+uint8 magic[6]
+uint16 version
+uint8 user_name_length;
+uint8 your_user_name[user_name_length]
+```
+The `magic` and `version` fields are in same meaning as in SSHOUT_API_HELLO. Field `your_user_name` is the user name associated to the public key that authenticated the client by SSH server; field `user_name_length` is the length of `your_user_name`.
 # User names
 SSHOUT identify users based only on user names. Each user name must not longer than 32 bytes (USER_NAME_MAX_LENGTH).
 # Querying On-line users

API modified by WHR

WHR — Sun, 20 May 2018 09:13:23 -0000

--- v22
+++ v23
@@ -15,7 +15,19 @@
 uint8 data[]
 ```
 The `length` field descripts the length of the whole packet, subtracting its own length; thus the length of `data` field should be `length + 1`. Packets can be no extra data at all, so the minimum value of `length` will be `1` for such packets.
-
+# Packet types
+```
+SSHOUT_API_HELLO 1
+SSHOUT_API_GET_ONLINE_USER 2
+SSHOUT_API_SEND_MESSAGE 3
+SSHOUT_API_GET_MOTD 4
+SSHOUT_API_PASS 128
+SSHOUT_API_ONLINE_USERS_INFO 129
+SSHOUT_API_RECEIVE_MESSAGE 130
+SSHOUT_API_USER_STATE_CHANGE 131
+SSHOUT_API_ERROR 132
+SSHOUT_API_MOTD 133
+```
 # Handshake
 To start the protocol, handshake must be done to make sure the client is connected to a SSHOUT API server, before any other packets; the packets used to handshake are SSHOUT_API_HELLO and SSHOUT_API_PASS, they are, respectively, client to server handshake and server to client handshake.
 The client at first send packet SSHOUT_API_HELLO to server; then the server response with packet SSHOUT_API_PASS.

API modified by WHR

WHR — Tue, 15 May 2018 13:43:12 -0000

--- v21
+++ v22
@@ -44,6 +44,7 @@
 ```
 Field `your_id` is the correponding `id` number of the user who queried this list.
 Field `count` is number of on-line users.
+IDs in this packet are only used to identify connections; it will be recycled after that connection ended.
 # Sending and receiving message
 Send a message is done by using client to server packet SSHOUT_API_SEND_MESSAGE. When a message is received, server to client packet SSHOUT_API_RECEIVE_MESSAGE will be sent from the server.

API modified by WHR

WHR — Tue, 15 May 2018 13:39:07 -0000

--- v20
+++ v21
@@ -24,7 +24,7 @@
 uint8 magic[6]
 uint16 version
 ```
-The `magic` field is a fixed length string which must be `SSHOUT` to indicate the protocol; the `version` field is the API version number, currently `1`.
+The `magic` field is a fixed length string which must be `SSHOUT` to identify the protocol; the `version` field is the API version number, currently `1`.
 # User names
 SSHOUT identify users based only on user names. Each user name must not longer than 32 bytes (USER_NAME_MAX_LENGTH).
 # Querying On-line users