/**
 * $Id: DOCUMENTATION,v 1.1.1.1 2002/12/23 01:53:03 meebey Exp $
 * $Revision: 1.1.1.1 $
 * $Author: meebey $
 * $Date: 2002/12/23 01:53:03 $
 */

Documention of Net_SmartIRC
-------------------------------

Contents:
- Overview of the class
- Setting related methods
- Controlling methods
- IRC related methods
- Internal methods
- Message Types

Overview of the class:
-------------------
Net_SmartIRC
	ban
	benchmark
	benchmarkend
	benchmarkstart
	bufferedsend
	changenick
	checkbuffer
	checktimer
	connect
	debug
	deop
	disconnect
	disconnecttime
	getlist
	gettopic
	gettype
	invite
	join
	kick
	listen
	listen_for
	log
	login
	message
	microint
	mode
	names
	nicknameinuse
	op
	part
	pong
	quit
	rawreceive
	rawsend
	receivedelay
	register_actionhandler
	register_timehandler
	reorderactionhandler
	reordertimehandler
	senddelay
	setlogdestination
	setlogfile
	settopic
	show_benchmark
	state
	unban
	unregister_actionhandler
	unregister_actionid
	unregister_timeid
	updatestate
	usesockets
	who
	whois
	whowas
	
Setting related methods:
----------------------
	benchmark
	debug
	receivedelay
	senddelay
	setlogdestination
	setlogfile
	usesockets

benchmark( BOOLEAN )
Enables/disables the benchmark engine

debug( DEBUGLEVEL )
Sets the debug level (bitwise), useful for testing/developing your code.
A full list of avialable debug levels see in this documentation 'Debug Levels'.
DEBUGLEVEL (contants):
Default: DEBUG_NOTICE

receivedelay( MILLISECONDS )
Sets the delaytime between messages that are received, this reduces your CPU load.
Don't set this too low, you won't receive any data if it doesn't wait long enough (min 100ms).
MILLISECONDS (integer):
Delaytime in milliseconds
Default: 250

senddelay( MILLISECONDS )
Sets the delaytime between messages that are sent, because IRC servers doesn't like floods.
This will avoid sending your messages too fast to the IRC server.
MILLISECONDS (integer):
Delaytime in milliseconds
Default: 250

setlogdestination( TYPE )
Sets the destination of log messages.
TYPE (constant):
 FILE for saving the log into a file
 STDOUT for echo the log to stdout
 SYSLOG for sending the log to the syslog
Default: STDOUT

setlogfile( FILE )
Sets the logfile, if logdestination is FILE.

usesockets( BOOLEAN )
Enables/disables the usage of real sockets instead of fsocks
(works only if your PHP build supports real sockets)
Default: FALSE

Controlling methods:
-------------------
	benchmarkend
	benchmarkstart
	connect
	disconnect
	register_actionhandler
	register_timehandler
	listen
	listen_for
	log

benchmarkend()
stops the benchmark and displays the result

benchmarkstart()
starts the benchmark (counters)

connect( IRCSERVER, PORT )
connects to the specified IRC server on the given port

disconnect( QUICK )
disconnects from the IRC server in the given quickness mode.
QUICK (boolean):	TRUE, just close the socket
									FALSE, send QUIT before closing the socket
Default: FALSE

register_actionhandler( TYPE, HANDLER, &OBJECT, METHODNAME )
Registers an actionhandler in Net_SmartIRC for calling it later.
TYPE (constants):				bits constants, see in this documentation Message Types
HANDLER (regex string):	the message that has to be in the IRC message in regex syntax
OBJECT (object):				a reference to the objects of the method
METHODNAME (string):		the methodname that will be called when the handler happens

register_timehandler( INTERVAL, &OBJECT, METHODNAME )
Registers an timehandler in Net_SmartIRC, which will be called by the specified interval.
INTERVAL (integer):			interval time in milliseconds
OBJECT (object):				a reference to the objects of the method
METHODNAME (string):		the methodname that will be called when the handler happens

listen()
Goes into receive and idle mode. Only call this if you want to "spawn" the bot.
No further lines of PHP code will be processed after this call, only the bot methods!

listen_for( TYPE, &RESULT )
Creates a special actionhandler for that given TYPE and saves the answer in RESULT.
This will only receive the requested type, immediately quit and disconnect from the IRC server.
Made for showing IRC statistics on your homepage, or other IRC related information.
TYPE (constant):				see in this documentation 'Message Types'
RESULT (string/array):	answer from the IRC server

log( LOGLEVEL, ENTRY )
Adds an entry to the log with Linux style log format
LOGLEVEL (constants):	bit constants (DEBUG_*)
ENTRY (string):				the new log string

IRC related methods:
-------------------
	ban
	changenick
	deop
	getlist
	gettopic
	invite
	join
	kick
	login
	message
	mode
	names
	op
	part
	quit
	settopic
	unban
	who
	whois
	whowas

ban( CHANNEL, HOSTMASK )
Bans the given hostmask on a channel.
CHANNEL (string)
HOSTMASK (string)

