17da8503a90c7f84787aa1ba978e2223893fa7727Alexey Samsonov// Copyright (c) 2012 The Chromium Authors. All rights reserved. 21e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany// Use of this source code is governed by a BSD-style license that can be 31e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany// found in the LICENSE file. 41e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany 51e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany#ifndef PPAPI_UTILITY_WEBSOCKET_WEBSOCKET_API_H_ 61e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany#define PPAPI_UTILITY_WEBSOCKET_WEBSOCKET_API_H_ 71e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany 81e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany#include "ppapi/c/ppb_websocket.h" 91e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany 101e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany/// @file 111e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany/// This file defines the WebSocketAPI interface. 121e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany 131e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryanynamespace pp { 141e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany 151e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryanyclass CompletionCallback; 161e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryanyclass Instance; 172d1fdb26e458c4ddc04155c1d421bced3ba90cd0Stephen Hinesclass Var; 187da8503a90c7f84787aa1ba978e2223893fa7727Alexey Samsonov 197da8503a90c7f84787aa1ba978e2223893fa7727Alexey Samsonov/// The <code>WebSocketAPI</code> class 207da8503a90c7f84787aa1ba978e2223893fa7727Alexey Samsonovclass WebSocketAPI { 217da8503a90c7f84787aa1ba978e2223893fa7727Alexey Samsonov public: 227da8503a90c7f84787aa1ba978e2223893fa7727Alexey Samsonov /// Constructs a WebSocketAPI object. 23c74b2ccbc0cf40bb401ebf3758e8e964b22acb3aKostya Serebryany explicit WebSocketAPI(Instance* instance); 242d1fdb26e458c4ddc04155c1d421bced3ba90cd0Stephen Hines 252d1fdb26e458c4ddc04155c1d421bced3ba90cd0Stephen Hines /// Destructs a WebSocketAPI object. 2638db30686c5962f8b5c877e29c6669d72198d42bKostya Serebryany virtual ~WebSocketAPI(); 2738db30686c5962f8b5c877e29c6669d72198d42bKostya Serebryany 2838db30686c5962f8b5c877e29c6669d72198d42bKostya Serebryany /// Connect() connects to the specified WebSocket server. Caller can call 2938db30686c5962f8b5c877e29c6669d72198d42bKostya Serebryany /// this method at most once. 3038db30686c5962f8b5c877e29c6669d72198d42bKostya Serebryany /// 3138db30686c5962f8b5c877e29c6669d72198d42bKostya Serebryany /// @param[in] url A <code>Var</code> of string type representing a WebSocket 3238db30686c5962f8b5c877e29c6669d72198d42bKostya Serebryany /// server URL. 332d1fdb26e458c4ddc04155c1d421bced3ba90cd0Stephen Hines /// @param[in] protocols A pointer to an array of string type 342d1fdb26e458c4ddc04155c1d421bced3ba90cd0Stephen Hines /// <code>Var</code> specifying sub-protocols. Each <code>Var</code> 352d1fdb26e458c4ddc04155c1d421bced3ba90cd0Stephen Hines /// represents one sub-protocol and its <code>PP_VarType</code> must be 362d1fdb26e458c4ddc04155c1d421bced3ba90cd0Stephen Hines /// <code>PP_VARTYPE_STRING</code>. This argument can be null only if 372d1fdb26e458c4ddc04155c1d421bced3ba90cd0Stephen Hines /// <code>protocol_count</code> is 0. 382d1fdb26e458c4ddc04155c1d421bced3ba90cd0Stephen Hines /// @param[in] protocol_count The number of sub-protocols in 3938db30686c5962f8b5c877e29c6669d72198d42bKostya Serebryany /// <code>protocols</code>. 4038db30686c5962f8b5c877e29c6669d72198d42bKostya Serebryany /// 4138db30686c5962f8b5c877e29c6669d72198d42bKostya Serebryany /// @return An int32_t containing an error code from 4238db30686c5962f8b5c877e29c6669d72198d42bKostya Serebryany /// <code>pp_errors.h</code>. 4338db30686c5962f8b5c877e29c6669d72198d42bKostya Serebryany /// See also <code>pp::WebSocket::Connect</code>. 4438db30686c5962f8b5c877e29c6669d72198d42bKostya Serebryany int32_t Connect(const Var& url, const Var protocols[], 4538db30686c5962f8b5c877e29c6669d72198d42bKostya Serebryany uint32_t protocol_count); 4638db30686c5962f8b5c877e29c6669d72198d42bKostya Serebryany 4738db30686c5962f8b5c877e29c6669d72198d42bKostya Serebryany /// Close() closes the specified WebSocket connection by specifying 482d1fdb26e458c4ddc04155c1d421bced3ba90cd0Stephen Hines /// <code>code</code> and <code>reason</code>. 4938db30686c5962f8b5c877e29c6669d72198d42bKostya Serebryany /// 5038db30686c5962f8b5c877e29c6669d72198d42bKostya Serebryany /// @param[in] code The WebSocket close code. Ignored if it is 0. 511e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany /// @param[in] reason A <code>Var</code> of string type which represents the 5238db30686c5962f8b5c877e29c6669d72198d42bKostya Serebryany /// WebSocket close reason. Ignored if it is undefined type. 5338db30686c5962f8b5c877e29c6669d72198d42bKostya Serebryany /// 5438db30686c5962f8b5c877e29c6669d72198d42bKostya Serebryany /// @return An int32_t containing an error code from 5538db30686c5962f8b5c877e29c6669d72198d42bKostya Serebryany /// <code>pp_errors.h</code>. 5638db30686c5962f8b5c877e29c6669d72198d42bKostya Serebryany /// See also <code>pp::WebSocket::Close</code>. 5738db30686c5962f8b5c877e29c6669d72198d42bKostya Serebryany int32_t Close(uint16_t code, const Var& reason); 5838db30686c5962f8b5c877e29c6669d72198d42bKostya Serebryany 5938db30686c5962f8b5c877e29c6669d72198d42bKostya Serebryany /// Send() sends a message to the WebSocket server. 6038db30686c5962f8b5c877e29c6669d72198d42bKostya Serebryany /// 6138db30686c5962f8b5c877e29c6669d72198d42bKostya Serebryany /// @param[in] data A message to send. The message is copied to internal 6238db30686c5962f8b5c877e29c6669d72198d42bKostya Serebryany /// buffer. So caller can free <code>data</code> safely after returning 6338db30686c5962f8b5c877e29c6669d72198d42bKostya Serebryany /// from the function. 6438db30686c5962f8b5c877e29c6669d72198d42bKostya Serebryany /// 6538db30686c5962f8b5c877e29c6669d72198d42bKostya Serebryany /// @return An int32_t containing an error code from 6638db30686c5962f8b5c877e29c6669d72198d42bKostya Serebryany /// <code>pp_errors.h</code>. 6738db30686c5962f8b5c877e29c6669d72198d42bKostya Serebryany /// See also <code>pp::WebSocket::SendMessage</code>. 6838db30686c5962f8b5c877e29c6669d72198d42bKostya Serebryany int32_t Send(const Var& data); 6938db30686c5962f8b5c877e29c6669d72198d42bKostya Serebryany 7038db30686c5962f8b5c877e29c6669d72198d42bKostya Serebryany /// GetBufferedAmount() returns the number of bytes of text and binary 7138db30686c5962f8b5c877e29c6669d72198d42bKostya Serebryany /// messages that have been queued for the WebSocket connection to send but 7238db30686c5962f8b5c877e29c6669d72198d42bKostya Serebryany /// have not been transmitted to the network yet. 7338db30686c5962f8b5c877e29c6669d72198d42bKostya Serebryany /// 7438db30686c5962f8b5c877e29c6669d72198d42bKostya Serebryany /// @return Returns the number of bytes. 756cbfae439b81221d2250ffe0331958f130259755Kostya Serebryany uint64_t GetBufferedAmount(); 766cbfae439b81221d2250ffe0331958f130259755Kostya Serebryany 776cbfae439b81221d2250ffe0331958f130259755Kostya Serebryany /// GetExtensions() returns the extensions selected by the server for the 786cbfae439b81221d2250ffe0331958f130259755Kostya Serebryany /// specified WebSocket connection. 796cbfae439b81221d2250ffe0331958f130259755Kostya Serebryany /// 806cbfae439b81221d2250ffe0331958f130259755Kostya Serebryany /// @return Returns a <code>Var</code> of string type. If called before the 816cbfae439b81221d2250ffe0331958f130259755Kostya Serebryany /// connection is established, its data is empty string. 826cbfae439b81221d2250ffe0331958f130259755Kostya Serebryany /// Currently its data is always an empty string. 836cbfae439b81221d2250ffe0331958f130259755Kostya Serebryany Var GetExtensions(); 846cbfae439b81221d2250ffe0331958f130259755Kostya Serebryany 85a3b0e5e4f9f48b2ed0baee10c0236eda7c21c660Kostya Serebryany /// GetProtocol() returns the sub-protocol chosen by the server for the 86a3b0e5e4f9f48b2ed0baee10c0236eda7c21c660Kostya Serebryany /// specified WebSocket connection. 87a3b0e5e4f9f48b2ed0baee10c0236eda7c21c660Kostya Serebryany /// 88a3b0e5e4f9f48b2ed0baee10c0236eda7c21c660Kostya Serebryany /// @return Returns a <code>Var</code> of string type. If called before the 89a3b0e5e4f9f48b2ed0baee10c0236eda7c21c660Kostya Serebryany /// connection is established, it contains the empty string. 90a3b0e5e4f9f48b2ed0baee10c0236eda7c21c660Kostya Serebryany Var GetProtocol(); 91a3b0e5e4f9f48b2ed0baee10c0236eda7c21c660Kostya Serebryany 92a3b0e5e4f9f48b2ed0baee10c0236eda7c21c660Kostya Serebryany /// GetReadyState() returns the ready state of the specified WebSocket 93a3b0e5e4f9f48b2ed0baee10c0236eda7c21c660Kostya Serebryany /// connection. 94a3b0e5e4f9f48b2ed0baee10c0236eda7c21c660Kostya Serebryany /// 95a3b0e5e4f9f48b2ed0baee10c0236eda7c21c660Kostya Serebryany /// @return Returns <code>PP_WEBSOCKETREADYSTATE_INVALID</code> if called 96a3b0e5e4f9f48b2ed0baee10c0236eda7c21c660Kostya Serebryany /// before connect() is called. 97a3b0e5e4f9f48b2ed0baee10c0236eda7c21c660Kostya Serebryany PP_WebSocketReadyState GetReadyState(); 98a3b0e5e4f9f48b2ed0baee10c0236eda7c21c660Kostya Serebryany 99a3b0e5e4f9f48b2ed0baee10c0236eda7c21c660Kostya Serebryany /// GetURL() returns the URL associated with specified WebSocket connection. 100a3b0e5e4f9f48b2ed0baee10c0236eda7c21c660Kostya Serebryany /// 101a3b0e5e4f9f48b2ed0baee10c0236eda7c21c660Kostya Serebryany /// @return Returns a <code>Var</code> of string type. If called before the 102af5bd2ee59a9f7bea74f43fccc6ea48979b7a4b0Kostya Serebryany /// connection is established, it contains the empty string. 103af5bd2ee59a9f7bea74f43fccc6ea48979b7a4b0Kostya Serebryany Var GetURL(); 104af5bd2ee59a9f7bea74f43fccc6ea48979b7a4b0Kostya Serebryany 105a3b0e5e4f9f48b2ed0baee10c0236eda7c21c660Kostya Serebryany /// WebSocketDidOpen() is invoked when the connection is established by 106a3b0e5e4f9f48b2ed0baee10c0236eda7c21c660Kostya Serebryany /// Connect(). 1071e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany virtual void WebSocketDidOpen() = 0; 108 109 /// WebSocketDidClose() is invoked when the connection is closed by errors or 110 /// Close(). 111 virtual void WebSocketDidClose(bool wasClean, 112 uint16_t code, 113 const Var& reason) = 0; 114 115 /// HandleWebSocketMessage() is invoked when a message is received. 116 virtual void HandleWebSocketMessage(const Var& message) = 0; 117 118 /// HandleWebSocketError() is invoked if the user agent was required to fail 119 /// the WebSocket connection or the WebSocket connection is closed with 120 /// prejudice. DidClose() always follows HandleError(). 121 virtual void HandleWebSocketError() = 0; 122 123 private: 124 class Implement; 125 Implement* impl_; 126}; 127 128} // namespace pp 129 130#endif // PPAPI_UTILITY_WEBSOCKET_WEBSOCKET_API_H_ 131