# Handling IRC events.

## Data Structures

struct | irc_callbacks_t
| Event callbacks structure. More...

## Typedefs

typedef void(* | irc_event_callback_t )(irc_session_t *session, const char *event, const char *origin, const char **params, unsigned int count)
| A most common event callback.
typedef void(* | irc_eventcode_callback_t )(irc_session_t *session, unsigned int event, const char *origin, const char **params, unsigned int count)
| A numeric event callback.
typedef void(* | irc_event_dcc_chat_t )(irc_session_t *session, const char *nick, const char *addr, irc_dcc_t dccid)
| A remote DCC CHAT request callback.
typedef void(* | irc_event_dcc_send_t )(irc_session_t *session, const char *nick, const char *addr, const char *filename, unsigned long size, irc_dcc_t dccid)
| A remote DCC CHAT request callback.

## Typedef Documentation

typedef void(* irc_event_callback_t)(irc_session_t *session, const char *event, const char *origin, const char **params, unsigned int count)

A most common event callback.

Parameters:

  | session | the session, which generates an event
  | event | the text name of the event. Useful in case you use a single event handler for several events simultaneously.
  | origin | the originator of the event. See the note below.
  | params | a list of event params. Depending on the event nature, it could have zero or more params. The actual number of params is specified in count. None of the params can be NULL, but 'params' pointer itself could be NULL for some events.
  | count | the total number of params supplied.

Every event generates a callback. This callback is generated by most events. Depending on the event nature, it can provide zero or more params. For each event, the number of provided params is fixed, and their meaning is described.

Every event has origin, though the origin variable may be NULL, which means that event origin is unknown. The origin usually looks like nick!host@ircserver, i.e. like tim!home@irc.krasnogorsk.ru. Such origins can not be used in IRC commands, and need to be stripped (i.e. host and server part should be cut off) before using. This can be done either explicitly, by calling irc_target_get_nick(), or implicitly for all the events - by setting the LIBIRC_OPTION_STRIPNICKS option with irc_option_set().

typedef void(* irc_event_dcc_chat_t)(irc_session_t *session, const char *nick, const char *addr, irc_dcc_t dccid)

A remote DCC CHAT request callback.

Parameters:

  | session | the session, which generates an event
  | nick | the person who requested DCC CHAT with you.
  | addr | the person's IP address in decimal-dot notation.
  | dccid | an id associated with this request. Use it in calls to irc_dcc_accept() or irc_dcc_decline().

This callback is called when someone requests DCC CHAT with you. In respond you should call either irc_dcc_accept() to accept chat request, or irc_dcc_decline() to decline chat request.

See also:
  irc_dcc_accept or irc_dcc_decline

typedef void(* irc_event_dcc_send_t)(irc_session_t *session, const char *nick, const char *addr, const char *filename, unsigned long size, irc_dcc_t dccid)

A remote DCC CHAT request callback.

Parameters:

  | session | the session, which generates an event
  | nick | the person who requested DCC CHAT with you.
  | addr | the person's IP address in decimal-dot notation.
  | filename | the sent filename.
  | size | the filename size.
  | dccid | an id associated with this request. Use it in calls to irc_dcc_accept() or irc_dcc_decline().

This callback is called when someone wants to send a file to you using DCC SEND. As with chat, in respond you should call either irc_dcc_accept() to accept this request and receive the file, or irc_dcc_decline() to decline this request.

See also:
  irc_dcc_accept or irc_dcc_decline

typedef void(* irc_eventcode_callback_t)(irc_session_t *session, unsigned int event, const char *origin, const char **params, unsigned int count)

A numeric event callback.

Parameters:

  | session | the session, which generates an event
  | event | the numeric code of the event. Useful in case you use a single event handler for several events simultaneously.
  | origin | the originator of the event. See the note below.
  | params | a list of event params. Depending on the event nature, it could have zero or more params. The actual number of params is specified in count. None of the params can be NULL, but 'params' pointer itself could be NULL for some events.
  | count | the total number of params supplied.

Most times in reply to your actions the IRC server generates numeric callbacks. Most of them are error codes, and some of them mark list start and list stop markers. Every code has its own set of params; for details you can either experiment, or read RFC 1459.

Every event has origin, though the origin variable may be NULL, which means that event origin is unknown. The origin usually looks like nick!host@ircserver, i.e. like tim!home@irc.krasnogorsk.ru. Such origins can not be used in IRC commands, and need to be stripped (i.e. host and server part should be cut off) before using. This can be done either explicitly, by calling irc_target_get_nick(), or implicitly for all the events - by setting the LIBIRC_OPTION_STRIPNICKS option with irc_option_set().