libircclient: IRC commands: channel management.

# IRC commands: channel management.

## Functions
int | irc_cmd_join (irc_session_t *session, const char *channel, const char *key)
| Joins the new IRC channel.
int | irc_cmd_part (irc_session_t *session, const char *channel)
| Leaves the IRC channel.
int | irc_cmd_invite (irc_session_t *session, const char *nick, const char *channel)
| Invites a user to invite-only channel.
int | irc_cmd_names (irc_session_t *session, const char *channel)
| Obtains a list of users who're in channel.
int | irc_cmd_list (irc_session_t *session, const char *channel)
| Obtains a list of active server channels with their topics.
int | irc_cmd_topic (irc_session_t *session, const char *channel, const char *topic)
| Views or changes the channel topic.
int | irc_cmd_channel_mode (irc_session_t *session, const char *channel, const char *mode)
| Views or changes the channel mode.
int | irc_cmd_kick (irc_session_t *session, const char *nick, const char *channel, const char *reason)
| Kick some lazy ass out of channel.

## Function Documentation

int irc_cmd_channel_mode | ( | irc_session_t * | session,
|  | const char * | channel,
|  | const char * | mode |
| ) |  |  |

Views or changes the channel mode.

Parameters:

  | session | An initiated and connected session.
  | channel | A channel name to invite to. Must not be NULL.
  | mode | A channel mode, described below. If NULL, the channel mode is not changed, just the old mode is returned.

Returns:
  Return code 0 means success. Other value means error, the error code may be obtained through irc_errno(). Any error, generated by the IRC server, is available through irc_callbacks_t::event_numeric.

The irc_cmd_channel_mode() is used to change or view the channel modes. The channel mode is returned if the mode is NULL. If the mode is not NULL, the mode for the channel will be changed. Note that, only channel operators can change the channel modes.

Channel mode is represended by the letters combination. Every letter has its own meaning in channel modes. Most channel mode letters are boolean (i.e. could only be set or reset), but a few channel mode letters accept a parameter. All channel options are set by adding a plus sign before the letter, and reset by adding a minus sign before the letter.

Here is the list of 'standard' channel modes:

- o nickname - gives (+o nick) or takes (-o nick) the channel operator privileges from a nickname. This mode affects the users in channel, not the channel itself. Examples: "+o tim", "-o watson".

- p - sets (+p) or resets (-p) private channel flag. Private channels are shown in channel list as 'Prv', without the topic.

- s - sets (+p) or resets (-p) secret channel flag. Secret channels aren't shown in channel list at all.

- i - sets (+i) or resets (-i) invite-only channel flag. When the flag is set, only the people who are invited by irc_cmd_invite(), can join this channel.

- t - sets (+t) or resets (-t) topic settable by channel operator only flag. When the flag is set, only the channel operators can change the channel topic.

- n - sets (+n) or resets (-n) the protection from the clients outside the channel. When the +n mode is set, only the clients, who are in channel, can send the messages to the channel.

- m - sets (+m) or resets (-m) the moderation of the channel. When the moderation mode is set, only channel operators and the users who have the +v user mode can speak in the channel.

- v nickname - gives (+v nick) or takes (-v nick) from user the ability to speak on a moderated channel. Examples: "+v tim", "-v watson".

- l number - sets (+l 20) or removes (-l) the restriction of maximum users in channel. When the restriction is set, and there is a number of users in the channel, no one can join the channel anymore.

- k key - sets (+k secret) or removes (-k) the password from the channel. When the restriction is set, any user joining the channel required to provide a channel key.

- b mask - sets (+b *!*@*.mil) or removes (-b *!*@*.mil) the ban mask on a user to keep him out of channel. Note that to remove the ban you must specify the ban mask to remove, not just "-b".

Note that the actual list of channel modes depends on the IRC server, and can be bigger. If you know the popular channel modes, which aren't mentioned here - please contact me at tim@krasnogorsk.ru

Possible error responces for this command from the RFC1459:

- LIBIRC_RFC_ERR_NEEDMOREPARAMS
- LIBIRC_RFC_ERR_CHANOPRIVSNEEDED
- LIBIRC_RFC_ERR_NOSUCHNICK
- LIBIRC_RFC_ERR_NOTONCHANNEL
- LIBIRC_RFC_ERR_KEYSET
- LIBIRC_RFC_ERR_UNKNOWNMODE
- LIBIRC_RFC_ERR_NOSUCHCHANNEL

And the mode information is given using following reply codes:

