Contents |
Commands
TODO: Move some parts over to the main spec, for the place commands
Entities like persons or places provide 3 interfaces to issue user commands, which are described here.
_request_do_something
To let a person entity do something a _request_do_command_method_here has to be sent to it. For example the _enter command lets your person entity enter a place. To do that via the _request_do interface you have to send a packet with the method _request_do_enter to it:
:_source psyc://123.12.3.2:-12432/~fippo :_target psyc://goodadvice.pages.de/~fippo :_place @dev _request_do_enter |
You should use the _request_do interface for clients with graphical user interface, automatons or similar applications, where those commands are mostly 'hardwired'. If you have to process arbitrary user input (command line commands) it is recommended to use the interfaces described below.
_request_something
For places the command requests differ as you have to leave out the _do in the method name.
_request_execute
All user commands can also be issued via the _request_execute interface. The advantage of this interface is, that clients don't have to map commands to protocol methods themselves, but instead send the command to the destination entity as they are (eg. a place or person).
The above example as _request_execute command looks like this:
:_source psyc://123.12.3.2:-12432/~fippo :_target psyc://goodadvice.pages.de/~fippo _request_execute enter @dev |
The method is _request_execute and the command is, along with its arguments, put into the body. But without any leading command characters, which have to be interpreted by the client.
_request_input
Whenever you want to implement a thin client you can use the _request_input method. It allows the clients to shift all command processing to the person entity. The PSYC variable _focus is used here to focus the command to a specific entity, which for example can be a place:
:_target psyc://host.tld/~nick :_focus psyc://oth.host/@place _request_input /kick eviluser |
Standard Person Commands
These are the commands PSYC person entities may want to implement:
| _request_do... | related variables | equivalent command |
|---|---|---|
| _action_whatever | _focus | /action |
| This command lets the person entity do a chat action, like _request_do_action_hug would virtually hug someone. | ||
| _add_friend | _nick_person or _person, _trustee | /friend |
| _cast | _method, _amount_friendivity | /cast (= /friendcast) |
| _clear_friend | _nick_person or _person | /cancel |
| _clear_log | /logclear | |
| _enter | _group | /enter |
| _enter_home | (too psyced specific) | /home |
| _examine | _person _trustee _tag _format | /examine /surf |
| _follow | /follow | |
| _help | /help | |
| _invite | _person _focus | /invite |
| _leave | _group | /leave |
| _list_peers | /show * | |
| _list_peers_JSON | /show data | |
| _list_places | /list | |
| _list_places_public | /places | |
| _list_users_public | /people | |
| _message | _person, _group | /tell and / |
| This sends a message to either a _person or a _group. | ||
| _presence | _degree_mood _degree_availability _degree_automation _description_presence | /availability /mood and many more |
| _quit | /quit | |
| _register | _password | /register |
| _remove_friend | _nick_person or _person | /unfriend |
| _retrieve | ||
| Generates a _status_storage with _application variables. | ||
| _save | /save | |
| _set | _key _value | /set |
| _show_log | _amount _match _parameter | /lastlog |
| _status | /status | |
| _store | _application* | |
| Stores all variables of the _application family in the entity storage. SHOULD also handle profile settings. | ||
| _subscribe | _group | /subscribe |
| _subscribe_permanent | _group | /subscribe |
| _time_boot | /uptime | |
| _unsubscribe | _group | /unsubscribe |
| _wake | _person | /wake |
Presence with PSYC clients
In PSYC, clients are in charge of setting and resetting presence states on behalf of their users. That means, that a client will probably want to transmit a _request_do_presence soon after logging in and before logging out using _request_do_quit. Quitting does not automatically send offline presence. This only happens when the client loses contact to the server abnormally.
Place command requests
| _request... | variables | equivalent command |
|---|---|---|
| _kick | _person | /kick |
| _nick | _nick_local (masquerade) | /nick |
| _set_masquerade | _flag_masquerade | /masq(uerade) |
| _set_owners | _list_owners | /owners |
| _set_public | _flag_public | /public |
| _set_style | _uniform_style | /style |
| _show_log | _match _amount _parameter | /history |
The _target MUST be aimed at a place (consider however, places potentially provide differing choices of methods). If your request is to be performed on behalf of an identity not identical to the source (typically the case for a client or external tool) you need to provide a _source_identification.
Replies
As replies to _request_do, _request_execute and _request_input any method from one of the method families can be expected. Use packet tags to detect whether a request failed or to get the reply of the request.