[ViewVC] Annotation of: cvs/Net-IRC-Server/README

NET::IRC::Server
      NET::IRCServer - a module to handle the IRC Protocol and implements a lightweight IRC Server (without server-to-server support)

SYNOPSIS
      use NET::IRC::Server;

      $server = NET::IRC::Server->new (srv_prefix => "mein.irc.server.funtzt.net");

      $s->set_send_cb (sub { ... });

      $s->parse_irc_stream (...)

METHODS
    new (srv_prefix => $server_prefix)
          srv_prefix - the prefix the server will use for irc commands from itself

    set_send_cb ($sub, [$command])
          The code-ref in the C<$sub> will be called everythime the server wants to send data to a client.

          If the C<$command> argument is given, the callback will only be called for irc-commands that match
          C<$command>. If the callback returns a true value when it's matched to a C<$command> the alternative callback
          (given without the C<$command>) won't be called.

          The callback will be called with following arguments: 
  
          $sub->($client, $data, $prefix, $command, $trailing, @params)

          $client   - the client datastructure you give C<parse_irc_stream ()>
          $data     - the raw data to send out, for example on a socket
          $prefix   - irc message prefix (may be undefined)
          $command  - irc command
          $trailing - the trailing irc parameter 
          @params   - the other params or the irc message

    set_cmd_cb ($cmd, $cb)
          Sets the command callback for the irc-command C<$cmd>.
          The callback is executed B<before> the command is evaluated
          by the server. If you want to prevent evaluation by the server
          later, you have to return a true value. Otherwise the server
          will evaluate the command and sends responses.

          There is are following special events/commands you can register
          a callback for, set C<$cmd> to:

          '*'    - to receive all commands
          '!'    - client successfully registered (after he send 
                   PASS, NICK and USER and all commands were successful,
                   NOTE: the returnvalue of this callback will be ignored)
  
          Arguments of the callback are like:

          $cb->($client, $ircmsg);

          $client  - the client datastructure for this command
          $ircmsg  - the irc-message hash containing:
          { 
            prefix => <irc-prefix>, 
            command => <irc-command>, 
            params => <irc-params including trailing>, 
            trailing => <the trailing parameter, also included in params>
          }

    send_srv_msg ($client, @msg)
          Sends a irc-message to C<$client> with the server-prefix.
          @msg should look like: (<command>, <trailing>, <param-1>, ..., <param-n>)

    send_msg ($client, @msg)
          Sends a irc-message to C<$client>.
          @msg should look like: (<prefix>, <command>, <trailing>, <param-1>, ..., <param-n>)

    send_nameslist ($client, $channel)
          This sends the names-list of C<$channel> to the C<$client>.

    feed_irc_data ($client, $data)
          Feeds raw IRC C<$data> for processing. When enough data for a command was
          feeded the command is handled and the callbacks set with C<set_cmd_cb> and C<set_post_cmd_cb>
          will be called. When the server wants to send a response he calls the callback set with C<set_send_cb>.

          The C<$client> data structure has to contain the C<hostname>-key, so the server can generate the irc
          message prefix for that client in his replys.

          In the callbacks the C<$client> data structure will be filled with followin keys:

          $client = {
            registered => <a flag (may be undef) whether the client finished the 
                           registration process and has a valid nickname and username>,
            nickname   => <the nickname the client currently has>,
            username   => <the username the client send when he logged in>,
            password   => <the password the client send when logged in>,
            hostname   => <this is what you have to provide>,
            channels   => { <channel-name> => 1, <channel2-name> => 1, ..., <channeln-name> }
                          (a hash of channel names the client is currently joined )
          };

    quit ($client, $quitmsg)
          It will remove the C<$client> from all lists in the server, and broadcasts the
          C<$quitmsg> to all users on the channels the C<$client> was.

    part_channel ($client, $channel, $reason)
         It will remove the C<$client> from the C<$channel> and will broadcast a PART to all members of that channel.
         The part C<$reason> may be undefined.

    join_channel ($client, $channel, $key)
         It will add the C<$client> to the C<$channel> and will broadcast a JOIN to all members of that channel.

    get_user_list ($channel)
          Get's the userlist of the $channel in the form:
          { nickname => client-structure, ... }

    register_nick ($client, $nick)
          Registers the nickname C<$nick> in the server and sets it's
          client data structure to C<$client>.

    get_nick ($nick)
          Returns the client datastructure for nickname C<$nick> or
          undef if there is no such nick;

    unregister_nick ($nick)
          Unregisters the nickname C<$nick> in the server.

    channel_exists ($channel)
          Return true if there are clients who are joined to that channel.

