QuakeNet's way of dealing with custom /who queries


/who <match>

/who <match> <fields>

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

In other words, /who takes maximally three parameters:
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):
  1. For each <element> (that is, comma-separated match field):
    1. If the element is an existing channel, send a reply for every user on that channel, that is visible to you (see 1. below).
    2. If the element is an existing nickname, send a reply for this user.
  2. If there is no comma in <match>,
    1. For each user that shares a channel with you, if the user matches the specified field, send a reply for this user.
    2. For each user that is visible to you (see 2. below), if the user matches the specified field, send a reply for this user.
  1. 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.
  2. 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]]

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

a or Amatch authname
h or Hmatch hostname
i or Imatch IP (won't work on users with usermode +h/+x)
n or Nmatch nickname
o or Omatch ircops only
r or Rmatch realname
s or Smatch server
u or Umatch userid
x or Xextra matching (IRCOPS ONLY)

All of these are optional; the default is "hnsu".
The fields to return in the 354 numeric.

a or Ainclude authname (or 0 if the user is not authed)
c or Cinclude channel (or ‘*’ if there is no visible channel)
d or Dinclude distance (a.k.a. hopcount: the number of servers between you and this user)
f or Finclude flags, one or more of:
Guser is gone (away)
Huser 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)
duser is deaf (usermode +d)
iuser is invisible (usermode +i) (IRCOPS ONLY)
wuser receives wallops (usermode +w) (IRCOPS ONLY)
guser receives debug information (usermode +g) (IRCOPS ONLY)
huser has a custom host set (usermode +h) (IRCOPS ONLY)
xuser has a hidden host (usermode +x)
(1) in the default 352-reply, only the most significant of these three will be returned
h or Hinclude hostname
i or Iinclude IP (will return for users with usermode +h/+x)
l or Linclude idle time (in seconds; users on your local server only, otherwise 0)
n or Ninclude nickname
r or Rinclude realname
s or Sinclude server (always *.quakenet.org at this moment)
t or Tinclude querytype (see below)
u or Uinclude userid

All of these are optional, although at least one is required to get 354 numerics.
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.

Copyright (c) 2004, David "Saturn" van Moolenbroek <saturn@quakenet.org>