README.md

   1 This is a modified version of the IRCClient framework by Nathan Ollerenshaw. It is partly based on the libircclient library by Georgy Yunaev. (See LICENSE for more info.) I’ve rewritten it to allow robust support for arbitrary text encodings, and fixed various other problems, as well making it fully Objective C native code. The original version of IRCClient, as well as libircclient, is available here: [http://sourceforge.net/projects/libircclient/](http://sourceforge.net/projects/libircclient/).
   2
   3 ---
   4
   5 ## Adding IRCClient to your application
   6
   7 (using Xcode)
   8 (these instructions apply to Xcode 7.1.1, build 7B1005)
   9
  10 1. Place the entire `IRCClient` folder in your project folder
  11
  12 2. Using **File -> Add Files…**, add `IRCClient.xcodeproj` to your project
  13
  14 3. Build the `IRCClient` framework target
  15
  16 4. Make sure the **Header Search Paths** build setting of your project contains the following entry:
  17    ```
  18    $(PROJECT_DIR)/
  19        (non-recursive)
  20    ```
  21
  22 5. Configure the build phases for your application target thusly:
  23
  24         * Add `IRCClient.framework` to **Link Binary With Libraries**
  25         * Add `IRCClient.framework` to **Target Dependencies**
  26         * Add a **Copy Files** build phase
  27         * Set destination for the just-added **Copy Files** build phase to **Frameworks**
  28         * Add `IRCClient.framework` to the just-added **Copy Files** build phase
  29
  30 6. Import IRCClient’s API into your code using `#import <IRCClient/IRCClient.h>`
  31
  32 7. If you’re using Swift in your project, add `IRCClient/IRCClient.h` to the **Objective-C Bridging Header** build setting.
  33
  34 ### Documentation
  35
  36 See the following header files for documentation:
  37
  38 * `IRCClientSession.h`
  39 * `IRCClientSessionDelegate.h`
  40 * `IRCClientChannel.h`
  41 * `IRCClientChannelDelegate.h`
  42
  43 ### NOTE on strings
  44
  45 IRCClient stores and passes all strings (messages, nicks, channel names, mode strings, channel topics, etc.) as `NSData` objects. Values passed to framework methods (such as the IRC commands) should also be in this format[^1]. This means that IRCClient is encoding-agnostic[^1]; it is up to you to pass it properly encoded representations of your text strings, and it is also up to you to select an appropriate encoding for display or other handling of received strings, as necessary. The `encoding` property of `IRCClientSession` and `IRCClientChannel` may be useful in this regard (i.e. for the convenience of associating a server’s or channel’s preferred encoding with the relevant server or channel object), although note that this property is almost entirely epiphenomenal[^2].
  46
  47 [^1]: Of course, IRCClient does not support UTF-16 nor any other non-8-bit encoding, as the IRC protocol does not support such encodings either.
  48
  49 [^2]: The `encoding` property of `IRCClientSession` does have one effect: it controls the encoding used by replies to `CTCP TIME` requests.
  50
  51 ---
  52
  53 ## Usage
  54
  55 To use this framework, you will need to write an `IRCClientSessionDelegate` to
  56 handle all of the events generated by the server, and an `IRCClientChannelDelegate`
  57 to handle all of the events generated by channels on that server.
  58
  59 You then create an `IRCClientSession` object in your code, assign the required
  60 properties, and call `-[connect:]` to connect to the server, place the connection
  61 on a new event queue and start receiving events. For example:
  62
  63 ```
  64 IRCClientSession *session = [IRCClientSession session];
  65 MyIRCClientSessionDelegate *controller = [[MyIRCClientSessionDelegate alloc] init];
  66
  67 session.delegate = controller;
  68 controller.session = session;
  69
  70 session.server = @"irc.libera.chat".dataAsUTF8;
  71 session.port = 6667;
  72 [session setNickname:@"test".dataAsUTF8
  73             username:@"test".dataAsUTF8
  74             realname:@"test".dataAsUTF8];
  75 [session connect];
  76 ```
  77
  78 If you have questions, bug reports, or suggestions regarding IRCClient,
  79 find Obormot on the Libera.Chat IRC network.
  80
  81 If you have any questions, bug reports, suggestions regarding libircclient,
  82 please visit [http://sourceforge.net/projects/libircclient/](http://sourceforge.net/projects/libircclient/).