IRCClient/IRCClient/IRCClientSession.h

//
//	IRCClientSession.h
//	IRCClient
/*! \mainpage IRCClient - a Cocoa IRC Framework to create IRC clients
 *
 * \section intro_sec Introduction
 *
 * IRCClient is a Cocoa Framework that uses the excellent libircclient library
 * written by Georgy Yunaev.
 *
 * \section usage Basic Usage
 *
 * To use this framework, you will need to write an IRCClientSessionDelegate to
 * handle all of the events generated by the server, and an IRCClientChannelDelegate
 * to handle all of the events generated by channels on that server.
 *
 * You then create an IRCClientSession object in your code, assign the required
 * properties, and call connect: to connect to the server and run: to create
 * the new thread and start receiving events. For example:
 *
 * \code
 * IRCClientSession *session = [[IRCClientSession alloc] init];
 * MyIRCClientSessionDelegate *controller = [[MyIRCClientSessionDelegate alloc] init];
 * 
 * session.delegate = controller;
 * controller.session = session;
 * 
 * NSData *server = [NSData dataWithBytes:@"chat.freenode.net".UTF8String length:strlen(@"chat.freenode.net".UTF8String.length) + 1];
 * NSUinteger port = 6665;
 * NSData *nickname = [NSData dataWithBytes:@"test".UTF8String length:strlen(@"test".UTF8String) + 1];
 * NSData *username = [NSData dataWithBytes:@"test".UTF8String length:strlen(@"test".UTF8String) + 1];
 * NSData *realname = [NSData dataWithBytes:@"test".UTF8String length:strlen(@"test".UTF8String) + 1];
 *
 * [session setServer:server];
 * [session setPort:port];
 * [session setNickname:nickname username:username realname:realname];
 * [session connect];
 * 
 * [session run]; //starts the thread
 * \endcode
 * 
 * \section author Author, copyright, support.
 *
 * If you have questions, bug reports, or suggestions regarding IRCClient,
 * find Obormot on the Freenode IRC network.
 *
 * If you have any questions, bug reports, suggestions regarding libircclient,
 * please visit http://libircclient.sourceforge.net
 *
 * <PRE>
 * libircclient Copyright (C) 2004-2009 Georgy Yunaev gyunaev@ulduzsoft.com
 * Original IRCClient Copyright (C) 2009 Nathan Ollerenshaw chrome@stupendous.net
 * Modified IRCClient Copyright 2015 Said Achmiz (www.saidachmiz.net)
 *
 * This library is free software; you can redistribute it and/or modify it 
 * under the terms of the GNU Lesser General Public License as published by 
 * the Free Software Foundation; either version 2 of the License, or (at your 
 * option) any later version.
 *
 * This library is distributed in the hope that it will be useful, but WITHOUT 
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public 
 * License for more details.
 * </PRE>
 */

#import <Foundation/Foundation.h>
#import "IRCClientSessionDelegate.h"

/** @class IRCClientSession
 *	@brief Represents a connected IRC Session.
 *
 *	IRCClientSession represents a single connection to an IRC server. After initialising
 *  the object, setting the delegate, server, port, and password (if required)
 *	properties, and setting the nickname, username and realname using the
 *	setNickname:username:realname: method, you call the connect: and run: methods 
 *	to connect to the IRC server and start a new thread.
 *
 *	This thread then sends messages to the IRC server delegate,
 *	or to the IRCClientChannel delegate, as required.
 */

/**********************************************/
#pragma mark IRCClientSession class declaration
/**********************************************/

@interface IRCClientSession : NSObject

/************************/
#pragma mark - Properties
/************************/

/** delegate to send events to. */
@property (assign) id <IRCClientSessionDelegate> delegate;

/** The version string for the client to send back on CTCP VERSION requests.
	There is usually no reason to set this, as IRCClient correctly sets its
	own version string automatically, but this can be any string you like.
 */
@property (copy) NSData *version;

/** IRC server to connect to */
@property (copy) NSData *server;

/** IRC port to connect to */
@property (assign) NSUInteger port;

/** Server password to provide on connect (may be left empty or nil) */
@property (copy) NSData *password;

/** Nickname of the connected client.
 */
@property (readonly) NSData *nickname;

/** Username of the connected client. Also known as the ident.
 */
@property (readonly) NSData *username;

/** Realname of the connected client.
 */
@property (readonly) NSData *realname;

/** The suggested text encoding for messages on this server.
 
	This is almost entirely irrelevant (except for CTCP TIME replies), as 
	all messages and other strings are taken and returned as C strings
	encapsulated in NSData objects. This property is for your convenience.
 
	You may change this at any time.
 */
@property (assign) NSStringEncoding encoding;

/** An NSDictionary of channels that the client is currently connected to.
	Keys are channel names (NSData objects containing C strings), values are
	IRCClientChannel objects.
 */
@property (readonly) NSDictionary *channels;

/** Returns YES if the server is currently connected successfully, and NO if
	it is not. */
