You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
227 lines
9.6 KiB
227 lines
9.6 KiB
9 years ago
|
/* Copyright (c) 2012 The Chromium Authors. All rights reserved.
|
||
|
|
* Use of this source code is governed by a BSD-style license that can be
|
||
|
|
* found in the LICENSE file.
|
||
|
|
*/
|
||
|
|
|
||
|
|
/* From ppb_url_loader.idl modified Thu Mar 28 10:07:37 2013. */
|
||
|
|
|
||
|
|
#ifndef PPAPI_C_PPB_URL_LOADER_H_
|
||
|
|
#define PPAPI_C_PPB_URL_LOADER_H_
|
||
|
|
|
||
|
|
#include "ppapi/c/pp_bool.h"
|
||
|
|
#include "ppapi/c/pp_completion_callback.h"
|
||
|
|
#include "ppapi/c/pp_instance.h"
|
||
|
|
#include "ppapi/c/pp_macros.h"
|
||
|
|
#include "ppapi/c/pp_resource.h"
|
||
|
|
#include "ppapi/c/pp_stdint.h"
|
||
|
|
|
||
|
|
#define PPB_URLLOADER_INTERFACE_1_0 "PPB_URLLoader;1.0"
|
||
|
|
#define PPB_URLLOADER_INTERFACE PPB_URLLOADER_INTERFACE_1_0
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @file
|
||
|
|
* This file defines the <strong>PPB_URLLoader</strong> interface for loading
|
||
|
|
* URLs.
|
||
|
|
*/
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @addtogroup Interfaces
|
||
|
|
* @{
|
||
|
|
*/
|
||
|
|
/**
|
||
|
|
* The <strong>PPB_URLLoader</strong> interface contains pointers to functions
|
||
|
|
* for loading URLs. The typical steps for loading a URL are:
|
||
|
|
*
|
||
|
|
* -# Call Create() to create a URLLoader object.
|
||
|
|
* -# Create a <code>URLRequestInfo</code> object and set properties on it.
|
||
|
|
* Refer to <code>PPB_URLRequestInfo</code> for further information.
|
||
|
|
* -# Call Open() with the <code>URLRequestInfo</code> as an argument.
|
||
|
|
* -# When Open() completes, call GetResponseInfo() to examine the response
|
||
|
|
* headers. Refer to <code>PPB_URLResponseInfo</code> for further information.
|
||
|
|
* -# Call ReadResponseBody() to stream the data for the response.
|
||
|
|
*
|
||
|
|
* Alternatively, if <code>PP_URLREQUESTPROPERTY_STREAMTOFILE</code> was set on
|
||
|
|
* the <code>URLRequestInfo</code> in step #2:
|
||
|
|
* - Call FinishStreamingToFile(), after examining the response headers
|
||
|
|
* (step #4), to wait for the downloaded file to be complete.
|
||
|
|
* - Then, access the downloaded file using the GetBodyAsFileRef() function of
|
||
|
|
* the <code>URLResponseInfo</code> returned in step #4.
|
||
|
|
*/
|
||
|
|
struct PPB_URLLoader_1_0 {
|
||
|
|
/**
|
||
|
|
* Create() creates a new <code>URLLoader</code> object. The
|
||
|
|
* <code>URLLoader</code> is associated with a particular instance, so that
|
||
|
|
* any UI dialogs that need to be shown to the user can be positioned
|
||
|
|
* relative to the window containing the instance.
|
||
|
|
*
|
||
|
|
* @param[in] instance A <code>PP_Instance</code> identifying one instance
|
||
|
|
* of a module.
|
||
|
|
*
|
||
|
|
* @return A <code>PP_Resource</code> corresponding to a URLLoader if
|
||
|
|
* successful, 0 if the instance is invalid.
|
||
|
|
*/
|
||
|
|
PP_Resource (*Create)(PP_Instance instance);
|
||
|
|
/**
|
||
|
|
* IsURLLoader() determines if a resource is an <code>URLLoader</code>.
|
||
|
|
*
|
||
|
|
* @param[in] resource A <code>PP_Resource</code> corresponding to a
|
||
|
|
* <code>URLLoader</code>.
|
||
|
|
*
|
||
|
|
* @return <code>PP_TRUE</code> if the resource is a <code>URLLoader</code>,
|
||
|
|
* <code>PP_FALSE</code> if the resource is invalid or some type other
|
||
|
|
* than <code>URLLoader</code>.
|
||
|
|
*/
|
||
|
|
PP_Bool (*IsURLLoader)(PP_Resource resource);
|
||
|
|
/**
|
||
|
|
* Open() begins loading the <code>URLRequestInfo</code>. The operation
|
||
|
|
* completes when response headers are received or when an error occurs. Use
|
||
|
|
* GetResponseInfo() to access the response headers.
|
||
|
|
*
|
||
|
|
* @param[in] loader A <code>PP_Resource</code> corresponding to a
|
||
|
|
* <code>URLLoader</code>.
|
||
|
|
* @param[in] resource A <code>PP_Resource</code> corresponding to a
|
||
|
|
* <code>URLRequestInfo</code>.
|
||
|
|
* @param[in] callback A <code>PP_CompletionCallback</code> to run on
|
||
|
|
* asynchronous completion of Open(). This callback will run when response
|
||
|
|
* headers for the url are received or error occurred. This callback
|
||
|
|
* will only run if Open() returns <code>PP_OK_COMPLETIONPENDING</code>.
|
||
|
|
*
|
||
|
|
* @return An int32_t containing an error code from <code>pp_errors.h</code>.
|
||
|
|
*/
|
||
|
|
int32_t (*Open)(PP_Resource loader,
|
||
|
|
PP_Resource request_info,
|
||
|
|
struct PP_CompletionCallback callback);
|
||
|
|
/**
|
||
|
|
* FollowRedirect() can be invoked to follow a redirect after Open()
|
||
|
|
* completed on receiving redirect headers.
|
||
|
|
*
|
||
|
|
* @param[in] loader A <code>PP_Resource</code> corresponding to a
|
||
|
|
* <code>URLLoader</code>.
|
||
|
|
* @param[in] callback A <code>PP_CompletionCallback</code> to run on
|
||
|
|
* asynchronous completion of FollowRedirect(). This callback will run when
|
||
|
|
* response headers for the redirect url are received or error occurred. This
|
||
|
|
* callback will only run if FollowRedirect() returns
|
||
|
|
* <code>PP_OK_COMPLETIONPENDING</code>.
|
||
|
|
*
|
||
|
|
* @return An int32_t containing an error code from <code>pp_errors.h</code>.
|
||
|
|
*/
|
||
|
|
int32_t (*FollowRedirect)(PP_Resource loader,
|
||
|
|
struct PP_CompletionCallback callback);
|
||
|
|
/**
|
||
|
|
* GetUploadProgress() returns the current upload progress (which is
|
||
|
|
* meaningful after Open() has been called). Progress only refers to the
|
||
|
|
* request body and does not include the headers.
|
||
|
|
*
|
||
|
|
* This data is only available if the <code>URLRequestInfo</code> passed
|
||
|
|
* to Open() had the <code>PP_URLREQUESTPROPERTY_REPORTUPLOADPROGRESS</code>
|
||
|
|
* property set to PP_TRUE.
|
||
|
|
*
|
||
|
|
* @param[in] loader A <code>PP_Resource</code> corresponding to a
|
||
|
|
* <code>URLLoader</code>.
|
||
|
|
* @param[in] bytes_sent The number of bytes sent thus far.
|
||
|
|
* @param[in] total_bytes_to_be_sent The total number of bytes to be sent.
|
||
|
|
*
|
||
|
|
* @return <code>PP_TRUE</code> if the upload progress is available,
|
||
|
|
* <code>PP_FALSE</code> if it is not available.
|
||
|
|
*/
|
||
|
|
PP_Bool (*GetUploadProgress)(PP_Resource loader,
|
||
|
|
int64_t* bytes_sent,
|
||
|
|
int64_t* total_bytes_to_be_sent);
|
||
|
|
/**
|
||
|
|
* GetDownloadProgress() returns the current download progress, which is
|
||
|
|
* meaningful after Open() has been called. Progress only refers to the
|
||
|
|
* response body and does not include the headers.
|
||
|
|
*
|
||
|
|
* This data is only available if the <code>URLRequestInfo</code> passed to
|
||
|
|
* Open() had the <code>PP_URLREQUESTPROPERTY_REPORTDOWNLOADPROGRESS</code>
|
||
|
|
* property set to <code>PP_TRUE</code>.
|
||
|
|
*
|
||
|
|
* @param[in] loader A <code>PP_Resource</code> corresponding to a
|
||
|
|
* <code>URLLoader</code>.
|
||
|
|
* @param[in] bytes_received The number of bytes received thus far.
|
||
|
|
* @param[in] total_bytes_to_be_received The total number of bytes to be
|
||
|
|
* received. The total bytes to be received may be unknown, in which case
|
||
|
|
* <code>total_bytes_to_be_received</code> will be set to -1.
|
||
|
|
*
|
||
|
|
* @return <code>PP_TRUE</code> if the download progress is available,
|
||
|
|
* <code>PP_FALSE</code> if it is not available.
|
||
|
|
*/
|
||
|
|
PP_Bool (*GetDownloadProgress)(PP_Resource loader,
|
||
|
|
int64_t* bytes_received,
|
||
|
|
int64_t* total_bytes_to_be_received);
|
||
|
|
/**
|
||
|
|
* GetResponseInfo() returns the current <code>URLResponseInfo</code> object.
|
||
|
|
*
|
||
|
|
* @param[in] instance A <code>PP_Resource</code> corresponding to a
|
||
|
|
* <code>URLLoader</code>.
|
||
|
|
*
|
||
|
|
* @return A <code>PP_Resource</code> corresponding to the
|
||
|
|
* <code>URLResponseInfo</code> if successful, 0 if the loader is not a valid
|
||
|
|
* resource or if Open() has not been called.
|
||
|
|
*/
|
||
|
|
PP_Resource (*GetResponseInfo)(PP_Resource loader);
|
||
|
|
/**
|
||
|
|
* ReadResponseBody() is used to read the response body. The size of the
|
||
|
|
* buffer must be large enough to hold the specified number of bytes to read.
|
||
|
|
* This function might perform a partial read.
|
||
|
|
*
|
||
|
|
* @param[in] loader A <code>PP_Resource</code> corresponding to a
|
||
|
|
* <code>URLLoader</code>.
|
||
|
|
* @param[in,out] buffer A pointer to the buffer for the response body.
|
||
|
|
* @param[in] bytes_to_read The number of bytes to read.
|
||
|
|
* @param[in] callback A <code>PP_CompletionCallback</code> to run on
|
||
|
|
* asynchronous completion. The callback will run if the bytes (full or
|
||
|
|
* partial) are read or an error occurs asynchronously. This callback will
|
||
|
|
* run only if this function returns <code>PP_OK_COMPLETIONPENDING</code>.
|
||
|
|
*
|
||
|
|
* @return An int32_t containing the number of bytes read or an error code
|
||
|
|
* from <code>pp_errors.h</code>.
|
||
|
|
*/
|
||
|
|
int32_t (*ReadResponseBody)(PP_Resource loader,
|
||
|
|
void* buffer,
|
||
|
|
int32_t bytes_to_read,
|
||
|
|
struct PP_CompletionCallback callback);
|
||
|
|
/**
|
||
|
|
* FinishStreamingToFile() is used to wait for the response body to be
|
||
|
|
* completely downloaded to the file provided by the GetBodyAsFileRef()
|
||
|
|
* in the current <code>URLResponseInfo</code>. This function is only used if
|
||
|
|
* <code>PP_URLREQUESTPROPERTY_STREAMTOFILE</code> was set on the
|
||
|
|
* <code>URLRequestInfo</code> passed to Open().
|
||
|
|
*
|
||
|
|
* @param[in] loader A <code>PP_Resource</code> corresponding to a
|
||
|
|
* <code>URLLoader</code>.
|
||
|
|
* @param[in] callback A <code>PP_CompletionCallback</code> to run on
|
||
|
|
* asynchronous completion. This callback will run when body is downloaded
|
||
|
|
* or an error occurs after FinishStreamingToFile() returns
|
||
|
|
* <code>PP_OK_COMPLETIONPENDING</code>.
|
||
|
|
*
|
||
|
|
* @return An int32_t containing the number of bytes read or an error code
|
||
|
|
* from <code>pp_errors.h</code>.
|
||
|
|
*/
|
||
|
|
int32_t (*FinishStreamingToFile)(PP_Resource loader,
|
||
|
|
struct PP_CompletionCallback callback);
|
||
|
|
/**
|
||
|
|
* Close is a pointer to a function used to cancel any pending IO and close
|
||
|
|
* the <code>URLLoader</code> object. Any pending callbacks will still run,
|
||
|
|
* reporting <code>PP_ERROR_ABORTED</code> if pending IO was interrupted.
|
||
|
|
* It is NOT valid to call Open() again after a call to this function.
|
||
|
|
*
|
||
|
|
* <strong>Note:</strong> If the <code>URLLoader</code> object is destroyed
|
||
|
|
* while it is still open, then it will be implicitly closed so you are not
|
||
|
|
* required to call Close().
|
||
|
|
*
|
||
|
|
* @param[in] loader A <code>PP_Resource</code> corresponding to a
|
||
|
|
* <code>URLLoader</code>.
|
||
|
|
*/
|
||
|
|
void (*Close)(PP_Resource loader);
|
||
|
|
};
|
||
|
|
|
||
|
|
typedef struct PPB_URLLoader_1_0 PPB_URLLoader;
|
||
|
|
/**
|
||
|
|
* @}
|
||
|
|
*/
|
||
|
|
|
||
|
|
#endif /* PPAPI_C_PPB_URL_LOADER_H_ */
|
||
|
|
|