changenick( NEWNICK )
Trys to set a new nickname, nickcollisions are handled.
NEWNICK (string)

deop( CHANNEL, NICKNAME )
Deops the specified user on a channel.
CHANNEL (string)
NICKNAME (string)

getlist( [CHANNELARRAY] )
Requests a channellist (use it with care, usualy its a looooong list).
CHANNELARRAY (string or array)

gettopic( CHANNEL )
Get the topic of the specified channel.
CHANNEL (string)

invite( NICKNAME, CHANNEL )
Intivites the given user to the channel.
NICKNAME (string)
CHANNEL (string)

join( CHANNEL, [KEY] )
Joins the channel with an optional key.
CHANNEL (string)
KEY (string)

kick( CHANNEL, NICKNAME, [REASON] )
Kicks a user out of the channel with an optional reason.
CHANNEL (string)
NICKNAME (string)
REASON (string)

login( NICK, REALNAME, [USERNAME] )
Registers the nickname and user information in the IRC network.
NICK (string)
REALNAME (string)
USERNAME (string)

message( TYPE, DESTINATION, MESSAGE )
Sends a message to a channel or user.
TYPE (constant):			defines the type, like QUERY/ACTION or CTCP see "Message Types"
DESTINATION (string):	can be a user or channel
MESSAGE (string):			the message

mode( TARGET, [NEWMODE] )
Changes/requests the mode of the given target.
TARGET (string):	the target, can be an user (only yourself) or a channel
NEWMODE (string):	the new mode like +ovb

names( CHANNELARRAY )
Requests a namelist of the given channel(s).
CHANNELARRAY (string or array)

op( CHANNEL, NICKNAME )
Ops a user on the given channel.
CHANNEL (string)
NICKNAME (string)

part( CHANNELARRAY, [REASON] )
Parting from channel(s).
CHANNELARRAY (string or array)
REASON (string)

quit( [QUITMESSAGE] )
Quitting from the IRC network.
QUITMESSAGE (string)

settopic( CHANNEL, TOPIC )
Change the topic of a channel.
CHANNEL (string)
TOPIC (string)

unban( CHANNEL, HOSTMASK )
Unbans the given hostmask on the specified channel.
CHANNEL (string)
HOSTMASK (string)

who( TARGET )
Receives the 'who' information of a user or channel.
TARGET (string)

whois( TARGET )
Receives the 'whois' information of a user or channel
TARGET (string)

whowas( TARGET )
Receives the 'whowas' information of a user or channel (if he left the IRC network)
TARGET (string)

Internal methods:
----------------
The following methods should _never_ be called directly,
but still documentated for developers!

	_bufferedsend
	_checkbuffer
	_checktimer
	_gettype
	_microint
	_nicknameinuse
	_pong
	_rawreceive
	_rawsend
	_reorderactionhandler
	_reordertimehandler
	_state
	_updatestate

_bufferedsend( DATA )
Adds a message to the messagequeue.
DATA (string)

_checkbuffer()
Checks the messagequeue for sending more/new messages.

_checktimer()
Checks the running timers and calls the registered timehandler,
when the interval is reached.

MESSAGE_TYPE: _gettype( LINE )
Analyses the type of a IRC message and returns the type.
LINE (string)
return value:
MESSAGE_TYPE (constant)

_pong( DATA )
Sending the reply PONG signal of the PING from the IRC server.
DATA (string)

_rawreceive()
Goes into receive main loop.

_rawsend( DATA )
Send directly a raw message to the IRC server.
DATA (string)

STATE: _state()
Returns the current connection state.
return value:
STATE_CONNECTED
STATE_DISCONNETED

_updatestate()
Updates the connection state.

Message Types:
--------------
For register_actionhandler() and message() you define a message type.
The IRC protocol defines different kinds of messages. I don't cover all of them because
there are just too many of them.
register_actionhandler() uses bitwise constats, eg. TYPE_QUERY|TYPE_NOTICE would match
if the message is TYPE_QUERY _or_ TYPE_NOTICE.
Net_SmartIRC supports currently the following message types:
TYPE_UNKNOWN
TYPE_CHANNEL
TYPE_QUERY
TYPE_CTCP
TYPE_NOTICE
TYPE_WHO
TYPE_JOIN
TYPE_INVITE
TYPE_ACTION
TYPE_TOPICCHANGE
TYPE_NICKCHANGE
TYPE_KICK
TYPE_QUIT
TYPE_LOGIN
TYPE_INFO
TYPE_LIST
TYPE_NAME
TYPE_MOTD
TYPE_MODECHANGE
TYPE_PART
TYPE_ERROR
TYPE_BANLIST
TYPE_TOPIC

Debug Levels:
------------
Here the list of avialable debug levels, used for the debug() setting and log() method:
DEBUG_NONE
DEBUG_NOTICE
DEBUG_CONNECTION
DEBUG_SOCKET
DEBUG_IRCMESSAGES
DEBUG_MESSAGETYPES
DEBUG_ACTIONHANDLER
DEBUG_TIMEHANDLER
DEBUG_ALL