@property (readonly, getter=isConnected) bool connected;

/** Stores arbitrary user info. */
@property (strong) NSDictionary *userInfo;

/***************************/
#pragma mark - Class methods
/***************************/

/**	Returns a dictionary of IRC numeric codes.
 
	The dictionary contains entries for all known IRC numeric codes (as keys).
	(The list is taken from https://www.alien.net.au/irc/irc2numerics.html .)
	
	The value for each key is an NSArray with the known numeric reply names for
	which the numeric code is used.
 
	Note that there is no gaurantee whatsoever that any given numeric reply 
	name will, in fact, describe the contents of the message; most IRC numeric
	messages have implementation-specific uses. See the various RFCs, and other
	info sources, for details.
 */
+ (NSDictionary *)ircNumericCodes;

/** Set the nickname, username, and realname for the session.
 
	Returns 1 if successfully set, 0 otherwise.
	(0 is returned if you try to call this method after the session has
	already connected; use the nick: method to attempt a nick change while
	connected.)
 */
- (int)setNickname:(NSData *)nickname username:(NSData *)username realname:(NSData *)realname;

/** Connect to the IRC server.
 
	Note that this performs the initial DNS lookup and the TCP connection, so if
	there are any problems you will be notified via the return code of the message.
 
	Look at the libircclient documentation for the different return codes.
 */
- (int)connect;

/** Disconnect from the IRC server.
 
	This always works, as it simply shuts down the socket. If you want to disconnect
	in a friendly way, you should use the quit: message.
 */
- (void)disconnect;

/**	Starts a new thread and starts the libircclient runloop, processing events and
	firing messages back to the main runloop as required. Calling this again will
	do nothing other than raise a warning in your logs.
 */
- (void)run;

/**************************/
#pragma mark - IRC commands
/**************************/

/** Sends a raw message to the IRC server. Please consult rfc1459 for the format
	of IRC commands. */
- (int)sendRaw:(NSData *)message;

/** quits the IRC server with the given reason.
 
	On success, a userQuit:withReason: event will be sent to the 
	IRCClientSessionDelegate with the nickname of the IRC client and the reason 
	provided by the user (or nil if no reason was provided).
 */
- (int)quit:(NSData *)reason;

/** Joins a channel with a given name and key
 
	On success, a userJoined:channel: event will be sent to the 
	IRCClientSessionDelegate with the nickname of the IRC client and the name of
	the channel that was joined.
 
	@param channel the channel to join
	@param key they key for the channel (may be nil)
 */
- (int)join:(NSData *)channel key:(NSData *)key;

/**	lists channels on the IRC server.
 
	@param channel a channel name or string to pass to the LIST command. 
	Implementation specific.
 */
- (int)list:(NSData *)channel;

/** sets the user mode for the IRC client
 
	@param mode string to set
 */
- (int)userMode:(NSData *)mode;

/**	sets the IRC client nickname.
 
	On success, a nickChangedFrom:to: event will be sent to the 
	IRCClientSessionDelegate with our old nick and the new nick that we now 
	have.
 
	@param newnick new nickname to set.
 */
- (int)nick:(NSData *)newnick;

/**	sends a WHOIS request to the IRC server
 
	@param nick nickname of the irc client to whois.
*/
- (int)whois:(NSData *)nick;

/**	send a PRIVMSG to another IRC client
 
	@param message message to send
	@param target the other IRC client to send the message to.
 */
- (int)message:(NSData *)message to:(NSData *)target;

/**	send a CTCP ACTION to another IRC client
 
	@param action the action message to send
	@param target the nickname of the irc client to send the message to.
 */
- (int)action:(NSData *)action to:(NSData *)target;

/**	send a NOTICE to another IRC client
 
	@param notice the message text to send
	@param target the nickname of the irc client to send the notice to.
 */
- (int)notice:(NSData *)notice to:(NSData *)target;

/** send a CTCP request to another IRC client
 
	@param request the CTCP request string to send
	@param target the nickname of the IRC client to send the request to.
 */
- (int)ctcpRequest:(NSData *)request target:(NSData *)target;

/** send a CTCP reply to another IRC client
 
	@param reply the CTCP reply string to send
	@param target the nickname of the IRC client to send the reply to.
 */
- (int)ctcpReply:(NSData *)reply target:(NSData *)target;

@end

/*************************************/
#pragma mark - Useful helper functions
/*************************************/

/**	Returns the nick part of a nick!user@host string.
 */
NSData* getNickFromNickUserHost(NSData *nickUserHost);

/**	Returns the user part of a nick!user@host string.
	May be blank if the user component can't be found 
	(i.e. if the passed string is not, in fact, in nick!user@host format).
 */
NSData* getUserFromNickUserHost(NSData *nickUserHost);

/**	Returns the host part of a nick!user@host string.
	May be blank if the host component can't be found 
	(i.e. if the passed string is not, in fact, in nick!user@host format).
 */
NSData* getHostFromNickUserHost(NSData *nickUserHost);