IRCObject handles all aspects of an IRC
connection. In almost all cases, you will want
to override this class and implement just the callback
methods specified in
IRCObject(Callbacks)
to handle everything.
A lot of arguments may not contain spaces. The general
procedure on processing these arguments is that
the method will cut the string off at the first space
and use the part of the string before the space and
fail only if that string is still invalid. Try to
avoid passing strings with spaces as the arguments
to the methods that warn not to.
Requests information on the precense of certain
nicknames listed in userList on the
network. userList is a space separated
list of users. For each user that is present, its name
will be added to the reply through the numeric message
RPL_ISON. See RFC 1459 for more
information on the ISON message.
This method attempts to become an IRC operator with
name aName and password
aPassword. Neither may contain spaces.
This is a totally different concept than channel
operators since it refers to operators of the
server as a whole. Please see RFC 1459 for more
information on the OPER command.
Sets the nickname to the aNick. This method
is quite similar to
-setNick:
but this will also actually send the nick change
request to the server if connected, and will only
affect the nickname stored by the object (which is
returned with -nick) if the the name change was
successful or the object is not yet
registered/connected. Please see RFC
1459 for more information on the NICK command.
Returns YES when the IRC object is
fully connected and registered with the IRC server.
Returns NO if the connection has not
made or this connection has not fully registered with
the server.
- (id) initWithNickname: (NSString*)aNickname withUserName: (NSString*)aUser withRealName: (NSString*)aRealName withPassword: (NSString*)aPassword;
This is a designated initialiser for the class.
This message will invite aPerson to the
channel specified by aChannel. Neither
may contain spaces and both are required. Please refer
to RFC 1459 concerning the INVITE command for additional
information.
Joins the channel aChannel with an
optional password of aPassword. Neither
may contain spaces, and both may be comma separated for
multiple channels/passwords. If there is one or
more passwords, it should match the number of channels
specified by aChannel. Please see RFC
1459 for more information on the JOIN command.
Kicks the user aPerson off of the channel
aChannel for the reason specified in
aReason. aReason may contain
spaces and is optional. If omitted the server will
most likely supply a default message.
aPerson and aChannel are
required and may not contain spaces. Please see
the KICK command for additional information in RFC
1459.
Used to kill the connection to aPerson with
a possible comment aComment. This is often
used by servers when duplicate nicknames are found and
may be available to the IRC operators.
aComment is optional and
aPerson may not contain spaces. Please see
RFC 1459 for additional information on the KILL
command.
Lists channel information about the channel specified
by aChannel on the server aServer.
aChannel may be a comma separated list and
may not contain spaces. aServer is optional.
If aChannel is omitted, then all channels on
the server will be listed. Please refer to RFC 1459 for
additional information on the LIST command.
Requests a list of users with a matching mask
aMask against their username and/or host.
This can optionally be done just against the IRC
operators. The mask aMask is
optional and may not contain spaces. Please see
RFC 1459 for more information regarding the WHO
message.
Leaves the channel aChannel with the
optional message aMessage.
aMessage may contain spaces, and
aChannel may not. aChannel may
also be a comma separated list of channels. Please see
RFC 1459 for more information on the PART command.
Quits IRC with an optional message.
aMessage can have spaces. If
aMessage is nil or
zero-length, the server will often provide its
own message. Please see RFC 1459 for more information
on the QUIT command.
Request the name of the administrator on the
optional server aServer.
aServer may not contain spaces. Please see
RFC 1459 for more information on the ADMIN command.
Requests information on a server
aServer. aServer is optional
and may not contain spaces. Please see RFC 1459 for
more information on the INFO command.
Requests the Message-Of-The-Day from server
aServer. aServer is optional
and may not contain spaces if present. The message of
the day is returned through the RPL_MOTD
numeric command.
Requests the names on a channel
aChannel. If aChannel is not
specified, all users in all channels will be
returned. The information will be returned via a
RPL_NAMREPLY numeric message. See the RFC
1459 for more information on the NAMES command.
Used to list servers connected to optional
aServer with an optional mask
aLink. Neither may contain spaces. See the
RFC 1459 for more information on the LINKS command.
Returns a series of statistics from
aServer. Specific queries can be made with
the optional query argument. Neither may
contain spaces and both are optional. See RFC 1459
for more information on the STATS message
- (id) requestServerToConnect: (NSString*)aServer to: (NSString*)connectServer onPort: (NSString*)aPort;
Requests that aServer connects to
connectServer on port aPort.
aServer and aPort are optional
and none may contain spaces. See RFC 1459 for more
information on the CONNECT command.
Requests size information from an optional
aServer and optionally forwards it to
anotherServer. See RFC 1459 for more
information on the LUSERS command
This message will request the route to a specific
server from a client. aServer is optional
and may not contain spaces; please see RFC 1459 for
more information on the TRACE command.
Requests a list of users logged into
aServer. aServer is optional
and may contain spaces. Please see RFC 1459 for
additional information on the USERS message.
Sends a CTCP aCTCP reply to
aPerson with the argument args.
args may contain spaces and is optional
while the rest may not. This method should be used to
respond to a CTCP message sent by another client.
See
-sendCTCPRequest:withArgument:to:
Sends a CTCP aCTCP request to
aPerson with an optional argument
args. args may contain a space
while the rest may not. This should be used to
request CTCP information from another client and
never for responding. See
-sendCTCPReply:withArgument:to:
- (id) sendMessage: (NSString*)aMessage to: (NSString*)aReceiver;
Sends a message aMessage to
aReceiver. aReceiver may be a
nickname or a channel name. aMessage
may contain spaces. This is used to carry out the basic
communication over IRC. Please see RFC 1459
for more information on the PRIVMSG message.
Sends a notice aNotice to
aReceiver. aReceiver may not
contain a space. This is generally not used except
for system messages and should rarely be used by a
regular client. Please see RFC 1459 for more
information on the NOTICE command.
Requests a PONG message from the server. The
argument aString is essential but may
contain spaces. The server will respond immediately
with a PONG message with the same argument. This
commnd is rarely needed by a client, but is sent out
often by servers to ensure connectivity of clients.
Please see RFC 1459 for more information on the PING
command.
Used to respond to a PING message. The argument sent
with the PING message should be the argument specified
by aString. aString is required
and may contain spaces. See RFC 1459 for more
informtion regarding the PONG command.
Sends a message to all operators currently online.
The actual implementation may vary from server to
server in regards to who can send and receive it.
aMessage is the message to be sent and may
contain spaces. Please see RFC 1459 for more
information regarding the WALLOPS command.
Sets status to away with the message
aMessage. While away, if a user should
send you a message, aMessage will be
returned to them to explain your absence.
aMessage may contain spaces. If omitted,
the user is marked as being present. Please refer to
the AWAY command in RFC 1459 for additional
information.
Sets the encoding that will be used for incoming as
well as outgoing messages. aEncoding should
be an 8-bit encoding for a typical IRC server. Uses the
system default by default.
Sets the encoding that will be used for incoming as
well as outgoing messages to a specific target.
aEncoding should be an 8-bit encoding for
a typical IRC server. Uses the encoding set with
setEncoding: by default.
Set the lowercasing selector. This is the selector that
is called on a NSString to get the lowercase form. Used
to determine if two nicknames are equivalent. Generally
aSelector would be either
@selector(lowercaseString) or
@selector(lowercaseIRCString).
By default, this is lowercaseIRCString but will be
autodetected from the server if possible. It
will be reset to lowercaseIRCString upon reconnection.
Used to query or set the mode on anObject
to the mode specified by aMode. Flags can be
added by adding a '+' to the aMode string
or removed by adding a '-' to the aMode
string. These flags may optionally have arguments
specified in aList and may be applied
to the object specified by anObject.
Examples:
aMode: @"+i" anObject: @"#gnustep" withParams: nil
sets the channel "#gnustep" to invite only.
aMode: @"+o" anObject: @"#gnustep" withParams: (@"aeruder")
makes aeruder a channel operator of #gnustep
Many servers have differing implementations of these
modes and may have various modes available to users.
None of the arguments may contain spaces. Please refer
to RFC 1459 for additional information on the MODE
message.
Sets the nickname that this object will attempt to use
upon a connection. Do not use this to change the
nickname once the object is connected, this is
only used when it is actually connecting. This method
returns nil if aNickname is
invalid and will set the error string accordingly.
aNickname is invalid if it contains a
space or is zero-length.
Sets the password that will be used upon connecting to
the IRC server. aPass can be
nil or zero-length, in which case no
password shall be used. aPass may not
contain a space. Will return nil and
set the error string if this fails.
Sets the real name that will be passed to the IRC
server on the next connection. If
aRealName is nil or
zero-length, the name "John Doe" shall be
used. This method will always succeed.
- (id) setTopicForChannel: (NSString*)aChannel to: (NSString*)aTopic;
Sets the topic for channel aChannel to
aTopic. If the aTopic is
omitted, the topic for aChannel will be
returned through the RPL_TOPIC numeric
message. aChannel may not contain
spaces. Please refer to the TOPIC command in RFC
1459 for more information.
Sets the user name that this object will give to the
server upon the next connection. If aUser
is invalid, it will use the user name of "netclasses".
aUser should not contain spaces. This
method will always succeed.
Requests information on a user aPerson.
aPerson may also be a comma separated list
for additional users. aServer is optional
and neither argument may contain spaces. Refer to RFC
1459 for additional information on the WHOIS command.
Requests information on a user aPerson
that is no longer connected to the server
aServer. A possible maximum number of
entries aNumber may be displayed. All
arguments may not contain spaces and
aServer and aNumber are
optional. Please refer to RFC 1459 for more
information regarding the WHOWAS message.
This category represents all the callback methods in
IRCObject. You can override these with a subclass.
All of them do not do anything especially important by
default, so feel free to not call the default
implementation. On any method ending with an
argument like 'from: (NSString *)aString',
aString could be in the format of
nickname!host. Please see the documentation
for
ExtractIRCNick()
,
ExtractIRCHost()
, and
SeparateIRCNickAndHost()
for more information.
- (id) CTCPReplyReceived: (NSString*)aCTCP withArgument: (NSString*)anArgument to: (NSString*)aReceiver from: (NSString*)aPerson;
Called when a CTCP reply has been received. The CTCP
reply type is stored in aCTCP with its
argument in anArgument. The actual
location that the CTCP reply was sent is stored in
aReceiver and the person who sent it is
stored in aPerson.
- (id) CTCPRequestReceived: (NSString*)aCTCP withArgument: (NSString*)anArgument to: (NSString*)aReceiver from: (NSString*)aPerson;
Called when a CTCP request has been received. The
CTCP request type is stored in aCTCP (could
be such things as DCC, PING, VERSION, etc.) and the
argument is stored in anArgument. The
actual location that the CTCP request is sent is
stored in aReceiver and the person who
sent it is stored in aPerson.
Called when an action has been received. The action
is stored in anAction and the sender is
stored in aSender. The person or channel
that the action is addressed to is stored in
aReceiver.
Called when someone leaves a channel. The channel is
stored in aChannel and the person who
left is stored in aParter. The parting
message will be stored in aMessage.
This method will be called if a connection cannot
register for whatever reason. This reason will be
outlined in aReason, but the best way
to track the reason is to watch the numeric commands
being received in the
-numericCommandReceived:withParams:from:
method.
Called when an IRC error has occurred. This is a
message sent by the server and its argument is
stored in anError. Typically you will be
disconnected after receiving one of these.
Called when the mode has been changed on
anObject. The actual mode change is stored
in aMode and the parameters are stored in
paramList. The person who changed the mode
is stored in aPerson. Consult RFC 1459 for
further information.
Called when a new nickname was needed while
registering because the other one was either
invalid or already taken. Without overriding this,
this method will simply try adding a underscore onto
it until it gets in. This method can be overridden to do
other nickname-changing schemes. The new nickname
should be directly set with
-changeNick:
Called when a numeric command has been received.
These are 3 digit numerical messages stored in
aCommand with a number of parameters
stored in paramList. The sender, almost
always the server, is stored in aSender.
These are often used for replies to requests such as
user lists and channel lists and other times they are
used for errors.
Called when a ping is received. These pings are
generally sent by the server. The correct method
of handling these would be to respond to them with
-sendPongWithArgument:
using anArgument as the argument. The
server that sent the ping is stored in
aSender.
Called when a pong is received. These are generally
in answer to a ping sent with
-sendPingWithArgument:
The argument anArgument is generally the
same as the argument sent with the ping.
aSender is the server that sent out the
pong.
This method will be called when the connection is
fully registered with the server. At this point it is
safe to start joining channels and carrying out other
typical IRC functions.
Called when a user has been kicked out of a channel.
The person's nickname is stored in aPerson
and the channel he/she was kicked out of is in
aChannel. aReason is the
kicker-supplied reason for the removal.
aKicker is the person who did the kicking.
This will not be accompanied by a
-channelParted:withMessage:from:
message, so it is safe to assume they are no
longer part of the channel after receiving this
method.
This is the lowlevel interface to IRCObject. One method
is a callback for when the object receives a raw message
from the connection, the other is a method used to write
raw messages across the connection
Handles an incoming line of text from the IRC
server by parsing it and doing the appropriate
actions as well as calling any needed callbacks.
See
[LineObject -lineReceived:]
for more information.
Additions of NSString that are used to upper/lower
case strings taking into account that on many servers
{}|^ are lowercase forms of []\~. Try not to depend on
this fact, some servers nowadays are drifting away from
this idea and will treat them as different characters
entirely.
Returns a lowercased string (and converts any of
[]\ characters found to {}| respectively). The original
RFC 1459 forgot to include these and thus this method
is included.
Returns a uppercased string (and converts any of
{}| characters found to []\ respectively). The original
RFC 1459 forgot to include these and thus this method
is included.
Returns the host portion of a prefix. On
any argument after from: in the class reference, the name
could be in the format nickname!host. Returns
nil if the prefix is not in
the correct format.
Returns the nickname portion of a prefix.
On any argument after from: in the class reference, the
name could be in the format of nickname!host. Will
always return a valid string.
Returns an array of the nickname/host of a
prefix. In the case that the array has only
one object, it will be the nickname. In the case that it
has two, it will be [nickname, host]. The object will
always be at least one object long
and never more than two.