• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# net_websocket.h
2
3## Overview
4
5Defines the WebSocket client module APIs.
6
7**File to include**: <network/netstack/net_websocket.h>
8
9**Library**: libnet_websocket.so
10
11**System capability**: SystemCapability.Communication.NetStack
12
13**Since**: 11
14
15**Related module**: [netstack](capi-netstack.md)
16
17## Summary
18
19### Functions
20
21| Name| Description|
22| -- | -- |
23| [struct WebSocket *OH_WebSocketClient_Constructor(WebSocket_OnOpenCallback onOpen, WebSocket_OnMessageCallback onMessage,WebSocket_OnErrorCallback onError, WebSocket_OnCloseCallback onclose)](#oh_websocketclient_constructor) | Constructor used to create a WebSocket client.|
24| [int OH_WebSocketClient_AddHeader(struct WebSocket *client, struct WebSocket_Header header)](#oh_websocketclient_addheader) | Adds the header information to the client request.|
25| [int OH_WebSocketClient_Connect(struct WebSocket *client, const char *url, struct WebSocket_RequestOptions options)](#oh_websocketclient_connect) | Connects the WebSocket client to the server.|
26| [int OH_WebSocketClient_Send(struct WebSocket *client, char *data, size_t length)](#oh_websocketclient_send) | Sends data from the WebSocket client to the server.|
27| [int OH_WebSocketClient_Close(struct WebSocket *client, struct WebSocket_CloseOption options)](#oh_websocketclient_close) | Closes the connection on the WebSocket client.|
28| [int OH_WebSocketClient_Destroy(struct WebSocket *client)](#oh_websocketclient_destroy) | Destorys the WebSocket client and releases the context and resources of the WebSocket connection.|
29
30## Function Description
31
32### OH_WebSocketClient_Constructor()
33
34```
35struct WebSocket *OH_WebSocketClient_Constructor(WebSocket_OnOpenCallback onOpen, WebSocket_OnMessageCallback onMessage,WebSocket_OnErrorCallback onError, WebSocket_OnCloseCallback onclose)
36```
37
38**Description**
39
40Constructor used to create a WebSocket client.
41
42**System capability**: SystemCapability.Communication.NetStack
43
44**Since**: 11
45
46
47**Parameters**
48
49| Name| Description|
50| -- | -- |
51| [WebSocket_OnOpenCallback](capi-net-websocket-type-h.md#websocket_onopencallback) onOpen |    Callback invoked when the WebSocket client receives an **open** message.|
52| [WebSocket_OnMessageCallback](capi-net-websocket-type-h.md#websocket_onmessagecallback) onMessage | Callback invoked when the WebSocket client receives a **Message** message.|
53| [WebSocket_OnErrorCallback](capi-net-websocket-type-h.md#websocket_onerrorcallback) onError |   Callback invoked when the WebSocket client receives an **error** message.|
54| [WebSocket_OnCloseCallback](capi-net-websocket-type-h.md#websocket_onclosecallback) onclose |   Callback invoked when the WebSocket client receives a **close** message.|
55
56**Returns**
57
58| Type                    | Description|
59|------------------------| -- |
60| [struct WebSocket](capi-netstack-websocket.md) * | Pointer to the WebSocket client if the operation is successful; **NULL** otherwise.|
61
62### OH_WebSocketClient_AddHeader()
63
64```
65int OH_WebSocketClient_AddHeader(struct WebSocket *client, struct WebSocket_Header header)
66```
67
68**Description**
69
70Adds the header information to the client request.
71
72**System capability**: SystemCapability.Communication.NetStack
73
74**Since**: 11
75
76
77**Parameters**
78
79| Name| Description|
80| -- | -- |
81| [struct WebSocket](capi-netstack-websocket.md) *client | Pointer to the WebSocket client.|
82| [struct WebSocket_Header](capi-netstack-websocket-header.md) header | Header information.|
83
84**Returns**
85
86| Type| Description|
87| -- | -- |
88| int | **0** if the operation is successful; a non-0 value otherwise. For details about the return values, see **OH_Websocket_ErrCode**.|
89
90### OH_WebSocketClient_Connect()
91
92```
93int OH_WebSocketClient_Connect(struct WebSocket *client, const char *url, struct WebSocket_RequestOptions options)
94```
95
96**Description**
97
98Connects the WebSocket client to the server.
99
100**System capability**: SystemCapability.Communication.NetStack
101
102**Required permission**: ohos.permission.INTERNET
103
104**Since**: 11
105
106
107**Parameters**
108
109| Name| Description|
110| -- | -- |
111| [struct WebSocket](capi-netstack-websocket.md) *client | Pointer to the WebSocket client.|
112| const char *url | IP address for the WebSocket client to connect to the server.|
113| [struct WebSocket_RequestOptions](capi-netstack-websocket-requestoptions.md) options | Optional parameters for connection establishment.|
114
115**Returns**
116
117| Type| Description|
118| -- | -- |
119| int | **0** if the operation is successful; a non-0 value otherwise. For details about the return values, see **OH_Websocket_ErrCode**.|
120
121### OH_WebSocketClient_Send()
122
123```
124int OH_WebSocketClient_Send(struct WebSocket *client, char *data, size_t length)
125```
126
127**Description**
128
129Sends data from the WebSocket client to the server.
130
131**System capability**: SystemCapability.Communication.NetStack
132
133**Required permission**: ohos.permission.INTERNET
134
135**Since**: 11
136
137
138**Parameters**
139
140| Name| Description|
141| -- | -- |
142| [struct WebSocket](capi-netstack-websocket.md) *client | WebSocket client.|
143| char *data |   Data sent by the WebSocket client.|
144| size_t length | Length of the data sent by the WebSocket client.|
145
146**Returns**
147
148| Type| Description|
149| -- | -- |
150| int | **0** if the operation is successful; a non-0 value otherwise. For details about the return values, see **OH_Websocket_ErrCode**.|
151
152### OH_WebSocketClient_Close()
153
154```
155int OH_WebSocketClient_Close(struct WebSocket *client, struct WebSocket_CloseOption options)
156```
157
158**Description**
159
160Lets the WebSocket client proactively close the connection.
161
162**System capability**: SystemCapability.Communication.NetStack
163
164**Required permission**: ohos.permission.INTERNET
165
166**Since**: 11
167
168
169**Parameters**
170
171| Name| Description|
172| -- | -- |
173| [struct WebSocket](capi-netstack-websocket.md) *client | WebSocket client.|
174| [struct WebSocket_CloseOption](capi-netstack-websocket-closeoption.md) options | Optional parameters for connection closure.|
175
176**Returns**
177
178| Type| Description|
179| -- | -- |
180| int | **0** if the operation is successful; a non-0 value otherwise. For details about the return values, see **OH_Websocket_ErrCode**.|
181
182### OH_WebSocketClient_Destroy()
183
184```
185int OH_WebSocketClient_Destroy(struct WebSocket *client)
186```
187
188**Description**
189
190Destorys the WebSocket client and releases the context and resources of the WebSocket connection.
191
192**System capability**: SystemCapability.Communication.NetStack
193
194**Required permission**: ohos.permission.INTERNET
195
196**Since**: 11
197
198
199**Parameters**
200
201| Name| Description|
202| -- | -- |
203| [struct WebSocket](capi-netstack-websocket.md) *client | WebSocket client.|
204
205**Returns**
206
207| Type| Description|
208| -- | -- |
209| int | **0** if the operation is successful; a non-0 value otherwise. For details about the return values, see **OH_Websocket_ErrCode**.|
210