1 /* 2 * Copyright (C) 2023 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup netstack 18 * @{ 19 * 20 * @brief Provides C APIs for the websocket client module. 21 22 * @since 11 23 * @version 1.0 24 */ 25 26 /** 27 * @file net_websocket.h 28 * 29 * @brief Defines the APIs for the websocket client module. 30 * 31 * @library libnet_websocket.so 32 * @kit NetworkKit 33 * @syscap SystemCapability.Communication.NetStack 34 * @since 11 35 * @version 1.0 36 */ 37 38 #ifndef NET_WEBSOCKET_H 39 #define NET_WEBSOCKET_H 40 41 #include <signal.h> 42 #include <stdint.h> 43 #include <string.h> 44 45 #include "net_websocket_type.h" 46 47 #ifdef __cplusplus 48 extern "C" { 49 #endif 50 51 /** 52 * @brief Constructor of websocket. 53 * 54 * @param onOpen Callback function invoked when a connection setup message is received. 55 * @param onMessage Callback function invoked when a message is received. 56 * @param onError Callback function invoked when a connection error message is received. 57 * @param onclose Callback function invoked when a connection closing message is closed. 58 * 59 * @return Pointer to the websocket client if success; NULL otherwise. 60 * @syscap SystemCapability.Communication.NetStack 61 * @since 11 62 * @version 1.0 63 */ 64 struct WebSocket *OH_WebSocketClient_Constructor(WebSocket_OnOpenCallback onOpen, WebSocket_OnMessageCallback onMessage, 65 WebSocket_OnErrorCallback onError, WebSocket_OnCloseCallback onclose); 66 67 /** 68 * @brief Adds the header information to the client request. 69 * 70 * @param client Pointer to the websocket client. 71 * @param header Header information 72 * @return 0 if success; non-0 otherwise. For details about error codes, see {@link OH_Websocket_ErrCode}. 73 * @syscap SystemCapability.Communication.NetStack 74 * @since 11 75 * @version 1.0 76 */ 77 int OH_WebSocketClient_AddHeader(struct WebSocket *client, struct WebSocket_Header header); 78 79 /** 80 * @brief Connects the client to the server. 81 * 82 * @param client Pointer to the websocket client. 83 * @param url URL for the client to connect to the server. 84 * @param options Optional parameters. 85 * @return 0 if success; non-0 otherwise. For details about error codes, see {@link OH_Websocket_ErrCode}. 86 * @permission ohos.permission.INTERNET 87 * @syscap SystemCapability.Communication.NetStack 88 * @since 11 89 * @version 1.0 90 */ 91 int OH_WebSocketClient_Connect(struct WebSocket *client, const char *url, struct WebSocket_RequestOptions options); 92 93 /** 94 * @brief Sends data from the client to the server. 95 * 96 * @param client Pointer to the websocket client. 97 * @param data Data sent by the client. 98 * @param length Length of the data sent by the client. 99 * @return 0 if success; non-0 otherwise. For details about error codes, see {@link OH_Websocket_ErrCode}. 100 * @permission ohos.permission.INTERNET 101 * @syscap SystemCapability.Communication.NetStack 102 * @since 11 103 * @version 1.0 104 */ 105 int OH_WebSocketClient_Send(struct WebSocket *client, char *data, size_t length); 106 107 /** 108 * @brief Closes a webSocket connection. 109 * 110 * @param client Pointer to the websocket client. 111 * @param options Optional parameters. 112 * @return 0 if success; non-0 otherwise. For details about error codes, see {@link OH_Websocket_ErrCode}. 113 * @permission ohos.permission.INTERNET 114 * @syscap SystemCapability.Communication.NetStack 115 * @since 11 116 * @version 1.0 117 */ 118 int OH_WebSocketClient_Close(struct WebSocket *client, struct WebSocket_CloseOption options); 119 120 /** 121 * @brief Releases the context and resources of the websocket connection. 122 * 123 * @param client Pointer to the websocket client. 124 * @return 0 if success; non-0 otherwise. For details about error codes, see {@link OH_Websocket_ErrCode}. 125 * @permission ohos.permission.INTERNET 126 * @syscap SystemCapability.Communication.NetStack 127 * @since 11 128 * @version 1.0 129 */ 130 int OH_WebSocketClient_Destroy(struct WebSocket *client); 131 132 #ifdef __cplusplus 133 } 134 #endif 135 136 /** @} */ 137 #endif // NET_WEBSOCKET_H 138