|
PircBot Java IRC Bot | |||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
org.jibble.pircbot
Class PircBot
java.lang.Object | +--org.jibble.pircbot.PircBot
- All Implemented Interfaces:
- ReplyConstants
- public abstract class PircBot
- extends Object
- implements ReplyConstants
- extends Object
PircBot is a Java framework for writing IRC bots quickly and easily.
It provides an event-driven architecture to handle common IRC events, flood protection, DCC support, ident support, and more. The comprehensive logfile format is suitable for use with pisg to generate channel statistics.
Methods of the PircBot class can be called to send events to the IRC server that it connects to. For example, calling the sendMessage method will send a message to a channel or user on the IRC server. Multiple servers can be supported using multiple instances of PircBot.
To perform an action when the PircBot receives a normal message from the IRC server, you would override the onMessage method defined in the PircBot class. All onXYZ methods in the PircBot class are automatically called when the event XYZ happens, so you would override these if you wish to do something when it does happen.
Some event methods, such as onPing, should only really perform a specific function (i.e. respond to a PING from the server). For your convenience, such methods are already correctly implemented in the PircBot and should not normally need to be overridden. Please read the full documentation for each method to see which ones are already implemented by the PircBot class.
Please visit the PircBot homepage at http://www.jibble.org/pircbot.php for full revision history, a beginners guide to creating your first PircBot and a list of some existing Java IRC bots and clients that use the PircBot framework.
- Version:
- 1.0.3 (Build time: Sat Jan 18 23:29:54 2003)
- Author:
- Paul James Mutton, http://www.jibble.org/
| Field Summary | |
static String |
VERSION
The definitive version number of this release of PircBot. |
| Constructor Summary | |
PircBot()
Constructs a PircBot with the default settings. |
|
| Method Summary | |
void |
ban(String channel,
String hostmask)
Bans a user from a channel. |
void |
changeNick(String newNick)
Attempt to change the current nick (nickname) of the bot when it is connected to an IRC server. |
void |
connect(String hostname)
Attempt to connect to the specified IRC server. |
void |
connect(String hostname,
int port)
Attempt to connect to the specified IRC server and port number. |
void |
connect(String hostname,
int port,
String password)
Attempt to connect to the specified IRC server using the supplied password. |
protected DccChat |
dccAcceptChatRequest(String sourceNick,
long address,
int port)
Attempts to accept a DCC CHAT request by a client. |
protected void |
dccReceiveFile(File file,
long address,
int port,
int size)
Receives a file that is being sent to us by a DCC SEND request. |
DccChat |
dccSendChatRequest(String nick,
int timeout)
Attempts to establish a DCC CHAT session with a client. |
void |
dccSendFile(File file,
String nick,
int timeout)
Issues a DCC SEND request to the specified nick. |
void |
deOp(String channel,
String nick)
Removes operator privilidges from a user on a channel. |
void |
deVoice(String channel,
String nick)
Removes voice privilidges from a user on a channel. |
void |
disconnect()
This method disconnects from the server cleanly by calling the quitServer() method. |
boolean |
equals(Object o)
Returns true if and only if the object being compared is the exact same instance as this PircBot. |
String[] |
getChannels()
Returns an array of all channels that we are in. |
String |
getFinger()
Gets the internal finger message of the PircBot. |
String |
getLogin()
Gets the internal login of the PircBot. |
int |
getMaxLineLength()
Gets the maximum length of any line that is sent via the IRC protocol. |
long |
getMessageDelay()
Returns the number of milliseconds that will be used to separate consecutive messages to the server from the outgoing message queue. |
String |
getName()
Gets the name of the PircBot. |
String |
getNick()
Returns the current nick of the bot. |
int |
getOutgoingQueueSize()
Gets the number of lines currently waiting in the outgoing message Queue. |
String |
getPassword()
Returns the last password that we used when connecting to an IRC server. |
int |
getPort()
Returns the port number of the last IRC server that the PircBot tried to connect to. |
String |
getServer()
Returns the name of the last IRC server the PircBot tried to connect to. |
User[] |
getUsers(String channel)
Returns an array of all users in the specified channel. |
String |
getVersion()
Gets the internal version of the PircBot. |
protected void |
handleLine(String line)
This method handles events when any line of text arrives from the server, then calling the appropriate method in the PircBot. |
int |
hashCode()
Returns the hashCode of this PircBot. |
long |
ipToLong(byte[] address)
A convenient method that accepts an IP address represented by a byte[] of size 4 and returns this as a long representation of the same IP address. |
boolean |
isConnected()
Returns whether or not the PircBot is currently connected to a server. |
void |
joinChannel(String channel)
Joins a channel. |
void |
joinChannel(String channel,
String key)
Joins a channel with a key. |
void |
kick(String channel,
String nick)
Kicks a user from a channel. |
void |
kick(String channel,
String nick,
String reason)
Kicks a user from a channel, giving a reason. |
void |
listChannels()
Issues a request for a list of all channels on the IRC server. |
void |
listChannels(String parameters)
Issues a request for a list of all channels on the IRC server. |
void |
log(String line)
Adds a line to the log. |
int[] |
longToIp(long address)
A convenient method that accepts an IP address represented as a long and returns an integer array of size 4 representing the same IP address. |
protected void |
onAction(String sender,
String login,
String hostname,
String target,
String action)
This method is called whenever an ACTION is sent from a user. |
protected void |
onChannelInfo(String channel,
int userCount,
String topic)
After calling the listChannels() method in PircBot, the server will start to send us information about each channel on the server. |
protected void |
onConnect()
This method is called once the PircBot has successfully connected to the IRC server. |
protected void |
onDccChatRequest(String sourceNick,
String sourceLogin,
String sourceHostname,
long address,
int port)
This method is called whenever a DCC CHAT request is sent to the PircBot. |
protected void |
onDccSendRequest(String sourceNick,
String sourceLogin,
String sourceHostname,
String filename,
long address,
int port,
int size)
This method is called whenever a DCC SEND request is sent to the PircBot. |
protected void |
onDeop(String channel,
String sourceNick,
String sourceLogin,
String sourceHostname,
String recipient)
Called when a user (possibly us) gets operator status taken away. |
protected void |
onDeVoice(String channel,
String sourceNick,
String sourceLogin,
String sourceHostname,
String recipient)
Called when a user (possibly us) gets voice status removed. |
protected void |
onDisconnect()
This method carries out the actions to be performed when the PircBot gets disconnected. |
protected void |
onFinger(String sourceNick,
String sourceLogin,
String sourceHostname,
String target)
This method is called whenever we receive a FINGER request. |
protected void |
onInvite(String targetNick,
String sourceNick,
String sourceLogin,
String sourceHostname,
String channel)
Called when we are invited to a channel by a user. |
protected void |
onJoin(String channel,
String sender,
String login,
String hostname)
This method is called whenever someone (possibly us) joins a channel which we are on. |
protected void |
onKick(String channel,
String kickerNick,
String kickerLogin,
String kickerHostname,
String recipientNick,
String reason)
This method is called whenever someone (possibly us) is kicked from any of the channels that we are in. |
protected void |
onMessage(String channel,
String sender,
String login,
String hostname,
String message)
This method is called whenever a message is sent to a channel. |
protected void |
onMode(String channel,
String sourceNick,
String sourceLogin,
String sourceHostname,
String mode)
Called when the mode of a channel is set. |
protected void |
onNickChange(String oldNick,
String login,
String hostname,
String newNick)
This method is called whenever someone (possibly us) changes nick on any of the channels that we are on. |
protected void |
onNotice(String sourceNick,
String sourceLogin,
String sourceHostname,
String target,
String notice)
This method is called whenever we receive a notice. |
protected void |
onOp(String channel,
String sourceNick,
String sourceLogin,
String sourceHostname,
String recipient)
Called when a user (possibly us) gets granted operator status for a channel. |
protected void |
onPart(String channel,
String sender,
String login,
String hostname)
This method is called whenever someone (possibly us) parts a channel which we are on. |
protected void |
onPing(String sourceNick,
String sourceLogin,
String sourceHostname,
String target,
String pingValue)
This method is called whenever we receive a PING request from another user. |
protected void |
onPrivateMessage(String sender,
String login,
String hostname,
String message)
This method is called whenever a private message is sent to the PircBot. |
protected void |
onQuit(String sourceNick,
String sourceLogin,
String sourceHostname,
String reason)
This method is called whenever someone (possibly us) quits from the server. |
protected void |
onRemoveChannelBan(String channel,
String sourceNick,
String sourceLogin,
String sourceHostname,
String hostmask)
Called when a hostmask ban is removed from a channel. |
protected void |
onRemoveChannelKey(String channel,
String sourceNick,
String sourceLogin,
String sourceHostname,
String key)
Called when a channel key is removed. |
protected void |
onRemoveChannelLimit(String channel,
String sourceNick,
String sourceLogin,
String sourceHostname)
Called when the user limit is removed for a channel. |
protected void |
onRemoveInviteOnly(String channel,
String sourceNick,
String sourceLogin,
String sourceHostname)
Called when a channel has 'invite only' removed. |
protected void |
onRemoveModerated(String channel,
String sourceNick,
String sourceLogin,
String sourceHostname)
Called when a channel has moderated mode removed. |
protected void |
onRemoveNoExternalMessages(String channel,
String sourceNick,
String sourceLogin,
String sourceHostname)
Called when a channel is set to allow messages from any user, even if they are not actually in the channel. |
protected void |
onRemovePrivate(String channel,
String sourceNick,
String sourceLogin,
String sourceHostname)
Called when a channel is marked as not being in private mode. |
protected void |
onRemoveSecret(String channel,
String sourceNick,
String sourceLogin,
String sourceHostname)
Called when a channel has 'secret' mode removed. |
protected void |
onRemoveTopicProtection(String channel,
String sourceNick,
String sourceLogin,
String sourceHostname)
Called when topic protection is removed for a channel. |
protected void |
onServerPing(String response)
The actions to perform when a PING request comes from the server. |
protected void |
onServerResponse(int code,
String response)
This method is called when we receive a numeric response from the IRC server. |
protected void |
onSetChannelBan(String channel,
String sourceNick,
String sourceLogin,
String sourceHostname,
String hostmask)
Called when a user (possibly us) gets banned from a channel. |
protected void |
onSetChannelKey(String channel,
String sourceNick,
String sourceLogin,
String sourceHostname,
String key)
Called when a channel key is set. |
protected void |
onSetChannelLimit(String channel,
String sourceNick,
String sourceLogin,
String sourceHostname,
int limit)
Called when a user limit is set for a channel. |
protected void |
onSetInviteOnly(String channel,
String sourceNick,
String sourceLogin,
String sourceHostname)
Called when a channel is set to 'invite only' mode. |
protected void |
onSetModerated(String channel,
String sourceNick,
String sourceLogin,
String sourceHostname)
Called when a channel is set to 'moderated' mode. |
protected void |
onSetNoExternalMessages(String channel,
String sourceNick,
String sourceLogin,
String sourceHostname)
Called when a channel is set to only allow messages from users that are in the channel. |
protected void |
onSetPrivate(String channel,
String sourceNick,
String sourceLogin,
String sourceHostname)
Called when a channel is marked as being in private mode. |
protected void |
onSetSecret(String channel,
String sourceNick,
String sourceLogin,
String sourceHostname)
Called when a channel is set to be in 'secret' mode. |
protected void |
onSetTopicProtection(String channel,
String sourceNick,
String sourceLogin,
String sourceHostname)
Called when topic protection is enabled for a channel. |
protected void |
onTime(String sourceNick,
String sourceLogin,
String sourceHostname,
String target)
This method is called whenever we receive a TIME request. |
protected void |
onTopic(String channel,
String topic)
This method is called whenever a user sets the topic, or when PircBot joins a new channel and discovers its topic. |
protected void |
onUnknown(String line)
This method is called whenever we receive a line from the server that the PircBot has not been programmed to recognise. |
protected void |
onUserList(String channel,
User[] users)
This method is called when we receive a user list from the server after joining a channel. |
protected void |
onVersion(String sourceNick,
String sourceLogin,
String sourceHostname,
String target)
This method is called whenever we receive a VERSION request. |
protected void |
onVoice(String channel,
String sourceNick,
String sourceLogin,
String sourceHostname,
String recipient)
Called when a user (possibly us) gets voice status granted in a channel. |
void |
op(String channel,
String nick)
Grants operator privilidges to a user on a channel. |
void |
partChannel(String channel)
Parts a channel. |
void |
partChannel(String channel,
String reason)
Parts a channel, giving a reason. |
void |
quitServer()
Quits from the IRC server. |
void |
quitServer(String reason)
Quits from the IRC server with a reason. |
void |
reconnect()
Reconnects to the IRC server that we were previously connected to. |
void |
sendAction(String target,
String action)
Sends an action to the channel or to a user. |
void |
sendCTCPCommand(String target,
String command)
Sends a CTCP command to a channel or user. |
void |
sendInvite(String nick,
String channel)
Sends an invitation to join a channel. |
void |
sendMessage(String target,
String message)
Sends a message to a channel or a private message to a user. |
void |
sendNotice(String target,
String notice)
Sends a notice to the channel or to a user. |
void |
sendRawLine(String line)
Sends a raw line to the IRC server as soon as possible, bypassing the outgoing message queue. |
protected void |
setFinger(String finger)
Sets the interal finger message. |
protected void |
setLogin(String login)
Sets the internal login of the Bot. |
void |
setMessageDelay(long delay)
Sets the number of milliseconds to delay between consecutive messages when there are multiple messages waiting in the outgoing message queue. |
void |
setMode(String channel,
String mode)
Set the mode of a channel. |
protected void |
setName(String name)
Sets the name of the bot, which will be used as its nick when it tries to join an IRC server. |
void |
setTopic(String channel,
String topic)
Set the topic for a channel. |
void |
setVerbose(boolean verbose)
Sets the verbose mode. |
protected void |
setVersion(String version)
Sets the internal version of the Bot. |
void |
startIdentServer()
Starts an ident server (Identification Protocol Server, RFC 1413). |
String |
toString()
Returns a String representation of this object. |
void |
unBan(String channel,
String hostmask)
Unbans a user from a channel. |
void |
voice(String channel,
String nick)
Grants voice privilidges to a user on a channel. |
| Methods inherited from class java.lang.Object |
clone, finalize, getClass, notify, notifyAll, wait, wait, wait |
| Field Detail |
VERSION
public static final String VERSION
- The definitive version number of this release of PircBot.
(Note: Change this before automatically building releases)
- See Also:
- Constant Field Values
| Constructor Detail |
PircBot
public PircBot()
- Constructs a PircBot with the default settings. Your own constructors
in classes which extend the PircBot abstract class should be responsible
for changing the default settings if required.
| Method Detail |
connect
public final void connect(String hostname) throws IOException, IrcException, NickAlreadyInUseException
- Attempt to connect to the specified IRC server.
The onConnect method is called upon success.
- Parameters:
hostname- The hostname of the server to connect to.- Throws:
IOException- if it was not possible to connect to the server.IrcException- if the server would not let us join it.NickAlreadyInUseException- if our nick is already in use on the server.
connect
public final void connect(String hostname, int port) throws IOException, IrcException, NickAlreadyInUseException
- Attempt to connect to the specified IRC server and port number.
The onConnect method is called upon success.
- Parameters:
hostname- The hostname of the server to connect to.port- The port number to connect to on the server.- Throws:
IOException- if it was not possible to connect to the server.IrcException- if the server would not let us join it.NickAlreadyInUseException- if our nick is already in use on the server.
connect
public final void connect(String hostname, int port, String password) throws IOException, IrcException, NickAlreadyInUseException
- Attempt to connect to the specified IRC server using the supplied
password.
The onConnect method is called upon success.
- Parameters:
hostname- The hostname of the server to connect to.port- The port number to connect to on the server.password- The password to use to join the server.- Throws:
IOException- if it was not possible to connect to the server.IrcException- if the server would not let us join it.NickAlreadyInUseException- if our nick is already in use on the server.
reconnect
public final void reconnect()
throws IOException,
IrcException,
NickAlreadyInUseException
- Reconnects to the IRC server that we were previously connected to.
If necessary, the appropriate port number and password will be used.
This method will throw an IrcException if we have never connected
to an IRC server previously.
- Throws:
IOException- if it was not possible to connect to the server.IrcException- if the server would not let us join it.NickAlreadyInUseException- if our nick is already in use on the server.- Since:
- 0.9.9
disconnect
public final void disconnect()
- This method disconnects from the server cleanly by calling the
quitServer() method. Providing the PircBot was connected to an
IRC server, the onDisconnect() will be called as soon as the
disconnection is made by the server.
- See Also:
quitServer,quitServer
startIdentServer
public final void startIdentServer()
- Starts an ident server (Identification Protocol Server, RFC 1413).
Most IRC servers attempt to contact the ident server on connecting hosts in order to determine the user's identity. A few IRC servers will not allow you to connect unless this information is provided.
So when a PircBot is run on a machine that does not run an ident server, it may be necessary to call this method to start one up.
Calling this method starts up an ident server which will respond with the login provided by calling getLogin() and then shut down immediately. It will also be shut down if it has not been contacted within 60 seconds of creation.
If you require an ident response, then the correct procedure is to start the ident server and then connect to the IRC server. The IRC server may then contact the ident server to get the information it needs.
The ident server will fail to start if there is already an ident server running on port 113, or if you are running as an unprivileged user who is unable to create a server socket on that port number.
If it is essential for you to use an ident server when connecting to an IRC server, then make sure that port 113 on your machine is visible to the IRC server so that it may contact the ident server.
- Since:
- 0.9c
joinChannel
public final void joinChannel(String channel)
- Joins a channel.
- Parameters:
channel- The name of the channel to join (eg "#cs").
joinChannel
public final void joinChannel(String channel, String key)
- Joins a channel with a key.
- Parameters:
channel- The name of the channel to join (eg "#cs").key- The key that will be used to join the channel.
partChannel
public final void partChannel(String channel)
- Parts a channel.
- Parameters:
channel- The name of the channel to leave.
partChannel
public final void partChannel(String channel, String reason)
- Parts a channel, giving a reason.
- Parameters:
channel- The name of the channel to leave.reason- The reason for parting the channel.
quitServer
public final void quitServer()
- Quits from the IRC server.
Providing we are actually connected to an IRC server, the
onDisconnect() method will be called as soon as the IRC server
disconnects us.
quitServer
public final void quitServer(String reason)
- Quits from the IRC server with a reason.
Providing we are actually connected to an IRC server, the
onDisconnect() method will be called as soon as the IRC server
disconnects us.
- Parameters:
reason- The reason for quitting the server.
sendRawLine
public final void sendRawLine(String line)
- Sends a raw line to the IRC server as soon as possible, bypassing the
outgoing message queue.
- Parameters:
line- The raw line to send to the IRC server.
sendMessage
public final void sendMessage(String target, String message)
- Sends a message to a channel or a private message to a user. These
messages are added to the outgoing message queue and sent at the
earliest possible opportunity.
Some examples: -
// Send the message "Hello!" to the channel #cs. sendMessage("#cs", "Hello!"); // Send a private message to Paul that says "Hi". sendMessage("Paul", "Hi");You may optionally apply colours, boldness, underlining, etc to the message by using theColorsclass.- Parameters:
target- The name of the channel or user nick to send to.message- The message to send.- See Also:
Colors
sendAction
public final void sendAction(String target, String action)
- Sends an action to the channel or to a user.
- Parameters:
target- The name of the channel or user nick to send to.action- The action to send.- See Also:
Colors
sendNotice
public final void sendNotice(String target, String notice)
- Sends a notice to the channel or to a user.
- Parameters:
target- The name of the channel or user nick to send to.notice- The notice to send.
sendCTCPCommand
public final void sendCTCPCommand(String target, String command)
- Sends a CTCP command to a channel or user. (Client to client protocol).
Examples of such commands are "PING
", "FINGER", "VERSION", etc. For example, if you wish to request the version of a user called "Dave", then you would call sendCTCPCommand("Dave", "VERSION");. The type of response to such commands is largely dependant on the target client software.- Parameters:
target- The name of the channel or user to send the CTCP message to.command- The CTCP command to send.- Since:
- 0.9.5
changeNick
public final void changeNick(String newNick)
- Attempt to change the current nick (nickname) of the bot when it
is connected to an IRC server.
After confirmation of a successful nick change, the getNick method
will return the new nick.
- Parameters:
newNick- The new nick to use.
setMode
public final void setMode(String channel, String mode)
- Set the mode of a channel.
This method attempts to set the mode of a channel. This
may require the bot to have operator status on the channel.
For example, if the bot has operator status, we can grant
operator status to "Dave" on the #cs channel
by calling setMode("#cs", "+o Dave");
An alternative way of doing this would be to use the op method.
- Parameters:
channel- The channel on which to perform the mode change.mode- The new mode to apply to the channel. This may include zero or more arguments if necessary.- See Also:
op
sendInvite
public final void sendInvite(String nick, String channel)
- Sends an invitation to join a channel. Some channels can be marked
as "invite-only", so it may be useful to allow a bot to invite people
into it.
- Parameters:
nick- The nick of the user to invitechannel- The channel you are inviting the user to join.
ban
public final void ban(String channel, String hostmask)
- Bans a user from a channel. An example of a valid hostmask is
"*!*compu@*.18hp.net". This may be used in conjunction with the
kick method to permanently remove a user from a channel.
Successful use of this method may require the bot to have operator
status itself.
- Parameters:
channel- The channel to ban the user from.hostmask- A hostmask representing the user we're banning.
unBan
public final void unBan(String channel, String hostmask)
- Unbans a user from a channel. An example of a valid hostmask is
"*!*compu@*.18hp.net".
Successful use of this method may require the bot to have operator
status itself.
- Parameters:
channel- The channel to unban the user from.hostmask- A hostmask representing the user we're unbanning.
op
public final void op(String channel, String nick)
- Grants operator privilidges to a user on a channel.
Successful use of this method may require the bot to have operator
status itself.
- Parameters:
channel- The channel we're opping the user on.nick- The nick of the user we are opping.
deOp
public final void deOp(String channel, String nick)
- Removes operator privilidges from a user on a channel.
Successful use of this method may require the bot to have operator
status itself.
- Parameters:
channel- The channel we're deopping the user on.nick- The nick of the user we are deopping.
voice
public final void voice(String channel, String nick)
- Grants voice privilidges to a user on a channel.
Successful use of this method may require the bot to have operator
status itself.
- Parameters:
channel- The channel we're voicing the user on.nick- The nick of the user we are voicing.
deVoice
public final void deVoice(String channel, String nick)
- Removes voice privilidges from a user on a channel.
Successful use of this method may require the bot to have operator
status itself.
- Parameters:
channel- The channel we're devoicing the user on.nick- The nick of the user we are devoicing.
setTopic
public final void setTopic(String channel, String topic)
- Set the topic for a channel.
This method attempts to set the topic of a channel. This
may require the bot to have operator status if the topic
is protected.
- Parameters:
channel- The channel on which to perform the mode change.topic- The new topic for the channel.
kick
public final void kick(String channel, String nick)
- Kicks a user from a channel.
This method attempts to kick a user from a channel and
may require the bot to have operator status in the channel.
- Parameters:
channel- The channel to kick the user from.nick- The nick of the user to kick.
kick
public final void kick(String channel, String nick, String reason)
- Kicks a user from a channel, giving a reason.
This method attempts to kick a user from a channel and
may require the bot to have operator status in the channel.
- Parameters:
channel- The channel to kick the user from.nick- The nick of the user to kick.reason- A description of the reason for kicking a user.
listChannels
public final void listChannels()
- Issues a request for a list of all channels on the IRC server.
When the PircBot receives information for each channel, it will
call the onChannelInfo method, which you will need to override
if you want it to do anything useful.
- See Also:
onChannelInfo
listChannels
public final void listChannels(String parameters)
- Issues a request for a list of all channels on the IRC server.
When the PircBot receives information for each channel, it will
call the onChannelInfo method, which you will need to override
if you want it to do anything useful.
Some IRC servers support certain parameters for LIST requests. One example is a parameter of ">10" to list only those channels that have more than 10 users in them. Whether these parameters are supported or not will depend on the IRC server software.
- Parameters:
parameters- The parameters to supply when requesting the list.- See Also:
onChannelInfo
dccSendFile
public final void dccSendFile(File file, String nick, int timeout)
- Issues a DCC SEND request to the specified nick.
After doing this, the recipient is allowed up to timeout milliseconds
to accept the request by connecting to the PircBot to start downloading
the file, otherwise the chance is lost. Once the recipient has connected,
we close the connection if the download is completed, if the download fails
or if no data is sent for a 30 second period. This methods starts a
new Thread to operate in and thus returns immediately. The method
performs no action if the file named does not exist. This method may
not be overridden.
- Parameters:
nick- The nick of the recipient.timeout- The number of milliseconds to wait for the recipient to accept the file (we recommend about 120000).- Since:
- 0.9c
dccReceiveFile
protected final void dccReceiveFile(File file, long address, int port, int size)
- Receives a file that is being sent to us by a DCC SEND request.
When we receive a DCC SEND request, we use this method to connect to
the sender and download the file. This method should only be called
by the onDccSendRequest method if you choose to do so. If we do not
receive any data for more than 30 seconds, then we close the connection.
This method will overwrite any existing file which has the same filename.
This method may not be overridden.
- Parameters:
address- The host address of the initiator as an integer.port- The port number to connect to in order to download the file.size- The size of the file. If not known, this must be -1.- Since:
- 0.9c
- See Also:
onDccSendRequest
dccSendChatRequest
public final DccChat dccSendChatRequest(String nick, int timeout)
- Attempts to establish a DCC CHAT session with a client. This method
issues the connection request to the client and then waits for the
client to respond. If the connection is successfully made, then a
DccChat object is returned by this method. If the connection is not
made within the time limit specified by the timeout value, then null
is returned.
It is strongly recommended that you call this method within a new Thread, as it may take a long time to return.
This method may not be overridden.
- Parameters:
nick- The nick of the user we are trying to establish a chat with.timeout- The number of milliseconds to wait for the recipient to accept the chat connection (we recommend about 120000).- Returns:
- a DccChat object that can be used to send and recieve lines of text. Returns null if the connection could not be made.
- Since:
- 0.9.8
- See Also:
DccChat
dccAcceptChatRequest
protected final DccChat dccAcceptChatRequest(String sourceNick, long address, int port)
- Attempts to accept a DCC CHAT request by a client. This method tries
to establish the connection to the client. Once the connection has been
established, a DccChat object is returned. The DccChat object can be
used to send and receive lines of text over the direct connection.
If a connection could not be established, the DccChat object returned is
null. This method is typically called by the onDccChatRequest method
and may not be overridden.
- Returns:
- a DccChat object that can be used to send and receive lines of text. Returns null if the connection could not be made.
- Since:
- 0.9c
- See Also:
DccChat
log
public void log(String line)
- Adds a line to the log. This log is currently output to the standard
output and is in the correct format for use by tools such as pisg, the
Perl IRC Statistics Generator. You may override this method if you wish
to do something else with log entries.
Each line in the log begins with a number which
represents the logging time (as the number of milliseconds since the
epoch). This timestamp and the following log entry are separated by
a single space character, " ". Outgoing messages are distinguishable
by a log entry that has ">>>" immediately following the space character
after the timestamp. DCC events use "+++" and warnings about unhandled
Exceptions and Errors use "###".
This implementation of the method will only cause log entries to be output if the PircBot has had its verbose mode turned on by calling setVerbose(true);
- Parameters:
line- The line to add to the log.
handleLine
protected final void handleLine(String line)
- This method handles events when any line of text arrives from the server,
then calling the appropriate method in the PircBot. This method is
protected and only called by the InputThread for this instance.
This method may not be overridden!
- Parameters:
line- The raw line of text from the server.
onConnect
protected void onConnect()
- This method is called once the PircBot has successfully connected to
the IRC server.
The implementation of this method in the PircBot abstract class performs no actions and may be overridden as required.
- Since:
- 0.9.6
onDisconnect
protected void onDisconnect()
- This method carries out the actions to be performed when the PircBot
gets disconnected. This may happen if the PircBot quits from the
server, or if the connection is unexpectedly lost.
Disconnection from the IRC server is detected immediately if either we or the server close the connection normally. If the connection to the server is lost, but neither we nor the server have explicitly closed the connection, then it may take a few minutes to detect (this is commonly referred to as a "ping timeout").
If you wish to get your IRC bot to automatically rejoin a server after the connection has been lost, then this is probably the ideal method to override to implement such functionality.
The implementation of this method in the PircBot abstract class performs no actions and may be overridden as required.
onServerResponse
protected void onServerResponse(int code,
String response)
- This method is called when we receive a numeric response from the
IRC server.
Numerics in the range from 001 to 099 are used for client-server connections only and should never travel between servers. Replies generated in response to commands are found in the range from 200 to 399. Error replies are found in the range from 400 to 599.
For example, we can use this method to discover the topic of a channel when we join it. If we join the channel #test which has a topic of "I am King of Test" then the response will be "
PircBot #test :I Am King of Test" with a code of 332 to signify that this is a topic. (This is just an example - note that overriding theonTopicmethod is an easier way of finding the topic for a channel). Check the IRC RFC for the full list of other command response codes.PircBot implements the interface ReplyConstants, which contains contstants that you may find useful here.
The implementation of this method in the PircBot abstract class performs no actions and may be overridden as required.
- Parameters:
code- The three-digit numerical code for the response.response- The full response from the IRC server.- See Also:
ReplyConstants
onUserList
protected void onUserList(String channel, User[] users)
- This method is called when we receive a user list from the server
after joining a channel.
Shortly after joining a channel, the IRC server sends a list of all users in that channel. The PircBot collects this information and calls this method as soon as it has the full list.
To obtain the nick of each user in the channel, call the getNick() method on each User object in the array.
At a later time, you may call the getUsers method to obtain an up to date list of the users in the channel.
The implementation of this method in the PircBot abstract class performs no actions and may be overridden as required.
- Parameters:
channel- The name of the channel.users- An array of User objects belonging to this channel.- Since:
- 1.0.0
- See Also:
User
onMessage
protected void onMessage(String channel, String sender, String login, String hostname, String message)
- This method is called whenever a message is sent to a channel.
The implementation of this method in the PircBot abstract class performs no actions and may be overridden as required.
- Parameters:
channel- The channel to which the message was sent.sender- The nick of the person who sent the message.login- The login of the person who sent the message.hostname- The hostname of the person who sent the message.message- The actual message sent to the channel.
onPrivateMessage
protected void onPrivateMessage(String sender, String login, String hostname, String message)
- This method is called whenever a private message is sent to the PircBot.
The implementation of this method in the PircBot abstract class performs no actions and may be overridden as required.
- Parameters:
sender- The nick of the person who sent the private message.login- The login of the person who sent the private message.hostname- The hostname of the person who sent the private message.message- The actual message.
onAction
protected void onAction(String sender, String login, String hostname, String target, String action)
- This method is called whenever an ACTION is sent from a user. E.g.
such events generated by typing "/me goes shopping" in most IRC clients.
The implementation of this method in the PircBot abstract class performs no actions and may be overridden as required.
- Parameters:
sender- The nick of the user that sent the action.login- The login of the user that sent the action.hostname- The hostname of the user that sent the action.target- The target of the action, be it a channel or our nick.action- The action carried out by the user.
onNotice
protected void onNotice(String sourceNick, String sourceLogin, String sourceHostname, String target, String notice)
- This method is called whenever we receive a notice.
The implementation of this method in the PircBot abstract class performs no actions and may be overridden as required.
- Parameters:
sourceNick- The nick of the user that sent the notice.sourceLogin- The login of the user that sent the notice.sourceHostname- The hostname of the user that sent the notice.target- The target of the notice, be it our nick or a channel name.notice- The notice message.
onJoin
protected void onJoin(String channel, String sender, String login, String hostname)
- This method is called whenever someone (possibly us) joins a channel
which we are on.
The implementation of this method in the PircBot abstract class performs no actions and may be overridden as required.
- Parameters:
channel- The channel which somebody joined.sender- The nick of the user who joined the channel.login- The login of the user who joined the channel.hostname- The hostname of the user who joined the channel.
onPart
protected void onPart(String channel, String sender, String login, String hostname)
- This method is called whenever someone (possibly us) parts a channel
which we are on.
The implementation of this method in the PircBot abstract class performs no actions and may be overridden as required.
- Parameters:
channel- The channel which somebody parted from.sender- The nick of the user who parted from the channel.login- The login of the user who parted from the channel.hostname- The hostname of the user who parted from the channel.
onNickChange
protected void onNickChange(String oldNick, String login, String hostname, String newNick)
- This method is called whenever someone (possibly us) changes nick on any
of the channels that we are on.
The implementation of this method in the PircBot abstract class performs no actions and may be overridden as required.
- Parameters:
oldNick- The old nick.login- The login of the user.hostname- The hostname of the user.newNick- The new nick.
onKick
protected void onKick(String channel, String kickerNick, String kickerLogin, String kickerHostname, String recipientNick, String reason)
- This method is called whenever someone (possibly us) is kicked from
any of the channels that we are in.
The implementation of this method in the PircBot abstract class performs no actions and may be overridden as required.
- Parameters:
channel- The channel from which the recipient was kicked.kickerNick- The nick of the user who performed the kick.kickerLogin- The login of the user who performed the kick.kickerHostname- The hostname of the user who performed the kick.reason- The reason given by the user who performed the kick.
onQuit
protected void onQuit(String sourceNick, String sourceLogin, String sourceHostname, String reason)
- This method is called whenever someone (possibly us) quits from the
server. We will only observe this if the user was in one of the
channels to which we are connected.
The implementation of this method in the PircBot abstract class performs no actions and may be overridden as required.
- Parameters:
sourceNick- The nick of the user that quit from the server.sourceLogin- The login of the user that quit from the server.sourceHostname- The hostname of the user that quit from the server.reason- The reason given for quitting the server.
onTopic
protected void onTopic(String channel, String topic)
- This method is called whenever a user sets the topic, or when
PircBot joins a new channel and discovers its topic.
The implementation of this method in the PircBot abstract class performs no actions and may be overridden as required.
- Parameters:
channel- The channel that the topic belongs to.topic- The topic for the channel.
onChannelInfo
protected void onChannelInfo(String channel, int userCount, String topic)
- After calling the listChannels() method in PircBot, the server
will start to send us information about each channel on the
server. You may override this method in order to receive the
information about each channel as soon as it is received.
Note that certain channels, such as those marked as hidden, may not appear in channel listings.
The implementation of this method in the PircBot abstract class performs no actions and may be overridden as required.
- Parameters:
channel- The name of the channel.userCount- The number of users visible in this channel.topic- The topic for this channel.- See Also:
listChannels
onMode
protected void onMode(String channel, String sourceNick, String sourceLogin, String sourceHostname, String mode)
- Called when the mode of a channel is set.
You may find it more convenient to decode the meaning of the mode string by overriding the onOp, onDeOp, onVoice, onDeVoice, onChannelKey, onDeChannelKey, onChannelLimit, onDeChannelLimit, onChannelBan or onDeChannelBan methods as appropriate.
The implementation of this method in the PircBot abstract class performs no actions and may be overridden as required.
- Parameters:
channel- The channel that the mode operation applies to.sourceNick- The nick of the user that set the mode.sourceLogin- The login of the user that set the mode.sourceHostname- The hostname of the user that set the mode.mode- The mode that has been set.
onOp
protected void onOp(String channel, String sourceNick, String sourceLogin, String sourceHostname, String recipient)
- Called when a user (possibly us) gets granted operator status for a channel.
This is a type of mode change and is also passed to the onMode method in the PircBot class.
The implementation of this method in the PircBot abstract class performs no actions and may be overridden as required.
- Parameters:
channel- The channel in which the mode change took place.sourceNick- The nick of the user that performed the mode change.sourceLogin- The login of the user that performed the mode change.sourceHostname- The hostname of the user that performed the mode change.recipient- The nick of the user that got 'opped'.- Since:
- 0.9.5
onDeop
protected void onDeop(String channel, String sourceNick, String sourceLogin, String sourceHostname, String recipient)
- Called when a user (possibly us) gets operator status taken away.
This is a type of mode change and is also passed to the onMode method in the PircBot class.
The implementation of this method in the PircBot abstract class performs no actions and may be overridden as required.
- Parameters:
channel- The channel in which the mode change took place.sourceNick- The nick of the user that performed the mode change.sourceLogin- The login of the user that performed the mode change.sourceHostname- The hostname of the user that performed the mode change.recipient- The nick of the user that got 'deopped'.- Since:
- 0.9.5
onVoice
protected void onVoice(String channel, String sourceNick, String sourceLogin, String sourceHostname, String recipient)
- Called when a user (possibly us) gets voice status granted in a channel.
This is a type of mode change and is also passed to the onMode method in the PircBot class.
The implementation of this method in the PircBot abstract class performs no actions and may be overridden as required.
- Parameters:
channel- The channel in which the mode change took place.sourceNick- The nick of the user that performed the mode change.sourceLogin- The login of the user that performed the mode change.sourceHostname- The hostname of the user that performed the mode change.recipient- The nick of the user that got 'voiced'.- Since:
- 0.9.5
onDeVoice
protected void onDeVoice(String channel, String sourceNick, String sourceLogin, String sourceHostname, String recipient)
- Called when a user (possibly us) gets voice status removed.
This is a type of mode change and is also passed to the onMode method in the PircBot class.
The implementation of this method in the PircBot abstract class performs no actions and may be overridden as required.
- Parameters:
channel- The channel in which the mode change took place.sourceNick- The nick of the user that performed the mode change.sourceLogin- The login of the user that performed the mode change.sourceHostname- The hostname of the user that performed the mode change.recipient- The nick of the user that got 'devoiced'.- Since:
- 0.9.5
onSetChannelKey
protected void onSetChannelKey(String channel, String sourceNick, String sourceLogin, String sourceHostname, String key)
- Called when a channel key is set. When the channel key has been set,
other users may only join that channel if they know the key. Channel keys
are sometimes referred to as passwords.
This is a type of mode change and is also passed to the onMode method in the PircBot class.
The implementation of this method in the PircBot abstract class performs no actions and may be overridden as required.
- Parameters:
channel- The channel in which the mode change took place.sourceNick- The nick of the user that performed the mode change.sourceLogin- The login of the user that performed the mode change.sourceHostname- The hostname of the user that performed the mode change.key- The new key for the channel.- Since:
- 0.9.5
onRemoveChannelKey
protected void onRemoveChannelKey(String channel, String sourceNick, String sourceLogin, String sourceHostname, String key)
- Called when a channel key is removed.
This is a type of mode change and is also passed to the onMode method in the PircBot class.
The implementation of this method in the PircBot abstract class performs no actions and may be overridden as required.
- Parameters:
channel- The channel in which the mode change took place.sourceNick- The nick of the user that performed the mode change.sourceLogin- The login of the user that performed the mode change.sourceHostname- The hostname of the user that performed the mode change.key- The key that was in use before the channel key was removed.- Since:
- 0.9.5
onSetChannelLimit
protected void onSetChannelLimit(String channel, String sourceNick, String sourceLogin, String sourceHostname, int limit)
- Called when a user limit is set for a channel. The number of users in
the channel cannot exceed this limit.
This is a type of mode change and is also passed to the onMode method in the PircBot class.
The implementation of this method in the PircBot abstract class performs no actions and may be overridden as required.
- Parameters:
channel- The channel in which the mode change took place.sourceNick- The nick of the user that performed the mode change.sourceLogin- The login of the user that performed the mode change.sourceHostname- The hostname of the user that performed the mode change.limit- The maximum number of users that may be in this channel at the same time.- Since:
- 0.9.5
onRemoveChannelLimit
protected void onRemoveChannelLimit(String channel, String sourceNick, String sourceLogin, String sourceHostname)
- Called when the user limit is removed for a channel.
This is a type of mode change and is also passed to the onMode method in the PircBot class.
The implementation of this method in the PircBot abstract class performs no actions and may be overridden as required.
- Parameters:
channel- The channel in which the mode change took place.sourceNick- The nick of the user that performed the mode change.sourceLogin- The login of the user that performed the mode change.sourceHostname- The hostname of the user that performed the mode change.- Since:
- 0.9.5
onSetChannelBan
protected void onSetChannelBan(String channel, String sourceNick, String sourceLogin, String sourceHostname, String hostmask)
- Called when a user (possibly us) gets banned from a channel. Being
banned from a channel prevents any user with a matching hostmask from
joining the channel. For this reason, most bans are usually directly
followed by the user being kicked :-)
This is a type of mode change and is also passed to the onMode method in the PircBot class.
The implementation of this method in the PircBot abstract class performs no actions and may be overridden as required.
- Parameters:
channel- The channel in which the mode change took place.sourceNick- The nick of the user that performed the mode change.sourceLogin- The login of the user that performed the mode change.sourceHostname- The hostname of the user that performed the mode change.hostmask- The hostmask of the user that has been banned.- Since:
- 0.9.5
onRemoveChannelBan
protected void onRemoveChannelBan(String channel, String sourceNick, String sourceLogin, String sourceHostname, String hostmask)
- Called when a hostmask ban is removed from a channel.
This is a type of mode change and is also passed to the onMode method in the PircBot class.
The implementation of this method in the PircBot abstract class performs no actions and may be overridden as required.
- Parameters:
channel- The channel in which the mode change took place.sourceNick- The nick of the user that performed the mode change.sourceLogin- The login of the user that performed the mode change.sourceHostname- The hostname of the user that performed the mode change.hostmask-- Since:
- 0.9.5
onSetTopicProtection
protected void onSetTopicProtection(String channel, String sourceNick, String sourceLogin, String sourceHostname)
- Called when topic protection is enabled for a channel. Topic protection
means that only operators in a channel may change the topic.
This is a type of mode change and is also passed to the onMode method in the PircBot class.
The implementation of this method in the PircBot abstract class performs no actions and may be overridden as required.
- Parameters:
channel- The channel in which the mode change took place.sourceNick- The nick of the user that performed the mode change.sourceLogin- The login of the user that performed the mode change.sourceHostname- The hostname of the user that performed the mode change.- Since:
- 0.9.5
onRemoveTopicProtection
protected void onRemoveTopicProtection(String channel, String sourceNick, String sourceLogin, String sourceHostname)
- Called when topic protection is removed for a channel.
This is a type of mode change and is also passed to the onMode method in the PircBot class.
The implementation of this method in the PircBot abstract class performs no actions and may be overridden as required.
- Parameters:
channel- The channel in which the mode change took place.sourceNick- The nick of the user that performed the mode change.sourceLogin- The login of the user that performed the mode change.sourceHostname- The hostname of the user that performed the mode change.- Since:
- 0.9.5
onSetNoExternalMessages
protected void onSetNoExternalMessages(String channel, String sourceNick, String sourceLogin, String sourceHostname)
- Called when a channel is set to only allow messages from users that
are in the channel.
This is a type of mode change and is also passed to the onMode method in the PircBot class.
The implementation of this method in the PircBot abstract class performs no actions and may be overridden as required.
- Parameters:
channel- The channel in which the mode change took place.sourceNick- The nick of the user that performed the mode change.sourceLogin- The login of the user that performed the mode change.sourceHostname- The hostname of the user that performed the mode change.- Since:
- 0.9.5
onRemoveNoExternalMessages
protected void onRemoveNoExternalMessages(String channel, String sourceNick, String sourceLogin, String sourceHostname)
- Called when a channel is set to allow messages from any user, even
if they are not actually in the channel.
This is a type of mode change and is also passed to the onMode method in the PircBot class.
The implementation of this method in the PircBot abstract class performs no actions and may be overridden as required.
- Parameters:
channel- The channel in which the mode change took place.sourceNick- The nick of the user that performed the mode change.sourceLogin- The login of the user that performed the mode change.sourceHostname- The hostname of the user that performed the mode change.- Since:
- 0.9.5
onSetInviteOnly
protected void onSetInviteOnly(String channel, String sourceNick, String sourceLogin, String sourceHostname)
- Called when a channel is set to 'invite only' mode. A user may only
join the channel if they are invited by someone who is already in the
channel.
This is a type of mode change and is also passed to the onMode method in the PircBot class.
The implementation of this method in the PircBot abstract class performs no actions and may be overridden as required.
- Parameters:
channel- The channel in which the mode change took place.sourceNick- The nick of the user that performed the mode change.sourceLogin- The login of the user that performed the mode change.sourceHostname- The hostname of the user that performed the mode change.- Since:
- 0.9.5
onRemoveInviteOnly
protected void onRemoveInviteOnly(String channel, String sourceNick, String sourceLogin, String sourceHostname)
- Called when a channel has 'invite only' removed.
This is a type of mode change and is also passed to the onMode method in the PircBot class.
The implementation of this method in the PircBot abstract class performs no actions and may be overridden as required.
- Parameters:
channel- The channel in which the mode change took place.sourceNick- The nick of the user that performed the mode change.sourceLogin- The login of the user that performed the mode change.sourceHostname- The hostname of the user that performed the mode change.- Since:
- 0.9.5
onSetModerated
protected void onSetModerated(String channel, String sourceNick, String sourceLogin, String sourceHostname)
- Called when a channel is set to 'moderated' mode. If a channel is
moderated, then only users who have been 'voiced' or 'opped' may speak
or change their nicks.
This is a type of mode change and is also passed to the onMode method in the PircBot class.
The implementation of this method in the PircBot abstract class performs no actions and may be overridden as required.
- Parameters:
channel- The channel in which the mode change took place.sourceNick- The nick of the user that performed the mode change.sourceLogin- The login of the user that performed the mode change.sourceHostname- The hostname of the user that performed the mode change.- Since:
- 0.9.5
onRemoveModerated
protected void onRemoveModerated(String channel, String sourceNick, String sourceLogin, String sourceHostname)
- Called when a channel has moderated mode removed.
This is a type of mode change and is also passed to the onMode method in the PircBot class.
The implementation of this method in the PircBot abstract class performs no actions and may be overridden as required.
- Parameters:
channel- The channel in which the mode change took place.sourceNick- The nick of the user that performed the mode change.sourceLogin- The login of the user that performed the mode change.sourceHostname- The hostname of the user that performed the mode change.- Since:
- 0.9.5
onSetPrivate
protected void onSetPrivate(String channel, String sourceNick, String sourceLogin, String sourceHostname)
- Called when a channel is marked as being in private mode.
This is a type of mode change and is also passed to the onMode method in the PircBot class.
The implementation of this method in the PircBot abstract class performs no actions and may be overridden as required.
- Parameters:
channel- The channel in which the mode change took place.sourceNick- The nick of the user that performed the mode change.sourceLogin- The login of the user that performed the mode change.sourceHostname- The hostname of the user that performed the mode change.- Since:
- 0.9.5
onRemovePrivate
protected void onRemovePrivate(String channel, String sourceNick, String sourceLogin, String sourceHostname)
- Called when a channel is marked as not being in private mode.
This is a type of mode change and is also passed to the onMode method in the PircBot class.
The implementation of this method in the PircBot abstract class performs no actions and may be overridden as required.
- Parameters:
channel- The channel in which the mode change took place.sourceNick- The nick of the user that performed the mode change.sourceLogin- The login of the user that performed the mode change.sourceHostname- The hostname of the user that performed the mode change.- Since:
- 0.9.5
onSetSecret
protected void onSetSecret(String channel, String sourceNick, String sourceLogin, String sourceHostname)
- Called when a channel is set to be in 'secret' mode. Such channels
typically do not appear on a server's channel listing.
This is a type of mode change and is also passed to the onMode method in the PircBot class.
The implementation of this method in the PircBot abstract class performs no actions and may be overridden as required.
- Parameters:
channel- The channel in which the mode change took place.sourceNick- The nick of the user that performed the mode change.sourceLogin- The login of the user that performed the mode change.sourceHostname- The hostname of the user that performed the mode change.- Since:
- 0.9.5
onRemoveSecret
protected void onRemoveSecret(String channel, String sourceNick, String sourceLogin, String sourceHostname)
- Called when a channel has 'secret' mode removed.
This is a type of mode change and is also passed to the onMode method in the PircBot class.
The implementation of this method in the PircBot abstract class performs no actions and may be overridden as required.
- Parameters:
channel- The channel in which the mode change took place.sourceNick- The nick of the user that performed the mode change.sourceLogin- The login of the user that performed the mode change.sourceHostname- The hostname of the user that performed the mode change.- Since:
- 0.9.5
onInvite
protected void onInvite(String targetNick, String sourceNick, String sourceLogin, String sourceHostname, String channel)
- Called when we are invited to a channel by a user.
The implementation of this method in the PircBot abstract class performs no actions and may be overridden as required.
- Parameters:
targetNick- The nick of the user being invited - should be us!sourceNick- The nick of the user that sent the invitation.sourceLogin- The login of the user that sent the invitation.sourceHostname- The hostname of the user that sent the invitation.channel- The channel that we're being invited to.- Since:
- 0.9.5
onDccSendRequest
protected void onDccSendRequest(String sourceNick, String sourceLogin, String sourceHostname, String filename, long address, int port, int size)
- This method is called whenever a DCC SEND request is sent to the PircBot.
This means that a client has requested to send a file to us.
This abstract implementation performs no action, which means that all
DCC SEND requests will be ignored by default. If you wish to save the
file, then you may override this method and call the dccReceiveFile
method from it, which connects to the sender and downloads the file, eg: -
public void onDccSendRequest(String sender, String login, String hostname, String filename, long address, int port, int size) {
// Check to see if we trust the sender first?
// Check that the filename isn't going to overwrite anything important?
dccReceiveFile(new File(filename), address, port, size);
// Method finishes when the download completes or if it fails.
}Each time this method is called, it is called from within a new Thread in order to allow multiple files to be downloaded by the PircBot at the same time.
Warning: Implementing this method and subsequently calling the dccReceiveFile method will cause a file to be written to disk. Please ensure that you make adequate security checks to make sure that this file will not overwrite anything important!
The implementation of this method in the PircBot abstract class performs no actions and may be overridden as required.
- Parameters:
filename- The suggested filename to be used when saving the file.address- The host address of the initiator as an integer.port- The port number to connect to if we want to receive the file.size- The size of the file in bytes. Older clients do not support this, in which case a value of -1 will be used.- Since:
- 0.9c
- See Also:
dccReceiveFile
onDccChatRequest
protected void onDccChatRequest(String sourceNick, String sourceLogin, String sourceHostname, long address, int port)
- This method is called whenever a DCC CHAT request is sent to the PircBot.
This means that a client has requested to chat to us directly rather than
via the IRC server. This is useful for sending many lines of text to and
from the bot without having to worry about flooding the server or any
operators of the server being able to "spy" on what is being said.
This abstract implementation performs no action, which means that all
DCC CHAT requests will be ignored by default. If you wish to accept
the connection, then you may override this method and call the dccAcceptChatRequest
method from it, which connects to the sender of the chat request and
returns a DccChat object which can be used to read lines from the user
and to send lines back. Here is an example of how to use the DccChat object: -
public void onDccChatRequest(String sourceNick, String sourceLogin, String sourceHostname, long address, int port) {
// Check to see if we want to accept the chat connection first?
DccChat chat = dccAcceptChatRequest(sourceNick, address, port);
if (chat != null) {
try {
chat.sendLine(Hi, what's your name?");
String name = chat.readLine();
chat.sendLine("Hello, " + name);
chat.close();
}
catch (IOException e) {
// The connection was lost
}
}
}Each time this method is called, it is called from within a new Thread in order to allow multiple DCC Chat sessions to run at the same time.
The implementation of this method in the PircBot abstract class performs no actions and may be overridden as required.
- Parameters:
address- The host address of the initiator as an integer.port- The port number to connect to if we want to chat.- Since:
- 0.9c
- See Also:
dccAcceptChatRequest
onVersion
protected void onVersion(String sourceNick, String sourceLogin, String sourceHostname, String target)
- This method is called whenever we receive a VERSION request.
This abstract implementation responds with the PircBot's _version string,
so if you override this method, be sure to either mimic its functionality
or to call super.onVersion(...);
- Parameters:
sourceNick- The nick of the user that sent the VERSION request.sourceLogin- The login of the user that sent the VERSION request.sourceHostname- The hostname of the user that sent the VERSION request.target- The target of the VERSION request, be it our nick or a channel name.
onPing
protected void onPing(String sourceNick, String sourceLogin, String sourceHostname, String target, String pingValue)
- This method is called whenever we receive a PING request from another
user.
This abstract implementation responds correctly, so if you override this method, be sure to either mimic its functionality or to call super.onPing(...);
- Parameters:
sourceNick- The nick of the user that sent the PING request.sourceLogin- The login of the user that sent the PING request.sourceHostname- The hostname of the user that sent the PING request.target- The target of the PING request, be it our nick or a channel name.pingValue- The value that was supplied as an argument to the PING command.
onServerPing
protected void onServerPing(String response)
- The actions to perform when a PING request comes from the server.
This sends back a correct response, so if you override this method, be sure to either mimic its functionality or to call super.onServerPing(response);
- Parameters:
response- The response that should be given back in your PONG.
onTime
protected void onTime(String sourceNick, String sourceLogin, String sourceHostname, String target)
- This method is called whenever we receive a TIME request.
This abstract implementation responds correctly, so if you override this method, be sure to either mimic its functionality or to call super.onTime(...);
- Parameters:
sourceNick- The nick of the user that sent the TIME request.sourceLogin- The login of the user that sent the TIME request.sourceHostname- The hostname of the user that sent the TIME request.target- The target of the TIME request, be it our nick or a channel name.
onFinger
protected void onFinger(String sourceNick, String sourceLogin, String sourceHostname, String target)
- This method is called whenever we receive a FINGER request.
This abstract implementation responds correctly, so if you override this method, be sure to either mimic its functionality or to call super.onFinger(...);
- Parameters:
sourceNick- The nick of the user that sent the FINGER request.sourceLogin- The login of the user that sent the FINGER request.sourceHostname- The hostname of the user that sent the FINGER request.target- The target of the FINGER request, be it our nick or a channel name.
onUnknown
protected void onUnknown(String line)
- This method is called whenever we receive a line from the server that
the PircBot has not been programmed to recognise.
The implementation of this method in the PircBot abstract class performs no actions and may be overridden as required.
- Parameters:
line- The raw line that was received from the server.
setVerbose
public final void setVerbose(boolean verbose)
- Sets the verbose mode. If verbose mode is set to true, then log entries
will be printed to the standard output. The default value is false and
will result in no output. For general development, we strongly recommend
setting the verbose mode to true.
- Parameters:
verbose- true if verbose mode is to be used. Default is false.
setName
protected final void setName(String name)
- Sets the name of the bot, which will be used as its nick when it
tries to join an IRC server. This should be set before joining
any servers, otherwise the default nick will be used. You would
typically call this method from the constructor of the class that
extends PircBot.
The changeNick method should be used if you wish to change your nick when you are connected to a server.
- Parameters:
name- The new name of the Bot.
setLogin
protected final void setLogin(String login)
- Sets the internal login of the Bot. This should be set before joining
any servers.
- Parameters:
login- The new login of the Bot.
setVersion
protected final void setVersion(String version)
- Sets the internal version of the Bot. This should be set before joining
any servers.
- Parameters:
version- The new version of the Bot.
setFinger
protected final void setFinger(String finger)
- Sets the interal finger message. This should be set before joining
any servers.
- Parameters:
finger- The new finger message for the Bot.
getName
public final String getName()
- Gets the name of the PircBot. This is the name that will be used as
as a nick when we try to join servers.
- Returns:
- The name of the PircBot.
getNick
public String getNick()
- Returns the current nick of the bot. Note that if you have just changed
your nick, this method will still return the old nick until confirmation
of the nick change is received from the server.
The nick returned by this method is maintained only by the PircBot class and is guaranteed to be correct in the context of the IRC server.
- Returns:
- The current nick of the bot.
- Since:
- 1.0.0
getLogin
public final String getLogin()
- Gets the internal login of the PircBot.
- Returns:
- The login of the PircBot.
getVersion
public final String getVersion()
- Gets the internal version of the PircBot.
- Returns:
- The version of the PircBot.
getFinger
public final String getFinger()
- Gets the internal finger message of the PircBot.
- Returns:
- The finger message of the PircBot.
isConnected
public final boolean isConnected()
- Returns whether or not the PircBot is currently connected to a server.
The result of this method should only act as a rough guide,
as the result may not be valid by the time you act upon it.
- Returns:
- True if and only if the PircBot is currently connected to a server.
setMessageDelay
public final void setMessageDelay(long delay)
- Sets the number of milliseconds to delay between consecutive
messages when there are multiple messages waiting in the
outgoing message queue. This has a default value of 1000ms.
It is a good idea to stick to this default value, as it will
prevent your bot from spamming servers and facing the subsequent
wrath! However, if you do need to change this delay value (not
recommended), then this is the method to use.
- Parameters:
delay- The number of milliseconds between each outgoing message.
getMessageDelay
public final long getMessageDelay()
- Returns the number of milliseconds that will be used to separate
consecutive messages to the server from the outgoing message queue.
- Returns:
- Number of milliseconds.
getMaxLineLength
public final int getMaxLineLength()
- Gets the maximum length of any line that is sent via the IRC protocol.
The IRC RFC specifies that line lengths, including the trailing \r\n
must not exceed 512 bytes. Hence, there is currently no option to
change this value in PircBot. All lines greater than this length
will be truncated before being sent to the IRC server.
- Returns:
- The maximum line length (currently fixed at 512)
getOutgoingQueueSize
public final int getOutgoingQueueSize()
- Gets the number of lines currently waiting in the outgoing message Queue.
If this returns 0, then the Queue is empty and any new message is likely
to be sent to the IRC server immediately.
- Returns:
- The number of lines in the outgoing message Queue.
- Since:
- 0.9.9
getServer
public final String getServer()
- Returns the name of the last IRC server the PircBot tried to connect to.
This does not imply that the connection attempt to the server was
successful (we suggest you look at the onConnect method).
A value of null is returned if the PircBot has never tried to connect
to a server.
- Returns:
- The name of the last machine we tried to connect to. Returns null if no connection attempts have ever been made.
getPort
public final int getPort()
- Returns the port number of the last IRC server that the PircBot tried
to connect to.
This does not imply that the connection attempt to the server was
successful (we suggest you look at the onConnect method).
A value of -1 is returned if the PircBot has never tried to connect
to a server.
- Returns:
- The port number of the last IRC server we connected to. Returns -1 if no connection attempts have ever been made.
- Since:
- 0.9.9
getPassword
public final String getPassword()
- Returns the last password that we used when connecting to an IRC server.
This does not imply that the connection attempt to the server was
successful (we suggest you look at the onConnect method).
A value of null is returned if the PircBot has never tried to connect
to a server using a password.
- Returns:
- The last password that we used when connecting to an IRC server. Returns null if we have not previously connected using a password.
- Since:
- 0.9.9
longToIp
public int[] longToIp(long address)
- A convenient method that accepts an IP address represented as a
long and returns an integer array of size 4 representing the same
IP address.
- Parameters:
address- the long value representing the IP address.- Returns:
- An int[] of size 4.
- Since:
- 0.9.4
ipToLong
public long ipToLong(byte[] address)
- A convenient method that accepts an IP address represented by a byte[]
of size 4 and returns this as a long representation of the same IP
address.
- Parameters:
address- the byte[] of size 4 representing the IP address.- Returns:
- a long representation of the IP address.
- Since:
- 0.9.4
equals
public boolean equals(Object o)
- Returns true if and only if the object being compared is the exact
same instance as this PircBot. This may be useful if you are writing
a multiple server IRC bot that uses more than one instance of PircBot.
- Returns:
- true if and only if Object o is a PircBot and equal to this.
- Since:
- 0.9.9
hashCode
public int hashCode()
- Returns the hashCode of this PircBot. This method can be called by hashed
collection classes and is useful for managing multiple instances of
PircBots in such collections.
- Returns:
- the hash code for this instance of PircBot.
- Since:
- 0.9.9
toString
public String toString()
- Returns a String representation of this object.
You may find this useful for debugging purposes, particularly
if you are using more than one PircBot instance to achieve
multiple server connectivity. The format of
this String may change between different versions of PircBot
but is currently something of the form
Version{PircBot x.y.z Java IRC Bot - www.jibble.org} Connected{true} Server{irc.dal.net} Port{6667} Password{}- Returns:
- a String representation of this object.
- Since:
- 0.9.10
getUsers
public final User[] getUsers(String channel)
- Returns an array of all users in the specified channel.
There are some important things to note about this method:-
- This method may not return a full list of users if you call it before the complete nick list has arrived from the IRC server.
- If you wish to find out which users are in a channel as soon as you join it, then you should override the onUserList method instead of calling this method, as the onUserList method is only called as soon as the full user list has been received.
- This method will return immediately, as it does not require any interaction with the IRC server.
- The bot must be in a channel to be able to know which users are in it.
- Returns:
- An array of User objects. This array is empty if we are not in the channel.
- Since:
- 1.0.0
- See Also:
onUserList
getChannels
public final String[] getChannels()
- Returns an array of all channels that we are in. Note that if you
call this method immediately after joining a new channel, the new
channel may not appear in this array as it is not possible to tell
if the join was successful until a response is received from the
IRC server.
- Returns:
- A String array containing the names of all channels that we are in.
- Since:
- 1.0.0
|
PircBot Java IRC Bot | |||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||