IRCClient/IRCClientSession.h

   1 //
   2 //      IRCClientSession.h
   3 //
   4 //  Modified IRCClient Copyright 2015-2021 Said Achmiz.
   5 //  Original IRCClient Copyright 2009 Nathan Ollerenshaw.
   6 //  libircclient Copyright 2004-2009 Georgy Yunaev.
   7 //
   8 //  See LICENSE and README.md for more info.
   9
  10 #import <Foundation/Foundation.h>
  11 #import "IRCClientSessionDelegate.h"
  12
  13 /** @class IRCClientSession
  14  *      @brief Represents a connected IRC Session.
  15  *
  16  *      IRCClientSession represents a single connection to an IRC server. After initialising
  17  *  the object, setting the delegate, server, port, and password (if required)
  18  *      properties, and setting the nickname, username and realname using the
  19  *      setNickname:username:realname: method, you call the connect: and run: methods
  20  *      to connect to the IRC server and place the connection on a new event queue.
  21  *
  22  *      This thread then sends messages to the IRC server delegate,
  23  *      or to the IRCClientChannel delegate, as required.
  24  */
  25
  26 /**********************************************/
  27 #pragma mark IRCClientSession class declaration
  28 /**********************************************/
  29
  30 @interface IRCClientSession : NSObject <NSStreamDelegate>
  31
  32 /******************************/
  33 #pragma mark - Class properties
  34 /******************************/
  35
  36 /**     Returns a dictionary of IRC numeric codes.
  37
  38         The dictionary contains entries for all known IRC numeric codes (as keys).
  39         (The list is taken from https://www.alien.net.au/irc/irc2numerics.html .)
  40
  41         The value for each key is an NSArray with the known numeric reply names for
  42         which the numeric code is used.
  43
  44         Note that there is no guarantee whatsoever that any given numeric reply
  45         name will, in fact, describe the contents of the message; most IRC numeric
  46         messages have implementation-specific uses. See the various RFCs, and other
  47         info sources, for details.
  48  */
  49 @property (class, nonatomic, readonly) NSDictionary <NSString *, NSDictionary *> *ircNumericCodes;
  50
  51 /************************/
  52 #pragma mark - Properties
  53 /************************/
  54
  55 /** Delegate to send events to. */
  56 @property (assign) id <IRCClientSessionDelegate> delegate;
  57
  58 /** The version string for the client to send back on CTCP VERSION requests.
  59         There is usually no reason to set this, as IRCClient correctly sets its
  60         own version string automatically, but this can be any string you like.
  61  */
  62 @property (copy, nonatomic) NSData *version;
  63
  64 /** IRC server to connect to. */
  65 @property (copy, nonatomic) NSData *server;
  66
  67 /** IRC port to connect to. */
  68 @property (assign) NSUInteger port;
  69
  70 /** Server password to provide on connect (may be left empty or nil). */
  71 @property (copy, nonatomic) NSData *password;
  72
  73 /** Nickname of the connected client.
  74  */
  75 @property (nonatomic, readonly) NSData *nickname;
  76
  77 /** Username of the connected client. Also known as the ident.
  78  */
  79 @property (nonatomic, readonly) NSData *username;
  80
  81 /** Realname of the connected client.
  82  */
  83 @property (nonatomic, readonly) NSData *realname;
  84
  85 /** The suggested text encoding for messages on this server.
  86
  87         This is almost entirely irrelevant (except for CTCP TIME replies), as
  88         all messages and other strings are taken and returned as  NSData objects.
  89         This property is for your convenience.
  90
  91         You may change this at any time.
  92  */
  93 @property (assign) NSStringEncoding encoding;
  94
  95 /** An NSDictionary of channels that the client is currently connected to.
  96         Keys are channel names (NSData), values are IRCClientChannel objects.
  97  */
  98 @property (nonatomic, readonly) NSDictionary <NSData *, IRCClientChannel *> *channels;
  99
 100 /** Returns YES if the server is currently connected successfully, and NO if
 101         it is not. */
 102 @property (readonly, getter=isConnected) BOOL connected;
 103
 104 /** Stores arbitrary user info. */
 105 @property (nonatomic, readonly) NSMutableDictionary *userInfo;
 106
 107 /********************************************/
 108 #pragma mark - Initializers & factory methods
 109 /********************************************/
 110
 111 +(instancetype) session;
 112
 113 /***************************/
 114 #pragma mark - Class methods
 115 /***************************/
 116
 117 /**     Returns the nick part of a nick!user@host string.
 118  */
 119 +(NSData *) nickFromNickUserHost:(NSData *)nickUserHost;
 120
 121 /**     Returns the user part of a nick!user@host string.
 122         May be blank if the user component can’t be found
 123         (i.e. if the passed string is not, in fact, in nick!user@host format).
 124  */
 125 +(NSData *) userFromNickUserHost:(NSData *)nickUserHost;
 126
 127 /**     Returns the host part of a nick!user@host string.
 128         May be blank if the host component can’t be found
 129         (i.e. if the passed string is not, in fact, in nick!user@host format).
 130  */
 131 +(NSData *) hostFromNickUserHost:(NSData *)nickUserHost;
 132
 133 /******************************/
 134 #pragma mark - Instance methods
 135 /******************************/
 136
 137 /** Set the nickname, username, and realname for the session.
 138
 139         Returns YES if successfully set, NO otherwise.
 140         (NO is returned if you try to call this method after the session has
 141         already connected; use the nick: method to attempt a nick change while
 142         connected.)
 143  */
 144 -(BOOL) setNickname:(NSData *)nickname
 145                    username:(NSData *)username
 146                    realname:(NSData *)realname;
 147
 148 /** Connect to the IRC server.
 149
 150         Note that this performs the initial DNS lookup and the TCP connection, so if
 151         there are any problems you will be notified via the return code of the message.
 152
 153         Look at the libircclient documentation for the different return codes.
 154  */
 155 -(int) connect;
 156
 157 /** Disconnect from the IRC server.
 158
 159         This always works, as it simply shuts down the socket. If you want to disconnect
 160         in a friendly way, you should use the quit: message.
 161  */
 162 -(void) disconnect;
 163
 164 /** Convert libircclient markup in a message to mIRC format codes.
 165  */
 166 -(NSData *) colorConvertToMIRC:(NSData *)message;
 167
 168 /** Convert mIRC format codes in a message to libircclient markup.
 169  */
 170 -(NSData *) colorConvertFromMIRC:(NSData *)message;
 171
 172 /** Remove mIRC format codes from a message.
 173  */
 174 -(NSData *) colorStripFromMIRC:(NSData *)message;
 175
 176 /**************************/
 177 #pragma mark - IRC commands
 178 /**************************/
 179
 180 /** Sends a raw message to the IRC server. Please consult RFC 1459 for the
 181         format of IRC commands.
 182  */
 183 -(int) sendRaw:(NSData *)message;
 184
 185 /** Quits the IRC server with the given reason.
 186
 187         On success, a -[userQuit:withReason:session:] event will be sent to the
 188         IRCClientSessionDelegate with the nickname of the IRC client and the reason
 189         provided by the user (or nil if no reason was provided).
 190
 191         @param reason The quit reason.
 192  */
 193 -(int) quit:(NSData *)reason;
 194
 195 /** Joins a channel with a given name and key.
 196
 197         On success, a -[joinedNewChannel:session:] event will be sent to the
 198         IRCClientSessionDelegate with the IRCClientChannel object representing the
 199         newly-joined channel.
 200
 201         @param channel The name of the channel to join.
 202         @param key The key for the channel (may be nil).
 203  */
 204 -(int) join:(NSData *)channel
 205                 key:(NSData *)key;
 206
 207 /**     Lists users in an IRC channel (or channels).
 208
 209         @param channel A channel name or string to pass to the NAMES command.
 210         Implementation specific.
 211  */
 212 -(int) names:(NSData *)channel;
 213
 214 /**     Lists channels on the IRC server.
 215
 216         @param channel A channel name or string to pass to the LIST command.
 217         Implementation specific.
 218  */
 219 -(int) list:(NSData *)channel;
 220
 221 /** Sets the user mode for the IRC client.
 222
 223         @param mode The mode string to set.
 224  */
 225 -(int) userMode:(NSData *)mode;
 226
 227 /**     Sets the IRC client nickname.
 228
 229         On success, a nickChangedFrom:to: event will be sent to the
 230         IRCClientSessionDelegate with our old nick and the new nick that we now
 231         have.
 232
 233         @param newnick The new nickname to set.
 234  */
 235 -(int) nick:(NSData *)newnick;
 236
 237 /**     Sends a WHO query to the IRC server.
 238
 239         @param nickmask Nickname mask of the IRC client to WHO.
 240  */
 241 -(int) who:(NSData *)nickmask;
 242
 243 /**     Sends a WHOIS query to the IRC server.
 244
 245         @param nick Nickname of the IRC client to WHOIS.
 246 */
 247 -(int) whois:(NSData *)nick;
 248
 249 /**     Send a PRIVMSG to another IRC client.
 250
 251         @param message Message to send.
 252         @param target The other IRC client to send the message to.
 253  */
 254 -(int) message:(NSData *)message
 255                         to:(NSData *)target;
 256
 257 /**     Sends a CTCP ACTION to another IRC client.
 258
 259         @param action The action message to send.
 260         @param target The nickname of the irc client to send the message to.
 261  */
 262 -(int) action:(NSData *)action
 263                    to:(NSData *)target;
 264
 265 /**     Send a NOTICE to another IRC client.
 266
 267         @param notice The message text to send.
 268         @param target The nickname of the irc client to send the notice to.
 269  */
 270 -(int) notice:(NSData *)notice
 271                    to:(NSData *)target;
 272
 273 /** Send a CTCP request to another IRC client.
 274
 275         @param request The CTCP request string to send.
 276         @param target The nickname of the IRC client to send the request to.
 277  */
 278 -(int) ctcpRequest:(NSData *)request
 279                         target:(NSData *)target;
 280
 281 /** Send a CTCP reply to another IRC client.
 282
 283         @param reply The CTCP reply string to send.
 284         @param target The nickname of the IRC client to send the reply to.
 285  */
 286 -(int) ctcpReply:(NSData *)reply
 287                   target:(NSData *)target;
 288
 289 @end