0
# Plugin Configuration
1

2
WebSocket plugin installation and configuration including ping intervals, frame size limits, content converters, and extension support.
3

4
## Required Imports
5

6
```kotlin
7
import io.ktor.client.*
8
import io.ktor.client.plugins.websocket.*
9
import kotlin.time.Duration
10
import kotlin.time.Duration.Companion.seconds
11
```
12

13
## Capabilities
14

15
### Plugin Installation
16

17
Install the WebSockets plugin in your HttpClient configuration.
18

19
```kotlin { .api }
20
/**
21
 * Installs the WebSockets plugin using the provided configuration block
22
 * @param config Configuration block for setting up WebSocket options
23
 */
24
fun HttpClientConfig<*>.WebSockets(config: WebSockets.Config.() -> Unit)
25
```
26

27
**Usage Examples:**
28

29
```kotlin
30
val client = HttpClient {
31
    install(WebSockets) {
32
        pingInterval = 30.seconds
33
        maxFrameSize = 1024 * 1024 // 1MB
34
    }
35
}
36

37
// Or using the configuration function
38
val client = HttpClient {
39
    WebSockets {
40
        pingInterval = 30.seconds
41
        maxFrameSize = 1024 * 1024
42
    }
43
}
44
```
45

46
### WebSockets Plugin Class
47

48
The main plugin class containing configuration and behavior.
49

50
```kotlin { .api }
51
/**
52
 * Client WebSocket plugin providing WebSocket communication capabilities
53
 * @param pingIntervalMillis Interval between ping messages in milliseconds
54
 * @param maxFrameSize Maximum size of a single WebSocket frame in bytes
55
 * @param contentConverter Optional converter for serialization/deserialization
56
 */
57
class WebSockets(
58
    val pingIntervalMillis: Long,
59
    val maxFrameSize: Long,
60
    val contentConverter: WebsocketContentConverter? = null
61
) {
62
    constructor()
63
    constructor(pingIntervalMillis: Long, maxFrameSize: Long)
64
    
65
    companion object Plugin : HttpClientPlugin<Config, WebSockets>
66
}
67
```
68

69
### Duration-Based Constructor
70

71
Create WebSockets instance with Duration-based ping configuration.
72

73
```kotlin { .api }
74
/**
75
 * Creates WebSockets plugin instance with Duration-based ping interval
76
 * @param pingInterval Interval between ping messages, null to disable
77
 * @param maxFrameSize Maximum frame size in bytes
78
 * @return Configured WebSockets instance
79
 */
80
fun WebSockets(
81
    pingInterval: Duration?,
82
    maxFrameSize: Long = Int.MAX_VALUE.toLong()
83
): WebSockets
84
```
85

86
### Configuration Class
87

88
Configuration options for the WebSockets plugin.
89

90
```kotlin { .api }
91
/**
92
 * Configuration class for WebSockets plugin
93
 */
94
class Config {
95
    /** Ping interval in milliseconds, use PINGER_DISABLED to disable */
96
    var pingIntervalMillis: Long
97
    
98
    /** Ping interval as Duration, null to disable pinger */
99
    var pingInterval: Duration?
100
    
101
    /** Maximum frame size in bytes */
102
    var maxFrameSize: Long
103
    
104
    /** Content converter for serialization/deserialization */
105
    var contentConverter: WebsocketContentConverter?
106
    
107
    /**
108
     * Configure WebSocket extensions
109
     * @param block Configuration block for WebSocket extensions
110
     */
111
    fun extensions(block: WebSocketExtensionsConfig.() -> Unit)
112
}
113
```
114

115
**Usage Examples:**
116

117
```kotlin
118
install(WebSockets) {
119
    // Set ping interval using Duration
120
    pingInterval = 20.seconds
121
    
122
    // Set ping interval using milliseconds
123
    pingIntervalMillis = 20000L
124
    
125
    // Disable ping
126
    pingInterval = null
127
    // or
128
    pingIntervalMillis = PINGER_DISABLED
129
    
130
    // Set maximum frame size
131
    maxFrameSize = 1024 * 1024 // 1MB
132
    
133
    // Configure content converter
134
    contentConverter = KotlinxWebsocketSerializationConverter(Json)
135
    
136
    // Configure extensions
137
    extensions {
138
        // Extension configuration
139
    }
140
}
141
```
142

143
### Extension Properties
144

145
Additional properties for convenient configuration.
146

147
```kotlin { .api }
148
/**
149
 * Gets ping interval as Duration from WebSockets instance
150
 * @return Duration or null if ping is disabled
151
 */
152
val WebSockets.pingInterval: Duration?
153

154
/**
155
 * Sets/gets ping interval as Duration in WebSockets configuration
156
 */
157
var WebSockets.Config.pingInterval: Duration?
158
```
159

160
## Constants
161

162
### Ping Configuration
163

164
```kotlin { .api }
165
/**
166
 * Constant indicating ping is disabled
167
 */
168
const val PINGER_DISABLED: Long = 0
169
```
170

171
## Engine Capabilities
172

173
### WebSocket Support Indicators
174

175
```kotlin { .api }
176
/**
177
 * Indicates if a client engine supports WebSockets
178
 */
179
data object WebSocketCapability : HttpClientEngineCapability<Unit>
180

181
/**
182
 * Indicates if a client engine supports WebSocket extensions
183
 */
184
data object WebSocketExtensionsCapability : HttpClientEngineCapability<Unit>
185
```
186

187
## Configuration Examples
188

189
### Basic Configuration
190

191
```kotlin
192
val client = HttpClient {
193
    install(WebSockets)
194
}
195
```
196

197
### Advanced Configuration
198

199
```kotlin
200
val client = HttpClient {
201
    install(WebSockets) {
202
        // Enable ping every 30 seconds
203
        pingInterval = 30.seconds
204
        
205
        // Set max frame size to 1MB
206
        maxFrameSize = 1024 * 1024
207
        
208
        // Add content converter for JSON serialization
209
        contentConverter = KotlinxWebsocketSerializationConverter(Json {
210
            prettyPrint = true
211
            ignoreUnknownKeys = true
212
        })
213
        
214
        // Configure extensions if needed
215
        extensions {
216
            // Extension-specific configuration
217
        }
218
    }
219
}
220
```
221

222
### Platform-Specific Notes
223

224
For iOS x64 applications, the WebSocket implementation uses the native iOS WebSocket capabilities optimized for iOS simulator environments. The configuration options work identically across all platforms, with platform-specific optimizations handled internally.