If you're not a developer, see software for a list of clients.

See also Category:Client and Team:Client.

Contents 1 Hello Developer! 1.1 Client protocol news 1.2 How to start 1.3 PSYC API 1.4 Related pages 1.5 Where to test 2 Issues 2.1 Charsets & Encoding 2.2 Room members 2.3 Use the _source, Luke 3 Common practice 3.1 Don't open windows on enter 3.2 Buddy Lists: How to handle the nickspace 3.3 Clearing the screen 3.4 Showing time stamps 4 See also

Hello Developer!

Good news, with the advent of the command requests the degree of kludginess of the PSYC client protocol is dropping below the levels of kludge it takes to write either a Jabber or an IRC client.^((s)) I am very proud of that. But find out for yourself and catch yourself having seriously fun writing a PSYC client! Yes! That's what we wanted in the end!

Client protocol news

Things recently changed in psyced's way to handle clients:

• _enter still comes with _list_members, but now it also includes the new member.
• _context _target and _source are now set (or rather left out) according to Routing, this affects history and lastlog as well. Make sure you are not looking at messages in history or lastlog which are older than this change!
• Fixed timestamps on lastlog.
• availability and mood are now persistent.
• psyced has been fixed to no longer attempt any charset conversions for native PSYC clients (/set charset is ignored for PSYC clients).
• Clients are currently considered self-sufficient to set their presence, that is: if you lose the connection to your server, you will not automatically be announced as being offline.

We should probably make it a distinction in the unlink procedure however, so that erroneous link break still triggers an announce()... or we should make it configurable - /set defaultavailability or something.

How to start

How do you start writing a client or any other PSYC application? First you need to choose between an unfinished new version of the protocol described in the specification, or use the existing described here. Then you can either follow that or this documentation. When you run into things that are not explained, you have three options to try out:

• See what comes over the wire and just use that.
• See how other client applications do it.
• Ask in psyc://psyced.org/@welcome.

But first you can look at the "Old" client protocol page for a rough way to start. The more detailed documentations follow below.

PSYC API

PSYC has a typical API that may fit your application, too. But you may aswell prefer to suggest changes to it. Just thought you should have seen it before you start.  :)

Also check out existing open-source software for parsers and libraries that could let you head out more easily. Unless of course you are here because of the thrill of writing a parser - but even though the syntax is a lot easier to parse than others, you will run into details which have been solved many times before, so why would you want to go through that, too?

Related pages

Many features you will like to provide in a client are discussed on other pages:

• Connecting to your identification. Or register one.
• Sending messages and receiving echoes.
• How to implement a PSYC protocol parser efficiently.
• How to implement method inheritance efficiently.
• How to dispatch and sort incoming messages: see API.
• Using the time variables when displaying lastlog.
• Issuing commands and actions.
• Changing your presence status.
• Group communication.
• Tagging packets.
• Don't do interserver Friendship Establishment, use commands instead.
• Inspect and modify your peer list of contacts.
• TCP, UDP and TLS circuits.
• Extras:
  • Pings.
  • Composing.
  • Encryption.
  • File Transfer and File Sharing.
  • Newscasting.
  • Storage.
  • Styled graphic profiles and Social Networking.
  • You may want to share the Textdb with psyced.
  • Trust graphs and editing tools.

If you also support XMPP and your user is providing you with a user@host notation of his identity, you may want to implement Protocol Switch so you can upgrade to PSYC if the identity resides on a multiprotocol server.

Where to test

Please use beta.ve.symlynX.com for testing. We like psyced.org to run for weeks or months, so it won't always be up to date. psyced has gotten much better at dealing with ghost users (when a client terminates without properly logging out, which is what you do all the time when testing), but still it can become impractical.

Issues

Charsets & Encoding

Negotiation of encoding is not available. PSYC transmits all content in UTF-8. The /set charset command is intended for IRC and telnet.

Room members

If you need to know the members of a room, you may want to send a _request_members message to it. You'll get the default _status_place_members. This is mostly not needed, because the room sends it automatically after joining.

Use the _source, Luke

Check if _source is your own UNI. If it is, use _source_relay instead. This is also needed if you send messages over your identification on the server (needed for XMPP entities, which are not really supported by net/psyc, to receive the echoes correctly).

<lynX> generally make use of _source_relay whenever _source is somebody you can trust. in the case of rooms, if you entered them it is part of the game to trust them.

Common practice

This is of course subject to discussion and taste, but I'd like to document certain things that have been standard behavior in most PSYC clients so far:

• Clients render any unknown message using psyctext.
• Clients submit user input that starts with a / using _request_execute.

Don't open windows on enter

Clients do not open windows for each and every of the user's contexts as some of them may be newsfeeds and they might be delivering messages only once a week, so you would only clutter the screen and limit the user in the way she feels she can collect subscriptions. In PSYC the number of subscribed places should be potentially unlimited.

Buddy Lists: How to handle the nickspace

The simple way is to use the prepacked _list_members_nicks coming from the identification and just display things as they are. Should you want to have a complete buddy list however, then you should try out _request_do_list_peers. It will also inform you of all aliases the user has set, so you can render any uniform like those in _list_members yourself, the way your user likes it.

Clearing the screen

Most PSYC interfaces, even the web chats and applets, clear the output area when the user enters an empty input = hits the enter key.

This serves the purpose of multi-tasking: When you are busy working in other windows and you come back to the chat you don't have to figure out where you left off reading. You just clear away things you have read.

Some people however hit enter by mistake.. so we added a /set clearscreen off.

Some clients also have the possibility to check for the CTRL-L key combination, which is the traditional unix refresh screen key code, sometimes also interpreted as clear screen. Supporting CTRL-L for clearing the output area is a good idea.

There are however other approaches to solving the problem, like graying out old conversation or inserting a horizontal ruler automatically whenever the window focus changes.

Also letting the user hit the ESC key to either dismiss or iconify the conversation window is a good tradition.

Best practice is probably to support all of these more or less popular ways for power users to interact with messaging and chat applications.

Showing time stamps

Having time stamps on every line of the chat output is a question of taste. Some people love it, some others would like a chat window to consume as little screen space as possible and prefer not to see timestamps. In PsycZilla we solved this brilliantly by outputting timestamps in their own HTML class and have a button which switches display on and off on a CSS level.

See also

See also Talk:Client for current and past discussion on client coding issues.