ircproxy  The Ultimate Cyborg

---

WhoRequest.h

Go to the documentation of this file.

// ircproxy -- An intelligent IRC proxy
//
//! @file WhoRequest.h
//! @brief Header of class WhoRequest
//
// Copyright (C) 2007 by
//
// Carlo Wood, Run on IRC <carlo@alinoe.com>
// RSA-1024 0x624ACAD5 1997-01-26                    Sign & Encrypt
// Fingerprint16 = 32 EC A7 B6 AC DB 65 A6  F6 F6 55 DD 1C DC FF 61
//
// This file may be distributed under the terms of the Q Public License
// version 1.0 as appearing in the file LICENSE.QPL included in the
// packaging of this file.

#ifndef WHOREQUEST_H
#define WHOREQUEST_H

#ifndef USE_PCH
#include <string>
#endif

class ClientSession;

//! @brief A class representing the options that can be passed to a WhoRequest.
//
// The "options" part can be as follows:
//
//  [<flags>][%[<fields>[,<querytype>]]]
//
// in which:
//
//  <flags>: can be a sequence of field matching flags, use mode matching flags
//           and special purpose flags
//
//    Field matching flags, when one of these is specified the field in
//    question is matched against the mask, otherwise it's not matched.
//
//    n   Nick (in nick!user@host)
//    u   Username (in nick!user@host)
//    h   Hostname (in nick!user@host)
//    i   Numeric IP (the unresolved host)
//    s   Servername (the canonic name of the server the guy is on)
//    r   Info text (formerly "Realname")
//    a   Account name
//
//    If no field-matching flags are specified they default to what old servers
//    used to do: nuhsr (= everything except the numeric IP)
//
//    User mode matching flags (specifying one of these means that only clients
//    with that umode are considered, what is not specified is always matched):
//
//    d   Join-delayed channel members
//    o   Irc operator
//    [In the future more flags will be supported, basically all
//     usermodes plus the +/- specificators to revert the filtering]
//
//    Special purpose flags:
//
//    x   If this is specified the extended visibility of information for opers
//        is applied, what this means depends on the fact that you are local or
//        global operator and on how the admin configured the server (global
//        and eventually local irc opers might be allowed with this flag to see
//        +i local users, to see all +i users, to see users into +p and/or +s
//        channels, and so on). Using the 'x' flag while not being an irc
//        operator is meaningless (it will be ignored), using it while oper'd
//        means that the query is almost certainly logged and the admin might
//        (rightfully) ask you an explanation on why you did.
//
//    The rest, what follows the %, that is [%[fields[,<querytype>]]], is as it
//    has always been since the first who.patch, the <fields> part specifies
//    which fields to include in the output as:
//
//    c : Include (first) channel name
//    d : Include "distance" in hops (hopcount)
//    f : Include flags (all of them)
//    h : Include hostname
//    i : Include IP
//    l : Include idle time (0 for remote users) [2.10.11+]
//    n : Include nick
//    r : Include real name
//    s : Include server name
//    t : Include the querytype in the reply
//    u : Include userID with eventual ~
//    a : Include account name
//    o : Include oplevel (shows 999 to users without ops in the channel)
//
//    And the ,<querytype> final option can be used to specify what you want the
//    server to say in the querytype field of the output, useful to filter the
//    output in scripts that do a kind of "on 354 ..."
//
//    If no %fields are specified the reply is _exactly_ the same as has always
//    been, numeric 352, same fields, same order.
//
class WhoOptions {
  private:
    std::string M_flags;                //!< Everything up till the '%'.
    unsigned int M_fields;              //!< Mask representing the fields, or 0 when no fields where given.
    std::string M_querytype;            //!< The query type, or empty when no query type was given.

  public:
    WhoOptions(void) : M_fields(0) { }
    WhoOptions(std::string const& options);

    //! Accessor for flags.
    std::string const& flags(void) const { return M_flags; }
    //! Accessor for fields.
    unsigned int fields(void) const { return M_fields; }
    //! Accessor for querytype.
    std::string const& querytype(void) const { return M_querytype; }

    //! Return the reassembled options string.
    std::string str(void) const;

    //! Return true if the mask is matched against channel names.
    bool matches_against_channel(void) const;
};

//! @brief A WHO request.
//
// Since ircu2.10.05 the format of the who query is.
//
// [:source] WHO <mask1> [<options> [<mask2>]]
//
// <mask2> is optional, if mask2 is present it's used for matching and mask1 is
// ignored, otherwise mask1 is used for matching, since mask2 is the last
// parameter it *can* contain a space and this can help when trying to match a
// "realname".
class WhoRequest {
  private:
    std::string M_mask;                 //!< The first or third parameter of the WHO request.
    WhoOptions M_options;               //!< The options of the WHO request.
    bool M_mask_contains_space;         //!< True if M_mask contains a space.
    bool M_mask_is_target;              //!< True if M_mask is a known target and M_target is valid.
    boost::shared_ptr<Target> M_target; //!< The target that M_mask refers to. Only valid if M_mask_is_target is true.

  private:
    void decode_mask(ClientSession& client_session);

  public:
    //! Construct a WhoRequest for WHO &lt;mask&gt;
    WhoRequest(ClientSession& client_session, std::string const& mask) : M_mask(mask) { decode_mask(client_session); }
    //! Construct a WhoRequest for WHO &lt;mask&gt; &lt;options&gt; or WHO &lt;dummy&gt; &lt;options&gt; :&lt;mask&gt;
    WhoRequest(ClientSession& client_session, std::string const& mask, std::string options) : M_mask(mask), M_options(options) { decode_mask(client_session); }

    //! Accessor for the mask.
    std::string const& mask(void) const { return M_mask; }
    //! Accessor for the options.
    WhoOptions const& options(void) const { return M_options; }
    //! Return true if the mask contains a space.
    bool mask_contains_space(void) const { return M_mask_contains_space; }
    //! Return true if the mask is a known target.
    bool mask_is_target(void) const { return M_mask_is_target; }
    //! Return the target that the mask contains.
    boost::shared_ptr<Target> const& mask_target(void) const { ASSERT(M_mask_is_target); return M_target; }
};

static unsigned int const field_t = 0x0001;     //!< the querytype in the reply
static unsigned int const field_c = 0x0002;     //!< (first) channel name.
static unsigned int const field_u = 0x0004;     //!< userID with eventual ~
static unsigned int const field_i = 0x0008;     //!< IP
static unsigned int const field_h = 0x0010;     //!< hostname
static unsigned int const field_s = 0x0020;     //!< server name
static unsigned int const field_n = 0x0040;     //!< nick
static unsigned int const field_f = 0x0080;     //!< flags (all of them)
static unsigned int const field_d = 0x0100;     //!< "distance" in hops (hopcount)
static unsigned int const field_l = 0x0200;     //!< idle time (0 for remote users) [2.10.11+]
static unsigned int const field_a = 0x0400;     //!< account name
static unsigned int const field_r = 0x0800;     //!< real name
static unsigned int const field_o = 0x1000;     //!< oplevel
static unsigned int const field_percentage = 0x2000;    //!< Set if the '%' character was seen.

#endif // WHOREQUEST_H

---