From a58eae8719572ccaaf8eeed2f5b32e195b0de944 Mon Sep 17 00:00:00 2001 From: "yzshen@chromium.org" Date: Sat, 22 Jun 2013 14:29:02 +0000 Subject: Update comments of the Pepper networking APIs. The following APIs are updated: - PPB_NetAddress_Dev - PPB_HostResolver_Dev - PPB_TCPSocket_Dev - PPB_UDPSocket_Dev BUG=247225 TEST=None Review URL: https://chromiumcodereview.appspot.com/16938011 git-svn-id: svn://svn.chromium.org/chrome/trunk/src@208037 0039d316-1c4b-4281-b951-d872f2087c98 --- ppapi/cpp/dev/host_resolver_dev.h | 69 ++++++++++++++++++++++- ppapi/cpp/dev/net_address_dev.h | 66 +++++++++++++++++++++- ppapi/cpp/dev/tcp_socket_dev.h | 115 +++++++++++++++++++++++++++++++++++++- ppapi/cpp/dev/udp_socket_dev.h | 105 +++++++++++++++++++++++++++++++++- 4 files changed, 350 insertions(+), 5 deletions(-) (limited to 'ppapi/cpp') diff --git a/ppapi/cpp/dev/host_resolver_dev.h b/ppapi/cpp/dev/host_resolver_dev.h index 592fd74..a746306 100644 --- a/ppapi/cpp/dev/host_resolver_dev.h +++ b/ppapi/cpp/dev/host_resolver_dev.h @@ -17,29 +17,96 @@ namespace pp { class CompletionCallback; class InstanceHandle; +/// The HostResolver_Dev class supports host name resolution. +/// +/// Permissions: In order to run Resolve(), apps permission +/// socket with subrule resolve-host is required. +/// For more details about network communication permissions, please see: +/// http://developer.chrome.com/apps/app_network.html class HostResolver_Dev : public Resource { public: + /// Default constructor for creating an is_null() + /// HostResolver_Dev object. HostResolver_Dev(); + /// A constructor used to create a HostResolver_Dev object. + /// + /// @param[in] instance The instance with which this resource will be + /// associated. explicit HostResolver_Dev(const InstanceHandle& instance); + /// A constructor used when you have received a PP_Resource as a + /// return value that has had 1 ref added for you. + /// + /// @param[in] resource A PPB_HostResolver_Dev resource. HostResolver_Dev(PassRef, PP_Resource resource); + /// The copy constructor for HostResolver_Dev. + /// + /// @param[in] other A reference to another HostResolver_Dev. HostResolver_Dev(const HostResolver_Dev& other); + /// The destructor. virtual ~HostResolver_Dev(); + /// The assignment operator for HostResolver_Dev. + /// + /// @param[in] other A reference to another HostResolver_Dev. + /// + /// @return A reference to this HostResolver_Dev object. HostResolver_Dev& operator=(const HostResolver_Dev& other); - // Returns true if the required interface is available. + /// Static function for determining whether the browser supports the + /// PPB_HostResolver_Dev interface. + /// + /// @return true if the interface is available, false otherwise. static bool IsAvailable(); + /// Requests resolution of a host name. If the call completes successully, the + /// results can be retrieved by GetCanonicalName(), + /// GetNetAddressCount() and GetNetAddress(). + /// + /// @param[in] host The host name (or IP address literal) to resolve. + /// @param[in] port The port number to be set in the resulting network + /// addresses. + /// @param[in] hint A PP_HostResolver_Hint_Dev structure + /// providing hints for host resolution. + /// @param[in] callback A CompletionCallback to be called upon + /// completion. + /// + /// @return An int32_t containing an error code from pp_errors.h. + /// PP_ERROR_NOACCESS will be returned if the caller doesn't have + /// required permissions. PP_ERROR_NAME_NOT_RESOLVED will be + /// returned if the host name couldn't be resolved. int32_t Resolve(const char* host, uint16_t port, const PP_HostResolver_Hint_Dev& hint, const CompletionCallback& callback); + + /// Gets the canonical name of the host. + /// + /// @return A string Var on success, which is an empty string + /// if PP_HOSTRESOLVER_FLAGS_CANONNAME is not set in the hint + /// flags when calling Resolve(); an undefined Var + /// if there is a pending Resolve() call or the previous + /// Resolve() call failed. Var GetCanonicalName() const; + + /// Gets the number of network addresses. + /// + /// @return The number of available network addresses on success; 0 if there + /// is a pending Resolve() call or the previous + /// Resolve() call failed. uint32_t GetNetAddressCount() const; + + /// Gets a network address. + /// + /// @param[in] index An index indicating which address to return. + /// + /// @return A NetAddress_Dev object. The object will be null + /// (i.e., is_null() returns true) if there is a pending + /// Resolve() call or the previous Resolve() call + /// failed, or the specified index is out of range. NetAddress_Dev GetNetAddress(uint32_t index) const; }; diff --git a/ppapi/cpp/dev/net_address_dev.h b/ppapi/cpp/dev/net_address_dev.h index e703980..4090aa3 100644 --- a/ppapi/cpp/dev/net_address_dev.h +++ b/ppapi/cpp/dev/net_address_dev.h @@ -14,36 +14,98 @@ namespace pp { class InstanceHandle; +/// The NetAddress_Dev class represents a network address. class NetAddress_Dev : public Resource { public: + /// Default constructor for creating an is_null() NetAddress_Dev + /// object. NetAddress_Dev(); + /// A constructor used when you have received a PP_Resource as a + /// return value that has had 1 ref added for you. + /// + /// @param[in] resource A PPB_NetAddress_Dev resource. NetAddress_Dev(PassRef, PP_Resource resource); + /// A constructor used to create a NetAddress_Dev object with the + /// specified IPv4 address. + /// + /// @param[in] instance The instance with which this resource will be + /// associated. + /// @param[in] ipv4_addr An IPv4 address. NetAddress_Dev(const InstanceHandle& instance, const PP_NetAddress_IPv4_Dev& ipv4_addr); + /// A constructor used to create a NetAddress_Dev object with the + /// specified IPv6 address. + /// + /// @param[in] instance The instance with which this resource will be + /// associated. + /// @param[in] ipv6_addr An IPv6 address. NetAddress_Dev(const InstanceHandle& instance, const PP_NetAddress_IPv6_Dev& ipv6_addr); + /// The copy constructor for NetAddress_Dev. + /// + /// @param[in] other A reference to another NetAddress_Dev. NetAddress_Dev(const NetAddress_Dev& other); + /// The destructor. virtual ~NetAddress_Dev(); + /// The assignment operator for NetAddress_Dev. + /// + /// @param[in] other A reference to another NetAddress_Dev. + /// + /// @return A reference to this NetAddress_Dev object. NetAddress_Dev& operator=(const NetAddress_Dev& other); - /// Static function for determining whether the browser supports the required - /// NetAddress interface. + /// Static function for determining whether the browser supports the + /// PPB_NetAddress_Dev interface. /// /// @return true if the interface is available, false otherwise. static bool IsAvailable(); + /// Gets the address family. + /// + /// @return The address family on success; + /// PP_NETADDRESS_FAMILY_UNSPECIFIED on failure. PP_NetAddress_Family_Dev GetFamily() const; + /// Returns a human-readable description of the network address. The + /// description is in the form of host [ ":" port ] and conforms to + /// http://tools.ietf.org/html/rfc3986#section-3.2 for IPv4 and IPv6 addresses + /// (e.g., "192.168.0.1", "192.168.0.1:99", or "[::1]:80"). + /// + /// @param[in] include_port Whether to include the port number in the + /// description. + /// + /// @return A string Var on success; an undefined + /// Var on failure. Var DescribeAsString(bool include_port) const; + /// Fills a PP_NetAddress_IPv4_Dev structure if the network + /// address is of PP_NETADDRESS_FAMILY_IPV4 address family. + /// Note that passing a network address of + /// PP_NETADDRESS_FAMILY_IPV6 address family will fail even if + /// the address is an IPv4-mapped IPv6 address. + /// + /// @param[out] ipv4_addr A PP_NetAddress_IPv4_Dev structure to + /// store the result. + /// + /// @return A boolean value indicating whether the operation succeeded. bool DescribeAsIPv4Address(PP_NetAddress_IPv4_Dev* ipv4_addr) const; + /// Fills a PP_NetAddress_IPv6_Dev structure if the network + /// address is of PP_NETADDRESS_FAMILY_IPV6 address family. + /// Note that passing a network address of + /// PP_NETADDRESS_FAMILY_IPV4 address family will fail - this + /// method doesn't map it to an IPv6 address. + /// + /// @param[out] ipv6_addr A PP_NetAddress_IPv6_Dev structure to + /// store the result. + /// + /// @return A boolean value indicating whether the operation succeeded. bool DescribeAsIPv6Address(PP_NetAddress_IPv6_Dev* ipv6_addr) const; }; diff --git a/ppapi/cpp/dev/tcp_socket_dev.h b/ppapi/cpp/dev/tcp_socket_dev.h index 16d7dee..0fc1cd2 100644 --- a/ppapi/cpp/dev/tcp_socket_dev.h +++ b/ppapi/cpp/dev/tcp_socket_dev.h @@ -15,34 +15,147 @@ namespace pp { class CompletionCallback; class InstanceHandle; +/// The TCPSocket_Dev class provides TCP socket operations. +/// +/// Permissions: Apps permission socket with subrule +/// tcp-connect is required for Connect(). +/// For more details about network communication permissions, please see: +/// http://developer.chrome.com/apps/app_network.html class TCPSocket_Dev: public Resource { public: + /// Default constructor for creating an is_null() TCPSocket_Dev + /// object. TCPSocket_Dev(); + /// A constructor used to create a TCPSocket_Dev object. + /// + /// @param[in] instance The instance with which this resource will be + /// associated. explicit TCPSocket_Dev(const InstanceHandle& instance); + /// A constructor used when you have received a PP_Resource as a + /// return value that has had 1 ref added for you. + /// + /// @param[in] resource A PPB_TCPSocket_Dev resource. TCPSocket_Dev(PassRef, PP_Resource resource); + /// The copy constructor for TCPSocket_Dev. + /// + /// @param[in] other A reference to another TCPSocket_Dev. TCPSocket_Dev(const TCPSocket_Dev& other); + /// The destructor. virtual ~TCPSocket_Dev(); + /// The assignment operator for TCPSocket_Dev. + /// + /// @param[in] other A reference to another TCPSocket_Dev. + /// + /// @return A reference to this TCPSocket_Dev object. TCPSocket_Dev& operator=(const TCPSocket_Dev& other); - // Returns true if the required interface is available. + /// Static function for determining whether the browser supports the + /// PPB_TCPSocket_Dev interface. + /// + /// @return true if the interface is available, false otherwise. static bool IsAvailable(); + /// Connects the socket to the given address. + /// + /// @param[in] addr A NetAddress_Dev object. + /// @param[in] callback A CompletionCallback to be called upon + /// completion. + /// + /// @return An int32_t containing an error code from pp_errors.h, + /// including (but not limited to): + /// - PP_ERROR_NOACCESS: the caller doesn't have required + /// permissions. + /// - PP_ERROR_ADDRESS_UNREACHABLE: addr is + /// unreachable. + /// - PP_ERROR_CONNECTION_REFUSED: the connection attempt was + /// refused. + /// - PP_ERROR_CONNECTION_FAILED: the connection attempt failed. + /// - PP_ERROR_CONNECTION_TIMEDOUT: the connection attempt timed + /// out. int32_t Connect(const NetAddress_Dev& addr, const CompletionCallback& callback); + + /// Gets the local address of the socket, if it is connected. + /// + /// @return A NetAddress_Dev object. The object will be null + /// (i.e., is_null() returns true) on failure. NetAddress_Dev GetLocalAddress() const; + + /// Gets the remote address of the socket, if it is connected. + /// + /// @return A NetAddress_Dev object. The object will be null + /// (i.e., is_null() returns true) on failure. NetAddress_Dev GetRemoteAddress() const; + + /// Reads data from the socket. The socket must be connected. It may perform a + /// partial read. + /// + /// Caveat: You should be careful about the lifetime of + /// buffer. Typically you will use a + /// CompletionCallbackFactory to scope callbacks to the lifetime + /// of your class. When your class goes out of scope, the callback factory + /// will not actually cancel the operation, but will rather just skip issuing + /// the callback on your class. This means that if the underlying + /// PPB_TCPSocket_Dev resource outlives your class, the browser + /// will still try to write into your buffer when the operation completes. + /// The buffer must be kept valid until then to avoid memory corruption. + /// If you want to release the buffer while the Read() call is + /// still pending, you should call Close() to ensure that the + /// buffer won't be accessed in the future. + /// + /// @param[out] buffer The buffer to store the received data on success. It + /// must be at least as large as bytes_to_read. + /// @param[in] bytes_to_read The number of bytes to read. + /// @param[in] callback A CompletionCallback to be called upon + /// completion. + /// + /// @return A non-negative number on success to indicate how many bytes have + /// been read, 0 means that end-of-file was reached; otherwise, an error code + /// from pp_errors.h. int32_t Read(char* buffer, int32_t bytes_to_read, const CompletionCallback& callback); + + /// Writes data to the socket. The socket must be connected. It may perform a + /// partial write. + /// + /// @param[in] buffer The buffer containing the data to write. + /// @param[in] bytes_to_write The number of bytes to write. + /// @param[in] callback A CompletionCallback to be called upon + /// completion. + /// + /// @return A non-negative number on success to indicate how many bytes have + /// been written; otherwise, an error code from pp_errors.h. int32_t Write(const char* buffer, int32_t bytes_to_write, const CompletionCallback& callback); + + /// Cancels all pending reads and writes and disconnects the socket. Any + /// pending callbacks will still run, reporting PP_ERROR_ABORTED + /// if pending IO was interrupted. After a call to this method, no output + /// buffer pointers passed into previous Read() calls will be + /// accessed. It is not valid to call Connect() again. + /// + /// The socket is implicitly closed if it is destroyed, so you are not + /// required to call this method. void Close(); + + /// Sets a socket option on the TCP socket. + /// Please see the PP_TCPSocket_Option_Dev description for option + /// names, value types and allowed values. + /// + /// @param[in] name The option to set. + /// @param[in] value The option value to set. + /// @param[in] callback A CompletionCallback to be called upon + /// completion. + /// + /// @return An int32_t containing an error code from pp_errors.h. + //// int32_t SetOption(PP_TCPSocket_Option_Dev name, const Var& value, const CompletionCallback& callback); diff --git a/ppapi/cpp/dev/udp_socket_dev.h b/ppapi/cpp/dev/udp_socket_dev.h index 9f46f0a..85f5cb2 100644 --- a/ppapi/cpp/dev/udp_socket_dev.h +++ b/ppapi/cpp/dev/udp_socket_dev.h @@ -18,35 +18,138 @@ class Var; template class CompletionCallbackWithOutput; +/// The UDPSocket_Dev class provides UDP socket operations. +/// +/// Permissions: Apps permission socket with subrule +/// udp-bind is required for Bind(); subrule +/// udp-send-to is required for SendTo(). +/// For more details about network communication permissions, please see: +/// http://developer.chrome.com/apps/app_network.html class UDPSocket_Dev: public Resource { public: + /// Default constructor for creating an is_null() UDPSocket_Dev + /// object. UDPSocket_Dev(); + /// A constructor used to create a UDPSocket_Dev object. + /// + /// @param[in] instance The instance with which this resource will be + /// associated. explicit UDPSocket_Dev(const InstanceHandle& instance); + /// A constructor used when you have received a PP_Resource as a + /// return value that has had 1 ref added for you. + /// + /// @param[in] resource A PPB_UDPSocket_Dev resource. UDPSocket_Dev(PassRef, PP_Resource resource); + /// The copy constructor for UDPSocket_Dev. + /// + /// @param[in] other A reference to another UDPSocket_Dev. UDPSocket_Dev(const UDPSocket_Dev& other); + /// The destructor. virtual ~UDPSocket_Dev(); + /// The assignment operator for UDPSocket_Dev. + /// + /// @param[in] other A reference to another UDPSocket_Dev. + /// + /// @return A reference to this UDPSocket_Dev object. UDPSocket_Dev& operator=(const UDPSocket_Dev& other); - // Returns true if the required interface is available. + /// Static function for determining whether the browser supports the + /// PPB_UDPSocket_Dev interface. + /// + /// @return true if the interface is available, false otherwise. static bool IsAvailable(); + /// Binds the socket to the given address. + /// + /// @param[in] addr A NetAddress_Dev object. + /// @param[in] callback A CompletionCallback to be called upon + /// completion. + /// + /// @return An int32_t containing an error code from pp_errors.h. + /// PP_ERROR_NOACCESS will be returned if the caller doesn't have + /// required permissions. PP_ERROR_ADDRESS_IN_USE will be + /// returned if the address is already in use. int32_t Bind(const NetAddress_Dev& addr, const CompletionCallback& callback); + + /// Get the address that the socket is bound to. The socket must be bound. + /// + /// @return A NetAddress_Dev object. The object will be null + /// (i.e., is_null() returns true) on failure. NetAddress_Dev GetBoundAddress(); + + /// Receives data from the socket and stores the source address. The socket + /// must be bound. + /// + /// Caveat: You should be careful about the lifetime of + /// buffer. Typically you will use a + /// CompletionCallbackFactory to scope callbacks to the lifetime + /// of your class. When your class goes out of scope, the callback factory + /// will not actually cancel the operation, but will rather just skip issuing + /// the callback on your class. This means that if the underlying + /// PPB_UDPSocket_Dev resource outlives your class, the browser + /// will still try to write into your buffer when the operation completes. + /// The buffer must be kept valid until then to avoid memory corruption. + /// If you want to release the buffer while the RecvFrom() call + /// is still pending, you should call Close() to ensure that the + /// buffer won't be accessed in the future. + /// + /// @param[out] buffer The buffer to store the received data on success. It + /// must be at least as large as num_bytes. + /// @param[in] num_bytes The number of bytes to receive. + /// @param[in] callback A CompletionCallbackWithOutput to be + /// called upon completion. + /// + /// @return A non-negative number on success to indicate how many bytes have + /// been received; otherwise, an error code from pp_errors.h. int32_t RecvFrom( char* buffer, int32_t num_bytes, const CompletionCallbackWithOutput& callback); + + /// Sends data to a specific destination. The socket must be bound. + /// + /// @param[in] buffer The buffer containing the data to send. + /// @param[in] num_bytes The number of bytes to send. + /// @param[in] addr A NetAddress_Dev object holding the + /// destination address. + /// @param[in] callback A CompletionCallback to be called upon + /// completion. + /// + /// @return A non-negative number on success to indicate how many bytes have + /// been sent; otherwise, an error code from pp_errors.h. + /// PP_ERROR_NOACCESS will be returned if the caller doesn't have + /// required permissions. int32_t SendTo(const char* buffer, int32_t num_bytes, const NetAddress_Dev& addr, const CompletionCallback& callback); + + /// Cancels all pending reads and writes, and closes the socket. Any pending + /// callbacks will still run, reporting PP_ERROR_ABORTED if + /// pending IO was interrupted. After a call to this method, no output + /// paramters passed into previous RecvFrom() calls will be + /// accessed. It is not valid to call Bind() again. + /// + /// The socket is implicitly closed if it is destroyed, so you are not + /// required to call this method. void Close(); + + /// Sets a socket option on the UDP socket. + /// Please see the PP_UDPSocket_Option_Dev description for option + /// names, value types and allowed values. + /// + /// @param[in] name The option to set. + /// @param[in] value The option value to set. + /// @param[in] callback A CompletionCallback to be called upon + /// completion. + /// + /// @return An int32_t containing an error code from pp_errors.h. int32_t SetOption(PP_UDPSocket_Option_Dev name, const Var& value, const CompletionCallback& callback); -- cgit v1.1