QuakeNet's way of dealing with custom /who queries

Format

/who <match>

/who <match> <fields>

/who <ignored> <fields> :<match>

In other words, /who takes maximally three parameters:

The first is obligatory: the match field.
The second is optional: a specification of which fields to match/return.
The third is optional: it overrides the first parameter, and can contain spaces if preceded by a colon (':').

Using the second match field instead of the first one can be useful when you want to find users based on a realname which contains spaces.

The match text

<match> ::= <element>[,<element>[,...]]

<element> ::= [nickname|channel|matchtext]

The matching process consists of the following steps (a bit generalized):

For each <element> (that is, comma-separated match field):

If the element is an existing channel, send a reply for every user on that channel, that is visible to you (see 1. below).
If the element is an existing nickname, send a reply for this user.

If there is no comma in <match>,

For each user that shares a channel with you, if the user matches the specified field, send a reply for this user.
For each user that is visible to you (see 2. below), if the user matches the specified field, send a reply for this user.

A user on a channel is visible to you, if you are on this channel, or if the channel is not secret/private and the user doesn’t have usermode +i set.
A user is visible to you, if you share a channel with this user, or if the user doesn’t have usermode +i set.

Note: as you can see, the matching process could potentially match the same user more than once. The /who processing code makes sure a user occurs only once in the /who output though, so you will never get the same nickname twice in one /who query.

Note 2: if you include the 'c' field in the includefields (see below), the returned channel will depend on the match case: A.i and B.i will always return the specified or shared channel, whereas A.ii and B.ii will return a more or less random channel or '*'.

The field specification

<fields> ::= [matchfields][%includefields[,querytype]]

matchfields

The fields to match the field against. If you specify more than one, <match> should match at least one of them (“OR”).

a or A match authname

h or H match hostname

i or I match IP (won't work on users with usermode +h/+x)

n or N match nickname

o or O match ircops only

r or R match realname

s or S match server

u or U match userid

x or X extra matching (IRCOPS ONLY)

All of these are optional; the default is "hnsu".

includefields

The fields to return in the 354 numeric.

a or A include authname (or 0 if the user is not authed)

c or C include channel (or ‘*’ if there is no visible channel)

d or D include distance (a.k.a. hopcount: the number of servers between you and this user)

f or F include flags, one or more of:

G user is gone (away)

H user is here (not away)

* user is IRCop (usermode +o/+O)

@ user is operator on the given channel (see 1)

+ user is voiced on the given channel (see 1)

! user is zombie on the given channel (see 1)

d user is deaf (usermode +d)

i user is invisible (usermode +i) (IRCOPS ONLY)

w user receives wallops (usermode +w) (IRCOPS ONLY)

g user receives debug information (usermode +g) (IRCOPS ONLY)

h user has a custom host set (usermode +h) (IRCOPS ONLY)

x user has a hidden host (usermode +x)

(1) in the default 352-reply, only the most significant of these three will be returned

h or H include hostname

i or I include IP (will return 127.0.0.1 for users with usermode +h/+x)

l or L include idle time (in seconds; users on your local server only, otherwise 0)

n or N include nickname

r or R include realname

s or S include server (always *.quakenet.org at this moment)

t or T include querytype (see below)

u or U include userid

All of these are optional, although at least one is required to get 354 numerics.

querytype

A user-specified number between 0 and 999 (inclusive), which can be returned with the “t” includefield. Choice and interpretation of this number are completely up to the client, for example a client can use it to identify which replies are generated by which /who query.

The replies

A reply is sent for each matched user. The IRC server only sends the new special 354 (RPL_WHOSPCRPL) numeric when you have specified one or more includefields in your /who query. Otherwise, it will send the normal 352 (RPL_WHOREPLY) numeric, which has this standard format:

:yourserver 352 yournick <channel> <userid> <host> <server> <nick> <flags> :<distance> <realname>

In other words, the 352 reply is very similar to, but not exactly the same as, the set of includefields "cuhsnfdr".

The 354 numeric has variable output, depending on the fields you requested for inclusion:

:yourserver 354 yournick [querytype] [channel] [userid] [IP] [host] [server] [nick] [flags] [distance] [idletime] [auth] [:realname]

In other words, the order in which the requested fields are returned, is "tcuihsnfdlar".

Note: the maximum number of replies depends on the number of specified includefields, and is calculated with the formula "2048 / (number_of_fields + 4)". So, the more fields you request, the less replies you'll get.

a or A	match authname
h or H	match hostname
i or I	match IP (won't work on users with usermode +h/+x)
n or N	match nickname
o or O	match ircops only
r or R	match realname
s or S	match server
u or U	match userid
x or X	extra matching (IRCOPS ONLY)