CocoaBots : Documents : Installation and Configuration Guide

Utilizing the CocoaBots framework is a simple process. The framework was designed to remove the complex details of network connectivity from the process of handling information and interacting with users. The basic steps for including the framework are as follows:

  1. Import the framework into your Cocoa application.
  2. Subclass any of the available bot types.
  3. Override the Message Methods.
  4. Configure the bot's connection parameters.
  5. Initiate a connection

Importing the CocoaBots Framework To import the framework into your XCode project, simply select the "Add to Project" menu item and navigate to the framework's location on your machine (/Library/Frameworks/CocoaBots.framework).

Creating a Bot Subclass: The CocoaBot super class provides much of the network oriented functionality of the bot. Subclassing it allows you to focus on managing data and interacting with users. To create the subclass, simply create a new Objective-C class in XCode and set its SuperClass to be the desired Bot type. In release 1.0, CocoaBots provides an IRCBot class.

@interface YourBot : IRCBot {


Overriding the Message Methods: The level of integration and message handling is decided by which of the following methods your subclass overrides:

  • -(BOOL)handlePRIVMSGMessage:(NSDictionary *)messageDict
    This is the simplest and most common method to override. The framework will call this method each time it receives a PRIVMSG. The method is passed an NSDictionary with the following keys: "msgSender", "msgRecipient" and "msgText". The framework will handle all other service related messages.

  • -(BOOL)handleMessage:(NSDictionary *)messageDict
    This is most low level method to override. It is called each time the framework receives data from the server it is connected to. This includes all server related messages. The method is passed an NSDictionary with the following key: "msg" -- which contains the complete text of the incoming message.

Configuring the bot's connection parameters: The connection parameters tell the bot which server to connect to and various other details specific to the bot type. For example, the IRCBot requires an NSDictionary with the following keys: "targetServer", "servername", "hostname", "nick", "username", "realname", "channelName". You can set the bot's connection parameters by simply creating an NSDictionary with those keys (and their proper values), then setting the bot's connectionParams dictionary

NSMutableDictionary *yourValues = [[NSMutableDictionary alloc] init];
[yourValues setObject:@"john" forKey:@"nick"];
botInstance.connectionParams = yourValues;

Initiating a connection to the server: Once the bot is configured, you can initiate a connection to the server and take advantage of the framework's API for interaction. To initiate the connection, simply call the -(BOOL)connectToServer:(NSError **)error method.

[botInstance connectToServer:&error];

Once the bot has connected successfully, you can handle the incoming data, send messages and more. The complete API for the framework is available in the CocoaBots IRCBot v1.0 API.

This site runs on ThoughtConduit v10.12.2 by Sensory Research