Using cpIRC

Compiling with cpIRC

To compile an IRC client (or other application) using the complete source for cpIRC, just make sure your compiler can find the source and include the cpIRC header file in your own source (if using the libraries, make sure the linker can find them and simply include the header file):
	#include "IRC.h"


	#include "IRC.h"

	IRC conn;

	conn.start("", 6667, "some nick", "some user", "some irc name", "some password");

Getting started

To use cpIRC, you first need to include the header file and then declare a new instance of it:
	#include "IRC.h"
and then:
	IRC conn;
The next step is to install any hooks/handlers/callback functions of yours that you wish cpIRC to call when a specified IRC event occurs:
	conn.hook_irc_command("irc response", &function_name);
where "irc response" is an IRC reply such as 376 or JOIN, and function_name is the name of a callback function of the format:
	int function_name(char* params, irc_reply_data* hostd, void* conn)
		IRC* irc_conn=(IRC*)conn; /* notice that you are passed a pointer to the connection object */
		return 0;
The irc_reply_data structure is defined as follows:
	struct irc_reply_data
		char* nick;
		char* ident;
		char* host;
		char* target; /* This variable contains things such as the target of a PRIVMSG/NOTICE message, 
				 ie. the channel or person it was sent to */
The next step is to connect to the IRC server and to invoke the message loop. This function will continue until there the connection is closed, so I recommend you fork or start a new thread if you wish to do other processing:
	conn.start("", 6667, "some nick", "some user", "some irc name", "some password");
The function call to IRC::start() is pretty self-explanatory. See the IRC protocol RFC if you do not understand the parts.

When you are sick of talking to the IRC server, just get one of your forked processes or spawned threads to issue this command:

and cpIRC will close the connection and the IRC::message_loop() function will return. You can see how easy it is to issue a command to the IRC server, the functions are as follows:
As of cpIRC v0.1.6 the following IRC commands are implemented as functions:

int IRC::join(char* channel);
Join a channel.
int IRC::part(char* channel);
Leave a channel.
int IRC::quit(char* message);
Disconnect from the IRC server.
int IRC::notice(char* target, char* message);
int IRC::notice(char* target, ...);
Send a notice. The second function allows usage like printf.
int IRC::privmsg(char* target, char* message);
int IRC::privmsg(char* target, ...);
Send a message. The second function allows usage like printf.
int IRC::kick(char* channel, char* nick);
int IRC::kick(char* channel, char* nick, char* message);
Kick somebody from a channel.
int IRC::mode(char* modes);
int IRC::mode(char* channel, char* modes, char* targets);
Change channel or user modes.
int IRC::nick(char* newnick);
Change your nickname.
int IRC::raw(char* data);
Issue a raw IRC command to the server.

and the following other functions are implemented:

int IRC::start(char* server, int port, char* nick, char* user, char* name, char* pass);
Connects to an IRC server.
int IRC::message_loop();
Start the IRC message loop, this is called to start the parsing of commands.
void IRC::hook_irc_command(char* cmd_name, int (*function_ptr)(char*, irc_reply_data*, void*));
This function is used to 'hook' an IRC command. It allows you to specify a function to be called when the appropriate response is received from the server.
void IRC::disconnect();
Disconnect from the IRC server. This function does not take a reason for quitting as a parameter.
int IRC::is_op(char* channel, char* nick);
Checks whether or not a user has ops in the specified channel.
int IRC::is_voice(char* channel, char* user);
Checks whether or not a user has voice in the specified channel.
char* IRC::current_nick();
Returns a pointer to a string holding the current nickname of the client.


Here is an example of a small program that uses cpIRC to connect to an IRC server and join a channel (note, a win32 program):
	#include <stdio.h>
	#include <windows.h>
	#include <process.h>

	#include "IRC.h"

	int end_of_motd(char* params, irc_reply_data* hostd, void* conn) /* our callback function */
		IRC* irc_conn=(IRC*)conn;
		irc_conn->join("#magpie"); /* join the channel #magpie */
		return 0;

	void cmd_thread(void* irc_conn) /* another thread just to wait until a key is pressed, and then quit */
		IRC* conn=(IRC*)irc_conn;

		getc(stdin); /* read in a character from standard in */
		conn->quit("Leaving"); /* send the Quit command to the IRC server */
		_endthread(); /* end the thread */

	void main()
		IRC conn; /* declare an IRC connection */
		WSADATA wsaData; /* winsock stuff, linux/unix/*bsd users need not worry about this */
		if (WSAStartup(MAKEWORD(1, 1), &wsaData)) /* more winsock rubbish */
			printf("Failed to initialise winsock!\n");
		conn.hook_irc_command("376", &end_of_motd); /* hook the end of MOTD message */
		_beginthread(cmd_thread, 0, (void*)&conn); /* spawn our key input thread */
		conn.start("", 6668, "cpirctest", "cpirctest", "cpIRC test", "password"); /* connect to a server */
		conn.message_loop(); /* start the message loop */
		WSACleanup(); /* more winsock stuff */
UNIX/Linux/*BSD examples may follow at a later date, but these are essentially the same - just no WinSock initialisation and the inclusion of a few extra header files.

<>#magpie @