jadedctrl/Chat-O-Matic
jadedctrl/ Chat-O-Matic
1
0
Disbranĉigi 0
Fontkodo Issues 20 Tirpetoj Actions Packages Projects Eldonoj 2 Wiki Activity

Formatting of README.ADDON.md

This commit is contained in:
Jaidyn Ann 2021-08-17 10:08:39 -05:00
parent 4bb6cfee7c
commit 5aeaf9284f
1 changed files with 39 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

73
README.ADDON.md
View File

@ -2,6 +2,7 @@ This file isn't comprehensive, and is only quick overview. It's probably
only useful in conjunction with skimming the appropriate headers only useful in conjunction with skimming the appropriate headers
(`application/ChatProtocol.h`, `application/ChatProtocolMessages.h`) and one of (`application/ChatProtocol.h`, `application/ChatProtocolMessages.h`) and one of
the included add-ons. the included add-ons.
This file's mostly here mostly here to clear up some behaviors that might not be This file's mostly here mostly here to clear up some behaviors that might not be
immediately clear. immediately clear.
@ -11,53 +12,54 @@ An add-on should export a few functions, and offer at least one class inheriting
ChatProtocol. ChatProtocol.
Each add-on must export the following functions; Each add-on must export the following functions;
ChatProtocol* protocol_at(int32 i) * `ChatProtocol* protocol_at(int32 i)`
int32 protocol_count() * `int32 protocol_count()`
const char* signature() * `const char* signature()`
const char* friendly_signature() * `const char* friendly_signature()`
uint32 version() * `uint32 version()`
A single add-on can support multiple protocols (the Purple add-on being the A single add-on can support multiple protocols (the Purple add-on being the
only current example of this)― but generally returning a "1" from only current example of this)― but generally returning a "1" from
protocol_count() and only returning a protocol from protocol_at(0) should be `protocol_count()` and only returning a protocol from `protocol_at(0)` should be
all you need. all you need.
For a full description of the ChatProtocol object, look through For a full description of the ChatProtocol object, look through
`application/ChatProtocol.h`. `application/ChatProtocol.h`.
Each ChatProtocol can be treated as either an account's instance, or solely for Each ChatProtocol can be treated as either an account's instance, or solely for
retrieving general metadata from the Icon(), Signature(), etc. methods― so retrieving general metadata from the `Icon()`, `Signature()`, etc. methods― so
please don't start the connection from the constructor. please don't start the connection from the constructor.
## Connection details ## Connection details
A ChatProtocol's UpdateSettings() method should be used to receive settings from A ChatProtocol's `UpdateSettings()` method should be used to receive settings
the program and declare a separate connection thread, but it generally shouldn't from the program and declare a separate connection thread, but it generally
actually start the connection nor this thread. shouldn't actually start the connection nor this thread.
The connection should be started when the user's status is set to STATUS_ONLINE― The connection should be started when the user's status is set to
and correspondingly, the connection should be paused or terminated when it is `STATUS_ONLINE`― and correspondingly, the connection should be paused or
STATUS_OFFLINE. The user should be able to easily toggle the connection this way terminated when it is `STATUS_OFFLINE`. The user should be able to easily toggle
without any real consequences. If this is impossible, then the add-on can send the connection this way without any real consequences. If this is impossible,
IM_PROTOCOL_DISABLE just as the user-status is set to offline. then the add-on can send `IM_PROTOCOL_DISABLE` just as the user-status is set
to offline.
STATUS_OFFLINE is for a momentary pause, i.e., the server is down or the user `STATUS_OFFLINE` is for a momentary pause, i.e., the server is down or the user
toggled the connection. The ChatProtocol will remain existent and active. toggled the connection. The ChatProtocol will remain existent and active.
If the status is set to offline by the protocol (and not the user!) Cardie will If the status is set to offline by the protocol (and not the user!) Cardie will
automatically attempt a reconnect after some time by trying to set the status automatically attempt a reconnect after some time by trying to set the status
to STATUS_ONLINE, which should toggle the connection. to `STATUS_ONLINE`, which should toggle the connection.
IM_PROTOCOL_DISABLE deletes the ChatProtocol, and should only be sent to the app `IM_PROTOCOL_DISABLE` deletes the ChatProtocol, and should only be sent to the
when an irrecoverable error requiring user intervention has happened, i.e., a app when an irrecoverable error requiring user intervention has happened, i.e.,
configuration error, incorrect password, etc. If possible, it's preferable to a configuration error, incorrect password, etc. If possible, it's preferable to
send the user a notification (with IM_ERROR) telling them about the problem, send the user a notification (with `IM_ERROR`) telling them about the problem,
just before sending IM_PROTOCOL_DISABLE. just before sending `IM_PROTOCOL_DISABLE`.
## Templates ## Templates
Each ChatProtocol has to provide UI "templates" for some important dialogues Each ChatProtocol has to provide UI "templates" for some important dialogues
through the SettingsTemplate() method. In order of importance, they are through the `SettingsTemplate()` method. In order of importance, they are
"account", "create_room", "join_room", and "roster". "account", "create_room", "join_room", and "roster".
"account" is used for accounts settings (seen by the user when configuring their "account" is used for accounts settings (seen by the user when configuring their
@ -66,6 +68,7 @@ and "roster" for adding/editing a contact on the roster.
Here's a shorter version of the XMPP add-on's "account" settings: Here's a shorter version of the XMPP add-on's "account" settings:
``
BMessage('IMst') { BMessage('IMst') {
setting[0] = BMessage(0x0) { setting[0] = BMessage(0x0) {
name = string("username") name = string("username")
@ -87,11 +90,13 @@ BMessage('IMst') {
type = int32(0x43535452 or 1129534546) type = int32(0x43535452 or 1129534546)
} }
} }
``
The template is a BMessage with sub-messages named "setting", each with, at The template is a BMessage with sub-messages named "setting", each with, at
least, an internal "name" (the slot used by Cardie in the message parameter of least, an internal "name" (the slot used by Cardie in the message parameter of
UpdateSettings()), a user-friendly label ("description"), and the slot type `UpdateSettings()`), a user-friendly label ("description"), and the slot type
in "type"― currently B_INT32_TYPE, B_STRING_TYPE, and B_BOOL_TYPE are accepted. in "type"― currently `B_INT32_TYPE`,` B_STRING_TYPE`, and `B_BOOL_TYPE` are
accepted.
By default, slots are not required, and it's accepted for the user to skip them. By default, slots are not required, and it's accepted for the user to skip them.
To make a slot required, put an error message into "error", warning the user To make a slot required, put an error message into "error", warning the user
@ -101,7 +106,7 @@ Also optionally accepted are "is_secret" to determine if entered text is
visible and "default" for a default value. visible and "default" for a default value.
The internal names of "settings" in these templates determine the values you The internal names of "settings" in these templates determine the values you
should expect to receive for some messages from the app, like IM_JOIN_ROOM. should expect to receive for some messages from the app, like `IM_JOIN_ROOM`.
@ -126,9 +131,9 @@ with their meanings:
* body Used for message-text, or explanation of an action (inviting or banning a user, etc) * body Used for message-text, or explanation of an action (inviting or banning a user, etc)
user_names and chat_names can be changed at will user_names and chat_names can be changed at will
(through IM_CONTACT_INFO/IM_USER_SET_NAME/IM_ROOM_PARTICIPANTS and (through `IM_CONTACT_INFO`/`IM_USER_SET_NAME`/`IM_ROOM_PARTICIPANTS` and
IM_ROOM_DATA/IM_ROOM_NAME_SET respectively), but user_ids and chat_ids cannot `IM_ROOM_DATA`/`IM_ROOM_NAME_SET` respectively), but user_ids and chat_ids
be changed. cannot be changed.
If you have to, you can "change" a chat or user's ID, by faking the user leaving If you have to, you can "change" a chat or user's ID, by faking the user leaving
and re-joining the room. This should be avoided if possible, since it breaks and re-joining the room. This should be avoided if possible, since it breaks
@ -144,13 +149,13 @@ a subsequent response to the previous message:
* Cardie (`IM_GET_ROOM_METADATA` & `IM_GET_ROOM_PARTICIPANTS`) → Protocol * Cardie (`IM_GET_ROOM_METADATA` & `IM_GET_ROOM_PARTICIPANTS`) → Protocol
* Protocol (`IM_ROOM_METADATA` & `IM_ROOM_PARTICIPANTS`) → Cardie * Protocol (`IM_ROOM_METADATA` & `IM_ROOM_PARTICIPANTS`) → Cardie
Preferably, IM_ROOM_METADATA and IM_ROOM_PARTICIPANTS should only be used as Preferably, `IM_ROOM_METADATA` and `IM_ROOM_PARTICIPANTS` should only be used as
above (in response to a request from Cardie) since they are silent and don't above (in response to a request from Cardie) since they are silent and don't
explicitly tell the user what's happened― whereas messages like explicitly tell the user what's happened― whereas messages like
IM_ROOM_PARTICIPANT_JOINED and IM_ROOM_SUBJECT_SET will inform the user of the `IM_ROOM_PARTICIPANT_JOINED` and `IM_ROOM_SUBJECT_SET` will inform the user of
change. the change.
You can send IM_ROOM_PARTICIPANTS multiple times in a row― users You can send `IM_ROOM_PARTICIPANTS` multiple times in a row― users
not mentioned in subsequent mentions are not implicitly removed from the not mentioned in subsequent mentions are not implicitly removed from the
user-list, you must send a separate IM_ROOM_PARTICIPANT_LEFT for each parting user-list, you must send a separate `IM_ROOM_PARTICIPANT_LEFT` for each parting
user. user.