// CkWebSocketW.h: interface for the CkWebSocketW class. // ////////////////////////////////////////////////////////////////////// // This header is generated for Chilkat 11.3.0 #ifndef _CkWebSocketW_H #define _CkWebSocketW_H #include "chilkatDefs.h" #include "CkString.h" #include "CkClassWithCallbacksW.h" class CkBinDataW; class CkStringBuilderW; class CkTaskW; class CkRestW; class CkBaseProgressW; #if !defined(__sun__) && !defined(__sun) #pragma pack (push, 8) #endif // CLASS: CkWebSocketW class CK_VISIBLE_PUBLIC CkWebSocketW : public CkClassWithCallbacksW { private: bool m_cbOwned; private: // Don't allow assignment or copying these objects. CkWebSocketW(const CkWebSocketW &); CkWebSocketW &operator=(const CkWebSocketW &); public: CkWebSocketW(void); virtual ~CkWebSocketW(void); static CkWebSocketW *createNew(void); CkWebSocketW(bool bCallbackOwned); static CkWebSocketW *createNew(bool bCallbackOwned); void CK_VISIBLE_PRIVATE inject(void *impl); // May be called when finished with the object to free/dispose of any // internal resources held by the object. void dispose(void); CkBaseProgressW *get_EventCallbackObject(void) const; void put_EventCallbackObject(CkBaseProgressW *progress); // BEGIN PUBLIC INTERFACE // ---------------------- // Properties // ---------------------- // If true, then a Close control frame is automatically sent in response to // receiving a Close control frame (assuming that we did not initiate the Close in // the first place). When the Close frame has both been received and sent, the // underlying connection is automatically closed (as per the WebSocket protocol RFC // specifications). Thus, if this property is true, then two things automatically // happen when a Close frame is received: (1) a Close frame is sent in response, // and (2) the connection is closed. // // The default value of this property is true. // bool get_CloseAutoRespond(void); // If true, then a Close control frame is automatically sent in response to // receiving a Close control frame (assuming that we did not initiate the Close in // the first place). When the Close frame has both been received and sent, the // underlying connection is automatically closed (as per the WebSocket protocol RFC // specifications). Thus, if this property is true, then two things automatically // happen when a Close frame is received: (1) a Close frame is sent in response, // and (2) the connection is closed. // // The default value of this property is true. // void put_CloseAutoRespond(bool newVal); // The reason string received with the Close frame, if any. void get_CloseReason(CkString &str); // The reason string received with the Close frame, if any. const wchar_t *closeReason(void); // If true, then a Close frame was already received on this websocket connection. // If CloseAutoRespond is false, then an application can check this property // value to determine if a Close frame should be sent in response. bool get_CloseReceived(void); // The status code received with the Close frame. If no status code was provided, // or no Close frame has yet been received, then this property will be 0. int get_CloseStatusCode(void); // true if the last data frame received by calling ReadFrame was a final frame. // Otherwise false. bool get_FinalFrame(void); // The number of bytes accumulated from one or more calls to ReadFrame. Accumulated // incoming frame data can be retrieved by calling GetFrameData, GetFrameDataSb, or // GetFrameDataBd. int get_FrameDataLen(void); // Indicates the type of frame received in the last call to ReadFrame. Possible // values are Continuation , Text , Binary , Close , Ping , or Pong . Initially // this property is set to the empty string because nothing has yet been received. void get_FrameOpcode(CkString &str); // Indicates the type of frame received in the last call to ReadFrame. Possible // values are Continuation , Text , Binary , Close , Ping , or Pong . Initially // this property is set to the empty string because nothing has yet been received. const wchar_t *frameOpcode(void); // The integer value of the opcode (type of frame) received in the last call to // ReadFrame. Possible values are:0 - Continuation // 1 - Text // 2 - Binary // 8 - Close // 9 - Ping // 10 - Pong int get_FrameOpcodeInt(void); // The interval in milliseconds between each AbortCheck event callback, which // enables an application to abort certain method calls before they complete. By // default, HeartbeatMs is set to 0 , meaning no AbortCheck event callbacks will // trigger. // // References: // 1: #AbortCheck int get_HeartbeatMs(void); // The interval in milliseconds between each AbortCheck event callback, which // enables an application to abort certain method calls before they complete. By // default, HeartbeatMs is set to 0 , meaning no AbortCheck event callbacks will // trigger. // // References: // 1: #AbortCheck void put_HeartbeatMs(int newVal); // The maximum amount of time to wait for additional incoming data when receiving, // or the max time to wait to send additional data. The default value is 30000 (30 // seconds). This is not an overall max timeout. Rather, it is the maximum time to // wait when receiving or sending has halted. int get_IdleTimeoutMs(void); // The maximum amount of time to wait for additional incoming data when receiving, // or the max time to wait to send additional data. The default value is 30000 (30 // seconds). This is not an overall max timeout. Rather, it is the maximum time to // wait when receiving or sending has halted. void put_IdleTimeoutMs(int newVal); // Returns true if the websocket is connected. Otherwise returns false. bool get_IsConnected(void); // If true, then a Ping frame was received, but no Pong frame has yet been sent // in response. The application should send a Pong frame by calling SendPong as // soon as possible. bool get_NeedSendPong(void); // If true, then a Pong frame is automatically sent when a Ping frame is // received. If set to false, then the application may check the NeedSendPong // property to determine if a Pong response is needed, and if so, may call the // SendPong method to send a Pong. // // Note: If this property is true, then the ReadFrame method will auto-consume // incoming Ping frames. In other words, ReadFrame will continue with reading the // next incoming frame (thus Ping frames will never be returned to the // application). This relieves the application from having to worry about receiving // and handling spurious Ping frames. // // The default value is true. // bool get_PingAutoRespond(void); // If true, then a Pong frame is automatically sent when a Ping frame is // received. If set to false, then the application may check the NeedSendPong // property to determine if a Pong response is needed, and if so, may call the // SendPong method to send a Pong. // // Note: If this property is true, then the ReadFrame method will auto-consume // incoming Ping frames. In other words, ReadFrame will continue with reading the // next incoming frame (thus Ping frames will never be returned to the // application). This relieves the application from having to worry about receiving // and handling spurious Ping frames. // // The default value is true. // void put_PingAutoRespond(bool newVal); // If true, then incoming Pong frames are automatically consumed, and a call to // ReadFrame will continue reading until it receives a non-Pong frame. The // PongConsumed property can be checked to see if the last ReadFrame method call // auto-consumed a Pong frame. // // The default value is true. // bool get_PongAutoConsume(void); // If true, then incoming Pong frames are automatically consumed, and a call to // ReadFrame will continue reading until it receives a non-Pong frame. The // PongConsumed property can be checked to see if the last ReadFrame method call // auto-consumed a Pong frame. // // The default value is true. // void put_PongAutoConsume(bool newVal); // Is true if the last call to ReadFrame auto-consumed a Pong frame. This // property is reset to false each time a ReadFrame method is called, and will // get set to true if (1) the PongAutoConsume property is true and (2) a Pong // frame was consumed within the ReadFrame method. // // The purpose of PongAutoConsume and PongConsumed is to eliminate the concern for // unanticipated Pong frames in the stream. In the websocket protocol, both sides // (client and server) may send Pong frames at any time. In addition, if a Ping // frame is sent, the corresponding Pong response frame can arrive at some // unanticipated point later in the conversation. It's also possible, if several // Ping frames are sent, that a Pong response frame is only sent for the most // recent Ping frame. The default behavior of Chilkat's WebSocket API is to // auto-consume incoming Pong frames and set this property to true. This allows // the application to call a ReadFrame method for whatever application data frame // it may be expecting, without needing to be concerned if the next incoming frame // is a Pong frame. // bool get_PongConsumed(void); // If the ReadFrame method returns false, this property holds the fail reason. It // can have one of the following values:0 - No failure. // 1 - Read Timeout. // 2 - Aborted by Application Callback. // 3 - Fatal Socket Error (Lost Connection). // 4 - Received invalid WebSocket frame bytes. // 99 - A catch-all for any unknown failure. (Should not ever occur. If it does, contact Chilkat.) int get_ReadFrameFailReason(void); // This is a catch-all property to be used for uncommon needs. This property // defaults to the empty string and should typically remain empty. Can be set to a // list of the following comma separated keywords: // * ProtectFromVpn - Introduced in v9.5.0.80. On Android systems, will bypass // any VPN that may be installed or active. void get_UncommonOptions(CkString &str); // This is a catch-all property to be used for uncommon needs. This property // defaults to the empty string and should typically remain empty. Can be set to a // list of the following comma separated keywords: // * ProtectFromVpn - Introduced in v9.5.0.80. On Android systems, will bypass // any VPN that may be installed or active. const wchar_t *uncommonOptions(void); // ---------------------- // Methods // ---------------------- // Adds the required WebSocket client-side open handshake headers. The headers // specifically added to the previously specified REST object (in the call to // UseConnection) are:Upgrade: websocket // Connection: Upgrade // Sec-WebSocket-Key: ... // Sec-WebSocket-Version: 13 bool AddClientHeaders(void); // Forcibly closes the underlying connection. This is a non-clean way to close the // connection, but may be used if needed. The clean way to close a websocket is to // send a Close frame, and then receive the Close response. bool CloseConnection(void); // Returns the accumulated received frame data as a string. Calling GetFrameData // clears the internal receive buffer. bool GetFrameData(CkString &outStr); // Returns the accumulated received frame data as a string. Calling GetFrameData // clears the internal receive buffer. const wchar_t *getFrameData(void); // Returns the accumulated received frame data as a string. Calling GetFrameData // clears the internal receive buffer. const wchar_t *frameData(void); // Returns the accumulated received frame data in a BinData object. The received // data is appended to the binData. // // Calling this method clears the internal receive buffer. // bool GetFrameDataBd(CkBinDataW &binData); // Returns the accumulated received frame data in a StringBuilder object. The // received data is appended to the sb. // // Calling this method clears the internal receive buffer. // bool GetFrameDataSb(CkStringBuilderW &sb); // Loads the caller of the task's async method. bool LoadTaskCaller(CkTaskW &task); // Check to see if data is available for reading on the websocket. Returns true // if data is waiting and false if no data is waiting to be read. bool PollDataAvailable(void); // Reads a single frame from the connected websocket. If a frame was successfuly // received, then the following properties are set: FrameOpcode, FrameDataLen, // FinalFrame, and the received frame data can be retrieved by calling // GetFrameData, GetFrameDataSb, or GetFrameDataBd. bool ReadFrame(void); // Creates an asynchronous task to call the ReadFrame method with the arguments // provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *ReadFrameAsync(void); // Sends a Close control frame. If includeStatus is true, then the statusCode is sent in the // application data part of the Close frame. A Close reason may be provided only if // includeStatus is true. If this Close was sent to satisfy an already-received Close // frame, then the underlying connection will also automatically be closed. // // Note: If a status code and reason are provided, the utf-8 representation of the // reason string must be 123 bytes or less. Chilkat will automatically truncate the // reason to 123 bytes if necessary. Also, the status code must be an integer in the // range 0 to 16383. // // The WebSocket protocol specifies some pre-defined status codes at WebSocket // Status Codes. For a normal closure, a status code value of 1000 should be used. // The reason can be any string, as long as it is 123 bytes or less. // // // References: // 1: https://tools.ietf.org/html/rfc6455#section-7.4.1 bool SendClose(bool includeStatus, int statusCode, const wchar_t *reason); // Creates an asynchronous task to call the SendClose method with the arguments // provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *SendCloseAsync(bool includeStatus, int statusCode, const wchar_t *reason); // Sends a single data frame containing a string. If this is the final frame in a // message, then finalFrame should be set to true. Otherwise set finalFrame equal to false. bool SendFrame(const wchar_t *stringToSend, bool finalFrame); // Creates an asynchronous task to call the SendFrame method with the arguments // provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *SendFrameAsync(const wchar_t *stringToSend, bool finalFrame); // Sends a single data frame containing binary data (the contents of bdToSend). If this // is the final frame in a message, then finalFrame should be set to true. Otherwise // set finalFrame equal to false. bool SendFrameBd(CkBinDataW &bdToSend, bool finalFrame); // Creates an asynchronous task to call the SendFrameBd method with the arguments // provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *SendFrameBdAsync(CkBinDataW &bdToSend, bool finalFrame); // Sends a single data frame containing a string (the contents of sbToSend). If this is // the final frame in a message, then finalFrame should be set to true. Otherwise set // finalFrame equal to false. bool SendFrameSb(CkStringBuilderW &sbToSend, bool finalFrame); // Creates an asynchronous task to call the SendFrameSb method with the arguments // provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *SendFrameSbAsync(CkStringBuilderW &sbToSend, bool finalFrame); // Sends a Ping control frame, optionally including text data. If pingData is // non-empty, the utf-8 representation of the string must be 125 bytes or less. // Chilkat will automatically truncate the pingData to 125 bytes if necessary. bool SendPing(const wchar_t *pingData); // Creates an asynchronous task to call the SendPing method with the arguments // provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *SendPingAsync(const wchar_t *pingData); // Sends a Pong control frame. If this Pong frame is sent to satisfy an // unresponded-to Ping frame, then the previously received Ping data is // automatically sent in this Pong frame. bool SendPong(void); // Creates an asynchronous task to call the SendPong method with the arguments // provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *SendPongAsync(void); // The caller will share ws's existing websocket connection, enabling // multi-threaded applications to read and write to the websocket simultaneously. // The provided C++ and C# examples illustrate this concept, which you can adapt to // your programming language. bool ShareConnection(CkWebSocketW &ws); // Initializes the connection for a WebSocket session. All WebSocket sessions begin // with a call to UseConnection. A Chilkat REST object is used for the connection // because the WebSocket handshake begins with an HTTP GET request. The Chilkat // REST API provides the ability to add custom headers, authentication, etc. to the // opening GET handshake. It also provides the ability to establish connections // over TLS or SSH and to benefit from the rich set of features already present // relating to HTTP proxies, SOCKS proxies, bandwidth throttling, IPv6, socket // options, etc. bool UseConnection(CkRestW &connection); // Called after sending the opening handshake from the Rest object. Validates the // server's response to the opening handshake message. If validation is successful, // the application may begin sending and receiving data and control frames. bool ValidateServerHandshake(void); // END PUBLIC INTERFACE }; #if !defined(__sun__) && !defined(__sun) #pragma pack (pop) #endif #endif