|
@@ -528,12 +528,21 @@ operator to check if the user is in a channel:
|
528
|
528
|
|
529
|
529
|
[source,kotlin]
|
530
|
530
|
----
|
531
|
|
-ircClient.userState["acidBurn"]?.let { knownUser ->
|
|
531
|
+ircClient.userState["acidBurn"]?.let { knownUser -> <1>
|
532
|
532
|
val accountName = knownUser.account
|
533
|
|
- val inChannel = "#channel" in knownUser
|
534
|
|
- val allChannels = knownUser.channels
|
|
533
|
+ val inChannel = "#channel" in knownUser <2>
|
|
534
|
+ val allChannels = knownUser.channels <3>
|
535
|
535
|
}
|
536
|
536
|
----
|
|
537
|
+<1> If the user isn't known, the call to `get` (using the `[]` operator)
|
|
538
|
+ returns null, so we use a `let` statement to deal only with the case
|
|
539
|
+ that the user is found.
|
|
540
|
+<2> Check if the user is present on the common channel `#channel`. If
|
|
541
|
+ the KtIrc client is not joined to that channel, it will always return
|
|
542
|
+ false. You can also use the `contains("#channel")` method instead of
|
|
543
|
+ the `in` operator.
|
|
544
|
+<3> Returns all common channels we share with the user; will never
|
|
545
|
+ include channels that the KtIrc client is not joined to.
|
537
|
546
|
|
538
|
547
|
==== ChannelState
|
539
|
548
|
|
|
@@ -578,8 +587,303 @@ ircClient.channelState["#ktirc"]?.users?.forEach { user ->
|
578
|
587
|
|
579
|
588
|
=== Events
|
580
|
589
|
|
|
590
|
+Incoming lines from the IRC server are covered by KtIrc to subclasses of
|
|
591
|
+`IrcEvent`. These, along with other more advance events, are then published
|
|
592
|
+to users of the client using the `onEvent` method in `IrcClient`.
|
|
593
|
+
|
|
594
|
+All events extend `IrcEvent`, which offers a single `metadata` property.
|
|
595
|
+This contains details related to the event:
|
|
596
|
+
|
|
597
|
+* `time` - the time at which the message occurred (if the server supports
|
|
598
|
+ the `server-time` capability), or the time at which we received it.
|
|
599
|
+ Always present.
|
|
600
|
+* `batchId` - an opaque string identifier for the batch the message is
|
|
601
|
+ part of (if the server supports the `batch` capability). Null for
|
|
602
|
+ messages not in a batch.
|
|
603
|
+* `messageId` - a unique, opaque string identifier for the message if
|
|
604
|
+ the server supports the `msgid` tag. Null otherwise.
|
|
605
|
+* `label` - a unique, opaque string identifier that ties a message to
|
|
606
|
+ a labelled command that was sent by KtIrc, if the server supports
|
|
607
|
+ the `labelled-replies` capability. Null otherwise.
|
|
608
|
+
|
|
609
|
+Several specialised versions of `IrcEvent` are used which allow for easier
|
|
610
|
+processing:
|
|
611
|
+
|
|
612
|
+.TargetedEvent
|
|
613
|
+
|
|
614
|
+A `TargetedEvent` is one that is targeted at either a user or a channel.
|
|
615
|
+`TargetedEvent` exposes a string `target` property that identifies the
|
|
616
|
+target of the message. This allows you to direct messages to the right
|
|
617
|
+handler or UI component more easily:
|
|
618
|
+
|
|
619
|
+[source,kotlin]
|
|
620
|
+----
|
|
621
|
+ircClient.onEvent { event ->
|
|
622
|
+ when (event) {
|
|
623
|
+ is TargetedEvent -> dispatchEvent(event.target, event)
|
|
624
|
+ }
|
|
625
|
+}
|
|
626
|
+----
|
|
627
|
+
|
|
628
|
+.SourcedEvent
|
|
629
|
+
|
|
630
|
+A large number of events come from a remote IRC user, and it can be
|
|
631
|
+useful to handle these in the same way. KtIrc offers a `SourcedEvent`
|
|
632
|
+interface for all events that originate from a user, and it exposes
|
|
633
|
+a single `user` property:
|
|
634
|
+
|
|
635
|
+[source,kotlin]
|
|
636
|
+----
|
|
637
|
+ircClient.onEvent { event ->
|
|
638
|
+ when (event) {
|
|
639
|
+ is SourcedEvent -> notifyAboutUserActivity(event.user)
|
|
640
|
+ }
|
|
641
|
+}
|
|
642
|
+----
|
|
643
|
+
|
|
644
|
+.ChannelMembershipAdjustment
|
|
645
|
+
|
|
646
|
+A number of events describe how the membership of a channel changes --
|
|
647
|
+namely, joins, parts, quits, kicks, names replies, and nick changes.
|
|
648
|
+All of these events implement the `ChannelMembershipAdjustment` interface
|
|
649
|
+which reduces the amount of logic you need to do if you wish to maintain
|
|
650
|
+a membership list (for example in a UI). The interface exposes three
|
|
651
|
+properties:
|
|
652
|
+
|
|
653
|
+* `addedUser` - a single nickname to be added _(String)_
|
|
654
|
+* `removedUser` - a single nickname to be removed _(String)_
|
|
655
|
+* `replacedUsers` - a list of nicknames to replace any existing ones with
|
|
656
|
+ _(Array<String>)_
|
|
657
|
+
|
|
658
|
+All the properties are nullable, and most events will only populate
|
|
659
|
+one of the three.
|
|
660
|
+
|
|
661
|
+==== Server events
|
|
662
|
+
|
|
663
|
+===== ServerConnecting
|
|
664
|
+* Type: IrcEvent
|
|
665
|
+* Properties: _(none)_
|
|
666
|
+
|
|
667
|
+This event is raised by KtIrc as soon as it starts attempting to connect to
|
|
668
|
+a server. It will be followed by either a <<ServerConnected>> or a
|
|
669
|
+<<ServerConnectionError>> event at some point.
|
|
670
|
+
|
|
671
|
+===== ServerConnected
|
|
672
|
+* Type: IrcEvent
|
|
673
|
+* Properties: _(none)_
|
|
674
|
+
|
|
675
|
+This event is raised by KtIrc when it has connected to the server, and is
|
|
676
|
+starting the process of registering, negotiating capabilities, etc.
|
|
677
|
+The server will *not* yet be ready for use - a <<ServerReady>> event will
|
|
678
|
+follow once all of the initial setup has completed.
|
|
679
|
+
|
|
680
|
+===== ServerConnectionError
|
|
681
|
+* Type: IrcEvent
|
|
682
|
+* Properties:
|
|
683
|
+** `error`: `ConnectionError` - the type of error that occurred
|
|
684
|
+** `details`: `String?` - information about the error, if available
|
|
685
|
+
|
|
686
|
+This event is raised by KtIrc when a problem occurred while connecting
|
|
687
|
+to the server. The `ConnectionError` enum will provide the cause of
|
|
688
|
+the error, if known:
|
|
689
|
+
|
|
690
|
+* `UnresolvableAddress` - the hostname provided could not be resolved
|
|
691
|
+ to an IP address
|
|
692
|
+* `ConnectionRefused` - the server did not answer a connection request
|
|
693
|
+ on the given port
|
|
694
|
+* `BadTlsCertificate` - there was an issue with the TLS certificate the
|
|
695
|
+ server presented (e.g. it was out of date, for the wrong domain, etc)
|
|
696
|
+* `Unknown` - the exact cause of the error isn't known
|
|
697
|
+
|
|
698
|
+This event will be followed by a <<ServerDisconnected>> event.
|
|
699
|
+
|
|
700
|
+===== ServerWelcome
|
|
701
|
+* Type: IrcEvent
|
|
702
|
+* Properties:
|
|
703
|
+** `server`: `String` - the name the server supplied for itself
|
|
704
|
+** `localNick`: `String` - the nickname the server says we are using
|
|
705
|
+
|
|
706
|
+This event is raised in response to the server sending a 001 WELCOME
|
|
707
|
+message. It contains the name that the server supplied for itself
|
|
708
|
+(for example, KtIrc may connect to a round-robin address like
|
|
709
|
+`irc.example.com` and the server it actually connects to then
|
|
710
|
+identifies itself as `node3.uk.irc.example.com`), and the nickname
|
|
711
|
+that the server says we are using.
|
|
712
|
+
|
|
713
|
+===== ServerFeaturesUpdated
|
|
714
|
+* Type: IrcEvent
|
|
715
|
+* Properties:
|
|
716
|
+** `serverFeatures`: `ServerFeatureMap` - the features supplied by the server
|
|
717
|
+
|
|
718
|
+Corresponds to the server sending a single 005 ISUPPORT line. Multiple
|
|
719
|
+events of this type may be raised in quick succession when features are
|
|
720
|
+split over multiple lines.
|
|
721
|
+
|
|
722
|
+In general, you should wait for a <<ServerReady>> event and then query the
|
|
723
|
+<<Features>> instead of relying on this event.
|
|
724
|
+
|
|
725
|
+===== ServerReady
|
|
726
|
+* Type: IrcEvent
|
|
727
|
+* Properties: _(none)_
|
|
728
|
+
|
|
729
|
+This event is raised by KtIrc when it has connected to a server,
|
|
730
|
+registered with the IRC network, and received all of the server's
|
|
731
|
+initial data describing its configurations and its features.
|
|
732
|
+
|
|
733
|
+At this point it is safe to start issuing commands, checking
|
|
734
|
+state, joining channels, etc.
|
|
735
|
+
|
|
736
|
+===== PingReceived
|
|
737
|
+* Type: IrcEvent
|
|
738
|
+* Properties:
|
|
739
|
+** `nonce`: `ByteArray` - the unique data that must be included in the reply
|
|
740
|
+
|
|
741
|
+Raised when the IRC server sends a PING message to the client. KtIrc will
|
|
742
|
+automatically reply with an appropriate PONG.
|
|
743
|
+
|
|
744
|
+===== ServerCapabilitiesReceived
|
|
745
|
+
|
|
746
|
+TODO
|
|
747
|
+
|
|
748
|
+===== ServerCapabilitiesAcknowledged
|
|
749
|
+
|
|
750
|
+TODO
|
|
751
|
+
|
|
752
|
+===== ServerCapabilitiesFinished
|
|
753
|
+
|
|
754
|
+TODO
|
|
755
|
+
|
|
756
|
+===== MotdLineReceived
|
|
757
|
+
|
|
758
|
+TODO
|
|
759
|
+
|
|
760
|
+===== MotdFinished
|
|
761
|
+
|
|
762
|
+TODO
|
|
763
|
+
|
|
764
|
+==== Channel events
|
|
765
|
+
|
|
766
|
+===== ChannelJoined
|
|
767
|
+
|
|
768
|
+TODO
|
|
769
|
+
|
|
770
|
+===== ChannelJoinFailed
|
|
771
|
+
|
|
772
|
+TODO
|
|
773
|
+
|
|
774
|
+===== ChannelParted
|
|
775
|
+
|
|
776
|
+TODO
|
|
777
|
+
|
|
778
|
+===== ChannelUserKicked
|
|
779
|
+
|
|
780
|
+TODO
|
|
781
|
+
|
|
782
|
+===== ChannelQuit
|
|
783
|
+
|
|
784
|
+TODO
|
|
785
|
+
|
|
786
|
+===== ChannelNickChanged
|
|
787
|
+
|
|
788
|
+TODO
|
|
789
|
+
|
|
790
|
+===== ChannelNamesReceived
|
|
791
|
+
|
|
792
|
+TODO
|
|
793
|
+
|
|
794
|
+===== ChannelNamesFinished
|
|
795
|
+
|
|
796
|
+TODO
|
|
797
|
+
|
|
798
|
+===== ChannelTopicDiscovered
|
|
799
|
+
|
|
800
|
+TODO
|
|
801
|
+
|
|
802
|
+===== ChannelTopicMetadataDiscovered
|
|
803
|
+
|
|
804
|
+TODO
|
|
805
|
+
|
|
806
|
+===== ChannelTopicChanged
|
|
807
|
+
|
|
808
|
+TODO
|
|
809
|
+
|
|
810
|
+
|
|
811
|
+==== Channel/User events
|
|
812
|
+
|
|
813
|
+TODO
|
|
814
|
+
|
|
815
|
+===== MessageReceived
|
|
816
|
+
|
|
817
|
+TODO
|
|
818
|
+
|
|
819
|
+===== NoticeReceived
|
|
820
|
+
|
|
821
|
+TODO
|
|
822
|
+
|
|
823
|
+===== ActionReceived
|
|
824
|
+
|
|
825
|
+TODO
|
|
826
|
+
|
|
827
|
+===== CtcpReceived
|
|
828
|
+
|
|
829
|
+TODO
|
|
830
|
+
|
|
831
|
+===== CtcpReplyReceived
|
|
832
|
+
|
|
833
|
+TODO
|
|
834
|
+
|
|
835
|
+===== UserQuit
|
|
836
|
+
|
|
837
|
+TODO
|
|
838
|
+
|
|
839
|
+===== UserNickChanged
|
|
840
|
+
|
|
841
|
+TODO
|
|
842
|
+
|
|
843
|
+===== UserHostChanged
|
|
844
|
+
|
|
845
|
+TODO
|
|
846
|
+
|
|
847
|
+===== UserAccountChanged
|
|
848
|
+
|
581
|
849
|
TODO
|
582
|
850
|
|
|
851
|
+===== ModeChanged
|
|
852
|
+
|
|
853
|
+TODO
|
|
854
|
+
|
|
855
|
+
|
|
856
|
+==== Other events
|
|
857
|
+
|
|
858
|
+===== AuthenticationMessage
|
|
859
|
+
|
|
860
|
+TODO
|
|
861
|
+
|
|
862
|
+===== SaslFinished
|
|
863
|
+
|
|
864
|
+TODO
|
|
865
|
+
|
|
866
|
+===== SaslMechanismNotAvailableError
|
|
867
|
+
|
|
868
|
+TODO
|
|
869
|
+
|
|
870
|
+===== BatchStarted
|
|
871
|
+
|
|
872
|
+TODO
|
|
873
|
+
|
|
874
|
+===== BatchFinished
|
|
875
|
+
|
|
876
|
+TODO
|
|
877
|
+
|
|
878
|
+===== BatchReceived
|
|
879
|
+
|
|
880
|
+TODO
|
|
881
|
+
|
|
882
|
+===== NicknameChangeFailed
|
|
883
|
+
|
|
884
|
+TODO
|
|
885
|
+
|
|
886
|
+
|
583
|
887
|
=== Messages
|
584
|
888
|
|
585
|
889
|
TODO
|