- LIBIRC_RFC_RPL_CHANNELMODEIS
- LIBIRC_RFC_RPL_BANLIST
- LIBIRC_RFC_RPL_ENDOFBANLIST

See also:
  irc_cmd_topic irc_cmd_list

int irc_cmd_invite | ( | irc_session_t * | session,
|  | const char * | nick,
|  | const char * | channel |
| ) |  |  |

Invites a user to invite-only channel.

Parameters:

  | session | An initiated and connected session.
  | nick | A nick to invite. Must not be NULL.
  | channel | A channel name to invite to. Must not be NULL.

Returns:
  Return code 0 means success. Other value means error, the error code may be obtained through irc_errno(). Any error, generated by the IRC server, is available through irc_callbacks_t::event_numeric.

This function is used to invite someone to invite-only channel. "Invite-only" is a channel mode, which restricts anyone, except invided, to join this channel. After invitation, the user could join this channel. The user, who is invited, will receive the irc_callbacks_t::event_invite event. Note that you must be a channel operator to INVITE the users.

Possible error responces for this command from the RFC1459:

- LIBIRC_RFC_ERR_NEEDMOREPARAMS
- LIBIRC_RFC_ERR_NOSUCHNICK
- LIBIRC_RFC_ERR_NOTONCHANNEL
- LIBIRC_RFC_ERR_ERR_USERONCHANNEL
- LIBIRC_RFC_ERR_ERR_CHANOPRIVSNEEDED

And on success one of the following replies returned:

- LIBIRC_RFC_RPL_INVITING
- LIBIRC_RFC_RPL_AWAY

See also:
  irc_callbacks_t::event_invite irc_cmd_channel_mode

int irc_cmd_join | ( | irc_session_t * | session,
|  | const char * | channel,
|  | const char * | key |
| ) |  |  |

Joins the new IRC channel.

Parameters:

  | session | An initiated and connected session.
  | channel | A channel name to join to. Must not be NULL.
  | key | Channel password. May be NULL.

Returns:
  Return code 0 means success. Other value means error, the error code may be obtained through irc_errno(). Any error, generated by the IRC server, is available through irc_callbacks_t::event_numeric.

This function is used to JOIN the IRC channel. If the channel is not exist, it will be automatically created by the IRC server. Note that to JOIN the password-protected channel, you must know the password, and specify it in the key argument.

If join is successful, the irc_callbacks_t::event_join is called (with origin == your nickname), then you are sent the channel's topic (using LIBIRC_RFC_RPL_TOPIC) and the list of users who are on the channel (using LIBIRC_RFC_RPL_NAMREPLY), which includes the user joining - namely you.

Possible error responces for this command from the RFC1459:

- LIBIRC_RFC_ERR_NEEDMOREPARAMS
- LIBIRC_RFC_ERR_BANNEDFROMCHAN
- LIBIRC_RFC_ERR_INVITEONLYCHAN
- LIBIRC_RFC_ERR_BADCHANNELKEY
- LIBIRC_RFC_ERR_CHANNELISFULL
- LIBIRC_RFC_ERR_BADCHANMASK
- LIBIRC_RFC_ERR_NOSUCHCHANNEL
- LIBIRC_RFC_ERR_TOOMANYCHANNELS

And on success the following replies returned:

- LIBIRC_RFC_RPL_TOPIC
- LIBIRC_RFC_RPL_NAMREPLY

int irc_cmd_kick | ( | irc_session_t * | session,
|  | const char * | nick,
|  | const char * | channel,
|  | const char * | reason |
| ) |  |  |

Kick some lazy ass out of channel.

Parameters:

  | session | An initiated and connected session.
  | nick | A nick to kick. Must not be NULL.
  | channel | A channel to kick this nick out of. Must not be NULL.
  | reason | A reason to kick. May be NULL.

Returns:
  Return code 0 means success. Other value means error, the error code may be obtained through irc_errno(). Any error, generated by the IRC server, is available through irc_callbacks_t::event_numeric.

This function is used to kick a person out of channel. Note that you must be a channel operator to kick anyone.

Possible error responces for this command from the RFC1459:

- LIBIRC_RFC_ERR_NEEDMOREPARAMS
- LIBIRC_RFC_ERR_BADCHANMASK
- LIBIRC_RFC_ERR_NOSUCHCHANNEL
- LIBIRC_RFC_ERR_NOTONCHANNEL
- LIBIRC_RFC_ERR_CHANOPRIVSNEEDED

On success the irc_callbacks_t::event_kick event will be generated.

See also:
  irc_callbacks_t::event_numeric

int irc_cmd_list | ( | irc_session_t * | session,
|  | const char * | channel |
| ) |  |  |