Revision:	1.1
Committed:	Sun Dec 4 09:54:48 2005 UTC (18 years, 5 months ago) by root
Branch:	MAIN
CVS Tags:	HEAD
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.1	NET::IRC::Server
2			NET::IRCServer - a module to handle the IRC Protocol and implements a lightweight IRC Server (without server-to-server support)
3
4			SYNOPSIS
5			use NET::IRC::Server;
6
7			$server = NET::IRC::Server->new (srv_prefix => "mein.irc.server.funtzt.net");
8
9			$s->set_send_cb (sub { ... });
10
11			$s->parse_irc_stream (...)
12
13			METHODS
14			new (srv_prefix => $server_prefix)
15			srv_prefix - the prefix the server will use for irc commands from itself
16
17			set_send_cb ($sub, [$command])
18			The code-ref in the C<$sub> will be called everythime the server wants to send data to a client.
19
20			If the C<$command> argument is given, the callback will only be called for irc-commands that match
21			C<$command>. If the callback returns a true value when it's matched to a C<$command> the alternative callback
22			(given without the C<$command>) won't be called.
23
24			The callback will be called with following arguments:
25
26			$sub->($client, $data, $prefix, $command, $trailing, @params)
27
28			$client - the client datastructure you give C<parse_irc_stream ()>
29			$data - the raw data to send out, for example on a socket
30			$prefix - irc message prefix (may be undefined)
31			$command - irc command
32			$trailing - the trailing irc parameter
33			@params - the other params or the irc message
34
35			set_cmd_cb ($cmd, $cb)
36			Sets the command callback for the irc-command C<$cmd>.
37			The callback is executed B<before> the command is evaluated
38			by the server. If you want to prevent evaluation by the server
39			later, you have to return a true value. Otherwise the server
40			will evaluate the command and sends responses.
41
42			There is are following special events/commands you can register
43			a callback for, set C<$cmd> to:
44
45			'*' - to receive all commands
46			'!' - client successfully registered (after he send
47			PASS, NICK and USER and all commands were successful,
48			NOTE: the returnvalue of this callback will be ignored)
49
50			Arguments of the callback are like:
51
52			$cb->($client, $ircmsg);
53
54			$client - the client datastructure for this command
55			$ircmsg - the irc-message hash containing:
56			{
57			prefix => <irc-prefix>,
58			command => <irc-command>,
59			params => <irc-params including trailing>,
60			trailing => <the trailing parameter, also included in params>
61			}
62
63			send_srv_msg ($client, @msg)
64			Sends a irc-message to C<$client> with the server-prefix.
65			@msg should look like: (<command>, <trailing>, <param-1>, ..., <param-n>)
66
67			send_msg ($client, @msg)
68			Sends a irc-message to C<$client>.
69			@msg should look like: (<prefix>, <command>, <trailing>, <param-1>, ..., <param-n>)
70
71			send_nameslist ($client, $channel)
72			This sends the names-list of C<$channel> to the C<$client>.
73
74			feed_irc_data ($client, $data)
75			Feeds raw IRC C<$data> for processing. When enough data for a command was
76			feeded the command is handled and the callbacks set with C<set_cmd_cb> and C<set_post_cmd_cb>
77			will be called. When the server wants to send a response he calls the callback set with C<set_send_cb>.
78
79			The C<$client> data structure has to contain the C<hostname>-key, so the server can generate the irc
80			message prefix for that client in his replys.
81
82			In the callbacks the C<$client> data structure will be filled with followin keys:
83
84			$client = {
85			registered => <a flag (may be undef) whether the client finished the
86			registration process and has a valid nickname and username>,
87			nickname => <the nickname the client currently has>,
88			username => <the username the client send when he logged in>,
89			password => <the password the client send when logged in>,
90			hostname => <this is what you have to provide>,
91			channels => { <channel-name> => 1, <channel2-name> => 1, ..., <channeln-name> }
92			(a hash of channel names the client is currently joined )
93			};
94
95			quit ($client, $quitmsg)
96			It will remove the C<$client> from all lists in the server, and broadcasts the
97			C<$quitmsg> to all users on the channels the C<$client> was.
98
99			part_channel ($client, $channel, $reason)
100			It will remove the C<$client> from the C<$channel> and will broadcast a PART to all members of that channel.
101			The part C<$reason> may be undefined.
102
103			join_channel ($client, $channel, $key)
104			It will add the C<$client> to the C<$channel> and will broadcast a JOIN to all members of that channel.
105
106			get_user_list ($channel)
107			Get's the userlist of the $channel in the form:
108			{ nickname => client-structure, ... }
109
110			register_nick ($client, $nick)
111			Registers the nickname C<$nick> in the server and sets it's
112			client data structure to C<$client>.
113
114			get_nick ($nick)
115			Returns the client datastructure for nickname C<$nick> or
116			undef if there is no such nick;
117
118			unregister_nick ($nick)
119			Unregisters the nickname C<$nick> in the server.
120
121			channel_exists ($channel)
122			Return true if there are clients who are joined to that channel.
123