15821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Copyright (c) 2011 The Chromium Authors. All rights reserved. 25821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Use of this source code is governed by a BSD-style license that can be 35821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// found in the LICENSE file. 45821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 55821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#ifndef PPAPI_CPP_URL_LOADER_H_ 65821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PPAPI_CPP_URL_LOADER_H_ 75821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 85821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "ppapi/c/pp_stdint.h" 95821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "ppapi/cpp/resource.h" 105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// @file 125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// This file defines the API for loading URLs. 135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)namespace pp { 145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class CompletionCallback; 165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class InstanceHandle; 175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class URLRequestInfo; 185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class URLResponseInfo; 195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// URLLoader provides an API for loading URLs. 215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// Refer to <code>ppapi/examples/url_loader/streaming.cc</code> 225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// for an example of how to use this class. 235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class URLLoader : public Resource { 245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) public: 255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// Default constructor for creating an is_null() 265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// <code>URLLoader</code> object. 275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) URLLoader() {} 285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// A constructor used when a <code>PP_Resource</code> is provided as a 305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// return value whose reference count we need to increment. 315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @param[in] resource A <code>PP_Resource</code> corresponding to a 335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// <code>URLLoader</code> resource. 345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) explicit URLLoader(PP_Resource resource); 355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// A constructor used to allocate a new URLLoader in the browser. The 375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// resulting object will be <code>is_null</code> if the allocation failed. 385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @param[in] instance The instance with which this resource will be 405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// associated. 415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) explicit URLLoader(const InstanceHandle& instance); 425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// The copy constructor for <code>URLLoader</code>. 445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @param other A <code>URLLoader</code> to be copied. 465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) URLLoader(const URLLoader& other); 475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// This function begins loading the <code>URLRequestInfo</code>. 495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// The operation completes when response headers are received or when an 505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// error occurs. Use GetResponseInfo() to access the response 515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// headers. 525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @param[in] request_info A <code>URLRequestInfo</code> corresponding to a 545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// URLRequestInfo. 555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @param[in] cc A <code>CompletionCallback</code> to run on asynchronous 565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// completion of Open(). This callback will run when response 57c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// headers for the url are received or error occurred. This callback 585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// will only run if Open() returns <code>PP_OK_COMPLETIONPENDING</code>. 595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @return An int32_t containing an error code from 615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// <code>pp_errors.h</code>. 625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int32_t Open(const URLRequestInfo& request_info, 635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const CompletionCallback& cc); 645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// This function can be invoked to follow a 665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// redirect after Open() completed on receiving redirect headers. 675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @param[in] cc A <code>CompletionCallback</code> to run on asynchronous 695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// completion of FollowRedirect(). This callback will run when response 70c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// headers for the redirect url are received or error occurred. This callback 715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// will only run if FollowRedirect() returns 725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// <code>PP_OK_COMPLETIONPENDING</code>. 735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @return An int32_t containing an error code from 755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// <code>pp_errors.h</code>. 765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int32_t FollowRedirect(const CompletionCallback& cc); 775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// This function returns the current upload progress (which is only 795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// meaningful after Open() has been called). Progress only refers to the 805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// request body and does not include the headers. 815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// This data is only available if the <code>URLRequestInfo</code> passed to 835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// Open() had the 845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// <code>PP_URLREQUESTPROPERTY_REPORTUPLOADPROGRESS</code> property set to 855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// <code>PP_TRUE</code>. 865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @param[in] bytes_sent The number of bytes sent thus far. 885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @param[in] total_bytes_to_be_sent The total number of bytes to be sent. 895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @return true if the upload progress is available, false if it is not 915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// available. 925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) bool GetUploadProgress(int64_t* bytes_sent, 935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int64_t* total_bytes_to_be_sent) const; 945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// This function returns the current download progress, which is meaningful 965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// after Open() has been called. Progress only refers to the response body 975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// and does not include the headers. 985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// This data is only available if the <code>URLRequestInfo</code> passed to 1005821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// Open() had the 1015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// <code>PP_URLREQUESTPROPERTY_REPORTDOWNLOADPROGRESS</code> property set to 1025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// PP_TRUE. 1035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 1045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @param[in] bytes_received The number of bytes received thus far. 1055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @param[in] total_bytes_to_be_received The total number of bytes to be 1065821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// received. The total bytes to be received may be unknown, in which case 1075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// <code>total_bytes_to_be_received</code> will be set to -1. 1085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 1095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @return true if the download progress is available, false if it is 1105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// not available. 1115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) bool GetDownloadProgress(int64_t* bytes_received, 1125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int64_t* total_bytes_to_be_received) const; 1135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// This is a function that returns the current 1155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// <code>URLResponseInfo</code> object. 1165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 1175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @return A <code>URLResponseInfo</code> corresponding to the 1185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// <code>URLResponseInfo</code> if successful, an <code>is_null</code> 1195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// object if the loader is not a valid resource or if Open() has not been 1205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// called. 1215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) URLResponseInfo GetResponseInfo() const; 1225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// This function is used to read the response body. The size of the buffer 1245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// must be large enough to hold the specified number of bytes to read. 1255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// This function might perform a partial read. 1265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 1275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @param[in,out] buffer A pointer to the buffer for the response body. 1285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @param[in] bytes_to_read The number of bytes to read. 1295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @param[in] cc A <code>CompletionCallback</code> to run on asynchronous 1305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// completion. The callback will run if the bytes (full or partial) are 1315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// read or an error occurs asynchronously. This callback will run only if 1325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// this function returns <code>PP_OK_COMPLETIONPENDING</code>. 1335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 1345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @return An int32_t containing the number of bytes read or an error code 1355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// from <code>pp_errors.h</code>. 1365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int32_t ReadResponseBody(void* buffer, 1375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int32_t bytes_to_read, 1385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const CompletionCallback& cc); 1395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// This function is used to wait for the response body to be completely 1415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// downloaded to the file provided by the GetBodyAsFileRef() in the current 1425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// <code>URLResponseInfo</code>. This function is only used if 1435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// <code>PP_URLREQUESTPROPERTY_STREAMTOFILE</code> was set on the 1445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// <code>URLRequestInfo</code> passed to Open(). 1455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 1465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @param[in] cc A <code>CompletionCallback</code> to run on asynchronous 1475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// completion. This callback will run when body is downloaded or an error 1485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// occurs after FinishStreamingToFile() returns 1495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// <code>PP_OK_COMPLETIONPENDING</code>. 1505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 1515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @return An int32_t containing the number of bytes read or an error code 1525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// from <code>pp_errors.h</code>. 1535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int32_t FinishStreamingToFile(const CompletionCallback& cc); 1545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// This function is used to cancel any pending IO and close the URLLoader 1565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// object. Any pending callbacks will still run, reporting 1575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// <code>PP_ERROR_ABORTED</code> if pending IO was interrupted. It is NOT 1585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// valid to call Open() again after a call to this function. 1595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 1605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// <strong>Note:</strong> If the <code>URLLoader</code> object is destroyed 1615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// while it is still open, then it will be implicitly closed so you are not 1625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// required to call Close(). 1635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) void Close(); 1645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)}; 1655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)} // namespace pp 1675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif // PPAPI_CPP_URL_LOADER_H_ 169