Obtains a list of active server channels with their topics.

Parameters:

  | session | An initiated and connected session.
  | channel | A channel name(s) to list. May be NULL, in which case all the channels will be listed. It is possible to specify more than a single channel, but several channel names should be separated by a comma.

Returns:
  Return code 0 means success. Other value means error, the error code may be obtained through irc_errno(). Any error, generated by the IRC server, is available through irc_callbacks_t::event_numeric.

This function is used to ask the IRC server for the active (existing) channels list. The list will be returned using LIBIRC_RFC_RPL_LISTSTART - LIBIRC_RFC_RPL_LIST - LIBIRC_RFC_RPL_LISTEND sequence. Note that "private" channels are listed (without their topics) as channel "Prv" unless the client generating the LIST query is actually on that channel. Likewise, secret channels are not listed at all unless the client is a member of the channel in question.

Possible error responces for this command from the RFC1459:

- LIBIRC_RFC_ERR_NOSUCHSERVER

And the channel list is returned using the following reply codes:

- LIBIRC_RFC_RPL_LISTSTART
- LIBIRC_RFC_RPL_LISTEND
- LIBIRC_RFC_RPL_LIST

int irc_cmd_names | ( | irc_session_t * | session,
|  | const char * | channel |
| ) |  |  |

Obtains a list of users who're in channel.

Parameters:

  | session | An initiated and connected session.
  | channel | A channel name(s) to obtain user list. Must not be NULL. It is possible to specify more than a single channel, but several channel names should be separated by a comma.

Returns:
  Return code 0 means success. Other value means error, the error code may be obtained through irc_errno(). Any error, generated by the IRC server, is available through irc_callbacks_t::event_numeric.

This function is used to ask the IRC server for the list of the users who're in specified channel. You can list all nicknames that are visible to you on any channel that you can see. The list of users will be returned using RPL_NAMREPLY and RPL_ENDOFNAMES numeric codes.

The channel names are returned by irc_callbacks_t::event_numeric using the following reply codes:

- LIBIRC_RFC_RPL_NAMREPLY
- LIBIRC_RFC_RPL_ENDOFNAMES

int irc_cmd_part | ( | irc_session_t * | session,
|  | const char * | channel |
| ) |  |  |

Leaves the IRC channel.

Parameters:

  | session | An initiated and connected session.
  | channel | A channel name to leave. Must not be NULL.

Returns:
  Return code 0 means success. Other value means error, the error code may be obtained through irc_errno(). Any error, generated by the IRC server, is available through irc_callbacks_t::event_numeric.

This function is used to leave the IRC channel you've already joined to. An attempt to leave the channel you aren't in results a LIBIRC_RFC_ERR_NOTONCHANNEL server error.

Possible error responces for this command from the RFC1459:

- LIBIRC_RFC_ERR_NEEDMOREPARAMS
- LIBIRC_RFC_ERR_NOSUCHCHANNEL
- LIBIRC_RFC_ERR_NOTONCHANNEL

int irc_cmd_topic | ( | irc_session_t * | session,
|  | const char * | channel,
|  | const char * | topic |
| ) |  |  |

Views or changes the channel topic.

Parameters:

  | session | An initiated and connected session.
  | channel | A channel name to invite to. Must not be NULL.
  | topic | A new topic to change. If NULL, the old topic will be returned, and topic won't changed.

Returns:
  Return code 0 means success. Other value means error, the error code may be obtained through irc_errno(). Any error, generated by the IRC server, is available through irc_callbacks_t::event_numeric.

The irc_cmd_topic() is used to change or view the topic of a channel. The topic for channel is returned if topic is NULL. If the topic is not NULL, the topic for the channel will be changed. Note that, depending on +t channel mode, you may be required to be a channel operator to change the channel topic.

If the command succeed, the IRC server will generate a RPL_NOTOPIC or RPL_TOPIC message, containing either old or changed topic. Also the IRC server can (but not have to) generate the non-RFC RPL_TOPIC_EXTRA message, containing the nick of person, who's changed the topic, and the time of latest topic change.

Possible error responces for this command from the RFC1459:

- LIBIRC_RFC_ERR_NEEDMOREPARAMS
- LIBIRC_RFC_ERR_CHANOPRIVSNEEDED
- LIBIRC_RFC_ERR_NOTONCHANNEL

And the topic information is returned using one of following reply codes:

- LIBIRC_RFC_RPL_NOTOPIC
- LIBIRC_RFC_RPL_TOPIC

See also:
  irc_callbacks_t::event_topic irc_cmd_channel_mode