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 variablesequivalent 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...variablesequivalent 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.