<!--
# license: Licensed to the Apache Software Foundation (ASF) under one
#         or more contributor license agreements.  See the NOTICE file
#         distributed with this work for additional information
#         regarding copyright ownership.  The ASF licenses this file
#         to you under the Apache License, Version 2.0 (the
#         "License"); you may not use this file except in compliance
#         with the License.  You may obtain a copy of the License at
#
#           http://www.apache.org/licenses/LICENSE-2.0
#
#         Unless required by applicable law or agreed to in writing,
#         software distributed under the License is distributed on an
#         "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
#         KIND, either express or implied.  See the License for the
#         specific language governing permissions and limitations
#         under the License.
-->

# cordova-plugin-file-transfer

[![Build Status](https://travis-ci.org/apache/cordova-plugin-file-transfer.svg)](https://travis-ci.org/apache/cordova-plugin-file-transfer)

Documentation du plugin : <doc/index.md>

Ce plugin vous permet de télécharger des fichiers.

Ce plugin définit global `FileTransfer` , `FileUploadOptions` constructeurs.

Bien que dans la portée globale, ils ne sont pas disponibles jusqu'après la `deviceready` événement.

    document.addEventListener (« deviceready », onDeviceReady, false) ;
    function onDeviceReady() {console.log(FileTransfer);}
    

## Installation

    cordova plugin add cordova-plugin-file-transfer
    

## Plates-formes supportées

  * Amazon Fire OS
  * Android
  * BlackBerry 10
  * Navigateur
  * Firefox OS **
  * iOS
  * Windows Phone 7 et 8 *
  * Windows 8
  * Windows

\ * *Ne supportent pas `onprogress` ni `abort()` *

\ ** *Ne prennent pas en charge les `onprogress` *

# Transfert de fichiers

L'objet de `FileTransfer` fournit un moyen de télécharger des fichiers à l'aide d'une requête HTTP multi-part POST ou PUT et pour télécharger des fichiers.

## Propriétés

  * **onprogress** : fonction appelée avec un `ProgressEvent` à chaque fois qu'un nouveau segment de données est transféré. *(Function)*

## Méthodes

  * **upload** : envoie un fichier à un serveur.

  * **download** : télécharge un fichier depuis un serveur.

  * **abort** : annule le transfert en cours.

## upload

**Paramètres**:

  * **fileURL** : système de fichiers URL représentant le fichier sur le périphérique. Pour la compatibilité ascendante, cela peut aussi être le chemin complet du fichier sur le périphérique. (Voir [Backwards Compatibility Notes] ci-dessous)

  * **server** : l'URL du serveur destiné à recevoir le fichier, encodée via `encodeURI()`.

  * **successCallback**: un rappel passé un `FileUploadResult` objet. *(Fonction)*

  * **errorCallback**: un rappel qui s'exécute si une erreur survient récupérer la `FileUploadResult` . Appelée avec un `FileTransferError` objet. *(Fonction)*

  * **options**: paramètres facultatifs *(objet)*. Clés valides :
    
      * **fileKey**: le nom de l'élément form. Valeur par défaut est `file` . (DOMString)
      * **fileName**: le nom de fichier à utiliser lorsque vous enregistrez le fichier sur le serveur. Valeur par défaut est `image.jpg` . (DOMString)
      * **httpMethod**: méthode de The HTTP à utiliser - soit `PUT` ou `POST` . Valeur par défaut est `POST` . (DOMString)
      * **type MIME**: le type mime des données à télécharger. Valeur par défaut est `image/jpeg` . (DOMString)
      * **params**: un ensemble de paires clé/valeur facultative pour passer dans la requête HTTP. (Objet)
      * **chunkedMode**: s'il faut télécharger les données en mode streaming mémorisé en bloc. Valeur par défaut est `true` . (Boolean)
      * **headers**: une carte des valeurs d'en-tête en-tête/nom. Un tableau permet de spécifier plusieurs valeurs. Sur iOS, FireOS et Android, si un en-tête nommé Content-Type n'est présent, les données de formulaire multipart servira pas. (Object)
      * **httpMethod**: The HTTP méthode à utiliser par exemple poster ou mis. Par défaut, `message`. (DOMString)

  * **trustAllHosts**: paramètre facultatif, valeur par défaut est `false` . Si la valeur est `true` , il accepte tous les certificats de sécurité. Ceci est utile car Android rejette des certificats auto-signés. N'est pas recommandé pour une utilisation en production. Supporté sur Android et iOS. *(booléen)*

### Exemple

    // !! Suppose fileURL variable contient une URL valide dans un fichier texte sur le périphérique, / / par exemple, cdvfile://localhost/persistent/path/to/file.txt var win = function (r) {console.log ("Code =" + r.responseCode) ;
        Console.log ("réponse =" + r.response) ;
        Console.log ("envoyés =" + r.bytesSent);}
    
    échouer var = function (erreur) {alert ("une erreur est survenue : Code =" + error.code) ;
        Console.log (« source de l'erreur de téléchargement » + error.source) ;
        Console.log ("erreur de téléchargement cible" + error.target);}
    
    options de var = new FileUploadOptions() ;
    options.fileKey = « fichier » ;
    options.fileName = fileURL.substr(fileURL.lastIndexOf('/') + 1) ;
    options.mimeType = « text/plain » ;
    
    var params = {} ;
    params.value1 = « test » ;
    params.Value2 = « param » ;
    
    options.params = params ;
    
    ft var = new FileTransfer() ;
    ft.upload (fileURL, encodeURI ("http://some.server.com/upload.php"), win, fail, options) ;
    

### Exemple avec téléchargement du Header et des Progress Events (Android et iOS uniquement)

    function win(r) {console.log ("Code =" + r.responseCode) ;
        Console.log ("réponse =" + r.response) ;
        Console.log ("envoyés =" + r.bytesSent);}
    
    function fail(error) {alert ("une erreur est survenue : Code =" + error.code) ;
        Console.log (« source de l'erreur de téléchargement » + error.source) ;
        Console.log ("erreur de téléchargement cible" + error.target);}
    
    var uri = encodeURI ("http://some.server.com/upload.php") ;
    
    options de var = new FileUploadOptions() ;
    options.fileKey="file" ;
    options.fileName=fileURL.substr(fileURL.lastIndexOf('/')+1) ;
    options.mimeType="text/plain" ;
    
    en-têtes var ={'headerParam':'headerValue'} ;
    
    options.Headers = en-têtes ;
    
    ft var = new FileTransfer() ;
    ft.OnProgress = function(progressEvent) {si (progressEvent.lengthComputable) {loadingStatus.setPercentage(progressEvent.loaded / progressEvent.total) ;
        } else {loadingStatus.increment() ;
        }
    };
    ft.upload (fileURL, uri, win, fail, options) ;
    

## FileUploadResult

A `FileUploadResult` objet est passé au rappel de succès la `FileTransfer` de l'objet `upload()` méthode.

### Propriétés

  * **bytesSent** : le nombre d'octets envoyés au serveur dans le cadre du téléchargement. (long)

  * **responseCode** : le code de réponse HTTP retourné par le serveur. (long)

  * **response** : la réponse HTTP renvoyée par le serveur. (DOMString)

  * **en-têtes** : en-têtes de réponse HTTP par le serveur. (Objet)
    
      * Actuellement pris en charge sur iOS seulement.

### Notes au sujet d'iOS

  * Ne prend pas en charge les propriétés `responseCode` et `bytesSent`.

## download

**Paramètres**:

  * **source** : l'URL du serveur depuis lequel télécharger le fichier, encodée via `encodeURI()`.

  * **target** : système de fichiers url représentant le fichier sur le périphérique. Pour la compatibilité ascendante, cela peut aussi être le chemin complet du fichier sur le périphérique. (Voir [Backwards Compatibility Notes] ci-dessous)

  * **successCallback** : une callback de succès à laquelle est passée un objet `FileEntry`. *(Function)*

  * **errorCallback**: un rappel qui s'exécute si une erreur se produit lors de la récupération du `FileEntry` . Appelée avec un `FileTransferError` objet. *(Fonction)*

  * **trustAllHosts**: paramètre facultatif, valeur par défaut est `false` . Si la valeur est `true` , il accepte tous les certificats de sécurité. Ceci peut être utile car Android rejette les certificats auto-signés. N'est pas recommandé pour une utilisation en production. Supporté sur Android et iOS. *(booléen)*

  * **options** : paramètres facultatifs, seules les en-têtes sont actuellement supportées (par exemple l'autorisation (authentification basique), etc.).

### Exemple

    // !! Suppose fileURL variable contient une URL valide vers un chemin d'accès sur le périphérique, / / par exemple, transfert de fichiers var cdvfile://localhost/persistent/path/to/downloads/ = new FileTransfer() ;
    var uri = encodeURI ("http://some.server.com/download.php") ;
    
    fileTransfer.download (uri, fileURL, function(entry) {console.log ("téléchargement complet:" + entry.toURL()) ;
        }, function(error) {console.log (« source de l'erreur de téléchargement » + error.source) ;
            Console.log (« erreur de téléchargement cible » + error.target) ;
            Console.log (« code d'erreur de téléchargement » + error.code) ;
        }, faux, {en-têtes: {« Autorisation »: « dGVzdHVzZXJuYW1lOnRlc3RwYXNzd29yZA base == "}}) ;
    

### Quirks wp8

  * Télécharger demande est mis en cache par l'implémentation native. Pour éviter la mise en cache, pass `if-Modified-Since` en-tête Télécharger méthode.

## abort

Abandonne un transfert en cours. Le rappel onerror est passé à un objet FileTransferError qui a un code d'erreur de FileTransferError.ABORT_ERR.

### Exemple

    // !! Suppose fileURL variable contient une URL valide dans un fichier texte sur le périphérique, / / par exemple, cdvfile://localhost/persistent/path/to/file.txt var win = function(r) {console.log ("ne devrait pas être appelée.");}
    
    var fail = function(error) {/ / error.code == FileTransferError.ABORT_ERR alert ("une erreur est survenue : Code =" + error.code) ;
        Console.log (« source de l'erreur de téléchargement » + error.source) ;
        Console.log ("erreur de téléchargement cible" + error.target);}
    
    options de var = new FileUploadOptions() ;
    options.fileKey="file" ;
    options.fileName="myphoto.jpg" ;
    options.mimeType="image/jpeg" ;
    
    ft var = new FileTransfer() ;
    ft.upload (fileURL, encodeURI ("http://some.server.com/upload.php"), win, fail, options) ;
    ft.Abort() ;
    

## FileTransferError

A `FileTransferError` objet est passé à un rappel d'erreur lorsqu'une erreur survient.

### Propriétés

  * **code** : l'un des codes d'erreur prédéfinis énumérés ci-dessous. (Number)

  * **source** : l'URI de la source. (String)

  * **target**: l'URI de la destination. (String)

  * **http_status** : code d'état HTTP. Cet attribut n'est disponible que lorsqu'un code de réponse est fourni via la connexion HTTP. (Number)

  * **corps** Corps de réponse. Cet attribut n'est disponible que lorsqu'une réponse est reçue de la connexion HTTP. (String)

  * **exception**: soit e.getMessage ou e.toString (String)

### Constantes

  * 1 = `FileTransferError.FILE_NOT_FOUND_ERR`
  * 2 = `FileTransferError.INVALID_URL_ERR`
  * 3 = `FileTransferError.CONNECTION_ERR`
  * 4 = `FileTransferError.ABORT_ERR`
  * 5 = `FileTransferError.NOT_MODIFIED_ERR`

## Backwards Compatibility Notes

Les versions précédentes de ce plugin n'accepterait périphérique--fichier-chemins d'accès absolus comme source pour les téléchargements, ou comme cible pour les téléchargements. Ces chemins seraient généralement de la forme

    / var/mobile/Applications/< application UUID >/Documents/chemin/vers/fichier (iOS), /storage/emulated/0/path/to/file (Android)
    

Pour vers l'arrière la compatibilité, ces chemins sont toujours acceptés, et si votre application a enregistré des chemins comme celles-ci dans un stockage persistant, alors ils peuvent continuer à être utilisé.

Ces chemins ont été précédemment exposés dans le `fullPath` propriété de `FileEntry` et `DirectoryEntry` les objets retournés par le fichier plugin. Nouvelles versions du fichier plugin, cependant, ne plus exposent ces chemins à JavaScript.

Si vous migrez vers une nouvelle (1.0.0 ou plus récent) version de fichier et vous avez précédemment utilisé `entry.fullPath` comme arguments à `download()` ou `upload()` , alors vous aurez besoin de modifier votre code pour utiliser le système de fichiers URL au lieu de cela.

`FileEntry.toURL()`et `DirectoryEntry.toURL()` retournent une URL de système de fichiers du formulaire

    cdvfile://localhost/persistent/path/to/file
    

qui peut être utilisé à la place le chemin d'accès absolu au fichier dans les deux `download()` et `upload()` méthodes.