From e0aa9cf5d4555c8d4f8898611ab175ca5bed5c9b Mon Sep 17 00:00:00 2001 From: "jond@google.com" Date: Tue, 27 Mar 2012 19:11:49 +0000 Subject: Cleaned up documentation (standard documentation rewrite). Review URL: http://codereview.chromium.org/9813011 git-svn-id: svn://svn.chromium.org/chrome/trunk/src@129236 0039d316-1c4b-4281-b951-d872f2087c98 --- ppapi/cpp/websocket.h | 139 +++++++++++++++++++++++++++++--------------------- 1 file changed, 82 insertions(+), 57 deletions(-) (limited to 'ppapi/cpp/websocket.h') diff --git a/ppapi/cpp/websocket.h b/ppapi/cpp/websocket.h index dce2330..8a4d6f4 100644 --- a/ppapi/cpp/websocket.h +++ b/ppapi/cpp/websocket.h @@ -9,7 +9,8 @@ #include "ppapi/cpp/resource.h" /// @file -/// This file defines the WebSocket interface. +/// This file defines the WebSocket interface providing bi-directional, +/// full-duplex, communications over a single TCP socket. namespace pp { @@ -17,7 +18,8 @@ class CompletionCallback; class InstanceHandle; class Var; -/// The WebSocket class +/// The WebSocket class providing bi-directional, +/// full-duplex, communications over a single TCP socket. class WebSocket : public Resource { public: /// Constructs a WebSocket object. @@ -29,104 +31,119 @@ class WebSocket : public Resource { /// Destructs a WebSocket object. virtual ~WebSocket(); - /// Connect() connects to the specified WebSocket server. Caller can call - /// this method at most once. + /// Connect() connects to the specified WebSocket server. You can call this + /// function once for an object. /// /// @param[in] url A Var of string type representing a WebSocket /// server URL. - /// @param[in] protocols A pointer to an array of string type - /// Var specifying sub-protocols. Each Var - /// represents one sub-protocol. This argument can be null only if + /// + /// @param[in] protocols A pointer to an array of Var of string + /// type specifying sub-protocols. Each Var represents one + /// sub-protocol. This argument can be null only if /// protocol_count is 0. + /// /// @param[in] protocol_count The number of sub-protocols in /// protocols. - /// @param[in] callback A CompletionCallback which is called + /// + /// @param[in] callback A CompletionCallback called /// when a connection is established or an error occurs in establishing /// connection. /// /// @return An int32_t containing an error code from /// pp_errors.h. /// Returns PP_ERROR_BADARGUMENT if specified url, - /// or protocols contains invalid string as - /// The WebSocket API specification defines. It corresponds to - /// SyntaxError of the specification. + /// or protocols contains invalid string as defined in + /// the WebSocket API specification. PP_ERROR_BADARGUMENT + /// corresponds to a SyntaxError in the WebSocket API specification. /// Returns PP_ERROR_NOACCESS if the protocol specified in the /// url is not a secure protocol, but the origin of the caller - /// has a secure scheme. Also returns it if the port specified in the - /// url is a port to which the user agent is configured to block - /// access because the port is a well-known port like SMTP. It corresponds to - /// SecurityError of the specification. - /// Returns PP_ERROR_INPROGRESS if the call is not the first - /// time. + /// has a secure scheme. Also returns PP_ERROR_NOACCESS if the + /// port specified in the url is a port that the user agent is + /// configured to block access to because it is a well-known port like SMTP. + /// PP_ERROR_NOACCESS corresponds to a SecurityError of the + /// specification. + /// Returns PP_ERROR_INPROGRESS if this is not the first call to + /// Connect(). int32_t Connect(const Var& url, const Var protocols[], uint32_t protocol_count, const CompletionCallback& callback); /// Close() closes the specified WebSocket connection by specifying /// code and reason. /// - /// @param[in] code The WebSocket close code. Ignored if it is 0. - /// @param[in] reason A Var of string type which represents the - /// WebSocket close reason. Ignored if it is undefined type. - /// @param[in] callback A CompletionCallback which is called - /// when the connection is closed or an error occurs in closing the - /// connection. + /// @param[in] code The WebSocket close code. This is ignored if it is 0. + /// PP_WEBSOCKETSTATUSCODE_NORMAL_CLOSURE must be used for the + /// usual case. To indicate some specific error cases, codes in the range + /// PP_WEBSOCKETSTATUSCODE_USER_REGISTERED_MIN to + /// PP_WEBSOCKETSTATUSCODE_USER_REGISTERED_MAX, and in the range + /// PP_WEBSOCKETSTATUSCODE_USER_PRIVATE_MIN to + /// PP_WEBSOCKETSTATUSCODE_USER_PRIVATE_MAX are available. + /// + /// @param[in] reason A Var of string type representing the + /// close reason. This is ignored if it is an undefined type. + /// + /// @param[in] callback A CompletionCallback called when the + /// connection is closed or an error occurs in closing the connection. /// /// @return An int32_t containing an error code from /// pp_errors.h. /// Returns PP_ERROR_BADARGUMENT if reason contains - /// an invalid character as a UTF-8 string, or longer than 123 bytes. It - /// corresponds to JavaScript SyntaxError of the specification. + /// an invalid character as a UTF-8 string, or is longer than 123 bytes. + /// PP_ERROR_BADARGUMENT corresponds to a JavaScript + /// SyntaxError in the WebSocket API specification. /// Returns PP_ERROR_NOACCESS if the code is not an integer - /// equal to 1000 or in the range 3000 to 4999. It corresponds to - /// InvalidAccessError of the specification. Returns - /// PP_ERROR_INPROGRESS if the call is not the first time. + /// equal to 1000 or in the range 3000 to 4999. + /// PP_ERROR_NOACCESS corresponds to an InvalidAccessError in + /// the WebSocket API specification. Returns PP_ERROR_INPROGRESS + /// if this is not the first call to Close(). int32_t Close(uint16_t code, const Var& reason, const CompletionCallback& callback); /// ReceiveMessage() receives a message from the WebSocket server. /// This interface only returns a single message. That is, this interface - /// must be called at least N times to receive N messages, no matter how - /// small each message is. + /// must be called at least N times to receive N messages, no matter the size + /// of each message. /// /// @param[out] message The received message is copied to provided /// message. The message must remain valid until - /// the ReceiveMessage operation completes. It will be a Var of - /// string or ArrayBuffer types on receiving. - /// @param[in] callback A CompletionCallback which is called - /// when the receiving message is completed. It is ignored if ReceiveMessage + /// ReceiveMessage() completes. Its received Var will be of + /// string or ArrayBuffer type. + /// + /// @param[in] callback A CompletionCallback called when + /// ReceiveMessage() completes. This callback is ignored if ReceiveMessage() /// completes synchronously and returns PP_OK. /// /// @return An int32_t containing an error code from /// pp_errors.h. - /// If an error is detected or connection is closed, returns + /// If an error is detected or connection is closed, ReceiveMessage() returns /// PP_ERROR_FAILED after all buffered messages are received. - /// Until buffered message become empty, continues to returns + /// Until buffered message become empty, ReceiveMessage() continues to return /// PP_OK as if connection is still established without errors. int32_t ReceiveMessage(Var* message, const CompletionCallback& callback); - /// Send() sends a message to the WebSocket server. + /// SendMessage() sends a message to the WebSocket server. /// - /// @param[in] data A message to send. The message is copied to internal - /// buffer. So caller can free data safely after returning - /// from the function. It must be a Var of string or ArrayBuffer - /// types. + /// @param[in] message A message to send. The message is copied to an internal + /// buffer, so the caller can free message safely after returning + /// from the function. This Var must be of string or + /// ArrayBuffer types. /// /// @return An int32_t containing an error code from /// pp_errors.h. /// Returns PP_ERROR_FAILED if the ReadyState is - /// PP_WEBSOCKETREADYSTATE_CONNECTING. It corresponds JavaScript - /// InvalidStateError of the specification. - /// Returns PP_ERROR_BADARGUMENT if provided - /// message of string type contains an invalid character as a - /// UTF-8 string. It corresponds to JavaScript SyntaxError of the - /// specification. + /// PP_WEBSOCKETREADYSTATE_CONNECTING. + /// PP_ERROR_FAILED corresponds to a JavaScript + /// InvalidStateError in the WebSocket API specification. + /// Returns PP_ERROR_BADARGUMENT if the provided + /// message contains an invalid character as a + /// UTF-8 string. PP_ERROR_BADARGUMENT corresponds to a + /// JavaScript SyntaxError in the WebSocket API specification. /// Otherwise, returns PP_OK, but it doesn't necessarily mean /// that the server received the message. int32_t SendMessage(const Var& message); /// GetBufferedAmount() returns the number of bytes of text and binary - /// messages that have been queued for the WebSocket connection to send but + /// messages that have been queued for the WebSocket connection to send, but /// have not been transmitted to the network yet. /// /// @return Returns the number of bytes. @@ -142,44 +159,52 @@ class WebSocket : public Resource { /// connection. /// /// @return Returns a Var of string type. If called before the - /// close reason is set, it contains an empty string. + /// close reason is set, the return value contains an empty string. Returns a + /// PP_VARTYPE_UNDEFINED if called on an invalid resource. Var GetCloseReason(); /// GetCloseWasClean() returns if the connection was closed cleanly for the /// specified WebSocket connection. /// /// @return Returns false if called before the connection is - /// closed, or called on an invalid resource. Otherwise, returns - /// true if the connection was closed cleanly, or returns - /// false if the connection was closed for abnormal reasons. + /// closed, called on an invalid resource, or closed for abnormal reasons. + /// Otherwise, returns true if the connection was closed + /// cleanly. bool GetCloseWasClean(); /// GetExtensions() returns the extensions selected by the server for the /// specified WebSocket connection. /// /// @return Returns a Var of string type. If called before the - /// connection is established, its data is an empty string. - /// Currently its data is always an empty string. + /// connection is established, the Var's data is an empty + /// string. Returns a PP_VARTYPE_UNDEFINED if called on an + /// invalid resource. Currently the Var's data for valid + /// resources are always an empty string. Var GetExtensions(); /// GetProtocol() returns the sub-protocol chosen by the server for the /// specified WebSocket connection. /// /// @return Returns a Var of string type. If called before the - /// connection is established, it contains the empty string. + /// connection is established, the Var contains the empty + /// string. Returns a code>PP_VARTYPE_UNDEFINED if called on an + /// invalid resource. Var GetProtocol(); /// GetReadyState() returns the ready state of the specified WebSocket /// connection. /// /// @return Returns PP_WEBSOCKETREADYSTATE_INVALID if called - /// before connect() is called. + /// before Connect() is called, or if this function is called on an + /// invalid resource. PP_WebSocketReadyState GetReadyState(); /// GetURL() returns the URL associated with specified WebSocket connection. /// /// @return Returns a Var of string type. If called before the - /// connection is established, it contains the empty string. + /// connection is established, the Var contains the empty + /// string. Returns a PP_VARTYPE_UNDEFINED if this function + /// is called on an invalid resource. Var GetURL(); }; -- cgit v1.1