You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

index.adoc 49KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442
  1. = KtIrc {version}
  2. Chris Smith
  3. :version: 1.1.1
  4. :toc: left
  5. :toc-position: left
  6. :toclevels: 5
  7. == About KtIrc
  8. KtIrc is a Kotlin JVM library for connecting to and interacting with IRC servers.
  9. It is still in an early stage of development. Its main features:
  10. .Built for Kotlin
  11. KtIrc is written in and designed for use in Kotlin; it uses extension methods,
  12. DSLs, sealed classes, and so on, to make it much easier to use than an
  13. equivalent Java library.
  14. .Coroutine-powered
  15. KtIrc uses co-routines for all of its input/output which lets it deal with
  16. IRC messages in the background while your app does other things, without
  17. the overhead of creating a new thread per IRC client.
  18. .Modern IRC standards
  19. KtIrc supports many IRCv3 features such as SASL authentication, message IDs,
  20. server timestamps, replies, reactions, account tags, and more. These features
  21. (where server support is available) make it easier to develop bots and
  22. clients, and enhance IRC with new user-facing functionality.
  23. == Getting started
  24. === Installing
  25. All you need to do to start using KtIrc is add a single dependency.
  26. KtIrc is published to JCenter, making it quick and easy to pull in
  27. to almost any project. The examples below show how to add the JCenter
  28. repository and then the KtIrc dependency; you may already be using
  29. JCenter for other dependencies -- in that case just skip the
  30. repository configuration!
  31. .Gradle (using Kotlin DSL)
  32. [source,kotlin,subs="attributes"]
  33. ----
  34. repositories {
  35. jcenter()
  36. }
  37. dependencies {
  38. implementation("com.dmdirc:ktirc:{version}")
  39. }
  40. ----
  41. .Gradle (using Groovy DSL)
  42. [source,groovy,subs="attributes"]
  43. ----
  44. buildscript {
  45. repositories {
  46. jcenter()
  47. }
  48. }
  49. implementation 'com.dmdirc:ktirc:{version}'
  50. ----
  51. .Maven
  52. [source,xml,subs="attributes"]
  53. ----
  54. <repositories>
  55. <repository>
  56. <id>jcenter</id>
  57. <url>https://jcenter.bintray.com</url>
  58. </repository>
  59. </repositories>
  60. <dependencies>
  61. <dependency>
  62. <groupId>com.dmdirc</groupId>
  63. <artifactId>ktirc</artifactId>
  64. <version>{version}</version>
  65. </dependency>
  66. </dependencies>
  67. ----
  68. === Creating your first client
  69. KtIrc provides a DSL ("domain specific language") for configuring a
  70. client that allows you to set the connection details, the user's
  71. details, and configure the behaviour of KtIrc itself. The DSL is
  72. accessed through the `IrcClient` function. For full details of all
  73. supported options, see the <<IrcClient DSL>> reference.
  74. A basic client will look like this:
  75. [source,kotlin]
  76. ----
  77. val client = IrcClient {
  78. server {
  79. host = "my.server.com"
  80. }
  81. profile {
  82. nickname = "nick"
  83. username = "username"
  84. realName = "Hi there"
  85. }
  86. }
  87. ----
  88. === Connecting and handling events
  89. Getting KtIrc to start connecting is as simple as calling the `connect()`
  90. method, but before that we probably want to add an event listener to deal
  91. with incoming messages:
  92. [source,kotlin]
  93. ----
  94. client.onEvent { event -> <1>
  95. when (event) { <2>
  96. is ServerReady ->
  97. client.sendJoin("#ktirc") <3>
  98. is ServerDisconnected ->
  99. client.connect()
  100. is MessageReceived ->
  101. if (event.message == "!test") <4>
  102. client.reply(event, "Test successful!") <5>
  103. }
  104. }
  105. client.connect() <6>
  106. ----
  107. <1> An event listener is registered using the `onEvent` method. It receives
  108. a single IrcEvent.
  109. <2> A Kotlin `when` statement provides a convenient way to switch on the
  110. type of event received.
  111. <3> Most common IRC commands have `send` methods defined to quickly and
  112. safely send the message with the right formatting.
  113. <4> Kotlin smart-casts the event, so you can access the properties specific
  114. to the matched event class, such as `message`.
  115. <5> The IrcClient class provides useful methods to react and respond to
  116. events.
  117. <6> The connect() method starts connecting and returns immediately. You'll
  118. receive events updating you on the progress.
  119. In this example, we're waiting for three events: `ServerReady`, which occurs
  120. after we have connected and the server has sent us all of the pre-amble
  121. such as its configuration and capabilities; `ServerDisconnected` which
  122. is raised whenever KtIrc gets disconnected from (or fails to connect to) the
  123. IRC server; and `MessageReceived` which occurs, unsuprisingly, whenever a
  124. message is received. KtIrc has many events: for more information, see the
  125. <<Events>> reference.
  126. [CAUTION]
  127. ====
  128. With this code, KtIrc will immediately try to reconnect as soon as it is
  129. disconnected. If the server closes the connection early (due to, for
  130. example, a bad password or the user being banned) this will result in a
  131. huge number of connection attempts in a short time. In real code you should
  132. always delay reconnections -- preferably with a backoff -- to avoid
  133. excessive connection attempts.
  134. ====
  135. You can see that KtIrc provides a number of useful methods for sending
  136. requests to the server, and reacting and responding to events. IRC
  137. commands that KtIrc supports can be invoked using the `send*` methods,
  138. which are documented in the <<Messages>> reference. Other useful methods
  139. such as `reply` can be found in the <<Utility methods>> reference.
  140. === Mandatory event handling
  141. In order to properly connect to IRC, stay connected, and handle
  142. incoming messages properly, the following events MUST be handled:
  143. .<<NicknameChangeRequired>>
  144. The nickname change required event occurs when connecting to a server
  145. if our initial nickname is taken. A new nickname must be supplied
  146. to continue connecting.
  147. .<<ServerDisconnected>>
  148. When KtIrc becomes disconnected from a server, or fails a connection
  149. attempt, it will raise this event. If you wish to stay connected
  150. to IRC you must call the `connect()` method to start a reconnection
  151. attempt after an appropriate delay.
  152. .<<BatchReceived>>
  153. On servers that support the IRCv3 batch capability, some incoming
  154. messages may be sent inside a batch. These could include join or
  155. quit messages during a netsplit, or other important messages you
  156. may need to process. At minimum, when receiving a BatchReceived
  157. event you should apply your normal processing to all the events
  158. contained within.
  159. === Versioning and deprecation
  160. As of version 1.0.0, KtIrc adheres to semantic versioning: you can
  161. expect to upgrade between minor versions without problems (e.g. from `1.1.2`
  162. to `1.13.7`); major version changes include breaking changes such as the
  163. removal of methods. You should check the changelog before updating to
  164. a new major version.
  165. Where at all possible, methods will be deprecated for a full major version
  166. cycle before being removed. e.g., a method deprecated in `0.5.0` will be
  167. present in all `1.x.x` releases and will likely be removed fully in `2.0.0`.
  168. This gives users of the library opportunity to migrate away from deprecated
  169. methods in advance of their removal.
  170. In KtIrc, we define a breaking change as one that either:
  171. * removes public methods, classes, or fields; or
  172. * adds required parameters to an existing public method; or
  173. * significantly alters the default behaviour without any API changes
  174. Note that changes that don't meet this threshold to be classed as "breaking"
  175. may still cause errors in downstream projects. In particular, new enum
  176. values may be added which could cause compilation errors if they are
  177. used exhaustively (e.g. in a `return when` construct with no `else` clause).
  178. == IrcClient DSL
  179. The DSL for creating a new `IrcClient` allows you to set a number of
  180. options relating to how KtIrc connects, what user details it provides,
  181. and how it behaves. The full range of options available in the DSL is
  182. shown below:
  183. [source,kotlin]
  184. ----
  185. server {
  186. host = "irc.example.com"
  187. port = 6667
  188. useTls = true
  189. password = "H4ckTh3Pl4n3t"
  190. }
  191. profile {
  192. nickname = "MyBot"
  193. username = "bot"
  194. realName = "Botomatic v1.2"
  195. }
  196. behaviour {
  197. requestModesOnJoin = true
  198. alwaysEchoMessages = true
  199. }
  200. sasl {
  201. mechanisms += "PLAIN"
  202. username = "botaccount"
  203. password = "s3cur3"
  204. }
  205. ----
  206. === Server settings
  207. The server block allows you to specify the details of the IRC server you
  208. wish to connect to:
  209. * `host` - the hostname or IP address of the server *(required)*
  210. * `port` - the port to connect on _(default: 6697)_
  211. * `useTls` - whether to use a secure connection or not _(default: true)_
  212. * `password` - the password to provide to the server _(default: null)_
  213. An alternative more compact syntax is available for configuring server details:
  214. [source,kotlin]
  215. ----
  216. server("irc.example.com", 6667, true, "H4ckTh3Pl4n3t")
  217. ----
  218. You can, if you wish, combine the two or use named parameters:
  219. [source,kotlin]
  220. ----
  221. server(useTls = true, port = 6697) {
  222. host = "irc.example.com"
  223. password = "H4ckTh3Pl4n3t"
  224. }
  225. ----
  226. === User profile
  227. The user profile controls how KtIrc will present itself to the IRC server, and
  228. how other users on that server will see the KtIrc user:
  229. * `nickname` - the initial nickname you wish to use *(required)*
  230. * `username` - the "username" to provide to the server _(default: KtIrc)_
  231. * `realName` - the "real name" that will be seen by other clients
  232. _(default: KtIrc User)_
  233. [TIP]
  234. ====
  235. The "username" is sometimes called the "ident" or "gecos". Some IRC servers
  236. will check for an ident reply from your host and use that in place of the
  237. username provided if it gets a response. The username (or ident reply)
  238. becomes part of your client's hostmask, and is visible to other users. It
  239. is unrelated to nickserv or other account usernames.
  240. ====
  241. As with the <<Server settings>> you can use a more compact syntax:
  242. [source,kotlin]
  243. ----
  244. profile("nickname", "username", "real name")
  245. ----
  246. === Behaviour
  247. The behaviour block allows you to tweak how KtIrc itself operates. These
  248. options allow you perform common operations automatically, or enjoy more
  249. advanced IRC features even if the server doesn't support them:
  250. * `requestModesOnJoin` - if enabled, automatically requests channel modes
  251. when the client joins a new channel _(default: false)_
  252. * `alwaysEchoMessages` - if enabled, every message you send will result
  253. in a `MessageReceived` event being returned. Servers that support the
  254. IRCv3 `echo-message` capability will do this automatically; enabling the
  255. behaviour will make all servers act the same way _(default: false)_
  256. * `preferIPv6` - if enabled, KtIrc will prefer to connect over IPv6 if the
  257. server publishes AAAA DNS records. If disabled, KtIrc will prefer IPv4.
  258. If the server is available exclusively on IPv4 or IPv6 then this option
  259. has no effect. _(default: true)_
  260. The behaviour block is optional in its entirety.
  261. === SASL configuration
  262. SASL ("Simple Authentication and Security Layer") is a standard mechanism
  263. for securely authenticating to a service that has recently been adopted
  264. for use in IRC. SASL supports a number of 'mechanisms' that describe how
  265. the data will be exchanged between the client and server. KtIrc supports
  266. the following mechanisms:
  267. * `EXTERNAL` - the server uses some external means to authenticate the
  268. client, instead of a username and password. On most servers this
  269. means checking the client certificate against one registered with
  270. the user's account. _(disabled by default)_
  271. * `PLAIN` - the client sends the username and password in plain text
  272. during the connection phase. This offers slightly more security
  273. than calling `nickserv identify` (for example) after connecting.
  274. * `SCRAM-SHA-1` - this mechanism involves a "salted challenge" being
  275. completed which results in both the server and the client proving that
  276. they know the user's password, but without it every being transmitted.
  277. This is based on the `SHA-1` algorithm which has known issues, but is
  278. more than sufficient when used in this manner.
  279. * `SCRAM-SHA-256` - the same as `SCRAM-SHA-1` but using the `SHA-256`
  280. algorithm instead, which is more modern and secure.
  281. To use `PLAIN`, `SCRAM-SHA-1` or `SCRAM-SHA-256`, you must supply a username
  282. and password in the configuration:
  283. [source,kotlin]
  284. ----
  285. sasl {
  286. username = "botaccount"
  287. password = "s3cur3"
  288. }
  289. ----
  290. KtIrc enables `SCRAM-SHA-256`, `SCRAM-SHA-1` and `PLAIN` by default, and will
  291. use them in that order of preference if the server supports more than one.
  292. You can modify the `mechanisms` parameter if you wish to disable one:
  293. [source,kotlin]
  294. ----
  295. sasl {
  296. mechanisms -= "PLAIN"
  297. username = "botaccount"
  298. password = "s3cur3"
  299. }
  300. ----
  301. You can also clear all the default mechanisms and provide your own list:
  302. [source,kotlin]
  303. ----
  304. sasl {
  305. mechanisms("SCRAM-SHA-256", "PLAIN")
  306. username = "botaccount"
  307. password = "s3cur3"
  308. }
  309. ----
  310. If you wish to enable the `EXTERNAL` mechanism, you do not need to provide
  311. a username or password:
  312. [source,kotlin]
  313. ----
  314. sasl {
  315. mechanisms("EXTERNAL")
  316. }
  317. ----
  318. Alternatively, if you wish to enable `EXTERNAL` but fall back to other
  319. mechanisms if it doesn't work:
  320. [source,kotlin]
  321. ----
  322. sasl {
  323. mechanisms += "EXTERNAL"
  324. username = "botaccount"
  325. password = "s3cur3"
  326. }
  327. ----
  328. The SASL block is optional in its entirety.
  329. == State
  330. KtIrc attempts to track all reasonable state of the IRC network. This includes
  331. details about the server, channels the client is joined to, and users that are
  332. also in those channels. The state is exposed in a several fields accessible
  333. from the `IrcClient`:
  334. === ServerState
  335. The server state provides information about the server, and our connection to
  336. it.
  337. [IMPORTANT]
  338. ====
  339. The server state will be updated frequently while KtIrc is connecting to a
  340. server. The values within it should not be relied upon until a `ServerReady`
  341. event is received, as they may be incomplete or estimates before then.
  342. ====
  343. .serverState.status (ServerStatus)
  344. Provides an enum containing the current server state. One of:
  345. * `Disconnected` - the server is not connected
  346. * `Connecting` - we are attempting to establish a connection
  347. * `Negotiating` - we are logging in, negotiating capabilities, etc
  348. * `Ready` - we are connected and commands may be sent
  349. .serverState.localNickname (String) [DEPRECATED]
  350. The current nickname we are using on the IRC server. While connecting this
  351. will default to the nickname from the <<User profile>>, but it may be updated
  352. if e.g. the nick is in use or not allowed.
  353. [WARNING]
  354. ====
  355. This property is deprecated in favour of the <<LocalUser>> property of `IrcClient`.
  356. You should migrate to using `localUser.nickname` in place of `serverSate.localNickname`.
  357. ====
  358. .serverState.serverName (String)
  359. The name the server uses for itself. While connecting this defaults to the
  360. hostname given in the <<Server settings>>, but it will be updated to the
  361. value provided by the server. For example, you may connect to
  362. `irc.example.com` and during the negotiation phase KtIrc will see that it
  363. is actually talking to `server3.uk.irc.example.com` and update the
  364. serverName to reflect that.
  365. [TIP]
  366. ====
  367. For a user-friendly identifier most servers provide a `NETWORK` token in
  368. the ISUPPORT reply, which is available via the <<Features>> property.
  369. ====
  370. .serverState.channelModePrefix (ModePrefixMapping)
  371. Provides a mapping from channel user modes (such as "o" for op, "v" for
  372. voice) to the prefixes used before nicknames (such as "@" and "+").
  373. To map prefixes to modes, you can use the `getMode()` or `getModes()`
  374. functions:
  375. [source,kotlin]
  376. ----
  377. getMode('@') == 'o'
  378. getModes("@+") == "ov"
  379. ----
  380. .serverState.channelTypes (String)
  381. Contains the types of channels that are allowed by the server, such as
  382. `\#&amp;` for normal channels ("#") and local channels ("&").
  383. ==== Capabilities
  384. The IRCv3 specifications introduce the concept of 'capability negotiation'.
  385. This allows the client and server to negotiate and enable new capabilities
  386. that are mutually supported.
  387. The capabilities state contains the following properties:
  388. .serverState.capabilities.negotiationState (CapabilitiesNegotiationState)
  389. The current state of negotiating with the server. One of:
  390. * `AWAITING_LIST` - we have requested a list of capabitilies and are awaiting
  391. a reply
  392. * `AWAITING_ACK` - we have sent the capabilities we want to enable, and are
  393. waitin for the server to acknowledge them
  394. * `AUTHENTICATING` - we are attempting to authenticate with SASL
  395. * `FINISHED` - we have completed negotiation
  396. Where a server does not support IRCv3 capability negotiation, the state will
  397. remain at `AWAITING_LIST`.
  398. .serverState.capabilities.advertisedCapabilities (Map<String, String>)
  399. Contains a map of capability names to values that the server offered. This
  400. should only be required for advance use cases, such as looking up the
  401. languages offered by a server when providing the user with a choice of
  402. translations.
  403. .serverState.capabilities.enabledCapabilities (Map<Capability, String>)
  404. Contains a map of capabilities that KtIrc has successfully negotiated with
  405. the server.
  406. ===== Supported capabilities
  407. * `sasl` - used to perform SASL authentication during connection
  408. * `message-tags` - allows arbitrary tags on messages
  409. * `server-time` - the server adds a timestamp tag to each incoming message
  410. * `account-tag` - the server adds an account tag to incoming user messages
  411. * `userhost-in-names` - the NAMES reply includes users hosts not just nicknames
  412. * `multi-prefix` - all modes are included in nick prefixes (e.g. `@+nick`)
  413. * `extended-join` - more information is sent when a user joins a channel
  414. * `batch` - allows multi-line responses to be batched together
  415. * `echo-message` - echos the client's own messages back to it
  416. * `draft/labeled-responses` - responses are labeled so the client knows which
  417. incoming message corresponds to which command it sent
  418. * `account-notify` - the server sends a message when a user's account changes
  419. * `away-notify` - the server sends a message when a user's away state changes
  420. * `chghost` - the server sends a message when a user's host changes
  421. ==== Features
  422. Features are KtIrc's way of exposing the information the server declares in
  423. its ISUPPORT messages. These describe how the server is configured, and what
  424. limits are placed on clients. You access features using the `features` map
  425. in the server state:
  426. [source,kotlin]
  427. ----
  428. ircClient.serverState.features[ServerFeature.Network]
  429. ----
  430. The following features are available:
  431. * `Network` - the name of the network the server belongs to __(String?)__
  432. * `ServerCaseMapping` - the current case mapping of the server __(CaseMapping!)__
  433. * `Modeprefixes` - the user mode prefix mapping (e.g. ov to @+) __(ModePrefixMapping!)__
  434. * `MaximumChannels` - the maximum number of channels a user can join __(Int?)__
  435. * `ChannelModes` - the modes supported in channels __(Array<String>?)__
  436. * `ChannelTypes` - the types of channel supported (e.g. "#&") __(String!)__
  437. * `MaximumChannelNameLength` - how long channel names may be __(Int!)__
  438. * `WhoxSupport` - whether the server supports extended whos ("WHOX") __(Boolean!)__
  439. [NOTE]
  440. ====
  441. If the server does not define a feature, KtIrc will either fall back to a
  442. default value based on the IRC RFCs or common practice (for those features
  443. identified with a non-null type such as `Int!` or `String!`); otherwise
  444. the value of the feature will be `null` (such as for those identified as
  445. `Int?` or `String?` types).
  446. ====
  447. === UserState
  448. The client's UserState object tracks the details of all users in common
  449. channels. It can be used to find the most up-to-date and comprehensive
  450. information for those users, as well as the set of channels that we share
  451. with them.
  452. The UserState is accessed via the `userState` property of IrcClient and
  453. acts as a map, accessible using either a nickname or a `User` object:
  454. [source,kotlin]
  455. ----
  456. ircClient.userState["acidBurn"]
  457. val user: User = myIrcEvent.user
  458. ircClient.userState[user]
  459. ----
  460. The UserState returns a `KnownUser` object which exposes a `details`
  461. property containing the <<User>> details, and a `channels` property
  462. containing the common channel names. You can also use the `in`
  463. operator to check if the user is in a channel:
  464. [source,kotlin]
  465. ----
  466. ircClient.userState["acidBurn"]?.let { knownUser -> <1>
  467. val accountName = knownUser.account
  468. val inChannel = "#channel" in knownUser <2>
  469. val allChannels = knownUser.channels <3>
  470. }
  471. ----
  472. <1> If the user isn't known, the call to `get` (using the `[]` operator)
  473. returns null, so we use a `let` statement to deal only with the case
  474. that the user is found.
  475. <2> Check if the user is present on the common channel `#channel`. If
  476. the KtIrc client is not joined to that channel, it will always return
  477. false. You can also use the `contains("#channel")` method instead of
  478. the `in` operator.
  479. <3> Returns all common channels we share with the user; will never
  480. include channels that the KtIrc client is not joined to.
  481. ==== User
  482. User objects have the following properties:
  483. * `nickname` - the current nickname of the user, always set
  484. * `ident` - the ident (username/"gecos") of the user, if known (null otherwise)
  485. * `hostname` - the hostname of the user, if known (null otherwise)
  486. * `account` - the account of the user, if known (null if account unknown, or user not registered)
  487. * `realName` - the real name of the user, if known (null otherwise)
  488. * `awayMessage` - the away message of the user, if known (null if away state unknown, or user not away)
  489. === LocalUser
  490. Contains a <<User>> instance corresponding to our own details on the IRC
  491. network. This is the same instance that would be returned from
  492. `ircClient.userState[nickname]` for the current nickname.
  493. While connecting this will default to a User with only a nickname, which will
  494. be taken from the <<User profile>>. It will be updated as more information
  495. is received from the IRC server.
  496. === ChannelState
  497. The ChannelState keeps track of the state for all channels that the client
  498. is joined to. It is indexed by channel name:
  499. [source,kotlin]
  500. ----
  501. ircClient.channelState["#ktirc"]
  502. ----
  503. Each channel's state contains the following properties:
  504. * `receivingUserList` - boolean value indicating whether we are in the process
  505. of receiving the list of users for the channel. If we are, the `users`
  506. property will be incomplete.
  507. * `modesDiscovered` - boolean value indicating whether we have received the
  508. full set of modes set on the channel. The `requestModesOnJoin` <<Behaviour>>
  509. allows you to make KtIrc request these automatically.
  510. * `topic` - a ChannelTopic object representing the current channel topic.
  511. If no topic is set, then a ChannelTopic with `null` properties will be
  512. provided.
  513. * `users` - a map of all known users in the channel, see <<Channel users>>
  514. for more information
  515. * `modes` - A map of the current channel modes and their values. Only
  516. complete if `modesDiscovered` is true.
  517. ==== Channel users
  518. Channel users are accessed using the `users` property, which provides an
  519. iterable map of nickname to `ChannelUser`. Each `ChannelUser` contains
  520. the nickname and current modes for that user. To get further details about
  521. a user, such as their hostmask or real name, you should query the <<UserState>>
  522. with the given nickname.
  523. [source,kotlin]
  524. ----
  525. ircClient.channelState["#ktirc"]?.users?.forEach { user ->
  526. println("${user.nickname} has modes ${user.modes}")
  527. }
  528. ----
  529. == Events
  530. Incoming lines from the IRC server are converted by KtIrc to subclasses of
  531. `IrcEvent`. These, along with other more advance events, are then published
  532. to users of the client using the `onEvent` method in `IrcClient`.
  533. All events extend `IrcEvent`, which offers a single `metadata` property.
  534. This contains details related to the event:
  535. * `time` - the time at which the message occurred (if the server supports
  536. the `server-time` capability), or the time at which we received it.
  537. Always present.
  538. * `batchId` - an opaque string identifier for the batch the message is
  539. part of (if the server supports the `batch` capability). Null for
  540. messages not in a batch.
  541. * `messageId` - a unique, opaque string identifier for the message if
  542. the server supports the `msgid` tag. Null otherwise.
  543. * `label` - a unique, opaque string identifier that ties a message to
  544. a labelled command that was sent by KtIrc, if the server supports
  545. the `labelled-replies` capability. Null otherwise.
  546. Several specialised versions of `IrcEvent` are used which allow for easier
  547. processing:
  548. .TargetedEvent
  549. A `TargetedEvent` is one that is targeted at either a user or a channel.
  550. `TargetedEvent` exposes a string `target` property that identifies the
  551. target of the message. This allows you to direct messages to the right
  552. handler or UI component more easily:
  553. [source,kotlin]
  554. ----
  555. ircClient.onEvent { event ->
  556. when (event) {
  557. is TargetedEvent -> dispatchEvent(event.target, event)
  558. }
  559. }
  560. ----
  561. .SourcedEvent
  562. A large number of events come from a remote IRC user, and it can be
  563. useful to handle these in the same way. KtIrc offers a `SourcedEvent`
  564. interface for all events that originate from a user, and it exposes
  565. a single `user` property:
  566. [source,kotlin]
  567. ----
  568. ircClient.onEvent { event ->
  569. when (event) {
  570. is SourcedEvent -> notifyAboutUserActivity(event.user)
  571. }
  572. }
  573. ----
  574. .ChannelMembershipAdjustment
  575. A number of events describe how the membership of a channel changes --
  576. namely, joins, parts, quits, kicks, names replies, and nick changes.
  577. All of these events implement the `ChannelMembershipAdjustment` interface
  578. which reduces the amount of logic you need to do if you wish to maintain
  579. a membership list (for example in a UI). The interface exposes three
  580. properties:
  581. * `addedUser` - a single nickname to be added _(String)_
  582. * `removedUser` - a single nickname to be removed _(String)_
  583. * `replacedUsers` - a list of nicknames to replace any existing ones with
  584. _(Array<String>)_
  585. All the properties are nullable, and most events will only populate
  586. one of the three.
  587. === Server events
  588. ==== ServerConnecting
  589. * Type: IrcEvent
  590. * Properties: _(none)_
  591. This event is raised by KtIrc as soon as it starts attempting to connect to
  592. a server. It will be followed by either a <<ServerConnected>> or a
  593. <<ServerConnectionError>> event at some point.
  594. ==== ServerConnected
  595. * Type: IrcEvent
  596. * Properties: _(none)_
  597. This event is raised by KtIrc when it has connected to the server, and is
  598. starting the process of registering, negotiating capabilities, etc.
  599. The server will *not* yet be ready for use - a <<ServerReady>> event will
  600. follow once all of the initial setup has completed.
  601. ==== ServerConnectionError
  602. * Type: IrcEvent
  603. * Properties:
  604. ** `error`: `ConnectionError` - the type of error that occurred
  605. ** `details`: `String?` - information about the error, if available
  606. This event is raised by KtIrc when a problem occurred while connecting
  607. to the server. The `ConnectionError` enum will provide the cause of
  608. the error, if known:
  609. * `UnresolvableAddress` - the hostname provided could not be resolved
  610. to an IP address
  611. * `ConnectionRefused` - the server did not answer a connection request
  612. on the given port
  613. * `BadTlsCertificate` - there was an issue with the TLS certificate the
  614. server presented (e.g. it was out of date, for the wrong domain, etc)
  615. * `Unknown` - the exact cause of the error isn't known
  616. This event will be followed by a <<ServerDisconnected>> event.
  617. ==== ServerWelcome
  618. * Type: IrcEvent
  619. * Properties:
  620. ** `server`: `String` - the name the server supplied for itself
  621. ** `localNick`: `String` - the nickname the server says we are using
  622. This event is raised in response to the server sending a 001 WELCOME
  623. message. It contains the name that the server supplied for itself
  624. (for example, KtIrc may connect to a round-robin address like
  625. `irc.example.com` and the server it actually connects to then
  626. identifies itself as `node3.uk.irc.example.com`), and the nickname
  627. that the server says we are using.
  628. ==== ServerReady
  629. * Type: IrcEvent
  630. * Properties: _(none)_
  631. This event is raised by KtIrc when it has connected to a server,
  632. registered with the IRC network, and received all of the server's
  633. initial data describing its configurations and its features.
  634. At this point it is safe to start issuing commands, checking
  635. state, joining channels, etc.
  636. ==== ServerDisconnected
  637. * Type: IrcEvent
  638. * Properties: _(none)_
  639. Raised in all cases where KtIrc has attempted to connect to an IRC server and
  640. has now been disconnected. KtIrc will not automatically attempt to reconnect;
  641. the `connect()` method should be called again after an appropriate delay.
  642. NOTE: All of KtIrc's internal state, such as details about users and
  643. channels, will be reset when disconnected from the server. State should not
  644. be queried until a new <<ServerReady>> event has been received, at which
  645. point it will have been recreated.
  646. ==== MotdLineReceived
  647. * Type: IrcEvent
  648. * Properties:
  649. ** `line`: `String` - the line of the message of the day that was received
  650. ** `first`: `Boolean` - true if the line is the first one received
  651. The MotdLineReceived event is raised whenever the server sends a single
  652. line of its Message of the Day. The `first` parameter is set on the
  653. first line of the MOTD so that special formatting or UI handling can
  654. be applied. When the MOTD is finished, a <<MotdFinished>> event is raised.
  655. ==== MotdFinished
  656. * Type: IrcEvent
  657. * Properties:
  658. ** `missing`: `Boolean` - indicates the MOTD was missing
  659. This event occurs in two circumstances: when the server has sent a
  660. series of <<MotdLineReceived>> events and has reached the end of the
  661. Message of the Day; or when the server has no MOTD to send and
  662. informs the client that the MOTD is missing.
  663. === Channel events
  664. NOTE: Many events such as <<MessageReceived>> apply to both channels and
  665. users. These are documented in the <<Channel/User events>> category.
  666. ==== ChannelJoined
  667. * Type: IrcEvent, TargetedEvent, SourcedEvent, ChannelMembershipAdjustment
  668. * Properties:
  669. ** `user`: `User` - the user that joined the channel
  670. ** `target`: `String` - the channel that was joined
  671. Raised whenever a user joins a channel, including the KtIrc client. You
  672. can determine whether the join applies to another user or the local client
  673. using the <<IsLocalClient>> utility method.
  674. When the local client joins a new channel, this event will typically be
  675. followed by one or more <<ChannelNamesReceived>> events, then
  676. <<ChannelNamesFinished>>, <<ChannelTopicDiscovered>> and if the
  677. `requestModesOnJoin` <<Behaviour>> is enabled a <<ModeChanged>> event.
  678. ==== ChannelJoinFailed
  679. * Type: IrcEvent, TargetedEvent
  680. * Properties:
  681. ** `target`: `String` - the channel that we tried to join
  682. ** `reason`: `JoinError` - the error that prevented us from joining
  683. The ChannelJoinFailed event is raised when we attempt to join a channel
  684. but the server doesn't allow us to do so. The reason parameter enumerates
  685. the possible problems:
  686. * `TooManyChannels` - we are already in the maximum number of channels allowed
  687. by the server.
  688. * `NoHiding` - the channel is no-hiding (+H), but we have invisible join/parts
  689. enabled.
  690. * `NeedKey` - the channel is keyed (+k) and a valid key was not provided
  691. * `NeedInvite` - the channel is invite only (+i) and no invite was received.
  692. * `NeedRegisteredNick` - the channel is limited to registered users only, and we
  693. are not registered.
  694. * `NeedTls` - the channel is secure-only, and we're not using TLS.
  695. * `NeedAdmin` - the channel is limited to server admins and we are not one.
  696. * `NeedOper` - the channel is limited to ircops and we are not one.
  697. * `Banned` - we are banned from the channel.
  698. * `ChannelFull` - the channel is limited (+l) and currently full.
  699. * `BadChannelName` - the channel name is disallowed by the server.
  700. * `Throttled` - we're trying to joiin too many channels and have been throttled.
  701. * `Unknown` - we don't know why.
  702. [WARNING]
  703. ====
  704. ChannelJoinFailed events are generated on a _best-effort_ basis by KtIrc. Error
  705. handling on IRC is very poorly standardised, and varies wildly between server
  706. implementations. For example, trying to join a secure-only channel on an
  707. ircd-seven server will send a NOTICE to the user instead of an error response,
  708. so no `ChannelJoinFailed` event will be raised.
  709. When tracking whether a join suceeded or failed you should combine monitoring
  710. for the response with a reasonable timeout, and assume failure if the timeout
  711. lapses without a <<ChannelJoined>> or <<ChannelJoinFailed>> event occurring.
  712. ====
  713. ==== ChannelParted
  714. * Type: IrcEvent, TargetedEvent, SourcedEvent, ChannelMembershipAdjustment
  715. * Properties:
  716. ** `user`: `User` - the user that parted the channel
  717. ** `target`: `String` - the channel that was parted
  718. ** `reason`: `String` - the user-supplied reason for parting
  719. Raised when any user parts a channel that we are on. Users can supply a reason
  720. when parting a channel; if they have done so the `reason` property will be
  721. non-empty.
  722. ==== ChannelUserKicked
  723. * Type: IrcEvent, TargetedEvent, SourcedEvent, ChannelMembershipAdjustment
  724. * Properties:
  725. ** `user`: `User` - the user that performed the kick
  726. ** `victim`: `String` - the nickname of the user that was kicked
  727. ** `target`: `String` - the channel that the victim was kicked from
  728. ** `reason`: `String` - the user-supplied reason for kicking
  729. This event occurs when a user is kicked (forcibly removed) from a channel.
  730. NOTE: The `user` is the one performing the kick, and will remain in the
  731. channel. The `victim` is the one being forcibly ejected.
  732. ==== ChannelQuit
  733. * Type: IrcEvent, TargetedEvent, SourcedEvent, ChannelMembershipAdjustment
  734. * Properties:
  735. ** `user`: `User` - the user that quit
  736. ** `target`: `String` - the channel that the user was in
  737. ** `reason`: `String` - the user-supplied reason for quitting
  738. After a <<UserQuit>> event, KtIrc will "fan out" the event to all of the
  739. channels that we share with the user and raise a `ChannelQuit` event for
  740. each channel. This is designed to make implementing certain features easier;
  741. if you fully handle a UserQuit event there is no need to also handle the
  742. ChannelQuit events, and vice-versa.
  743. Users and servers can supply a reason when a user quits; if supplied then
  744. the `reason` parameter will be non-empty.
  745. ==== ChannelNickChanged
  746. * Type: IrcEvent, TargetedEvent, SourcedEvent, ChannelMembershipAdjustment
  747. * Properties:
  748. ** `user`: `User` - the user who has changed their nickname
  749. ** `target`: `String` - the channel that the user is in
  750. ** `newNick`: `String` - the user's new nickname
  751. After a <<UserNickChanged>> event, KtIrc will "fan out" the event to
  752. all of the channels that we share with the user and raise a `ChannelNickChanged`
  753. event for each channel. This is designed to make implementing certain features
  754. easier; if you fully handle a UserNickChanged event there is no need to also
  755. handle the ChannelNickChanged events, and vice-versa.
  756. TIP: The user property will contain the user's old details, but you will
  757. not be able to access additional information from the <<UserState>> using
  758. these details as KtIrc will have internally renamed the user to use the
  759. new nickname.
  760. ==== ChannelNamesReceived
  761. * Type: IrcEvent, TargetedEvent
  762. * Properties:
  763. ** `target`: `String` - the channel that the user is in
  764. ** `names`: `List<String>` - the partial list of names that are in the channel
  765. When we join a channel (or manually request it) the IRC server sends the
  766. list of channel members in a sequence of NAMES messages. KtIrc raises a
  767. `ChannelNamesReceived` event for each of these messages.
  768. WARNING: The given names may not be a complete list of members of the channel,
  769. as more names could follow. The format of the names varies between IRC servers
  770. and depending on the IRCv3 <<Capabilities>> that KtIrc negotiated. Most
  771. implementations should simply wait for <<ChannelNamesFinished>> and then request
  772. the complete list of names from KtIrc's <<ChannelState>>.
  773. ==== ChannelNamesFinished
  774. * Type: IrcEvent, TargetedEvent, ChannelMembershipAdjustment
  775. * Properties:
  776. ** `target`: `String` - the channel whose names response has finished
  777. Raised when the IRC server has finished receiving all of the names of users
  778. that are currently in a channel. At this point you can query the channel's
  779. <<ChannelState>> to get a detailed list of members.
  780. ==== ChannelTopicDiscovered
  781. * Type: IrcEvent, TargetedEvent
  782. * Properties:
  783. ** `target`: `String` - the channel whose topic was discovered
  784. ** `topic`: `String?` - the topic in the channel, if any
  785. `ChannelTopicDiscovered` occurs when we join a channel (or manually request
  786. that the server repeats the current topic) and contains the current channel
  787. topic. If there is no topic set, the `topic` parameter will be `null`.
  788. Metadata about the topic, such as who set it and when, is contained in the
  789. <<ChannelTopicMetadataDiscovered>> event which should follow this one, if
  790. the topic was set.
  791. ==== ChannelTopicMetadataDiscovered
  792. * Type: IrcEvent, TargetedEvent
  793. * Properties:
  794. ** `target`: `String` - the channel whose topic metadata was discovered
  795. ** `user`: `User` - the user who set the topic
  796. ** `setTime`: `LocalDateTime` - the time at which the topic was set
  797. Provides meta-data relating to a topic that was previously set on the
  798. channel.
  799. NOTE: The given user may not exist on the network any more, or may have
  800. changed details since the topic was set. You should not expect to be able
  801. to look up the user's details in the <<UserState>>, or interact with them
  802. directly on IRC.
  803. ==== ChannelTopicChanged
  804. * Type: IrcEvent, TargetedEvent, SourcedEvent
  805. * Properties:
  806. ** `user`: `User` - the user who has changed the topic
  807. ** `target`: `String` - the channel that the topic was changed in
  808. ** `topic`: `String?` - the channel's new topic
  809. Raised when a user changes the topic of a channel we are joined to. If
  810. the topic was cleared/removed, the `topic` parameter will be `null`.
  811. ==== ChannelAway
  812. * Type: IrcEvent, TargetedEvent, SourcedEvent
  813. * Properties:
  814. ** `user`: `User` - the user whose away state has changed
  815. ** `target`: `String` - the channel that the user is in
  816. ** `message`: `String?` - the away message, or `null` if the user is back
  817. After a <<UserAway>> event, KtIrc will "fan out" the event to all of the
  818. channels that we share with the user and raise a `ChannelAway`
  819. event for each channel. This is designed to make implementing certain features
  820. easier; if you fully handle a UserAway event there is no need to also
  821. handle the ChannelAway events, and vice-versa.
  822. === Channel/User events
  823. These are events that may be targeted to either a channel or a user. You
  824. can use the <<IsChannel>> method to determine whether the target of one
  825. of these events is a channel or not.
  826. ==== MessageReceived
  827. * Type: IrcEvent, TargetedEvent, SourcedEvent
  828. * Properties:
  829. ** `user`: `User` - the user who sent the message
  830. ** `target`: `String` - the channel or user the message was sent to
  831. ** `message`: `String` - the text of the message
  832. Raised whenever we receive a message on a channel or directly to our
  833. local user. CTCPs and Actions, which are client-side extensions to
  834. messages will not raise this event; instead they will raise
  835. <<CtcpReceived>> and <<ActionReceived>> respectively.
  836. The <<Reply>> function can be used to reply to a message,
  837. automatically selecting the appropriate target and including the
  838. message ID in the reply where supported by the IRC server.
  839. ==== NoticeReceived
  840. * Type: IrcEvent, TargetedEvent, SourcedEvent
  841. * Properties:
  842. ** `user`: `User` - the user who sent the notice
  843. ** `target`: `String` - the channel or user the notice was sent to
  844. ** `message`: `String` - the text of the notice
  845. Raised whenever we receive a notice on a channel or directly to our
  846. local user. CTCP replies, which are client-side extensions to
  847. notices will not raise this event; instead they will raise
  848. <<CtcpReplyReceived>>.
  849. During connection, notices may be received which target either the
  850. magic string `AUTH` or `*`, as the client's nickname is not yet
  851. known.
  852. ==== ActionReceived
  853. * Type: IrcEvent, TargetedEvent, SourcedEvent
  854. * Properties:
  855. ** `user`: `User` - the user who sent the action
  856. ** `target`: `String` - the channel or user the action was sent to
  857. ** `action`: `String` - the text of the action
  858. Raised whenever we receive an 'action' message on a channel or
  859. directly to our local user. Actions are a client-side extension
  860. to the IRC protocol that allow users to describe something they
  861. are doing.
  862. ==== CtcpReceived
  863. * Type: IrcEvent, TargetedEvent, SourcedEvent
  864. * Properties:
  865. ** `user`: `User` - the user who sent the CTCP
  866. ** `target`: `String` - the channel or user the CTCP was sent to
  867. ** `type`: `String` - the type of the CTCP
  868. ** `content`: `String` - the (possibly empty) content of the CTCP
  869. Raised in response to a message that contains a CTCP
  870. (client-to-client protocol) message other than an action.
  871. CTCPs have a type, such as `PING`, `VERSION`, and optionally
  872. some content such as a timestamp or nonce when requesting a PING.
  873. KtIrc does not reply to any CTCPs by itself. Replies to CTCPs are
  874. by convention sent to the originating user, even if the CTCP is
  875. sent to a channel.
  876. ==== CtcpReplyReceived
  877. * Type: IrcEvent, TargetedEvent, SourcedEvent
  878. * Properties:
  879. ** `user`: `User` - the user who sent the CTCP reply
  880. ** `target`: `String` - the channel or user the reply was sent to
  881. ** `type`: `String` - the type of the CTCP reply
  882. ** `content`: `String` - the (possibly empty) content of the CTCP reply
  883. Raised in response to a notice that contains a CTCP
  884. (client-to-client protocol) reply. This usually occurs after we
  885. have issued a CTCP request to a user or channel, and the `content`
  886. argument will contain the remote client's response.
  887. Replies to CTCPs are by convention sent to the originating user,
  888. even if the CTCP is sent to a channel. The `target` parameter
  889. should therefore be the local user in most cases.
  890. === User events
  891. TODO
  892. ==== UserAway
  893. * Type: IrcEvent, SourcedEvent
  894. * Properties:
  895. ** `user`: `User` - the user who has changed their away state
  896. ** `message`: `String?` - the away message, or `null` if the user is back
  897. Raised when we are informed that a user has changed away states. If the server
  898. supports the `away-notify` capability we will receive notifications for all
  899. users in our common channels; otherwise, we will only receive notifications
  900. for our own user.
  901. If the user is away but we don't know the reason for it, the `message`
  902. property will be empty.
  903. ==== ModeChanged
  904. TODO
  905. ==== UserQuit
  906. TODO
  907. ==== UserNickChanged
  908. TODO
  909. ==== UserHostChanged
  910. TODO
  911. ==== UserAccountChanged
  912. TODO
  913. === Other events
  914. ==== PingReceived
  915. * Type: IrcEvent
  916. * Properties:
  917. ** `nonce`: `ByteArray` - the unique data that must be included in the reply
  918. Raised when the IRC server sends a PING message to the client. KtIrc will
  919. automatically reply with an appropriate PONG.
  920. ==== ServerFeaturesUpdated
  921. * Type: IrcEvent
  922. * Properties:
  923. ** `serverFeatures`: `ServerFeatureMap` - the features supplied by the server
  924. Corresponds to the server sending a single 005 ISUPPORT line. Multiple
  925. events of this type may be raised in quick succession when features are
  926. split over multiple lines.
  927. In general, you should wait for a <<ServerReady>> event and then query the
  928. <<Features>> instead of relying on this event.
  929. ==== ServerCapabilitiesReceived
  930. TODO
  931. ==== ServerCapabilitiesAcknowledged
  932. TODO
  933. ==== ServerCapabilitiesFinished
  934. TODO
  935. ==== AuthenticationMessage
  936. TODO
  937. ==== SaslFinished
  938. TODO
  939. ==== SaslMechanismNotAvailableError
  940. TODO
  941. ==== BatchStarted
  942. TODO
  943. ==== BatchFinished
  944. TODO
  945. ==== BatchReceived
  946. TODO
  947. ==== NicknameChangeFailed
  948. * Type: IrcEvent
  949. * Properties:
  950. ** `cause`: `NicknameChangeError` - the reason the nickname must be changed
  951. Raised when the server informs us that our desired nickname is not available
  952. for some reason. The `cause` parameter will contain a specific reason given
  953. by the server:
  954. * `ErroneousNickname` - the nickname is not allowed by the server (e.g. it used
  955. restricted characters)
  956. * `AlreadyInUse` - the nickname is already in use
  957. * `Collision` - the nickname has collided with another somehow
  958. * `NoNicknameGiven` - no nickname was provided
  959. ==== NicknameChangeRequired
  960. * Type: IrcEvent, NicknameChangeFailed
  961. * Properties:
  962. ** `cause`: `NicknameChangeError` - the reason the nickname must be changed
  963. Raised during a connection attempt when there is a problem with the nickname
  964. that KtIrc was told to use. The exact problem will be detailed in the `cause`
  965. parameter, and has the same options as the <<NicknameChangeFailed>> event.
  966. Upon receiving this event, a new nickname MUST be chosen and sent to the
  967. server with the <<sendNickChange>> method. Failure to do so will result
  968. in the IRC server terminating the connection.
  969. WARNING: `NicknameChangeRequired` currently extends `NicknameChangeFailed`
  970. for backwards compatibility. This will be removed in KtIrc 2.0.0, and
  971. both events will need to be handled separately.
  972. == Messages
  973. TODO
  974. === sendNickChange
  975. TODO
  976. == Utility methods
  977. TODO
  978. === IsChannel
  979. TODO
  980. === IsLocalClient
  981. TODO
  982. === React
  983. TODO
  984. === Reply
  985. TODO
  986. == IRCv3 support
  987. The following table shows KtIrc's IRCv3 support as of this release:
  988. [cols=3,options="header,autowidth"]
  989. |===
  990. | Feature
  991. | Status
  992. | Notes
  993. 3+h| Capability negotiation
  994. | https://ircv3.net/specs/core/capability-negotiation.html[CAP]
  995. | {set:cellbgcolor:#a7eeaa} Supported
  996. | {set:cellbgcolor!}
  997. See <<Supported capabilities>> for the caps KtIrc will negotiate
  998. | https://ircv3.net/specs/core/capability-negotiation.html#cap-ls-version[CAP 302]
  999. | {set:cellbgcolor:#a7eeaa} Supported
  1000. | {set:cellbgcolor!}
  1001. See <<Supported capabilities>> for the caps KtIrc will negotiate
  1002. | https://ircv3.net/specs/core/capability-negotiation.html#cap-notify[cap-notify]
  1003. | {set:cellbgcolor:#f7d5d3} No support
  1004. | {set:cellbgcolor!}
  1005. 3+h| Published specifications
  1006. | https://ircv3.net/specs/extensions/account-notify-3.1.html[account-notify] v3.1
  1007. | {set:cellbgcolor:#a7eeaa} Supported
  1008. | {set:cellbgcolor!}
  1009. See <<UserAccountChanged>>
  1010. | https://ircv3.net/specs/extensions/account-tag-3.2.html[account-tag] v3.2
  1011. | {set:cellbgcolor:#a7eeaa} Supported
  1012. | {set:cellbgcolor!}
  1013. Accounts are automatically added to `User` properties in events
  1014. | https://ircv3.net/specs/extensions/away-notify-3.1.html[away-notify] v3.1
  1015. | {set:cellbgcolor:#a7eeaa} Supported
  1016. | {set:cellbgcolor!}
  1017. See <<UserAway>>.
  1018. | https://ircv3.net/specs/extensions/batch-3.2.html[batch] v3.2
  1019. | {set:cellbgcolor:#a7eeaa} Supported
  1020. | {set:cellbgcolor!}
  1021. See <<BatchReceived>>
  1022. | https://ircv3.net/specs/extensions/chghost-3.2.html[chghost] v3.2
  1023. | {set:cellbgcolor:#a7eeaa} Supported
  1024. | {set:cellbgcolor!}
  1025. See <<UserHostChanged>>
  1026. | https://ircv3.net/specs/extensions/echo-message-3.2.html[echo-message] v3.2
  1027. | {set:cellbgcolor:#a7eeaa} Supported
  1028. | {set:cellbgcolor!}
  1029. See also the `alwaysEchoMessages` <<Behaviour>>
  1030. | https://ircv3.net/specs/extensions/extended-join-3.1.html[extended-join] v3.1
  1031. | {set:cellbgcolor:#a7eeaa} Supported
  1032. | {set:cellbgcolor!}
  1033. Additional details are automatically added to `User` properties in events
  1034. | https://ircv3.net/specs/extensions/invite-notify-3.2.html[invite-notify] v3.2
  1035. | {set:cellbgcolor:#f7d5d3} No support
  1036. | {set:cellbgcolor!}
  1037. | https://ircv3.net/specs/extensions/message-tags.html[message-tags]
  1038. | {set:cellbgcolor:#a7eeaa} Supported
  1039. | {set:cellbgcolor!}
  1040. Exposed in the metadata property of <<Events>>
  1041. | https://ircv3.net/specs/core/monitor-3.2.html[monitor]
  1042. | {set:cellbgcolor:#f7d5d3} No support
  1043. | {set:cellbgcolor!}
  1044. | https://ircv3.net/specs/extensions/multi-prefix-3.1.html[multi-prefix] v3.1
  1045. | {set:cellbgcolor:#a7eeaa} Supported
  1046. | {set:cellbgcolor!}
  1047. Automatically included in <<ChannelState>>
  1048. | https://ircv3.net/specs/extensions/sasl-3.1.html[SASL] v3.1
  1049. | {set:cellbgcolor:#a7eeaa} Supported
  1050. | {set:cellbgcolor!}
  1051. See <<SASL configuration>>
  1052. | https://ircv3.net/specs/extensions/sasl-3.2.html[SASL] v3.2
  1053. | {set:cellbgcolor:#eeeeaa} Partial support
  1054. | {set:cellbgcolor!}
  1055. Notifications via `cap-notify` not yet supported. See <<SASL configuration>>
  1056. | https://ircv3.net/specs/extensions/server-time-3.2.html[server-time] v3.2
  1057. | {set:cellbgcolor:#a7eeaa} Supported
  1058. | {set:cellbgcolor!}
  1059. Exposed in the metadata property of <<Events>>
  1060. | https://ircv3.net/specs/extensions/sts.html[sts]
  1061. | {set:cellbgcolor:#f7d5d3} No support
  1062. | {set:cellbgcolor!}
  1063. | https://ircv3.net/specs/extensions/userhost-in-names-3.2.html[userhost-in-names] v3.2
  1064. | {set:cellbgcolor:#a7eeaa} Supported
  1065. | {set:cellbgcolor!}
  1066. Automatically included in <<UserState>>
  1067. | https://ircv3.net/specs/extensions/webirc.html[webirc]
  1068. | {set:cellbgcolor:#f7d5d3} No support
  1069. | {set:cellbgcolor!}
  1070. 3+h| Draft specifications
  1071. | https://github.com/ircv3/ircv3-specifications/pull/363[brb]
  1072. | {set:cellbgcolor:#f7d5d3} No support
  1073. | {set:cellbgcolor!}
  1074. | https://github.com/ircv3/ircv3-specifications/pull/308[channel renaming]
  1075. | {set:cellbgcolor:#f7d5d3} No support
  1076. | {set:cellbgcolor!}
  1077. | https://github.com/ircv3/ircv3-specifications/pull/349[chathistory]
  1078. | {set:cellbgcolor:#f7d5d3} No support
  1079. | {set:cellbgcolor!}
  1080. | https://github.com/ircv3/ircv3-specifications/pull/346[delivered]
  1081. | {set:cellbgcolor:#f7d5d3} No support
  1082. | {set:cellbgcolor!}
  1083. | https://github.com/ircv3/ircv3-specifications/pull/304[editmsg]
  1084. | {set:cellbgcolor:#f7d5d3} No support
  1085. | {set:cellbgcolor!}
  1086. | https://ircv3.net/specs/extensions/labeled-response.html[labeled-response]
  1087. | {set:cellbgcolor:#a7eeaa} Supported
  1088. | {set:cellbgcolor!}
  1089. Exposed in the metadata property of <<Events>>
  1090. | https://ircv3.net/specs/extensions/message-ids.html[message-ids]
  1091. | {set:cellbgcolor:#f7d5d3} No support
  1092. | {set:cellbgcolor!}
  1093. | https://github.com/ircv3/ircv3-specifications/pull/330[migrate]
  1094. | {set:cellbgcolor:#f7d5d3} No support
  1095. | {set:cellbgcolor!}
  1096. | https://ircv3.net/specs/client-tags/react.html[react]
  1097. | {set:cellbgcolor:#eeeeaa} Partial support
  1098. | {set:cellbgcolor!}
  1099. Sending via <<React>> method, no events generated
  1100. | https://github.com/ircv3/ircv3-specifications/pull/347[read]
  1101. | {set:cellbgcolor:#f7d5d3} No support
  1102. | {set:cellbgcolor!}
  1103. | https://github.com/ircv3/ircv3-specifications/pull/276[register]
  1104. | {set:cellbgcolor:#f7d5d3} No support
  1105. | {set:cellbgcolor!}
  1106. | https://ircv3.net/specs/client-tags/reply.html[reply]
  1107. | {set:cellbgcolor:#eeeeaa} Partial support
  1108. | {set:cellbgcolor!}
  1109. Sending via <<Reply>> method, not processed on incoming messages
  1110. | https://github.com/ircv3/ircv3-specifications/pull/306[resume]
  1111. | {set:cellbgcolor:#f7d5d3} No support
  1112. | {set:cellbgcolor!}
  1113. | https://github.com/ircv3/ircv3-specifications/pull/361[setname]
  1114. | {set:cellbgcolor:#f7d5d3} No support
  1115. | {set:cellbgcolor!}
  1116. | https://github.com/ircv3/ircv3-specifications/pull/357[standard replies]
  1117. | {set:cellbgcolor:#f7d5d3} No support
  1118. | {set:cellbgcolor!}
  1119. | https://github.com/ircv3/ircv3-specifications/pull/348[typing]
  1120. | {set:cellbgcolor:#f7d5d3} No support
  1121. | {set:cellbgcolor!}
  1122. 3+h|Vendor specifications
  1123. |===