Therefore, libircpp derives both the user and channel class from a common ancestor, unimaginatively called an entity. The entity class is used wherever a user or channel could be equally valid - for example, the recipient of messages is an entity.
name() // Retrieves the channel's name or user's nick (you can also use nick()) cmd_privmsg() // Sends a privmsg to the user or channel cmd_notice() // Sends a notice to the user or channel cmd_ctcp() // Sends a CTCP message to the user or channel cmd_action() // Sends a CTCP ACTION (/me) to the user or channelYou may use these functions without having to convert the entity to a user or a channel. For operations more specific to users or channels, you must convert the entity object into either a user or a channel first
sig_privmsg_msg // Emitted when a privmsg is recieved for the user or channel sig_notice_msg // Emitted when a notice is received for the user or channel sig_ctcp_msg // Emitted when a CTCP message is received for the user or channel
is_user() and is_channel() will return true if the entity is a user or a channel respectively. to_user() and to_channel() will return a reference to the object correctly cast to a user or a channel respectively. You can use them like this:
if(msg.to().is_channel()) {
// It's a channel
const channel& c = msg.to().to_channel();
// Now do channel stuff using channel object c
}
else if(msg.to().is_user()) {
// It's a user
const user& u = msg.to().to_user();
// Now do user stuff using user object u
}
To appease the C++ purists who are now jumping up and down shouting "dynamic_cast!" - yes, you can use dynamic_cast to convert the entity to a user or channel. The convenience functions mentioned above are for those who don't want to deal with exceptions.If you call to_channel() on an entity that is a user, the null channel object will be returned. Similarly, if you call to_user() on an entity that is a channel, the null user object will be returned. So an alternative way of converting entities is:
channel& c = msg.to().to_channel();
if(c) {
// It's a channel, do channel stuff here
}
u.nick(); // Returns the user's nickname username(); // Returns the user's username (ident) hostname(); // Returns the user's hostname (IP) realname(); // Returns the user's realneame (gecos)The nick() function will always be available, but the username(), hostname() and realname() data may not be available. This is because, upon joining a channel, only a list of nicks is provided by the irc server. When a user sends a privmsg or notice, the username and hostname are sent, and libircpp then saves the appropriate data in the user object. The realname can only be retrieved from a /whois or /who reply. So, if you need to ensure that all the data is available, you must do a cmd_who or cmd_whois on the user, and wait for the appropriate whois or who reply, before calling the information functions.
sig_join_msg // Emitted when anyone (including you) joins the channel sig_part_msg // Emitted when anyone (including you) parts from the channel sig_quit_msg // Emitted when anyone in the channel (including you) quits IRC sig_mode_msg // Emitted when a mode on the channel is changed sig_singlemode_msg // Emitted for each individual mode change on the channel sig_topic_msg // Emitted when the channel topic is changed sig_kick_ms // Emitted when someone is kicked from the channel sig_invite_msg // Emitted when someone is invited to the channel sig_numeric // Emitted when a numeric message for the channel is recievedMost of these signals mirror signals emitted by the session object. The difference between these signals and the session object's signals is that these signals are only emitted for messages to this channel. The session object signals are emitted for messages to all channels.
For more information on the sig_singlemode_msg signal, please see the section on mode messages in the messages chapter.
cmd_part() // Causes you to leave the channel cmd_topic() // Changes the channel topic cmd_kick() // Kicks someone from the channel cmd_invite() // Invites someone to the channel cmd_names() // Requests a list of names of the occupants of the channelAgain, most of these mirror commands available in the session object, but do not require the name parameter as they relate to the channel object they are called on. There is no cmd_join() function as the channel object is only created when the channel is successfully joined. To join a channel, use the session object's cmd_join() with the channel's name. If the join is successful, you can retrieve the channel object's reference from the sig_join_msg signal.
if(u) {
// The user is valid
}
if(!c) {
// No valid channel object
}
if(msg.target()) {
// The message has a target
}
This arrangement also means it is always valid to do things like:
cout << "Recipient: " << msg.to().name() << endl;If the message has no recipient, the null user will be used, and the name printed will be blank - but will not throw an exception or cause any errors.
If you need a reference to the null user or channel object directly, they can be retrieved with the session's functions:
s.nulluser(); // Returns the null user s.nullchannel(); // Returns the null channelNext: User and Channel Lists