From a4b1438809935f143b5ddaa9f5f28c26235c6e2b Mon Sep 17 00:00:00 2001 From: "jond@google.com" Date: Fri, 24 Feb 2012 02:22:07 +0000 Subject: Fixed some grammar. Review URL: http://codereview.chromium.org/9347047 git-svn-id: svn://svn.chromium.org/chrome/trunk/src@123408 0039d316-1c4b-4281-b951-d872f2087c98 --- ppapi/api/ppb_websocket.idl | 119 ++++++++++++++++++++++++------------------- ppapi/c/ppb_websocket.h | 121 ++++++++++++++++++++++++-------------------- 2 files changed, 133 insertions(+), 107 deletions(-) (limited to 'ppapi') diff --git a/ppapi/api/ppb_websocket.idl b/ppapi/api/ppb_websocket.idl index c5bb7c2..8b2eb4a 100644 --- a/ppapi/api/ppb_websocket.idl +++ b/ppapi/api/ppb_websocket.idl @@ -4,7 +4,8 @@ */ /** - * This file defines the PPB_WebSocket interface. + * This file defines the PPB_WebSocket interface providing + * bi-directional, full-duplex, communications over a single TCP socket. */ label Chrome { M18 = 1.0 @@ -46,7 +47,8 @@ enum PP_WebSocketReadyState { /** * This enumeration contains status codes. These codes are used in Close() and - * GetCloseCode(). See also RFC 6455, The WebSocket Protocol. + * GetCloseCode(). Refer to RFC 6455, The WebSocket Protocol, for further + * information. * PP_WEBSOCKETSTATUSCODE_NORMAL_CLOSURE and codes in the range * PP_WEBSOCKETSTATUSCODE_USER_REGISTERED_MIN to * PP_WEBSOCKETSTATUSCODE_USER_REGISTERED_MAX, and @@ -160,6 +162,10 @@ enum PP_WebSocketCloseCode { PP_WEBSOCKETSTATUSCODE_USER_PRIVATE_MAX = 4999 }; +/** + * The PPB_WebSocket interface provides bi-directional, + * full-duplex, communications over a single TCP socket. + */ interface PPB_WebSocket { /** * Create() creates a WebSocket instance. @@ -187,8 +193,8 @@ interface PPB_WebSocket { PP_Bool IsWebSocket([in] PP_Resource resource); /** - * Connect() connects to the specified WebSocket server. Caller can call this - * method at most once for a web_socket. + * Connect() connects to the specified WebSocket server. You can call this + * function once for a web_socket. * * @param[in] web_socket A PP_Resource corresponding to a * WebSocket. @@ -205,23 +211,25 @@ interface PPB_WebSocket { * @param[in] protocol_count The number of sub-protocols in * protocols. * - * @param[in] callback A PP_CompletionCallback which is called + * @param[in] callback A PP_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. + * Returns PP_ERROR_BADARGUMENT if the specified + * url, or protocols contain an 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 SecurityError of the + * specification. + * Returns PP_ERROR_INPROGRESS if this is not the first call to + * Connect(). */ int32_t Connect([in] PP_Resource web_socket, [in] PP_Var url, @@ -244,23 +252,25 @@ interface PPB_WebSocket { * PP_WEBSOCKETSTATUSCODE_USER_PRIVATE_MIN to * PP_WEBSOCKETSTATUSCODE_USER_PRIVATE_MAX are available. * - * @param[in] reason A PP_Var which represents the WebSocket - * close reason. Ignored if it is PP_VARTYPE_UNDEFINED. + * @param[in] reason A PP_Var representing the WebSocket + * close reason. This is ignored if it is PP_VARTYPE_UNDEFINED. * Otherwise, its PP_VarType must be * PP_VARTYPE_STRING. * - * @param[in] callback A PP_CompletionCallback which is called + * @param[in] callback A PP_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 InvalidAccessError of the specification. Returns + * PP_ERROR_INPROGRESS if this is not the first call to + * Close(). */ int32_t Close([in] PP_Resource web_socket, [in] uint16_t code, @@ -270,26 +280,25 @@ interface PPB_WebSocket { /** * 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. + * be called at least N times to receive N messages, no matter the size of + * each message. * * @param[in] web_socket A PP_Resource corresponding to a * WebSocket. * * @param[out] message The received message is copied to provided * message. The message must remain valid until - * the ReceiveMessage operation completes. Its PP_VarType - * will be PP_VARTYPE_STRING or - * PP_VARTYPE_ARRAY_BUFFER on receiving. + * ReceiveMessage() completes. Its received PP_VarType will be + * PP_VARTYPE_STRING or PP_VARTYPE_ARRAY_BUFFER. * - * @param[in] callback A PP_CompletionCallback which is called - * when the receiving message is completed. It is ignored if ReceiveMessage - * completes synchronously and returns PP_OK. + * @param[in] callback A PP_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([in] PP_Resource web_socket, @@ -302,19 +311,21 @@ interface PPB_WebSocket { * @param[in] web_socket A PP_Resource corresponding to a * WebSocket. * - * @param[in] message A message to send. The message is copied to internal - * buffer. So caller can free message safely after returning - * from the function. Its PP_VarType must be + * @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. Its sent PP_VarType must be * PP_VARTYPE_STRING or PP_VARTYPE_ARRAY_BUFFER. * * @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. - * Otherwise, returns PP_OK, but it doesn't necessarily mean + * PP_WEBSOCKETREADYSTATE_CONNECTING. + * PP_ERROR_FAILED corresponds to the 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 the JavaScript + * SyntaxError in the WebSocket API specification. + * Otherwise, returns PP_OK, which doesn't necessarily mean * that the server received the message. */ int32_t SendMessage([in] PP_Resource web_socket, @@ -322,7 +333,7 @@ interface PPB_WebSocket { /** * 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. * * @param[in] web_socket A PP_Resource corresponding to a @@ -351,7 +362,7 @@ interface PPB_WebSocket { * WebSocket. * * @return Returns a PP_VARTYPE_STRING var. If called before the - * close reason is set, it contains an empty string. Returns a + * close reason is set, the return value contains an empty string. Returns a * PP_VARTYPE_UNDEFINED if called on an invalid resource. */ PP_Var GetCloseReason([in] PP_Resource web_socket); @@ -364,9 +375,9 @@ interface PPB_WebSocket { * WebSocket. * * @return Returns PP_FALSE if called before the connection is - * closed, or called on an invalid resource. Otherwise, returns - * PP_TRUE if the connection was closed cleanly, or returns - * PP_FALSE if the connection was closed for abnormal reasons. + * closed, called on an invalid resource, or closed for abnormal reasons. + * Otherwise, returns PP_TRUE if the connection was closed + * cleanly. */ PP_Bool GetCloseWasClean([in] PP_Resource web_socket); @@ -378,9 +389,9 @@ interface PPB_WebSocket { * WebSocket. * * @return Returns a PP_VARTYPE_STRING var. If called before the - * connection is established, its data is an empty string. Returns a + * connection is established, the var's data is an empty string. Returns a * PP_VARTYPE_UNDEFINED if called on an invalid resource. - * Currently its data for valid resources are always an empty string. + * Currently the var's data for valid resources are always an empty string. */ PP_Var GetExtensions([in] PP_Resource web_socket); @@ -392,7 +403,7 @@ interface PPB_WebSocket { * WebSocket. * * @return Returns a PP_VARTYPE_STRING var. If called before the - * connection is established, it contains the empty string. Returns a + * connection is established, the var contains the empty string. Returns a * PP_VARTYPE_UNDEFINED if called on an invalid resource. */ PP_Var GetProtocol([in] PP_Resource web_socket); @@ -405,7 +416,8 @@ interface PPB_WebSocket { * WebSocket. * * @return Returns PP_WEBSOCKETREADYSTATE_INVALID if called - * before connect() is called, or called on an invalid resource. + * before Connect() is called, or if this function is called on an + * invalid resource. */ PP_WebSocketReadyState GetReadyState([in] PP_Resource web_socket); @@ -416,8 +428,9 @@ interface PPB_WebSocket { * WebSocket. * * @return Returns a PP_VARTYPE_STRING var. If called before the - * connection is established, it contains the empty string. Return a - * PP_VARTYPE_UNDEFINED if called on an invalid resource. + * connection is established, the var contains the empty string. Returns a + * PP_VARTYPE_UNDEFINED if this function is called on an + * invalid resource. */ PP_Var GetURL([in] PP_Resource web_socket); }; diff --git a/ppapi/c/ppb_websocket.h b/ppapi/c/ppb_websocket.h index 8fac7d2..1f59a5cd 100644 --- a/ppapi/c/ppb_websocket.h +++ b/ppapi/c/ppb_websocket.h @@ -3,7 +3,7 @@ * found in the LICENSE file. */ -/* From ppb_websocket.idl modified Mon Feb 6 14:29:34 2012. */ +/* From ppb_websocket.idl modified Wed Feb 15 11:18:43 2012. */ #ifndef PPAPI_C_PPB_WEBSOCKET_H_ #define PPAPI_C_PPB_WEBSOCKET_H_ @@ -21,7 +21,8 @@ /** * @file - * This file defines the PPB_WebSocket interface. + * This file defines the PPB_WebSocket interface providing + * bi-directional, full-duplex, communications over a single TCP socket. */ @@ -61,7 +62,8 @@ PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_WebSocketReadyState, 4); /** * This enumeration contains status codes. These codes are used in Close() and - * GetCloseCode(). See also RFC 6455, The WebSocket Protocol. + * GetCloseCode(). Refer to RFC 6455, The WebSocket Protocol, for further + * information. * PP_WEBSOCKETSTATUSCODE_NORMAL_CLOSURE and codes in the range * PP_WEBSOCKETSTATUSCODE_USER_REGISTERED_MIN to * PP_WEBSOCKETSTATUSCODE_USER_REGISTERED_MAX, and @@ -165,6 +167,10 @@ PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_WebSocketCloseCode, 4); * @addtogroup Interfaces * @{ */ +/** + * The PPB_WebSocket interface provides bi-directional, + * full-duplex, communications over a single TCP socket. + */ struct PPB_WebSocket_1_0 { /** * Create() creates a WebSocket instance. @@ -190,8 +196,8 @@ struct PPB_WebSocket_1_0 { */ PP_Bool (*IsWebSocket)(PP_Resource resource); /** - * Connect() connects to the specified WebSocket server. Caller can call this - * method at most once for a web_socket. + * Connect() connects to the specified WebSocket server. You can call this + * function once for a web_socket. * * @param[in] web_socket A PP_Resource corresponding to a * WebSocket. @@ -208,23 +214,25 @@ struct PPB_WebSocket_1_0 { * @param[in] protocol_count The number of sub-protocols in * protocols. * - * @param[in] callback A PP_CompletionCallback which is called + * @param[in] callback A PP_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. + * Returns PP_ERROR_BADARGUMENT if the specified + * url, or protocols contain an 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 SecurityError of the + * specification. + * Returns PP_ERROR_INPROGRESS if this is not the first call to + * Connect(). */ int32_t (*Connect)(PP_Resource web_socket, struct PP_Var url, @@ -246,23 +254,25 @@ struct PPB_WebSocket_1_0 { * PP_WEBSOCKETSTATUSCODE_USER_PRIVATE_MIN to * PP_WEBSOCKETSTATUSCODE_USER_PRIVATE_MAX are available. * - * @param[in] reason A PP_Var which represents the WebSocket - * close reason. Ignored if it is PP_VARTYPE_UNDEFINED. + * @param[in] reason A PP_Var representing the WebSocket + * close reason. This is ignored if it is PP_VARTYPE_UNDEFINED. * Otherwise, its PP_VarType must be * PP_VARTYPE_STRING. * - * @param[in] callback A PP_CompletionCallback which is called + * @param[in] callback A PP_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 InvalidAccessError of the specification. Returns + * PP_ERROR_INPROGRESS if this is not the first call to + * Close(). */ int32_t (*Close)(PP_Resource web_socket, uint16_t code, @@ -271,26 +281,25 @@ struct PPB_WebSocket_1_0 { /** * 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. + * be called at least N times to receive N messages, no matter the size of + * each message. * * @param[in] web_socket A PP_Resource corresponding to a * WebSocket. * * @param[out] message The received message is copied to provided * message. The message must remain valid until - * the ReceiveMessage operation completes. Its PP_VarType - * will be PP_VARTYPE_STRING or - * PP_VARTYPE_ARRAY_BUFFER on receiving. + * ReceiveMessage() completes. Its received PP_VarType will be + * PP_VARTYPE_STRING or PP_VARTYPE_ARRAY_BUFFER. * - * @param[in] callback A PP_CompletionCallback which is called - * when the receiving message is completed. It is ignored if ReceiveMessage - * completes synchronously and returns PP_OK. + * @param[in] callback A PP_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)(PP_Resource web_socket, @@ -302,25 +311,27 @@ struct PPB_WebSocket_1_0 { * @param[in] web_socket A PP_Resource corresponding to a * WebSocket. * - * @param[in] message A message to send. The message is copied to internal - * buffer. So caller can free message safely after returning - * from the function. Its PP_VarType must be + * @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. Its sent PP_VarType must be * PP_VARTYPE_STRING or PP_VARTYPE_ARRAY_BUFFER. * * @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. - * Otherwise, returns PP_OK, but it doesn't necessarily mean + * PP_WEBSOCKETREADYSTATE_CONNECTING. + * PP_ERROR_FAILED corresponds to the 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 the JavaScript + * SyntaxError in the WebSocket API specification. + * Otherwise, returns PP_OK, which doesn't necessarily mean * that the server received the message. */ int32_t (*SendMessage)(PP_Resource web_socket, struct PP_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. * * @param[in] web_socket A PP_Resource corresponding to a @@ -347,7 +358,7 @@ struct PPB_WebSocket_1_0 { * WebSocket. * * @return Returns a PP_VARTYPE_STRING var. If called before the - * close reason is set, it contains an empty string. Returns a + * close reason is set, the return value contains an empty string. Returns a * PP_VARTYPE_UNDEFINED if called on an invalid resource. */ struct PP_Var (*GetCloseReason)(PP_Resource web_socket); @@ -359,9 +370,9 @@ struct PPB_WebSocket_1_0 { * WebSocket. * * @return Returns PP_FALSE if called before the connection is - * closed, or called on an invalid resource. Otherwise, returns - * PP_TRUE if the connection was closed cleanly, or returns - * PP_FALSE if the connection was closed for abnormal reasons. + * closed, called on an invalid resource, or closed for abnormal reasons. + * Otherwise, returns PP_TRUE if the connection was closed + * cleanly. */ PP_Bool (*GetCloseWasClean)(PP_Resource web_socket); /** @@ -372,9 +383,9 @@ struct PPB_WebSocket_1_0 { * WebSocket. * * @return Returns a PP_VARTYPE_STRING var. If called before the - * connection is established, its data is an empty string. Returns a + * connection is established, the var's data is an empty string. Returns a * PP_VARTYPE_UNDEFINED if called on an invalid resource. - * Currently its data for valid resources are always an empty string. + * Currently the var's data for valid resources are always an empty string. */ struct PP_Var (*GetExtensions)(PP_Resource web_socket); /** @@ -385,7 +396,7 @@ struct PPB_WebSocket_1_0 { * WebSocket. * * @return Returns a PP_VARTYPE_STRING var. If called before the - * connection is established, it contains the empty string. Returns a + * connection is established, the var contains the empty string. Returns a * PP_VARTYPE_UNDEFINED if called on an invalid resource. */ struct PP_Var (*GetProtocol)(PP_Resource web_socket); @@ -397,7 +408,8 @@ struct PPB_WebSocket_1_0 { * WebSocket. * * @return Returns PP_WEBSOCKETREADYSTATE_INVALID if called - * before connect() is called, or called on an invalid resource. + * before Connect() is called, or if this function is called on an + * invalid resource. */ PP_WebSocketReadyState (*GetReadyState)(PP_Resource web_socket); /** @@ -407,8 +419,9 @@ struct PPB_WebSocket_1_0 { * WebSocket. * * @return Returns a PP_VARTYPE_STRING var. If called before the - * connection is established, it contains the empty string. Return a - * PP_VARTYPE_UNDEFINED if called on an invalid resource. + * connection is established, the var contains the empty string. Returns a + * PP_VARTYPE_UNDEFINED if this function is called on an + * invalid resource. */ struct PP_Var (*GetURL)(PP_Resource web_socket); }; -- cgit v1.1