|
@@ -9,18 +9,27 @@ import java.time.LocalDateTime
|
9
|
9
|
/**
|
10
|
10
|
* Metadata associated with an event.
|
11
|
11
|
*
|
12
|
|
- * @param time The best-guess time at which the event occurred.
|
13
|
|
- * @param batchId The ID of the batch this event is part of, if any.
|
14
|
|
- * @param messageId The unique ID of this message, if any.
|
15
|
|
- * @param label The label of the command that this event was sent in response to, if any.
|
|
12
|
+ * @property time The best-guess time at which the event occurred.
|
|
13
|
+ * @property batchId The ID of the batch this event is part of, if any.
|
|
14
|
+ * @property messageId The unique ID of this message, if any.
|
|
15
|
+ * @property label The label of the command that this event was sent in response to, if any.
|
16
|
16
|
*/
|
17
|
|
-data class EventMetadata(
|
|
17
|
+data class EventMetadata internal constructor(
|
18
|
18
|
val time: LocalDateTime,
|
19
|
19
|
val batchId: String? = null,
|
20
|
20
|
val messageId: String? = null,
|
21
|
21
|
val label: String? = null)
|
22
|
22
|
|
23
|
|
-/** Base class for all events. */
|
|
23
|
+/**
|
|
24
|
+ * Base class for all events raised by KtIrc.
|
|
25
|
+ *
|
|
26
|
+ * An event occurs in response to some action by the IRC server. Most events correspond to a single
|
|
27
|
+ * line received from the server (such as [NoticeReceived]), but some happen when a combination
|
|
28
|
+ * of lines lead to a certain state (e.g. [ServerReady]), and the [BatchReceived] event in particular
|
|
29
|
+ * can contain *many* lines received from the server.
|
|
30
|
+ *
|
|
31
|
+ * @property metadata Meta-data about the received event
|
|
32
|
+ */
|
24
|
33
|
sealed class IrcEvent(val metadata: EventMetadata) {
|
25
|
34
|
|
26
|
35
|
/** The time at which the event occurred. */
|
|
@@ -33,6 +42,8 @@ sealed class IrcEvent(val metadata: EventMetadata) {
|
33
|
42
|
|
34
|
43
|
/**
|
35
|
44
|
* Base class for events that are targeted to a channel or user.
|
|
45
|
+ *
|
|
46
|
+ * @param target The target of the event - either a channel name, or nick name
|
36
|
47
|
*/
|
37
|
48
|
sealed class TargetedEvent(metadata: EventMetadata, val target: String) : IrcEvent(metadata) {
|
38
|
49
|
|
|
@@ -48,10 +59,8 @@ sealed class TargetedEvent(metadata: EventMetadata, val target: String) : IrcEve
|
48
|
59
|
* Interface implemented by events that come from a particular user.
|
49
|
60
|
*/
|
50
|
61
|
interface SourcedEvent {
|
51
|
|
-
|
52
|
62
|
/** The user that caused the event. */
|
53
|
63
|
val user: User
|
54
|
|
-
|
55
|
64
|
}
|
56
|
65
|
|
57
|
66
|
/** Raised when a connection to the server is being established. */
|
|
@@ -66,7 +75,12 @@ class ServerDisconnected(metadata: EventMetadata) : IrcEvent(metadata)
|
66
|
75
|
/** Raised when an error occurred trying to connect. */
|
67
|
76
|
class ServerConnectionError(metadata: EventMetadata, val error: ConnectionError, val details: String?) : IrcEvent(metadata)
|
68
|
77
|
|
69
|
|
-/** Raised when the server is ready for use. */
|
|
78
|
+/**
|
|
79
|
+ * Raised when the server is ready for use.
|
|
80
|
+ *
|
|
81
|
+ * At this point, you should be able to freely send messages to the IRC server and can start joining channels etc, and
|
|
82
|
+ * the server state will contain relevant information about the server, its features, etc.
|
|
83
|
+ */
|
70
|
84
|
class ServerReady(metadata: EventMetadata) : IrcEvent(metadata)
|
71
|
85
|
|
72
|
86
|
/** Raised when the server initially welcomes us to the IRC network. */
|
|
@@ -108,7 +122,7 @@ class ChannelTopicMetadataDiscovered(metadata: EventMetadata, channel: String, v
|
108
|
122
|
/**
|
109
|
123
|
* Raised when a channel's topic is changed.
|
110
|
124
|
*
|
111
|
|
- * If the topic has been unset (cleared), [topic] will be `null`
|
|
125
|
+ * @property topic The new topic of the channel, or `null` if the topic has been unset (cleared)
|
112
|
126
|
*/
|
113
|
127
|
class ChannelTopicChanged(metadata: EventMetadata, override val user: User, channel: String, val topic: String?) : TargetedEvent(metadata, channel), SourcedEvent
|
114
|
128
|
|