1eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch// Copyright 2013 The Chromium Authors. All rights reserved. 2eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch// Use of this source code is governed by a BSD-style license that can be 3eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch// found in the LICENSE file. 4eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch 5eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch#ifndef PPAPI_CPP_UDP_SOCKET_H_ 6eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch#define PPAPI_CPP_UDP_SOCKET_H_ 7eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch 8eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch#include "ppapi/c/ppb_udp_socket.h" 9eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch#include "ppapi/cpp/net_address.h" 10eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch#include "ppapi/cpp/pass_ref.h" 11eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch#include "ppapi/cpp/resource.h" 12eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch 13eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdochnamespace pp { 14eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch 15eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdochclass CompletionCallback; 16eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdochclass InstanceHandle; 17eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdochclass Var; 18eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch 19eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdochtemplate <typename T> class CompletionCallbackWithOutput; 20eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch 21eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch/// The <code>UDPSocket</code> class provides UDP socket operations. 22eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch/// 23eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch/// Permissions: Apps permission <code>socket</code> with subrule 24eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch/// <code>udp-bind</code> is required for <code>Bind()</code>; subrule 25eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch/// <code>udp-send-to</code> is required for <code>SendTo()</code>. 26eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch/// For more details about network communication permissions, please see: 27eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch/// http://developer.chrome.com/apps/app_network.html 28eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdochclass UDPSocket : public Resource { 29eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch public: 30eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// Default constructor for creating an is_null() <code>UDPSocket</code> 31eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// object. 32eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch UDPSocket(); 33eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch 34eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// A constructor used to create a <code>UDPSocket</code> object. 35eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// 36eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// @param[in] instance The instance with which this resource will be 37eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// associated. 38eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch explicit UDPSocket(const InstanceHandle& instance); 39eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch 40eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// A constructor used when you have received a <code>PP_Resource</code> as a 41eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// return value that has had 1 ref added for you. 42eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// 43eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// @param[in] resource A <code>PPB_UDPSocket</code> resource. 44eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch UDPSocket(PassRef, PP_Resource resource); 45eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch 46eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// The copy constructor for <code>UDPSocket</code>. 47eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// 48eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// @param[in] other A reference to another <code>UDPSocket</code>. 49eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch UDPSocket(const UDPSocket& other); 50eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch 51eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// The destructor. 52eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch virtual ~UDPSocket(); 53eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch 54eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// The assignment operator for <code>UDPSocket</code>. 55eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// 56eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// @param[in] other A reference to another <code>UDPSocket</code>. 57eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// 58eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// @return A reference to this <code>UDPSocket</code> object. 59eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch UDPSocket& operator=(const UDPSocket& other); 60eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch 61eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// Static function for determining whether the browser supports the 62eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// <code>PPB_UDPSocket</code> interface. 63eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// 64eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// @return true if the interface is available, false otherwise. 65eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch static bool IsAvailable(); 66eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch 67eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// Binds the socket to the given address. 68eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// 69eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// @param[in] addr A <code>NetAddress</code> object. 70eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// @param[in] callback A <code>CompletionCallback</code> to be called upon 71eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// completion. 72eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// 73eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// @return An int32_t containing an error code from <code>pp_errors.h</code>. 74eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// <code>PP_ERROR_NOACCESS</code> will be returned if the caller doesn't have 75eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// required permissions. <code>PP_ERROR_ADDRESS_IN_USE</code> will be 76eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// returned if the address is already in use. 77eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch int32_t Bind(const NetAddress& addr, 78eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch const CompletionCallback& callback); 79eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch 80eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// Get the address that the socket is bound to. The socket must be bound. 81eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// 82eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// @return A <code>NetAddress</code> object. The object will be null 83eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// (i.e., is_null() returns true) on failure. 84eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch NetAddress GetBoundAddress(); 85eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch 86eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// Receives data from the socket and stores the source address. The socket 87eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// must be bound. 88eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// 89eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// <strong>Caveat:</strong> You should be careful about the lifetime of 90eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// <code>buffer</code>. Typically you will use a 91eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// <code>CompletionCallbackFactory</code> to scope callbacks to the lifetime 92eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// of your class. When your class goes out of scope, the callback factory 93eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// will not actually cancel the operation, but will rather just skip issuing 94eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// the callback on your class. This means that if the underlying 95eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// <code>PPB_UDPSocket</code> resource outlives your class, the browser 96eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// will still try to write into your buffer when the operation completes. 97eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// The buffer must be kept valid until then to avoid memory corruption. 98eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// If you want to release the buffer while the <code>RecvFrom()</code> call 99eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// is still pending, you should call <code>Close()</code> to ensure that the 100eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// buffer won't be accessed in the future. 101eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// 102eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// @param[out] buffer The buffer to store the received data on success. It 103eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// must be at least as large as <code>num_bytes</code>. 104eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// @param[in] num_bytes The number of bytes to receive. 105eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// @param[in] callback A <code>CompletionCallbackWithOutput</code> to be 106eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// called upon completion. 107eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// 108eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// @return A non-negative number on success to indicate how many bytes have 109eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// been received; otherwise, an error code from <code>pp_errors.h</code>. 110eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch int32_t RecvFrom( 111eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch char* buffer, 112eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch int32_t num_bytes, 113eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch const CompletionCallbackWithOutput<NetAddress>& callback); 114eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch 115eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// Sends data to a specific destination. The socket must be bound. 116eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// 117eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// @param[in] buffer The buffer containing the data to send. 118eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// @param[in] num_bytes The number of bytes to send. 119eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// @param[in] addr A <code>NetAddress</code> object holding the destination 120eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// address. 121eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// @param[in] callback A <code>CompletionCallback</code> to be called upon 122eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// completion. 123eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// 124eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// @return A non-negative number on success to indicate how many bytes have 125eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// been sent; otherwise, an error code from <code>pp_errors.h</code>. 126eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// <code>PP_ERROR_NOACCESS</code> will be returned if the caller doesn't have 127eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// required permissions. 128eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch int32_t SendTo(const char* buffer, 129eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch int32_t num_bytes, 130eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch const NetAddress& addr, 131eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch const CompletionCallback& callback); 132eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch 133eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// Cancels all pending reads and writes, and closes the socket. Any pending 134eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// callbacks will still run, reporting <code>PP_ERROR_ABORTED</code> if 135eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// pending IO was interrupted. After a call to this method, no output 136eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// paramters passed into previous <code>RecvFrom()</code> calls will be 137eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// accessed. It is not valid to call <code>Bind()</code> again. 138eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// 139eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// The socket is implicitly closed if it is destroyed, so you are not 140eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// required to call this method. 141eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch void Close(); 142eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch 143eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// Sets a socket option on the UDP socket. 144eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// Please see the <code>PP_UDPSocket_Option</code> description for option 145eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// names, value types and allowed values. 146eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// 147eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// @param[in] name The option to set. 148eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// @param[in] value The option value to set. 149eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// @param[in] callback A <code>CompletionCallback</code> to be called upon 150eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// completion. 151eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// 152eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch /// @return An int32_t containing an error code from <code>pp_errors.h</code>. 153eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch int32_t SetOption(PP_UDPSocket_Option name, 154eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch const Var& value, 155eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch const CompletionCallback& callback); 156eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch}; 157eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch 158eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch} // namespace pp 159eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch 160eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch#endif // PPAPI_CPP_UDP_SOCKET_H_ 161