Browse Source

More documentation work

tags/v1.0.0
Chris Smith 5 years ago
parent
commit
2e454521a5
1 changed files with 307 additions and 3 deletions
  1. 307
    3
      docs/index.adoc

+ 307
- 3
docs/index.adoc View File

@@ -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

Loading…
Cancel
Save